source: Daodan/MSYS2/usr/share/doc/Msys/cygserver.README@ 1173

Last change on this file since 1173 was 1166, checked in by rossy, 3 years ago

Daodan: Replace MinGW build env with an up-to-date MSYS2 env

File size: 7.9 KB
RevLine 
[1166]1What 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
23Cygserver 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
147How 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
162The 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
193If you have problems with Cygserver, or you have found a bug, or you
194think you have found a bug, or you don't understand configuration file
195options, the mailing list <cygwin@cygwin.com> is the right place to ask
196questions.
197
198Have fun!
Note: See TracBrowser for help on using the repository browser.