* cygserver.sgml: New file.

	* using.sgml: Include Cygserver docs.

3 files changed, 280 insertions, 0 deletions

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  <corinna@vinschen.de>
+
+	* cygserver.sgml: New file.
+	* using.sgml: Include Cygserver docs.
+
 2004-03-26  Joshua Daniel Franklin  <joshuadfranklin@yahoo.com>
 	* 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 @@
+<sect1 id="using-cygserver"><title>Cygserver</title>
+
+<sect2 id="what-is-cygserver"><title>What is Cygserver?</title>
+
+<para>
+  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.
+</para>
+<para>
+  The implemented services so far are:
+</para>
+<itemizedlist Mark="bullet">
+  <listitem><para>Control slave tty/pty handle dispersal from tty owner to other
+    processes without compromising the owner processes' security.</para></listitem>
+  <listitem><para>XSI IPC Message Queues.</para></listitem>
+  <listitem><para>XSI IPC Semaphores.</para></listitem>
+  <listitem><para>XSI IPC Shared Memory.</para></listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="cygserver-command-line"><title>Cygserver command line options</title>
+
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+<para>
+  The recognized options are:
+</para>
+
+<itemizedlist spacing="compact">
+  <screen>-f, --config-file &lt;file&gt;</screen>
+  <para>  
+    Use &lt;file&gt; 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.
+  </para>
+<para>
+    This option has no counterpart in the configuration file, for obvious
+   reasons.
+<listitem>
+  <screen>-c, --cleanup-threads &lt;num&gt;</screen>
+  <para>  
+    Number of threads started to perform cleanup tasks.  Default is 2.
+    Configuration file option:  kern.srv.cleanup_threads
+  </para>
+</listitem>
+<listitem>
+  <screen>-r, --request-threads &lt;num&gt;</screen>
+  <para>  
+    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
+  </para>
+</listitem>
+<listitem>
+  <screen>-d, --debug</screen>
+  <para>  
+    Log debug messages to stderr.  These will clutter your stderr output with
+    a lot of information, typically only useful to developers.
+  </para>
+</listitem>
+<listitem>
+  <screen>-e, --stderr</screen>
+  <para>  
+    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
+  </para>
+</listitem>
+<listitem>
+  <screen>-E, --no-stderr</screen>
+  <para>  
+    Don't log to stderr.  Configuration file option:  kern.log.stderr
+  </para>
+</listitem>
+<listitem>
+  <screen>-y, --syslog</screen>
+  <para>  
+    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
+  </para>
+</listitem>
+<listitem>
+  <screen>-Y, --no-syslog</screen>
+  <para>  
+    Don't log to syslog.  Configuration file option:  kern.log.syslog
+  </para>
+</listitem>
+<listitem>
+  <screen>-l, --log-level &lt;level&gt;</screen>
+   <para> 
+    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
+  </para>
+</listitem>
+<listitem>
+  <screen>-m, --no-sharedmem</screen>
+  <para>  
+    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
+  </para>
+</listitem>
+<listitem>
+  <screen>-q, --no-msgqueues</screen>
+  <para>  
+    Don't start XSI IPC Message Queues. 
+    Configuration file option:  kern.srv.msgqueues
+  </para>
+</listitem>
+<listitem>
+  <screen>-s, --no-semaphores</screen>
+  <para>  
+    Don't start XSI IPC Semaphores.
+    Configuration file option:  kern.srv.semaphores
+  </para>
+</listitem>
+<listitem>
+  <screen>-S, --shutdown</screen>
+  <para>  
+    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'.
+  </para>
+</listitem>
+<listitem>
+  <screen>-h, --help</screen>
+  <para>  
+    Output usage information and exit.
+  </para>
+</listitem>
+<listitem>
+  <screen>-v, --version</screen>
+  <para>  
+    Output version information and exit.
+  </para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="start-cygserver"><title>How to start Cygserver</title>
+
+<para>
+  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.
+</para>
+<para>
+  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).
+</para>
+<para>
+  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.
+</para>
+
+</sect2>
+
+<sect2 id="use-cygserver"><title>How to use the Cygserver services</title>
+
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+<para>
+  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.:
+</para>
+<para>
+  <screen>
+    set CYGWIN=server
+  </screen>
+</para>
+<para>
+  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':
+</para>
+<para>
+  <screen>
+    cygrunsrv -I foo -p /usr/sbin/foo -e "CYGWIN=server"
+  </screen>
+</para>
+
+</sect2>
+
+<sect2 id="cygserver-config"><title>The Cygserver configuration file</title>
+
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+<para>
+  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.
+</para>
+
+</sect2>
+
+</sect1>
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