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