]>
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. | |
15 | ||
16 | ||
17 | Cygserver command line options: | |
18 | ||
19 | Options to Cygserver take the normal UNIX-style `-X' or `--longoption' form. | |
20 | Nearly all options have a counterpart in the configuration file (see below) | |
21 | so setting them on the command line isn't really necessary. Command line | |
22 | options override settings from the Cygserver configuration file. | |
23 | ||
24 | The one-character options are prepended by a single dash, the long variants | |
25 | are prepended with two dashes. Arguments to options are marked in angle | |
26 | brackets below. These are not part of the actual syntax but are used only to | |
27 | denote the arguments. Note that all arguments are required. Cygserver | |
28 | has no options with optional arguments. | |
29 | ||
30 | The options recognized are: | |
31 | ||
32 | -f, --config-file <file> | |
33 | ||
34 | Use <file> as configuration file instead of the default configuration | |
35 | line. The default configuration file is /etc/cygserver.conf, typically. | |
36 | The --help and --version options will print the default configuration | |
37 | pathname. | |
38 | ||
39 | This option has no counterpart in the configuration file, for obvious | |
40 | reasons. | |
41 | ||
42 | -c, --cleanup-threads <num> | |
43 | ||
44 | Number of threads started to perform cleanup tasks. Default is 2. | |
45 | Configuration file option: kern.srv.cleanup_threads | |
46 | ||
47 | -r, --request-threads <num> | |
48 | ||
49 | Number of threads started to serve application requests. Default is 10. | |
50 | The -c and -r options can be used to play with Cygserver's performance | |
51 | under heavy load conditions or on slow machines. | |
52 | Configuration file option: kern.srv.request_threads | |
53 | ||
54 | -d, --debug | |
55 | ||
56 | Log debug messages to stderr. These will clutter your stderr output with | |
57 | a lot of information, typically only useful to developers. | |
58 | ||
59 | -e, --stderr | |
60 | ||
61 | Force logging to stderr. This is the default if stderr is connected to | |
62 | a tty. Otherwise, the default is logging to the system log. By using | |
63 | the -e, -E, -y, -Y options (or the appropriate settings in the | |
64 | configuration file), you can explicitely set the logging output as you | |
65 | like, even to both, stderr and syslog. | |
66 | Configuration file option: kern.log.stderr | |
67 | ||
68 | -E, --no-stderr | |
69 | ||
70 | Don't log to stderr. Configuration file option: kern.log.stderr | |
71 | ||
72 | -y, --syslog | |
73 | ||
74 | Force logging to the system log. This is the default, if stderr is not | |
75 | connected to a tty, e. g. redirected to a file. Note, that on 9x/Me | |
76 | systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT. | |
77 | Configuration file option: kern.log.syslog | |
78 | ||
79 | -Y, --no-syslog | |
80 | ||
81 | Don't log to syslog. Configuration file option: kern.log.syslog | |
82 | ||
83 | -l, --log-level <level> | |
84 | ||
85 | Set the verbosity level of the logging output. Valid values are between | |
86 | 1 and 7. The default level is 6, which is relatively chatty. If you set | |
87 | it to 1, you will get only messages which are printed under severe conditions, | |
88 | which will result in stopping Cygserver itself. | |
89 | Configuration file option: kern.log.level | |
90 | ||
91 | -m, --no-sharedmem | |
92 | ||
93 | Don't start XSI IPC Shared Memory support. If you don't need XSI IPC | |
94 | Shared Memory support, you can switch it off here. | |
95 | Configuration file option: kern.srv.sharedmem | |
96 | ||
97 | -q, --no-msgqueues | |
98 | ||
99 | Don't start XSI IPC Message Queues. | |
100 | Configuration file option: kern.srv.msgqueues | |
101 | ||
102 | -s, --no-semaphores | |
103 | ||
104 | Don't start XSI IPC Semaphores. | |
105 | Configuration file option: kern.srv.semaphores | |
106 | ||
107 | -S, --shutdown | |
108 | ||
109 | Shutdown a running daemon and exit. Other methods are sending a SIGHUP | |
110 | to the Cygserver PID or, if running as service under NT, calling | |
111 | `net stop cygserver' or `cygrunsrv -E cygserver'. | |
112 | ||
113 | -h, --help | |
114 | ||
115 | Output usage information and exit. | |
116 | ||
117 | -v, --version | |
118 | ||
119 | Output version information and exit. | |
120 | ||
121 | ||
122 | How to start Cygserver: | |
123 | ||
124 | Before you run Cygserver for the first time, you should run the | |
125 | /usr/bin/cygserver-config script once. It creates the default | |
126 | configuration file and, upon request, installs Cygserver as service | |
127 | when running under NT. The script only performs a default install, | |
128 | with no further options given to Cygserver when running as service. | |
129 | Due to the wide configurability by changing the configuration file, | |
130 | that's typically not necessary. | |
131 | ||
132 | On Windows 9x/Me, just start Cygserver in any console window. It's | |
133 | advisable to redirect stderr to a file of choice (e. g. | |
134 | /var/log/cygserver.log) and to use the -e and -Y options or the | |
135 | set the appropriate settings in the configuration file (see below). | |
136 | ||
137 | On Windows NT/2000/XP or 2003, you should always run Cygserver as a | |
138 | service under LocalSystem account. This is the way it is installed | |
139 | for you by the /usr/bin/cygserver-config script. | |
140 | ||
141 | ||
142 | How to use the Cygserver services: | |
143 | ||
144 | The Cygserver services are used by Cygwin applications only if you | |
145 | set the environment variable CYGWIN to contain the string "server". | |
146 | You must do this before starting the application. | |
147 | ||
148 | Typically, you don't need any other option, so it's ok to set CYGWIN | |
149 | just to "server". It is not necessary to set the CYGWIN environment | |
150 | variable prior to starting the Cygserver process itself, but it won't | |
151 | hurt to do so. | |
152 | ||
153 | The easiest way is to set the environment variable CYGWIN to the values | |
154 | you want in the Windows system environment and to reboot the machine. | |
155 | This is advisable, since it allows you to set the variable once and | |
156 | then forget about it. It also ensures that services as well as desktop | |
157 | applications have the same setting. | |
158 | ||
159 | If you don't want that for whatever reason, you can set the | |
160 | variable in the /cygwin.bat file which is used in the net distribution, | |
161 | to start a Cygwin bash from the desktop. In that file, you can set | |
162 | the CYGWIN variable using Windows command line interpreter syntax, e. g.: | |
163 | ||
164 | set CYGWIN=server | |
165 | ||
166 | If you don't set CYGWIN in the system environment, but you're running | |
167 | other Cygwin services, these services need to get that CYGWIN value by | |
168 | setting the environment using the appropriate cygrunsrv option '-e' when | |
169 | installing the service. Example installing a service 'foo': | |
170 | ||
171 | cygrunsrv -I foo -p /usr/sbin/foo -e "CYGWIN=server" | |
172 | ||
173 | ||
174 | The Cygserver configuration file: | |
175 | ||
176 | Cygserver has many options, which allow to customize the server | |
177 | to your needs. Customization is accomplished by editing the configuration | |
178 | file, which is by default /etc/cygserver.conf. This file is read only | |
179 | once on startup of Cygserver. There's no option to re-read the file on | |
180 | runtime by, say, sending a signal to Cygserver. | |
181 | ||
182 | The configuration file determines how Cygserver operates. There are | |
183 | options which set the number of threads running in parallel, options | |
184 | for setting how and what to log and options to set various maximum | |
185 | values for the IPC services. | |
186 | ||
187 | The default configuration file delivered with Cygserver is installed | |
188 | to /etc/defaults/etc. The /usr/bin/cygserver-config script copies it to | |
189 | /etc, giving you the option to overwrite an already existing file or to | |
190 | leave it alone. Therefore, the /etc file is safe to be changed by you, | |
191 | since it will not be overwritten by a later update installation. | |
192 | ||
193 | The default configuration file contains many comments which describe | |
194 | everything needed to understand the settings. A comment at the start of the | |
195 | file describes the syntax rules for the file. The default options are shown | |
196 | in the file but are commented out. | |
197 | ||
198 | It is generally a good idea to uncomment only options which you intend to | |
199 | change from the default values. Since reading the options file on Cygserver | |
200 | startup doesn't take much time, it's also considered good practice to keep | |
201 | all other comments in the file. This keeps you from searching for clues | |
202 | in other sources. | |
203 | ||
204 | ||
205 | If you have problems with Cygserver, or you have found a bug, or you | |
206 | think you have found a bug, or you don't understand configuration file | |
207 | options, the mailing list <cygwin@cygwin.com> is the right place to ask | |
208 | questions. | |
209 | ||
210 | Have fun! |