]>
Commit | Line | Data |
---|---|---|
4bd66285 CV |
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. | |
d4db08d7 CV |
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. | |
4bd66285 CV |
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 | ||
2d015bd6 CV |
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 | ||
4bd66285 CV |
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 | |
7131554a | 102 | connected to a tty, e. g. redirected to a file. |
4bd66285 CV |
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 | ||
7131554a CV |
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. | |
4bd66285 CV |
160 | |
161 | ||
4bd66285 CV |
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! |