winsup/doc/cygserver.sgml

   1 <sect1 id="using-cygserver"><title>Cygserver</title>
   2
   3 <sect2 id="what-is-cygserver"><title>What is Cygserver?</title>
   4
   5 <para>
   6   Cygserver is a program which is designed to run as a background service.
   7   It provides Cygwin applications with services which require security
   8   arbitration or which need to persist while no other cygwin application
   9   is running.
  10 </para>
  11 <para>
  12   The implemented services so far are:
  13 </para>
  14 <itemizedlist mark="bullet">
  15   <listitem><para>Control slave tty/pty handle dispersal from tty owner to other
  16     processes without compromising the owner processes' security.</para></listitem>
  17   <listitem><para>XSI IPC Message Queues.</para></listitem>
  18   <listitem><para>XSI IPC Semaphores.</para></listitem>
  19   <listitem><para>XSI IPC Shared Memory.</para></listitem>
  20   <listitem><para>Allows non-privileged users to store obfuscated
  21   passwords in the registry to be used by <command>setuid</command> and
  22   <command>seteuid</command> calls to create user tokens with network
  23   credentials.  This service is used by <command><link
  24   linkend="passwd">passwd</link> -R</command>.  Using the stored
  25   passwords in <command>set(e)uid</command> does not require running
  26   Cygserver.  For details, see <xref linkend="ntsec-setuid-overview"></xref>.
  27   </para></listitem>
  28 </itemizedlist>
  29
  30 </sect2>
  31
  32 <sect2 id="cygserver-command-line"><title>Cygserver command line options</title>
  33
  34 <para>
  35   Options to Cygserver take the normal UNIX-style `-X' or `--longoption' form.
  36   Nearly all options have a counterpart in the configuration file (see below)
  37   so setting them on the command line isn't really necessary.  Command line
  38   options override settings from the Cygserver configuration file.
  39 </para>
  40 <para>
  41   The one-character options are prepended by a single dash, the long variants
  42   are prepended with two dashes.  Arguments to options are marked in angle
  43   brackets below.  These are not part of the actual syntax but are used only to
  44   denote the arguments.  Note that all arguments are required.  Cygserver
  45   has no options with optional arguments.
  46 </para>
  47 <para>
  48   The recognized options are:
  49 </para>
  50
  51 <itemizedlist spacing="compact">
  52 <listitem>
  53   <screen>-f, --config-file &lt;file&gt;</screen>
  54   <para>
  55     Use &lt;file&gt; as configuration file instead of the default configuration
  56     line.  The default configuration file is /etc/cygserver.conf.
  57     The --help and --version options will print the default configuration
  58     pathname.
  59   </para>
  60   <para>
  61     This option has no counterpart in the configuration file, for obvious
  62    reasons.
  63   </para>
  64 </listitem>
  65 <listitem>
  66   <screen>-c, --cleanup-threads &lt;num&gt;</screen>
  67   <para>
  68     Number of threads started to perform cleanup tasks.  Default is 2.
  69     Configuration file option:  kern.srv.cleanup_threads
  70   </para>
  71 </listitem>
  72 <listitem>
  73   <screen>-r, --request-threads &lt;num&gt;</screen>
  74   <para>
  75     Number of threads started to serve application requests.  Default is 10.
  76     The -c and -r options can be used to play with Cygserver's performance
  77     under heavy load conditions or on slow machines.
  78     Configuration file option:  kern.srv.request_threads
  79   </para>
  80 </listitem>
  81 <listitem>
  82   <screen>-d, --debug</screen>
  83   <para>
  84     Log debug messages to stderr.  These will clutter your stderr output with
  85     a lot of information, typically only useful to developers.
  86   </para>
  87 </listitem>
  88 <listitem>
  89   <screen>-e, --stderr</screen>
  90   <para>
  91     Force logging to stderr.  This is the default if stderr is connected to
  92     a tty.  Otherwise, the default is logging to the system log.  By using
  93     the -e, -E, -y, -Y options (or the appropriate settings in the
  94     configuration file), you can explicitly set the logging output as you
  95     like, even to both, stderr and syslog.
  96     Configuration file option:  kern.log.stderr
  97   </para>
  98 </listitem>
  99 <listitem>
 100   <screen>-E, --no-stderr</screen>
 101   <para>
 102     Don't log to stderr.  Configuration file option:  kern.log.stderr
 103   </para>
 104 </listitem>
 105 <listitem>
 106   <screen>-y, --syslog</screen>
 107   <para>
 108     Force logging to the system log.  This is the default, if stderr is not
 109     connected to a tty, e. g. redirected to a file.
 110     Configuration file option:  kern.log.syslog
 111   </para>
 112 </listitem>
 113 <listitem>
 114   <screen>-Y, --no-syslog</screen>
 115   <para>
 116     Don't log to syslog.  Configuration file option:  kern.log.syslog
 117   </para>
 118 </listitem>
 119 <listitem>
 120   <screen>-l, --log-level &lt;level&gt;</screen>
 121    <para>
 122     Set the verbosity level of the logging output.  Valid values are between
 123     1 and 7.  The default level is 6, which is relatively chatty.  If you set
 124     it to 1, you will get only messages which are printed under severe conditions,
 125     which will result in stopping Cygserver itself.
 126     Configuration file option:  kern.log.level
 127   </para>
 128 </listitem>
 129 <listitem>
 130   <screen>-m, --no-sharedmem</screen>
 131   <para>
 132     Don't start XSI IPC Shared Memory support.  If you don't need XSI IPC
 133     Shared Memory support, you can switch it off here.
 134     Configuration file option:  kern.srv.sharedmem
 135   </para>
 136 </listitem>
 137 <listitem>
 138   <screen>-q, --no-msgqueues</screen>
 139   <para>
 140     Don't start XSI IPC Message Queues.
 141     Configuration file option:  kern.srv.msgqueues
 142   </para>
 143 </listitem>
 144 <listitem>
 145   <screen>-s, --no-semaphores</screen>
 146   <para>
 147     Don't start XSI IPC Semaphores.
 148     Configuration file option:  kern.srv.semaphores
 149   </para>
 150 </listitem>
 151 <listitem>
 152   <screen>-S, --shutdown</screen>
 153   <para>
 154     Shutdown a running daemon and exit.  Other methods are sending a SIGHUP
 155     to the Cygserver PID or, if running as service, calling `net stop
 156     cygserver' or `cygrunsrv -E cygserver'.
 157   </para>
 158 </listitem>
 159 <listitem>
 160   <screen>-h, --help</screen>
 161   <para>
 162     Output usage information and exit.
 163   </para>
 164 </listitem>
 165 <listitem>
 166   <screen>-v, --version</screen>
 167   <para>
 168     Output version information and exit.
 169   </para>
 170 </listitem>
 171 </itemizedlist>
 172
 173 </sect2>
 174
 175 <sect2 id="start-cygserver"><title>How to start Cygserver</title>
 176
 177 <para>
 178   Before you run Cygserver for the first time, you should run the
 179   /usr/bin/cygserver-config script once.  It creates the default
 180   configuration file and, upon request, installs Cygserver as service.
 181   The script only performs a default install, with no further options
 182   given to Cygserver when running as service.  Due to the wide
 183   configurability by changing the configuration file, that's typically
 184   not necessary.
 185 </para>
 186 <para>
 187   You should always run Cygserver as a service under LocalSystem account.
 188   This is the way it is installed for you by the /usr/bin/cygserver-config
 189   script.
 190 </para>
 191
 192 </sect2>
 193
 194 <sect2 id="cygserver-config"><title>The Cygserver configuration file</title>
 195
 196 <para>
 197   Cygserver has many options, which allow you 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 only read
 200   once, at startup of Cygserver.  There's no option to re-read the file at
 201   runtime by, say, sending a signal to Cygserver.
 202 </para>
 203 <para>
 204   The configuration file determines how Cygserver operates.  There are
 205   options which set the number of threads running in parallel, options
 206   for setting how and what to log and options to set various maximum
 207   values for the IPC services.
 208 </para>
 209 <para>
 210   The default configuration file delivered with Cygserver is installed
 211   to /etc/defaults/etc.  The /usr/bin/cygserver-config script copies it to
 212   /etc, giving you the option to overwrite an already existing file or to
 213   leave it alone.  Therefore, the /etc file is safe to be changed by you,
 214   since it will not be overwritten by a later update installation.
 215 </para>
 216 <para>
 217   The default configuration file contains many comments which describe
 218   everything needed to understand the settings.  A comment at the start of the
 219   file describes the syntax rules for the file.  The default options are shown
 220   in the file but are commented out.
 221 </para>
 222 <para>
 223   It is generally a good idea to uncomment only options which you intend to
 224   change from the default values.  Since reading the options file on Cygserver
 225   startup doesn't take much time, it's also considered good practice to keep
 226   all other comments in the file.  This keeps you from searching for clues
 227   in other sources.
 228 </para>
 229
 230 </sect2>
 231
 232 </sect1>