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.
  97
  98   -Y, --no-syslog
  99
 100     Don't log to syslog.  Configuration file option:  kern.log.syslog
 101
 102   -l, --log-level <level>
 103
 104     Set the verbosity level of the logging output.  Valid values are between
 105     1 and 7.  The default level is 6, which is relatively chatty.  If you set
 106     it to 1, you will get only messages which are printed under severe conditions,
 107     which will result in stopping Cygserver itself.
 108     Configuration file option:  kern.log.level
 109
 110   -m, --no-sharedmem
 111
 112     Don't start XSI IPC Shared Memory support.  If you don't need XSI IPC
 113     Shared Memory support, you can switch it off here.
 114     Configuration file option:  kern.srv.sharedmem
 115
 116   -q, --no-msgqueues
 117
 118     Don't start XSI IPC Message Queues.
 119     Configuration file option:  kern.srv.msgqueues
 120
 121   -s, --no-semaphores
 122
 123     Don't start XSI IPC Semaphores.
 124     Configuration file option:  kern.srv.semaphores
 125
 126   -S, --shutdown
 127
 128     Shutdown a running daemon and exit.  Other methods are sending a SIGHUP
 129     to the Cygserver PID or, if running as service under NT, calling
 130     `net stop cygserver' or `cygrunsrv -E cygserver'.
 131
 132   -h, --help
 133
 134     Output usage information and exit.
 135
 136   -v, --version
 137
 138     Output version information and exit.
 139
 140
 141 How to start Cygserver:
 142
 143   Before you run Cygserver for the first time, you should run the
 144   /usr/bin/cygserver-config script once.  It creates the default
 145   configuration file and, upon request, installs Cygserver as service
 146   when running under NT.  The script only performs a default install,
 147   with no further options given to Cygserver when running as service.
 148   Due to the wide configurability by changing the configuration file,
 149   that's typically not necessary.
 150
 151   It's best practice to run Cygserver as a service under LocalSystem
 152   account.  This is the way it is installed for you by the
 153   /usr/bin/cygserver-config script.
 154
 155
 156 How to use the Cygserver services:
 157
 158   The Cygserver services are used by Cygwin applications only if you
 159   set the environment variable CYGWIN to contain the string "server".
 160   You must do this before starting the application.
 161
 162   Typically, you don't need any other option, so it's ok to set CYGWIN
 163   just to "server".  It is not necessary to set the CYGWIN environment
 164   variable prior to starting the Cygserver process itself, but it won't
 165   hurt to do so.
 166
 167   The easiest way is to set the environment variable CYGWIN to the values
 168   you want in the Windows system environment and to reboot the machine.
 169   This is advisable, since it allows you to set the variable once and
 170   then forget about it.  It also ensures that services as well as desktop
 171   applications have the same setting.
 172
 173   If you don't want that for whatever reason, you can set the
 174   variable in the /cygwin.bat file which is used in the net distribution,
 175   to start a Cygwin bash from the desktop.  In that file, you can set
 176   the CYGWIN variable using Windows command line interpreter syntax, e. g.:
 177
 178     set CYGWIN=server
 179
 180   If you don't set CYGWIN in the system environment, but you're running
 181   other Cygwin services, these services need to get that CYGWIN value by
 182   setting the environment using the appropriate cygrunsrv option '-e' when
 183   installing the service.  Example installing a service 'foo':
 184
 185     cygrunsrv -I foo -p /usr/sbin/foo -e "CYGWIN=server"
 186
 187
 188 The Cygserver configuration file:
 189
 190   Cygserver has many options, which allow to customize the server
 191   to your needs.  Customization is accomplished by editing the configuration
 192   file, which is by default /etc/cygserver.conf.  This file is read only
 193   once on startup of Cygserver.  There's no option to re-read the file on
 194   runtime by, say, sending a signal to Cygserver.
 195
 196   The configuration file determines how Cygserver operates.  There are
 197   options which set the number of threads running in parallel, options
 198   for setting how and what to log and options to set various maximum
 199   values for the IPC services.
 200
 201   The default configuration file delivered with Cygserver is installed
 202   to /etc/defaults/etc.  The /usr/bin/cygserver-config script copies it to
 203   /etc, giving you the option to overwrite an already existing file or to
 204   leave it alone.  Therefore, the /etc file is safe to be changed by you,
 205   since it will not be overwritten by a later update installation.
 206
 207   The default configuration file contains many comments which describe
 208   everything needed to understand the settings.  A comment at the start of the
 209   file describes the syntax rules for the file.  The default options are shown
 210   in the file but are commented out.
 211
 212   It is generally a good idea to uncomment only options which you intend to
 213   change from the default values.  Since reading the options file on Cygserver
 214   startup doesn't take much time, it's also considered good practice to keep
 215   all other comments in the file.  This keeps you from searching for clues
 216   in other sources.
 217
 218
 219 If you have problems with Cygserver, or you have found a bug, or you
 220 think you have found a bug, or you don't understand configuration file
 221 options, the mailing list <cygwin@cygwin.com> is the right place to ask
 222 questions.
 223
 224 Have fun!