winsup/cygserver/README

   1 What is Cygserver?
   2
   3   Cygserver is a program which is designed to run as a background service.
   4   It provides Cygwin applications with services which require security
   5   arbitration or which need to persist while no other cygwin application
   6   is running.
   7
   8   The implemented services so far are:
   9
  10   - Control slave tty/pty handle dispersal from tty owner to other
  11     processes without compromising the owner processes' security.
  12   - XSI IPC Message Queues.
  13   - XSI IPC Semaphores.
  14   - XSI IPC Shared Memory.
  15
  16
  17 Cygserver command line options:
  18
  19   Options to Cygserver take the normal UNIX-style `-X' or `--longoption' form.
  20   Nearly all options have a counterpart in the configuration file (see below)
  21   so setting them on the command line isn't really necessary.  Command line
  22   options override settings from the Cygserver configuration file.
  23
  24   The one-character options are prepended by a single dash, the long variants
  25   are prepended with two dashes.  Arguments to options are marked in angle
  26   brackets below.  These are not part of the actual syntax but are used only to
  27   denote the arguments.  Note that all arguments are required.  Cygserver
  28   has no options with optional arguments.
  29
  30   The options recognized are:
  31
  32   -f, --config-file <file>
  33
  34     Use <file> as configuration file instead of the default configuration
  35     line.  The default configuration file is /etc/cygserver.conf, typically.
  36     The --help and --version options will print the default configuration
  37     pathname.
  38
  39     This option has no counterpart in the configuration file, for obvious
  40    reasons.
  41
  42   -c, --cleanup-threads <num>
  43
  44     Number of threads started to perform cleanup tasks.  Default is 2.
  45     Configuration file option:  kern.srv.cleanup_threads
  46
  47   -r, --request-threads <num>
  48
  49     Number of threads started to serve application requests.  Default is 10.
  50     The -c and -r options can be used to play with Cygserver's performance
  51     under heavy load conditions or on slow machines.
  52     Configuration file option:  kern.srv.request_threads
  53
  54   -p, --process-cache <num>
  55
  56     Number of processes which can connect concurrently to cygserver.
  57     Default is 62.  Each process connected to cygserver is a synchronization
  58     object which has to be maintained.  The data structure to maintain these
  59     processes is the so-called "process cache".  In theory, an arbitrary
  60     number of processes could connect to cygserver, but due to the need to
  61     synchronize, the higher the number of connected processes, the more
  62     synchronization overhead exists.  By using this option, you can set an
  63     upper limit to the synchronization effort.  If more than 62 processes
  64     try to connect to cygserver concurrently, two additional synchronization
  65     threads are necessary, and one for each further 62 concurrent
  66     processes.  So, useful values for the --process-cache option are 62, 124,
  67     186, 248, 310.  310 is the maximum value.
  68     Configuration file option:  kern.srv.process_cache_size
  69
  70     NOTE:  The number of child processes of a single parent process is limited
  71     to 256.  So in case of taking advantage of a process cache size beyond 256,
  72     keep in mind that not all of these processes can be child processes of one
  73     single parent process.
  74
  75   -d, --debug
  76
  77     Log debug messages to stderr.  These will clutter your stderr output with
  78     a lot of information, typically only useful to developers.
  79
  80   -e, --stderr
  81
  82     Force logging to stderr.  This is the default if stderr is connected to
  83     a tty.  Otherwise, the default is logging to the system log.  By using
  84     the -e, -E, -y, -Y options (or the appropriate settings in the
  85     configuration file), you can explicitely set the logging output as you
  86     like, even to both, stderr and syslog.
  87     Configuration file option:  kern.log.stderr
  88
  89   -E, --no-stderr
  90
  91     Don't log to stderr.  Configuration file option:  kern.log.stderr
  92
  93   -y, --syslog
  94
  95     Force logging to the system log.  This is the default, if stderr is not
  96     connected to a tty, e. g. redirected to a file.  Note, that on 9x/Me
  97     systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT.
  98     Configuration file option:  kern.log.syslog
  99
 100   -Y, --no-syslog
 101
 102     Don't log to syslog.  Configuration file option:  kern.log.syslog
 103
 104   -l, --log-level <level>
 105
 106     Set the verbosity level of the logging output.  Valid values are between
 107     1 and 7.  The default level is 6, which is relatively chatty.  If you set
 108     it to 1, you will get only messages which are printed under severe conditions,
 109     which will result in stopping Cygserver itself.
 110     Configuration file option:  kern.log.level
 111
 112   -m, --no-sharedmem
 113
 114     Don't start XSI IPC Shared Memory support.  If you don't need XSI IPC
 115     Shared Memory support, you can switch it off here.
 116     Configuration file option:  kern.srv.sharedmem
 117
 118   -q, --no-msgqueues
 119
 120     Don't start XSI IPC Message Queues.
 121     Configuration file option:  kern.srv.msgqueues
 122
 123   -s, --no-semaphores
 124
 125     Don't start XSI IPC Semaphores.
 126     Configuration file option:  kern.srv.semaphores
 127
 128   -S, --shutdown
 129
 130     Shutdown a running daemon and exit.  Other methods are sending a SIGHUP
 131     to the Cygserver PID or, if running as service under NT, calling
 132     `net stop cygserver' or `cygrunsrv -E cygserver'.
 133
 134   -h, --help
 135
 136     Output usage information and exit.
 137
 138   -v, --version
 139
 140     Output version information and exit.
 141
 142
 143 How to start Cygserver:
 144
 145   Before you run Cygserver for the first time, you should run the
 146   /usr/bin/cygserver-config script once.  It creates the default
 147   configuration file and, upon request, installs Cygserver as service
 148   when running under NT.  The script only performs a default install,
 149   with no further options given to Cygserver when running as service.
 150   Due to the wide configurability by changing the configuration file,
 151   that's typically not necessary.
 152
 153   On Windows 9x/Me, just start Cygserver in any console window.  It's
 154   advisable to redirect stderr to a file of choice (e. g.
 155   /var/log/cygserver.log) and to use the -e and -Y options or the
 156   set the appropriate settings in the configuration file (see below).
 157
 158   On Windows NT/2000/XP or 2003, you should always run Cygserver as a
 159   service under LocalSystem account.  This is the way it is installed
 160   for you by the /usr/bin/cygserver-config script.
 161
 162
 163 How to use the Cygserver services:
 164
 165   The Cygserver services are used by Cygwin applications only if you
 166   set the environment variable CYGWIN to contain the string "server".
 167   You must do this before starting the application.
 168
 169   Typically, you don't need any other option, so it's ok to set CYGWIN
 170   just to "server".  It is not necessary to set the CYGWIN environment
 171   variable prior to starting the Cygserver process itself, but it won't
 172   hurt to do so.
 173
 174   The easiest way is to set the environment variable CYGWIN to the values
 175   you want in the Windows system environment and to reboot the machine.
 176   This is advisable, since it allows you to set the variable once and
 177   then forget about it.  It also ensures that services as well as desktop
 178   applications have the same setting.
 179
 180   If you don't want that for whatever reason, you can set the
 181   variable in the /cygwin.bat file which is used in the net distribution,
 182   to start a Cygwin bash from the desktop.  In that file, you can set
 183   the CYGWIN variable using Windows command line interpreter syntax, e. g.:
 184
 185     set CYGWIN=server
 186
 187   If you don't set CYGWIN in the system environment, but you're running
 188   other Cygwin services, these services need to get that CYGWIN value by
 189   setting the environment using the appropriate cygrunsrv option '-e' when
 190   installing the service.  Example installing a service 'foo':
 191
 192     cygrunsrv -I foo -p /usr/sbin/foo -e "CYGWIN=server"
 193
 194
 195 The Cygserver configuration file:
 196
 197   Cygserver has many options, which allow to customize the server
 198   to your needs.  Customization is accomplished by editing the configuration
 199   file, which is by default /etc/cygserver.conf.  This file is read only
 200   once on startup of Cygserver.  There's no option to re-read the file on
 201   runtime by, say, sending a signal to Cygserver.
 202
 203   The configuration file determines how Cygserver operates.  There are
 204   options which set the number of threads running in parallel, options
 205   for setting how and what to log and options to set various maximum
 206   values for the IPC services.
 207
 208   The default configuration file delivered with Cygserver is installed
 209   to /etc/defaults/etc.  The /usr/bin/cygserver-config script copies it to
 210   /etc, giving you the option to overwrite an already existing file or to
 211   leave it alone.  Therefore, the /etc file is safe to be changed by you,
 212   since it will not be overwritten by a later update installation.
 213
 214   The default configuration file contains many comments which describe
 215   everything needed to understand the settings.  A comment at the start of the
 216   file describes the syntax rules for the file.  The default options are shown
 217   in the file but are commented out.
 218
 219   It is generally a good idea to uncomment only options which you intend to
 220   change from the default values.  Since reading the options file on Cygserver
 221   startup doesn't take much time, it's also considered good practice to keep
 222   all other comments in the file.  This keeps you from searching for clues
 223   in other sources.
 224
 225
 226 If you have problems with Cygserver, or you have found a bug, or you
 227 think you have found a bug, or you don't understand configuration file
 228 options, the mailing list <cygwin@cygwin.com> is the right place to ask
 229 questions.
 230
 231 Have fun!