Allow skipping kill_process_tree().
[nssm.git] / README.txt
1 NSSM: The Non-Sucking Service Manager\r
2 Version 2.24, 2014-08-31\r
3 \r
4 NSSM is a service helper program similar to srvany and cygrunsrv.  It can \r
5 start any application as an NT service and will restart the service if it \r
6 fails for any reason.\r
7 \r
8 NSSM also has a graphical service installer and remover.\r
9 \r
10 Full documentation can be found online at\r
11 \r
12                               http://nssm.cc/\r
13 \r
14 Since version 2.0, the GUI can be bypassed by entering all appropriate \r
15 options on the command line.\r
16 \r
17 Since version 2.1, NSSM can be compiled for x64 platforms.\r
18 Thanks Benjamin Mayrargue.\r
19 \r
20 Since version 2.2, NSSM can be configured to take different actions\r
21 based on the exit code of the managed application.\r
22 \r
23 Since version 2.3, NSSM logs to the Windows event log more elegantly.\r
24 \r
25 Since version 2.5, NSSM respects environment variables in its parameters.\r
26 \r
27 Since version 2.8, NSSM tries harder to shut down the managed application\r
28 gracefully and throttles restart attempts if the application doesn't run\r
29 for a minimum amount of time.\r
30 \r
31 Since version 2.11, NSSM respects srvany's AppEnvironment parameter.\r
32 \r
33 Since version 2.13, NSSM is translated into French.\r
34 Thanks François-Régis Tardy.\r
35 \r
36 Since version 2.15, NSSM is translated into Italian.\r
37 Thanks Riccardo Gusmeroli.\r
38 \r
39 Since version 2.17, NSSM can try to shut down console applications by\r
40 simulating a Control-C keypress.  If they have installed a handler routine\r
41 they can clean up and shut down gracefully on receipt of the event.\r
42 \r
43 Since version 2.17, NSSM can redirect the managed application's I/O streams\r
44 to an arbitrary path.\r
45 \r
46 Since version 2.18, NSSM can be configured to wait a user-specified amount\r
47 of time for the application to exit when shutting down.\r
48 \r
49 Since version 2.19, many more service options can be configured with the\r
50 GUI installer as well as via the registry.\r
51 \r
52 Since version 2.19, NSSM can add to the service's environment by setting\r
53 AppEnvironmentExtra in place of or in addition to the srvany-compatible\r
54 AppEnvironment.\r
55 \r
56 Since version 2.22, NSSM can set the managed application's process priority\r
57 and CPU affinity.\r
58 \r
59 Since version 2.22, NSSM can apply an unconditional delay before restarting\r
60 an application which has exited.\r
61 \r
62 Since version 2.22, NSSM can rotate existing output files when redirecting I/O.\r
63 \r
64 Since version 2.22, NSSM can set service display name, description, startup\r
65 type, log on details and dependencies.\r
66 \r
67 Since version 2.22, NSSM can manage existing services.\r
68 \r
69 \r
70 Usage\r
71 -----\r
72 In the usage notes below, arguments to the program may be written in angle\r
73 brackets and/or square brackets.  <string> means you must insert the\r
74 appropriate string and [<string>] means the string is optional.  See the\r
75 examples below...\r
76 \r
77 Note that everywhere <servicename> appears you may substitute the\r
78 service's display name.\r
79 \r
80 \r
81 Installation using the GUI\r
82 --------------------------\r
83 To install a service, run\r
84 \r
85     nssm install <servicename>\r
86 \r
87 You will be prompted to enter the full path to the application you wish \r
88 to run and any command line options to pass to that application.\r
89 \r
90 Use the system service manager (services.msc) to control advanced service \r
91 properties such as startup method and desktop interaction.  NSSM may \r
92 support these options at a later time...\r
93 \r
94 \r
95 Installation using the command line\r
96 -----------------------------------\r
97 To install a service, run\r
98 \r
99     nssm install <servicename> <application> [<options>]\r
100 \r
101 NSSM will then attempt to install a service which runs the named application \r
102 with the given options (if you specified any).\r
103 \r
104 Don't forget to enclose paths in "quotes" if they contain spaces!\r
105 \r
106 If you want to include quotes in the options you will need to """quote""" the\r
107 quotes.\r
108 \r
109 \r
110 Managing the service\r
111 --------------------\r
112 NSSM will launch the application listed in the registry when you send it a \r
113 start signal and will terminate it when you send a stop signal.  So far, so \r
114 much like srvany.  But NSSM is the Non-Sucking service manager and can take \r
115 action if/when the application dies.\r
116 \r
117 With no configuration from you, NSSM will try to restart itself if it notices\r
118 that the application died but you didn't send it a stop signal.  NSSM will\r
119 keep trying, pausing between each attempt, until the service is successfully\r
120 started or you send it a stop signal.\r
121 \r
122 NSSM will pause an increasingly longer time between subsequent restart attempts\r
123 if the service fails to start in a timely manner, up to a maximum of four\r
124 minutes.  This is so it does not consume an excessive amount of CPU time trying\r
125 to start a failed application over and over again.  If you identify the cause\r
126 of the failure and don't want to wait you can use the Windows service console\r
127 (where the service will be shown in Paused state) to send a continue signal to\r
128 NSSM and it will retry within a few seconds.\r
129 \r
130 By default, NSSM defines "a timely manner" to be within 1500 milliseconds.\r
131 You can change the threshold for the service by setting the number of\r
132 milliseconds as a REG_DWORD value in the registry at\r
133 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppThrottle.\r
134 \r
135 Alternatively, NSSM can pause for a configurable amount of time before\r
136 attempting to restart the application even if it successfully ran for the\r
137 amount of time specified by AppThrottle.  NSSM will consult the REG_DWORD value\r
138 at HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppRestartDelay\r
139 for the number of milliseconds to wait before attempting a restart.  If\r
140 AppRestartDelay is set and the application is determined to be subject to\r
141 throttling, NSSM will pause the service for whichever is longer of the\r
142 configured restart delay and the calculated throttle period.\r
143 \r
144 If AppRestartDelay is missing or invalid, only throttling will be applied.\r
145 \r
146 NSSM will look in the registry under\r
147 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppExit for\r
148 string (REG_EXPAND_SZ) values corresponding to the exit code of the application.\r
149 If the application exited with code 1, for instance, NSSM will look for a\r
150 string value under AppExit called "1" or, if it does not find it, will\r
151 fall back to the AppExit (Default) value.  You can find out the exit code\r
152 for the application by consulting the system event log.  NSSM will log the\r
153 exit code when the application exits.\r
154 \r
155 Based on the data found in the registry, NSSM will take one of three actions:\r
156 \r
157 If the value data is "Restart" NSSM will try to restart the application as\r
158 described above.  This is its default behaviour.\r
159 \r
160 If the value data is "Ignore" NSSM will not try to restart the application\r
161 but will continue running itself.  This emulates the (usually undesirable)\r
162 behaviour of srvany.  The Windows Services console would show the service\r
163 as still running even though the application has exited.\r
164 \r
165 If the value data is "Exit" NSSM will exit gracefully.  The Windows Services\r
166 console would show the service as stopped.  If you wish to provide\r
167 finer-grained control over service recovery you should use this code and\r
168 edit the failure action manually.  Please note that Windows versions prior\r
169 to Vista will not consider such an exit to be a failure.  On older versions\r
170 of Windows you should use "Suicide" instead.\r
171 \r
172 If the value data is "Suicide" NSSM will simulate a crash and exit without\r
173 informing the service manager.  This option should only be used for\r
174 pre-Vista systems where you wish to apply a service recovery action.  Note\r
175 that if the monitored application exits with code 0, NSSM will only honour a\r
176 request to suicide if you explicitly configure a registry key for exit code 0.\r
177 If only the default action is set to Suicide NSSM will instead exit gracefully.\r
178 \r
179 \r
180 Application priority\r
181 --------------------\r
182 NSSM can set the priority class of the managed application.  NSSM will look in\r
183 the registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\r
184 for the REG_DWORD entry AppPriority.  Valid values correspond to arguments to\r
185 SetPriorityClass().  If AppPriority() is missing or invalid the\r
186 application will be launched with normal priority.\r
187 \r
188 \r
189 Processor affinity\r
190 ------------------\r
191 NSSM can set the CPU affinity of the managed application.  NSSM will look in\r
192 the registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\r
193 for the REG_SZ entry AppAffinity.   It should specify a comma-separated listed\r
194 of zero-indexed processor IDs.  A range of processors may optionally be\r
195 specified with a dash.  No other characters are allowed in the string.\r
196 \r
197 For example, to specify the first; second; third and fifth CPUs, an appropriate\r
198 AppAffinity would be 0-2,4.\r
199 \r
200 If AppAffinity is missing or invalid, NSSM will not attempt to restrict the\r
201 application to specific CPUs.\r
202 \r
203 Note that the 64-bit version of NSSM can configure a maximum of 64 CPUs in this\r
204 way and that the 32-bit version can configure a maxium of 32 CPUs even when\r
205 running on 64-bit Windows.\r
206 \r
207 \r
208 Stopping the service\r
209 --------------------\r
210 When stopping a service NSSM will attempt several different methods of killing\r
211 the monitored application, each of which can be disabled if necessary.\r
212 \r
213 First NSSM will attempt to generate a Control-C event and send it to the\r
214 application's console.  Batch scripts or console applications may intercept\r
215 the event and shut themselves down gracefully.  GUI applications do not have\r
216 consoles and will not respond to this method.\r
217 \r
218 Secondly NSSM will enumerate all windows created by the application and send\r
219 them a WM_CLOSE message, requesting a graceful exit.\r
220 \r
221 Thirdly NSSM will enumerate all threads created by the application and send\r
222 them a WM_QUIT message, requesting a graceful exit.  Not all applications'\r
223 threads have message queues; those which do not will not respond to this\r
224 method.\r
225 \r
226 Finally NSSM will call TerminateProcess() to request that the operating\r
227 system forcibly terminate the application.  TerminateProcess() cannot be\r
228 trapped or ignored, so in most circumstances the application will be killed.\r
229 However, there is no guarantee that it will have a chance to perform any\r
230 tidyup operations before it exits.\r
231 \r
232 Any or all of the methods above may be disabled.  NSSM will look for the\r
233 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppStopMethodSkip\r
234 registry value which should be of type REG_DWORD set to a bit field describing\r
235 which methods should not be applied.\r
236 \r
237   If AppStopMethodSkip includes 1, Control-C events will not be generated.\r
238   If AppStopMethodSkip includes 2, WM_CLOSE messages will not be posted.\r
239   If AppStopMethodSkip includes 4, WM_QUIT messages will not be posted.\r
240   If AppStopMethodSkip includes 8, TerminateProcess() will not be called.\r
241 \r
242 If, for example, you knew that an application did not respond to Control-C\r
243 events and did not have a thread message queue, you could set AppStopMethodSkip\r
244 to 5 and NSSM would not attempt to use those methods to stop the application.\r
245 \r
246 Take great care when including 8 in the value of AppStopMethodSkip.  If NSSM\r
247 does not call TerminateProcess() it is possible that the application will not\r
248 exit when the service stops.\r
249 \r
250 By default NSSM will allow processes 1500ms to respond to each of the methods\r
251 described above before proceeding to the next one.  The timeout can be\r
252 configured on a per-method basis by creating REG_DWORD entries in the\r
253 registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
254 \r
255   AppStopMethodConsole\r
256   AppStopMethodWindow\r
257   AppStopMethodThreads\r
258 \r
259 Each value should be set to the number of milliseconds to wait.  Please note\r
260 that the timeout applies to each process in the application's process tree,\r
261 so the actual time to shutdown may be longer than the sum of all configured\r
262 timeouts if the application spawns multiple subprocesses.\r
263 \r
264 To skip applying the above stop methods to all processes in the application's\r
265 process tree, applying them only to the original application process, set the\r
266 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppKillProcessTree\r
267 registry value, which should be of type REG_DWORD, to 0.\r
268 \r
269 \r
270 Console window\r
271 --------------\r
272 By default, NSSM will create a console window so that applications which\r
273 are capable of reading user input can do so - subject to the service being\r
274 allowed to interact with the desktop.\r
275 \r
276 Creation of the console can be suppressed by setting the integer (REG_DWORD)\r
277 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppNoConsole\r
278 registry value to 1.\r
279 \r
280 \r
281 I/O redirection\r
282 ---------------\r
283 NSSM can redirect the managed application's I/O to any path capable of being\r
284 opened by CreateFile().  This enables, for example, capturing the log output\r
285 of an application which would otherwise only write to the console or accepting\r
286 input from a serial port.\r
287 \r
288 NSSM will look in the registry under\r
289 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for the keys\r
290 corresponding to arguments to CreateFile().  All are optional.  If no path is\r
291 given for a particular stream it will not be redirected.  If a path is given\r
292 but any of the other values are omitted they will be receive sensible defaults.\r
293 \r
294   AppStdin: Path to receive input.\r
295   AppStdout: Path to receive output.\r
296   AppStderr: Path to receive error output.\r
297 \r
298 Parameters for CreateFile() are providing with the "AppStdinShareMode",\r
299 "AppStdinCreationDisposition" and "AppStdinFlagsAndAttributes" values (and\r
300 analogously for stdout and stderr).\r
301 \r
302 In general, if you want the service to log its output, set AppStdout and\r
303 AppStderr to the same path, eg C:\Users\Public\service.log, and it should\r
304 work.  Remember, however, that the path must be accessible to the user\r
305 running the service.\r
306 \r
307 \r
308 File rotation\r
309 -------------\r
310 When using I/O redirection, NSSM can rotate existing output files prior to\r
311 opening stdout and/or stderr.  An existing file will be renamed with a\r
312 suffix based on the file's last write time, to millisecond precision.  For\r
313 example, the file nssm.log might be rotated to nssm-20131221T113939.457.log.\r
314 \r
315 NSSM will look in the registry under\r
316 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for REG_DWORD\r
317 entries which control how rotation happens.\r
318 \r
319 If AppRotateFiles is missing or set to 0, rotation is disabled.  Any non-zero\r
320 value enables rotation.\r
321 \r
322 If AppRotateSeconds is non-zero, a file will not be rotated if its last write\r
323 time is less than the given number of seconds in the past.\r
324 \r
325 If AppRotateBytes is non-zero, a file will not be rotated if it is smaller\r
326 than the given number of bytes.  64-bit file sizes can be handled by setting\r
327 a non-zero value of AppRotateBytesHigh.\r
328 \r
329 Rotation is independent of the CreateFile() parameters used to open the files.\r
330 They will be rotated regardless of whether NSSM would otherwise have appended\r
331 or replaced them.\r
332 \r
333 NSSM can also rotate files which hit the configured size threshold while the\r
334 service is running.  Additionally, you can trigger an on-demand rotation by\r
335 running the command\r
336 \r
337     nssm rotate <servicename>\r
338 \r
339 On-demand rotations will happen after the next line of data is read from\r
340 the managed application, regardless of the value of AppRotateBytes. Be aware\r
341 that if the application is not particularly verbose the rotation may not\r
342 happen for some time.\r
343 \r
344 To enable online and on-demand rotation, set AppRotateOnline to a non-zero\r
345 value.\r
346 \r
347 Note that online rotation requires NSSM to intercept the application's I/O\r
348 and create the output files on its behalf.  This is more complex and\r
349 error-prone than simply redirecting the I/O streams before launching the\r
350 application.  Therefore online rotation is not enabled by default.\r
351 \r
352 \r
353 Environment variables\r
354 ---------------------\r
355 NSSM can replace or append to the managed application's environment.  Two\r
356 multi-valued string (REG_MULTI_SZ) registry values are recognised under\r
357 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
358 \r
359 AppEnvironment defines a list of environment variables which will override\r
360 the service's environment.  AppEnvironmentExtra defines a list of\r
361 environment variables which will be added to the service's environment.\r
362 \r
363 Each entry in the list should be of the form KEY=VALUE.  It is possible to\r
364 omit the VALUE but the = symbol is mandatory.\r
365 \r
366 Environment variables listed in both AppEnvironment and AppEnvironmentExtra\r
367 are subject to normal expansion, so it is possible, for example, to update the\r
368 system path by setting "PATH=C:\bin;%PATH%" in AppEnvironmentExtra.  Variables\r
369 are expanded in the order in which they appear, so if you want to include the\r
370 value of one variable in another variable you should declare the dependency\r
371 first.\r
372 \r
373 Because variables defined in AppEnvironment override the existing\r
374 environment it is not possible to refer to any variables which were previously\r
375 defined.\r
376 \r
377 For example, the following AppEnvironment block:\r
378 \r
379       PATH=C:\Windows\System32;C:\Windows\r
380       PATH=C:\bin;%PATH%\r
381 \r
382 Would result in a PATH of "C:\bin;C:\Windows\System32;C:\Windows" as expected.\r
383 \r
384 Whereas the following AppEnvironment block:\r
385 \r
386       PATH=C:\bin;%PATH%\r
387 \r
388 Would result in a path containing only C:\bin and probably cause the\r
389 application to fail to start.\r
390 \r
391 Most people will want to use AppEnvironmentExtra exclusively.  srvany only\r
392 supports AppEnvironment.\r
393 \r
394 \r
395 Managing services using the GUI\r
396 -------------------------------\r
397 NSSM can edit the settings of existing services with the same GUI that is\r
398 used to install them.  Run\r
399 \r
400     nssm edit <servicename>\r
401 \r
402 to bring up the GUI.\r
403 \r
404 NSSM offers limited editing capabilities for services other than those which\r
405 run NSSM itself.  When NSSM is asked to edit a service which does not have\r
406 the App* registry settings described above, the GUI will allow editing only\r
407 system settings such as the service display name and description.\r
408 \r
409 \r
410 Managing services using the command line\r
411 ----------------------------------------\r
412 NSSM can retrieve or set individual service parameters from the command line.\r
413 In general the syntax is as follows, though see below for exceptions.\r
414 \r
415     nssm get <servicename> <parameter>\r
416 \r
417     nssm set <servicename> <parameter> <value>\r
418 \r
419 Parameters can also be reset to their default values.\r
420 \r
421     nssm reset <servicename> <parameter>\r
422 \r
423 The parameter names recognised by NSSM are the same as the registry entry\r
424 names described above, eg AppDirectory.\r
425 \r
426 NSSM offers limited editing capabilities for Services other than those which\r
427 run NSSM itself.  The parameters recognised are as follows:\r
428 \r
429   Description: Service description.\r
430   DisplayName: Service display name.\r
431   ImagePath: Path to the service executable.\r
432   ObjectName: User account which runs the service.\r
433   Name: Service key name.\r
434   Start: Service startup type.\r
435   Type: Service type.\r
436 \r
437 These correspond to the registry values under the service's key\r
438 HKLM\SYSTEM\CurrentControlSet\Services\<service>.\r
439 \r
440 \r
441 Note that NSSM will concatenate all arguments passed on the command line\r
442 with spaces to form the value to set.  Thus the following two invocations\r
443 would have the same effect.\r
444 \r
445     nssm set <servicename> Description "NSSM managed service"\r
446 \r
447     nssm set <servicename> Description NSSM managed service\r
448 \r
449 \r
450 Non-standard parameters\r
451 -----------------------\r
452 The AppEnvironment and AppEnvironmentExtra parameters recognise an\r
453 additional argument when querying the environment.  The following syntax\r
454 will print all extra environment variables configured for a service\r
455 \r
456     nssm get <servicename> AppEnvironmentExtra\r
457 \r
458 whereas the syntax below will print only the value of the CLASSPATH\r
459 variable if it is configured in the environment block, or the empty string\r
460 if it is not configured.\r
461 \r
462     nssm get <servicename> AppEnvironmentExtra CLASSPATH\r
463 \r
464 When setting an environment block, each variable should be specified as a\r
465 KEY=VALUE pair in separate command line arguments.  For example:\r
466 \r
467     nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes TEMP=C:\Temp\r
468 \r
469 \r
470 The AppExit parameter requires an additional argument specifying the exit\r
471 code to get or set.  The default action can be specified with the string\r
472 Default.\r
473 \r
474 For example, to get the default exit action for a service you should run\r
475 \r
476     nssm get <servicename> AppExit Default\r
477 \r
478 To get the exit action when the application exits with exit code 2, run\r
479 \r
480     nssm get <servicename> AppExit 2\r
481 \r
482 Note that if no explicit action is configured for a specified exit code,\r
483 NSSM will print the default exit action.\r
484 \r
485 To set configure the service to stop when the application exits with an\r
486 exit code of 2, run\r
487 \r
488     nssm set <servicename> AppExit 2 Exit\r
489 \r
490 \r
491 The AppPriority parameter is used to set the priority class of the\r
492 managed application.  Valid priorities are as follows:\r
493 \r
494   REALTIME_PRIORITY_CLASS\r
495   HIGH_PRIORITY_CLASS\r
496   ABOVE_NORMAL_PRIORITY_CLASS\r
497   NORMAL_PRIORITY_CLASS\r
498   BELOW_NORMAL_PRIORITY_CLASS\r
499   IDLE_PRIORITY_CLASS\r
500 \r
501 \r
502 The DependOnGroup and DependOnService parameters are used to query or set\r
503 the dependencies for the service.  When setting dependencies, each service\r
504 or service group (preceded with the + symbol) should be specified in\r
505 separate command line arguments.  For example:\r
506 \r
507     nssm set <servicename> DependOnService RpcSs LanmanWorkstation\r
508 \r
509 \r
510 The Name parameter can only be queried, not set.  It returns the service's\r
511 registry key name.  This may be useful to know if you take advantage of\r
512 the fact that you can substitute the service's display name anywhere where\r
513 the syntax calls for <servicename>.\r
514 \r
515 \r
516 The ObjectName parameter requires an additional argument only when setting\r
517 a username.  The additional argument is the password of the user.\r
518 \r
519 To retrieve the username, run\r
520 \r
521     nssm get <servicename> ObjectName\r
522 \r
523 To set the username and password, run\r
524 \r
525     nssm set <servicename> ObjectName <username> <password>\r
526 \r
527 Note that the rules of argument concatenation still apply.  The following\r
528 invocation is valid and will have the expected effect.\r
529 \r
530     nssm set <servicename> ObjectName <username> correct horse battery staple\r
531 \r
532 The following well-known usernames do not need a password.  The password\r
533 parameter can be omitted when using them:\r
534 \r
535   "LocalSystem" aka "System" aka "NT Authority\System"\r
536   "LocalService" aka "Local Service" aka "NT Authority\Local Service"\r
537   "NetworkService" aka "Network Service" aka "NT Authority\Network Service"\r
538 \r
539 \r
540 The Start parameter is used to query or set the startup type of the service.\r
541 Valid service startup types are as follows:\r
542 \r
543   SERVICE_AUTO_START: Automatic startup at boot.\r
544   SERVICE_DELAYED_START: Delayed startup at boot.\r
545   SERVICE_DEMAND_START: Manual service startup.\r
546   SERVICE_DISABLED: The service is disabled.\r
547 \r
548 Note that SERVICE_DELAYED_START is not supported on versions of Windows prior\r
549 to Vista.  NSSM will set the service to automatic startup if delayed start is\r
550 unavailable.\r
551 \r
552 \r
553 The Type parameter is used to query or set the service type.  NSSM recognises\r
554 all currently documented service types but will only allow setting one of two\r
555 types:\r
556 \r
557   SERVICE_WIN32_OWN_PROCESS: A standalone service.  This is the default.\r
558   SERVICE_INTERACTIVE_PROCESS: A service which can interact with the desktop.\r
559 \r
560 Note that a service may only be configured as interactive if it runs under\r
561 the LocalSystem account.  The safe way to configure an interactive service\r
562 is in two stages as follows.\r
563 \r
564     nssm reset <servicename> ObjectName\r
565     nssm set <servicename> Type SERVICE_INTERACTIVE_PROCESS\r
566 \r
567 \r
568 Controlling services using the command line\r
569 -------------------------------------------\r
570 NSSM offers rudimentary service control features.\r
571 \r
572     nssm start <servicename>\r
573 \r
574     nssm restart <servicename>\r
575 \r
576     nssm stop <servicename>\r
577 \r
578     nssm status <servicename>\r
579 \r
580 \r
581 Removing services using the GUI\r
582 -------------------------------\r
583 NSSM can also remove services.  Run\r
584 \r
585     nssm remove <servicename>\r
586 \r
587 to remove a service.  You will prompted for confirmation before the service \r
588 is removed.  Try not to remove essential system services...\r
589 \r
590 \r
591 Removing service using the command line\r
592 ---------------------------------------\r
593 To remove a service without confirmation from the GUI, run\r
594 \r
595     nssm remove <servicename> confirm\r
596 \r
597 Try not to remove essential system services...\r
598 \r
599 \r
600 Logging\r
601 -------\r
602 NSSM logs to the Windows event log.  It registers itself as an event log source\r
603 and uses unique event IDs for each type of message it logs.  New versions may\r
604 add event types but existing event IDs will never be changed.\r
605 \r
606 Because of the way NSSM registers itself you should be aware that you may not\r
607 be able to replace the NSSM binary if you have the event viewer open and that\r
608 running multiple instances of NSSM from different locations may be confusing if\r
609 they are not all the same version.\r
610 \r
611 \r
612 Example usage\r
613 -------------\r
614 To install an Unreal Tournament server:\r
615 \r
616     nssm install UT2004 c:\games\ut2004\system\ucc.exe server\r
617 \r
618 To run the server as the "games" user:\r
619 \r
620     nssm set UT2004 ObjectName games password\r
621 \r
622 To configure the server to log to a file:\r
623 \r
624     nssm set UT2004 AppStdout c:\games\ut2004\service.log\r
625 \r
626 To restrict the server to a single CPU:\r
627 \r
628     nssm set UT2004 AppAffinity 0\r
629 \r
630 To remove the server:\r
631 \r
632     nssm remove UT2004 confirm\r
633 \r
634 To find out the service name of a service with a display name:\r
635 \r
636     nssm get "Background Intelligent Transfer Service" Name\r
637 \r
638 \r
639 Building NSSM from source\r
640 -------------------------\r
641 NSSM is known to compile with Visual Studio 2008 and later.  Older Visual\r
642 Studio releases may or may not work if you install an appropriate SDK and\r
643 edit the nssm.vcproj and nssm.sln files to set a lower version number.\r
644 They are known not to work with default settings.\r
645 \r
646 NSSM will also compile with Visual Studio 2010 but the resulting executable\r
647 will not run on versions of Windows older than XP SP2.  If you require\r
648 compatiblity with older Windows releases you should change the Platform\r
649 Toolset to v90 in the General section of the project's Configuration\r
650 Properties.\r
651 \r
652 \r
653 Credits\r
654 -------\r
655 Thanks to Bernard Loh for finding a bug with service recovery.\r
656 Thanks to Benjamin Mayrargue (www.softlion.com) for adding 64-bit support.\r
657 Thanks to Joel Reingold for spotting a command line truncation bug.\r
658 Thanks to Arve Knudsen for spotting that child processes of the monitored\r
659 application could be left running on service shutdown, and that a missing\r
660 registry value for AppDirectory confused NSSM.\r
661 Thanks to Peter Wagemans and Laszlo Keresztfalvi for suggesting throttling\r
662 restarts.\r
663 Thanks to Eugene Lifshitz for finding an edge case in CreateProcess() and for\r
664 advising how to build messages.mc correctly in paths containing spaces.\r
665 Thanks to Rob Sharp for pointing out that NSSM did not respect the\r
666 AppEnvironment registry value used by srvany.\r
667 Thanks to Szymon Nowak for help with Windows 2000 compatibility.\r
668 Thanks to François-Régis Tardy and Gildas le Nadan for French translation.\r
669 Thanks to Emilio Frini for spotting that French was inadvertently set as\r
670 the default language when the user's display language was not translated.\r
671 Thanks to Riccardo Gusmeroli and Marco Certelli for Italian translation.\r
672 Thanks to Eric Cheldelin for the inspiration to generate a Control-C event\r
673 on shutdown.\r
674 Thanks to Brian Baxter for suggesting how to escape quotes from the command\r
675 prompt.\r
676 Thanks to Russ Holmann for suggesting that the shutdown timeout be configurable.\r
677 Thanks to Paul Spause for spotting a bug with default registry entries.\r
678 Thanks to BUGHUNTER for spotting more GUI bugs.\r
679 Thanks to Doug Watson for suggesting file rotation.\r
680 Thanks to Арслан Сайдуганов for suggesting setting process priority.\r
681 Thanks to Robert Middleton for suggestion and draft implementation of process\r
682 affinity support.\r
683 Thanks to Andrew RedzMax for suggesting an unconditional restart delay.\r
684 Thanks to Bryan Senseman for noticing that applications with redirected stdout\r
685 and/or stderr which attempt to read from stdin would fail.\r
686 Thanks to Czenda Czendov for help with Visual Studio 2013 and Server 2012R2.\r
687 Thanks to Alessandro Gherardi for reporting and draft fix of the bug whereby\r
688 the second restart of the application would have a corrupted environment.\r
689 Thanks to Hadrien Kohl for suggesting to disable the console window's menu.\r
690 Thanks to Allen Vailliencourt for noticing bugs with configuring the service to\r
691 run under a local user account.\r
692 Thanks to Sam Townsend for noticing a regression with TerminateProcess().\r
693 Thanks to Barrett Lewis for suggesting the option to skip terminating the\r
694 application's child processes.\r
695 \r
696 Licence\r
697 -------\r
698 NSSM is public domain.  You may unconditionally use it and/or its source code \r
699 for any purpose you wish.\r