* cygserver.sgml: New file.
* using.sgml: Include Cygserver docs.
This commit is contained in:
Corinna Vinschen
parent
989ea48440
commit
999ecb4cad
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 <file></screen>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
This option has no counterpart in the configuration file, for obvious
|
||||
reasons.
|
||||
<listitem>
|
||||
<screen>-c, --cleanup-threads <num></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 <num></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 <level></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>
|
||||
|
|
@ -14,6 +14,8 @@ DOCTOOL-INSERT-using-specialnames
|
|||
|
||||
DOCTOOL-INSERT-using-cygwinenv
|
||||
|
||||
DOCTOOL-INSERT-using-cygserver
|
||||
|
||||
DOCTOOL-INSERT-using-utils
|
||||
|
||||
DOCTOOL-INSERT-using-effectively
|
||||
|
|
|
|||
Loading…
Reference in New Issue