From 999ecb4cad715aea333f78b85ef423b747bf9561 Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Sat, 27 Mar 2004 15:59:44 +0000 Subject: [PATCH] * cygserver.sgml: New file. * using.sgml: Include Cygserver docs. --- winsup/doc/ChangeLog | 5 + winsup/doc/cygserver.sgml | 273 ++++++++++++++++++++++++++++++++++++++ winsup/doc/using.sgml | 2 + 3 files changed, 280 insertions(+) create mode 100644 winsup/doc/cygserver.sgml diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index c1f207b94..e0509234e 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,8 @@ +2004-03-27 Corinna Vinschen + + * cygserver.sgml: New file. + * using.sgml: Include Cygserver docs. + 2004-03-26 Joshua Daniel Franklin * cygwinenv.sgml: Add example for CYGWIN=error_start. * pathnames.sgml: Update list of /dev/ devices. diff --git a/winsup/doc/cygserver.sgml b/winsup/doc/cygserver.sgml new file mode 100644 index 000000000..76be94d72 --- /dev/null +++ b/winsup/doc/cygserver.sgml @@ -0,0 +1,273 @@ +Cygserver + +What is Cygserver? + + + Cygserver is a program which is designed to run as a background service. + It provides Cygwin applications with services which require security + arbitration or which need to persist while no other cygwin application + is running. + + + The implemented services so far are: + + + Control slave tty/pty handle dispersal from tty owner to other + processes without compromising the owner processes' security. + XSI IPC Message Queues. + XSI IPC Semaphores. + XSI IPC Shared Memory. + + + + +Cygserver command line options + + + Options to Cygserver take the normal UNIX-style `-X' or `--longoption' form. + Nearly all options have a counterpart in the configuration file (see below) + so setting them on the command line isn't really necessary. Command line + options override settings from the Cygserver configuration file. + + + The one-character options are prepended by a single dash, the long variants + are prepended with two dashes. Arguments to options are marked in angle + brackets below. These are not part of the actual syntax but are used only to + denote the arguments. Note that all arguments are required. Cygserver + has no options with optional arguments. + + + The recognized options are: + + + + -f, --config-file <file> + + Use <file> as configuration file instead of the default configuration + line. The default configuration file is /etc/cygserver.conf, typically. + The --help and --version options will print the default configuration + pathname. + + + This option has no counterpart in the configuration file, for obvious + reasons. + + -c, --cleanup-threads <num> + + Number of threads started to perform cleanup tasks. Default is 2. + Configuration file option: kern.srv.cleanup_threads + + + + -r, --request-threads <num> + + Number of threads started to serve application requests. Default is 10. + The -c and -r options can be used to play with Cygserver's performance + under heavy load conditions or on slow machines. + Configuration file option: kern.srv.request_threads + + + + -d, --debug + + Log debug messages to stderr. These will clutter your stderr output with + a lot of information, typically only useful to developers. + + + + -e, --stderr + + Force logging to stderr. This is the default if stderr is connected to + a tty. Otherwise, the default is logging to the system log. By using + the -e, -E, -y, -Y options (or the appropriate settings in the + configuration file), you can explicitely set the logging output as you + like, even to both, stderr and syslog. + Configuration file option: kern.log.stderr + + + + -E, --no-stderr + + Don't log to stderr. Configuration file option: kern.log.stderr + + + + -y, --syslog + + Force logging to the system log. This is the default, if stderr is not + connected to a tty, e. g. redirected to a file. Note, that on 9x/Me + systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT. + Configuration file option: kern.log.syslog + + + + -Y, --no-syslog + + Don't log to syslog. Configuration file option: kern.log.syslog + + + + -l, --log-level <level> + + Set the verbosity level of the logging output. Valid values are between + 1 and 7. The default level is 6, which is relatively chatty. If you set + it to 1, you will get only messages which are printed under severe conditions, + which will result in stopping Cygserver itself. + Configuration file option: kern.log.level + + + + -m, --no-sharedmem + + Don't start XSI IPC Shared Memory support. If you don't need XSI IPC + Shared Memory support, you can switch it off here. + Configuration file option: kern.srv.sharedmem + + + + -q, --no-msgqueues + + Don't start XSI IPC Message Queues. + Configuration file option: kern.srv.msgqueues + + + + -s, --no-semaphores + + Don't start XSI IPC Semaphores. + Configuration file option: kern.srv.semaphores + + + + -S, --shutdown + + Shutdown a running daemon and exit. Other methods are sending a SIGHUP + to the Cygserver PID or, if running as service under NT, calling + `net stop cygserver' or `cygrunsrv -E cygserver'. + + + + -h, --help + + Output usage information and exit. + + + + -v, --version + + Output version information and exit. + + + + + + +How to start Cygserver + + + Before you run Cygserver for the first time, you should run the + /usr/bin/cygserver-config script once. It creates the default + configuration file and, upon request, installs Cygserver as service + when running under NT. The script only performs a default install, + with no further options given to Cygserver when running as service. + Due to the wide configurability by changing the configuration file, + that's typically not necessary. + + + On Windows 9x/Me, just start Cygserver in any console window. It's + advisable to redirect stderr to a file of choice (e. g. + /var/log/cygserver.log) and to use the -e and -Y options or the + set the appropriate settings in the configuration file (see below). + + + On Windows NT/2000/XP or 2003, you should always run Cygserver as a + service under LocalSystem account. This is the way it is installed + for you by the /usr/bin/cygserver-config script. + + + + +How to use the Cygserver services + + + The Cygserver services are used by Cygwin applications only if you + set the environment variable CYGWIN to contain the string "server". + You must do this before starting the application. + + + Typically, you don't need any other option, so it's ok to set CYGWIN + just to "server". It is not necessary to set the CYGWIN environment + variable prior to starting the Cygserver process itself, but it won't + hurt to do so. + + + The easiest way is to set the environment variable CYGWIN to the values + you want in the Windows system environment and to reboot the machine. + This is advisable, since it allows you to set the variable once and + then forget about it. It also ensures that services as well as desktop + applications have the same setting. + + + If you don't want that for whatever reason, you can set the + variable in the /cygwin.bat file which is used in the net distribution, + to start a Cygwin bash from the desktop. In that file, you can set + the CYGWIN variable using Windows command line interpreter syntax, e. g.: + + + + set CYGWIN=server + + + + If you don't set CYGWIN in the system environment, but you're running + other Cygwin services, these services need to get that CYGWIN value by + setting the environment using the appropriate cygrunsrv option '-e' when + installing the service. Example installing a service 'foo': + + + + cygrunsrv -I foo -p /usr/sbin/foo -e "CYGWIN=server" + + + + + +The Cygserver configuration file + + + Cygserver has many options, which allow to customize the server + to your needs. Customization is accomplished by editing the configuration + file, which is by default /etc/cygserver.conf. This file is read only + once on startup of Cygserver. There's no option to re-read the file on + runtime by, say, sending a signal to Cygserver. + + + The configuration file determines how Cygserver operates. There are + options which set the number of threads running in parallel, options + for setting how and what to log and options to set various maximum + values for the IPC services. + + + The default configuration file delivered with Cygserver is installed + to /etc/defaults/etc. The /usr/bin/cygserver-config script copies it to + /etc, giving you the option to overwrite an already existing file or to + leave it alone. Therefore, the /etc file is safe to be changed by you, + since it will not be overwritten by a later update installation. + + + The default configuration file contains many comments which describe + everything needed to understand the settings. A comment at the start of the + file describes the syntax rules for the file. The default options are shown + in the file but are commented out. + + + It is generally a good idea to uncomment only options which you intend to + change from the default values. Since reading the options file on Cygserver + startup doesn't take much time, it's also considered good practice to keep + all other comments in the file. This keeps you from searching for clues + in other sources. + + + + + diff --git a/winsup/doc/using.sgml b/winsup/doc/using.sgml index 13a353c52..4678cff93 100644 --- a/winsup/doc/using.sgml +++ b/winsup/doc/using.sgml @@ -14,6 +14,8 @@ DOCTOOL-INSERT-using-specialnames DOCTOOL-INSERT-using-cygwinenv +DOCTOOL-INSERT-using-cygserver + DOCTOOL-INSERT-using-utils DOCTOOL-INSERT-using-effectively