"Fossies" - the Fresh Open Source Software Archive

Member "cygwin-snapshot-20210913-1/winsup/cygserver/README" (7 May 2021, 8136 Bytes) of package /windows/misc/cygwin-20210913-src-x86_64.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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   - Allows non-privileged users to store obfuscated passwords in the
   16     registry to be used for setuid(2) to create user tokens with network
   17     credentials.  This service is used by `passwd -R'.  Using the stored
   18     passwords in setuid(2) does not require running cygserver.  The
   19     registry storage is the same as Windows uses to store passwords for
   20     accounts running Windows services.
   21 
   22 
   23 Cygserver command line options:
   24 
   25   Options to Cygserver take the normal UNIX-style `-X' or `--longoption' form.
   26   Nearly all options have a counterpart in the configuration file (see below)
   27   so setting them on the command line isn't really necessary.  Command line
   28   options override settings from the Cygserver configuration file.
   29 
   30   The one-character options are prepended by a single dash, the long variants
   31   are prepended with two dashes.  Arguments to options are marked in angle
   32   brackets below.  These are not part of the actual syntax but are used only to
   33   denote the arguments.  Note that all arguments are required.  Cygserver
   34   has no options with optional arguments.
   35   
   36   The options recognized are:
   37 
   38   -f, --config-file <file>
   39   
   40     Use <file> as configuration file instead of the default configuration
   41     line.  The default configuration file is /etc/cygserver.conf, typically. 
   42     The --help and --version options will print the default configuration
   43     pathname.
   44 
   45     This option has no counterpart in the configuration file, for obvious
   46    reasons.
   47 
   48   -c, --cleanup-threads <num>  
   49   
   50     Number of threads started to perform cleanup tasks.  Default is 2.
   51     Configuration file option:  kern.srv.cleanup_threads
   52 
   53   -r, --request-threads <num>  
   54   
   55     Number of threads started to serve application requests.  Default is 10.
   56     The -c and -r options can be used to play with Cygserver's performance
   57     under heavy load conditions or on slow machines.
   58     Configuration file option:  kern.srv.request_threads
   59 
   60   -p, --process-cache <num>
   61 
   62     Number of processes which can connect concurrently to cygserver.
   63     Default is 62.  Each process connected to cygserver is a synchronization
   64     object which has to be maintained.  The data structure to maintain these
   65     processes is the so-called "process cache".  In theory, an arbitrary
   66     number of processes could connect to cygserver, but due to the need to
   67     synchronize, the higher the number of connected processes, the more
   68     synchronization overhead exists.  By using this option, you can set an
   69     upper limit to the synchronization effort.  If more than 62 processes
   70     try to connect to cygserver concurrently, two additional synchronization
   71     threads are necessary, and one for each further 62 concurrent
   72     processes.  So, useful values for the --process-cache option are 62, 124,
   73     186, 248, 310.  310 is the maximum value.
   74     Configuration file option:  kern.srv.process_cache_size
   75 
   76     NOTE:  The number of child processes of a single parent process is limited
   77     to 256.  So in case of taking advantage of a process cache size beyond 256,
   78     keep in mind that not all of these processes can be child processes of one
   79     single parent process.
   80 
   81   -d, --debug
   82   
   83     Log debug messages to stderr.  These will clutter your stderr output with
   84     a lot of information, typically only useful to developers.
   85 
   86   -e, --stderr
   87   
   88     Force logging to stderr.  This is the default if stderr is connected to
   89     a tty.  Otherwise, the default is logging to the system log.  By using
   90     the -e, -E, -y, -Y options (or the appropriate settings in the
   91     configuration file), you can explicitely set the logging output as you
   92     like, even to both, stderr and syslog.
   93     Configuration file option:  kern.log.stderr
   94 
   95   -E, --no-stderr
   96   
   97     Don't log to stderr.  Configuration file option:  kern.log.stderr
   98 
   99   -y, --syslog
  100   
  101     Force logging to the system log.  This is the default, if stderr is not
  102     connected to a tty, e. g. redirected to a file.
  103 
  104   -Y, --no-syslog
  105   
  106     Don't log to syslog.  Configuration file option:  kern.log.syslog
  107 
  108   -l, --log-level <level>
  109   
  110     Set the verbosity level of the logging output.  Valid values are between
  111     1 and 7.  The default level is 6, which is relatively chatty.  If you set
  112     it to 1, you will get only messages which are printed under severe conditions,
  113     which will result in stopping Cygserver itself.
  114     Configuration file option:  kern.log.level
  115 
  116   -m, --no-sharedmem
  117   
  118     Don't start XSI IPC Shared Memory support.  If you don't need XSI IPC
  119     Shared Memory support, you can switch it off here.
  120     Configuration file option:  kern.srv.sharedmem
  121 
  122   -q, --no-msgqueues
  123   
  124     Don't start XSI IPC Message Queues. 
  125     Configuration file option:  kern.srv.msgqueues
  126 
  127   -s, --no-semaphores
  128   
  129     Don't start XSI IPC Semaphores.
  130     Configuration file option:  kern.srv.semaphores
  131 
  132   -S, --shutdown
  133   
  134     Shutdown a running daemon and exit.  Other methods are sending a SIGHUP
  135     to the Cygserver PID or, if running as service under NT, calling
  136     `net stop cygserver' or `cygrunsrv -E cygserver'.
  137 
  138   -h, --help
  139   
  140     Output usage information and exit.
  141 
  142   -v, --version
  143   
  144     Output version information and exit.
  145 
  146 
  147 How to start Cygserver:
  148 
  149   Before you run Cygserver for the first time, you should run the
  150   /usr/bin/cygserver-config script once.  It creates the default
  151   configuration file and, upon request, installs Cygserver as service
  152   when running under NT.  The script only performs a default install,
  153   with no further options given to Cygserver when running as service.
  154   Due to the wide configurability by changing the configuration file,
  155   that's typically not necessary.
  156 
  157   It's best practice to run Cygserver as a service under LocalSystem
  158   account.  This is the way it is installed for you by the
  159   /usr/bin/cygserver-config script.
  160 
  161 
  162 The Cygserver configuration file:
  163 
  164   Cygserver has many options, which allow to customize the server
  165   to your needs.  Customization is accomplished by editing the configuration
  166   file, which is by default /etc/cygserver.conf.  This file is read only
  167   once on startup of Cygserver.  There's no option to re-read the file on
  168   runtime by, say, sending a signal to Cygserver.
  169 
  170   The configuration file determines how Cygserver operates.  There are
  171   options which set the number of threads running in parallel, options
  172   for setting how and what to log and options to set various maximum
  173   values for the IPC services.
  174 
  175   The default configuration file delivered with Cygserver is installed
  176   to /etc/defaults/etc.  The /usr/bin/cygserver-config script copies it to
  177   /etc, giving you the option to overwrite an already existing file or to
  178   leave it alone.  Therefore, the /etc file is safe to be changed by you,
  179   since it will not be overwritten by a later update installation.
  180 
  181   The default configuration file contains many comments which describe
  182   everything needed to understand the settings.  A comment at the start of the
  183   file describes the syntax rules for the file.  The default options are shown
  184   in the file but are commented out.
  185 
  186   It is generally a good idea to uncomment only options which you intend to
  187   change from the default values.  Since reading the options file on Cygserver
  188   startup doesn't take much time, it's also considered good practice to keep
  189   all other comments in the file.  This keeps you from searching for clues
  190   in other sources.
  191 
  192 
  193 If you have problems with Cygserver, or you have found a bug, or you
  194 think you have found a bug, or you don't understand configuration file
  195 options, the mailing list <cygwin@cygwin.com> is the right place to ask
  196 questions.
  197 
  198 Have fun!