| 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!
|
|---|
