cc63c5de66b7c2b8cd3c26b7dac092edf3052230
[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 Since version 2.25, NSSM can execute commands in response to service events.\r
70 \r
71 Since version 2.25, NSSM can list services it manages.\r
72 \r
73 Since version 2.25, NSSM can dump the configuration of services it manages.\r
74 \r
75 Since version 2.25, NSSM can show the processes managed by a service.\r
76 \r
77 \r
78 Usage\r
79 -----\r
80 In the usage notes below, arguments to the program may be written in angle\r
81 brackets and/or square brackets.  <string> means you must insert the\r
82 appropriate string and [<string>] means the string is optional.  See the\r
83 examples below...\r
84 \r
85 Note that everywhere <servicename> appears you may substitute the\r
86 service's display name.\r
87 \r
88 \r
89 Installation using the GUI\r
90 --------------------------\r
91 To install a service, run\r
92 \r
93     nssm install <servicename>\r
94 \r
95 You will be prompted to enter the full path to the application you wish \r
96 to run and any command line options to pass to that application.\r
97 \r
98 Use the system service manager (services.msc) to control advanced service \r
99 properties such as startup method and desktop interaction.  NSSM may \r
100 support these options at a later time...\r
101 \r
102 \r
103 Installation using the command line\r
104 -----------------------------------\r
105 To install a service, run\r
106 \r
107     nssm install <servicename> <application> [<options>]\r
108 \r
109 NSSM will then attempt to install a service which runs the named application \r
110 with the given options (if you specified any).\r
111 \r
112 Don't forget to enclose paths in "quotes" if they contain spaces!\r
113 \r
114 If you want to include quotes in the options you will need to """quote""" the\r
115 quotes.\r
116 \r
117 \r
118 Managing the service\r
119 --------------------\r
120 NSSM will launch the application listed in the registry when you send it a \r
121 start signal and will terminate it when you send a stop signal.  So far, so \r
122 much like srvany.  But NSSM is the Non-Sucking service manager and can take \r
123 action if/when the application dies.\r
124 \r
125 With no configuration from you, NSSM will try to restart itself if it notices\r
126 that the application died but you didn't send it a stop signal.  NSSM will\r
127 keep trying, pausing between each attempt, until the service is successfully\r
128 started or you send it a stop signal.\r
129 \r
130 NSSM will pause an increasingly longer time between subsequent restart attempts\r
131 if the service fails to start in a timely manner, up to a maximum of four\r
132 minutes.  This is so it does not consume an excessive amount of CPU time trying\r
133 to start a failed application over and over again.  If you identify the cause\r
134 of the failure and don't want to wait you can use the Windows service console\r
135 (where the service will be shown in Paused state) to send a continue signal to\r
136 NSSM and it will retry within a few seconds.\r
137 \r
138 By default, NSSM defines "a timely manner" to be within 1500 milliseconds.\r
139 You can change the threshold for the service by setting the number of\r
140 milliseconds as a REG_DWORD value in the registry at\r
141 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppThrottle.\r
142 \r
143 Alternatively, NSSM can pause for a configurable amount of time before\r
144 attempting to restart the application even if it successfully ran for the\r
145 amount of time specified by AppThrottle.  NSSM will consult the REG_DWORD value\r
146 at HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppRestartDelay\r
147 for the number of milliseconds to wait before attempting a restart.  If\r
148 AppRestartDelay is set and the application is determined to be subject to\r
149 throttling, NSSM will pause the service for whichever is longer of the\r
150 configured restart delay and the calculated throttle period.\r
151 \r
152 If AppRestartDelay is missing or invalid, only throttling will be applied.\r
153 \r
154 NSSM will look in the registry under\r
155 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppExit for\r
156 string (REG_EXPAND_SZ) values corresponding to the exit code of the application.\r
157 If the application exited with code 1, for instance, NSSM will look for a\r
158 string value under AppExit called "1" or, if it does not find it, will\r
159 fall back to the AppExit (Default) value.  You can find out the exit code\r
160 for the application by consulting the system event log.  NSSM will log the\r
161 exit code when the application exits.\r
162 \r
163 Based on the data found in the registry, NSSM will take one of three actions:\r
164 \r
165 If the value data is "Restart" NSSM will try to restart the application as\r
166 described above.  This is its default behaviour.\r
167 \r
168 If the value data is "Ignore" NSSM will not try to restart the application\r
169 but will continue running itself.  This emulates the (usually undesirable)\r
170 behaviour of srvany.  The Windows Services console would show the service\r
171 as still running even though the application has exited.\r
172 \r
173 If the value data is "Exit" NSSM will exit gracefully.  The Windows Services\r
174 console would show the service as stopped.  If you wish to provide\r
175 finer-grained control over service recovery you should use this code and\r
176 edit the failure action manually.  Please note that Windows versions prior\r
177 to Vista will not consider such an exit to be a failure.  On older versions\r
178 of Windows you should use "Suicide" instead.\r
179 \r
180 If the value data is "Suicide" NSSM will simulate a crash and exit without\r
181 informing the service manager.  This option should only be used for\r
182 pre-Vista systems where you wish to apply a service recovery action.  Note\r
183 that if the monitored application exits with code 0, NSSM will only honour a\r
184 request to suicide if you explicitly configure a registry key for exit code 0.\r
185 If only the default action is set to Suicide NSSM will instead exit gracefully.\r
186 \r
187 \r
188 Application priority\r
189 --------------------\r
190 NSSM can set the priority class of the managed application.  NSSM will look in\r
191 the registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\r
192 for the REG_DWORD entry AppPriority.  Valid values correspond to arguments to\r
193 SetPriorityClass().  If AppPriority() is missing or invalid the\r
194 application will be launched with normal priority.\r
195 \r
196 \r
197 Processor affinity\r
198 ------------------\r
199 NSSM can set the CPU affinity of the managed application.  NSSM will look in\r
200 the registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\r
201 for the REG_SZ entry AppAffinity.   It should specify a comma-separated listed\r
202 of zero-indexed processor IDs.  A range of processors may optionally be\r
203 specified with a dash.  No other characters are allowed in the string.\r
204 \r
205 For example, to specify the first; second; third and fifth CPUs, an appropriate\r
206 AppAffinity would be 0-2,4.\r
207 \r
208 If AppAffinity is missing or invalid, NSSM will not attempt to restrict the\r
209 application to specific CPUs.\r
210 \r
211 Note that the 64-bit version of NSSM can configure a maximum of 64 CPUs in this\r
212 way and that the 32-bit version can configure a maxium of 32 CPUs even when\r
213 running on 64-bit Windows.\r
214 \r
215 \r
216 Stopping the service\r
217 --------------------\r
218 When stopping a service NSSM will attempt several different methods of killing\r
219 the monitored application, each of which can be disabled if necessary.\r
220 \r
221 First NSSM will attempt to generate a Control-C event and send it to the\r
222 application's console.  Batch scripts or console applications may intercept\r
223 the event and shut themselves down gracefully.  GUI applications do not have\r
224 consoles and will not respond to this method.\r
225 \r
226 Secondly NSSM will enumerate all windows created by the application and send\r
227 them a WM_CLOSE message, requesting a graceful exit.\r
228 \r
229 Thirdly NSSM will enumerate all threads created by the application and send\r
230 them a WM_QUIT message, requesting a graceful exit.  Not all applications'\r
231 threads have message queues; those which do not will not respond to this\r
232 method.\r
233 \r
234 Finally NSSM will call TerminateProcess() to request that the operating\r
235 system forcibly terminate the application.  TerminateProcess() cannot be\r
236 trapped or ignored, so in most circumstances the application will be killed.\r
237 However, there is no guarantee that it will have a chance to perform any\r
238 tidyup operations before it exits.\r
239 \r
240 Any or all of the methods above may be disabled.  NSSM will look for the\r
241 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppStopMethodSkip\r
242 registry value which should be of type REG_DWORD set to a bit field describing\r
243 which methods should not be applied.\r
244 \r
245   If AppStopMethodSkip includes 1, Control-C events will not be generated.\r
246   If AppStopMethodSkip includes 2, WM_CLOSE messages will not be posted.\r
247   If AppStopMethodSkip includes 4, WM_QUIT messages will not be posted.\r
248   If AppStopMethodSkip includes 8, TerminateProcess() will not be called.\r
249 \r
250 If, for example, you knew that an application did not respond to Control-C\r
251 events and did not have a thread message queue, you could set AppStopMethodSkip\r
252 to 5 and NSSM would not attempt to use those methods to stop the application.\r
253 \r
254 Take great care when including 8 in the value of AppStopMethodSkip.  If NSSM\r
255 does not call TerminateProcess() it is possible that the application will not\r
256 exit when the service stops.\r
257 \r
258 By default NSSM will allow processes 1500ms to respond to each of the methods\r
259 described above before proceeding to the next one.  The timeout can be\r
260 configured on a per-method basis by creating REG_DWORD entries in the\r
261 registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
262 \r
263   AppStopMethodConsole\r
264   AppStopMethodWindow\r
265   AppStopMethodThreads\r
266 \r
267 Each value should be set to the number of milliseconds to wait.  Please note\r
268 that the timeout applies to each process in the application's process tree,\r
269 so the actual time to shutdown may be longer than the sum of all configured\r
270 timeouts if the application spawns multiple subprocesses.\r
271 \r
272 To skip applying the above stop methods to all processes in the application's\r
273 process tree, applying them only to the original application process, set the\r
274 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppKillProcessTree\r
275 registry value, which should be of type REG_DWORD, to 0.\r
276 \r
277 \r
278 Console window\r
279 --------------\r
280 By default, NSSM will create a console window so that applications which\r
281 are capable of reading user input can do so - subject to the service being\r
282 allowed to interact with the desktop.\r
283 \r
284 Creation of the console can be suppressed by setting the integer (REG_DWORD)\r
285 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppNoConsole\r
286 registry value to 1.\r
287 \r
288 \r
289 I/O redirection\r
290 ---------------\r
291 NSSM can redirect the managed application's I/O to any path capable of being\r
292 opened by CreateFile().  This enables, for example, capturing the log output\r
293 of an application which would otherwise only write to the console or accepting\r
294 input from a serial port.\r
295 \r
296 NSSM will look in the registry under\r
297 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for the keys\r
298 corresponding to arguments to CreateFile().  All are optional.  If no path is\r
299 given for a particular stream it will not be redirected.  If a path is given\r
300 but any of the other values are omitted they will be receive sensible defaults.\r
301 \r
302   AppStdin: Path to receive input.\r
303   AppStdout: Path to receive output.\r
304   AppStderr: Path to receive error output.\r
305 \r
306 Parameters for CreateFile() are providing with the "AppStdinShareMode",\r
307 "AppStdinCreationDisposition" and "AppStdinFlagsAndAttributes" values (and\r
308 analogously for stdout and stderr).\r
309 \r
310 In general, if you want the service to log its output, set AppStdout and\r
311 AppStderr to the same path, eg C:\Users\Public\service.log, and it should\r
312 work.  Remember, however, that the path must be accessible to the user\r
313 running the service.\r
314 \r
315 \r
316 File rotation\r
317 -------------\r
318 When using I/O redirection, NSSM can rotate existing output files prior to\r
319 opening stdout and/or stderr.  An existing file will be renamed with a\r
320 suffix based on the file's last write time, to millisecond precision.  For\r
321 example, the file nssm.log might be rotated to nssm-20131221T113939.457.log.\r
322 \r
323 NSSM will look in the registry under\r
324 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for REG_DWORD\r
325 entries which control how rotation happens.\r
326 \r
327 If AppRotateFiles is missing or set to 0, rotation is disabled.  Any non-zero\r
328 value enables rotation.\r
329 \r
330 If AppRotateSeconds is non-zero, a file will not be rotated if its last write\r
331 time is less than the given number of seconds in the past.\r
332 \r
333 If AppRotateBytes is non-zero, a file will not be rotated if it is smaller\r
334 than the given number of bytes.  64-bit file sizes can be handled by setting\r
335 a non-zero value of AppRotateBytesHigh.\r
336 \r
337 If AppRotateDelay is non-zero, NSSM will pause for the given number of\r
338 milliseconds after rotation.\r
339 \r
340 If AppStdoutCopyAndTruncate or AppStderrCopyAndTruncate are non-zero, the\r
341 stdout (or stderr respectively) file will be rotated by first taking a copy\r
342 of the file then truncating the original file to zero size.  This allows\r
343 NSSM to rotate files which are held open by other processes, preventing the\r
344 usual MoveFile() from succeeding.  Note that the copy process may take some\r
345 time if the file is large, and will temporarily consume twice as much disk\r
346 space as the original file.  Note also that applications reading the log file\r
347 may not notice that the file size changed.  Using this option in conjunction\r
348 with AppRotateDelay may help in that case.\r
349 \r
350 Rotation is independent of the CreateFile() parameters used to open the files.\r
351 They will be rotated regardless of whether NSSM would otherwise have appended\r
352 or replaced them.\r
353 \r
354 NSSM can also rotate files which hit the configured size threshold while the\r
355 service is running.  Additionally, you can trigger an on-demand rotation by\r
356 running the command\r
357 \r
358     nssm rotate <servicename>\r
359 \r
360 On-demand rotations will happen after the next line of data is read from\r
361 the managed application, regardless of the value of AppRotateBytes. Be aware\r
362 that if the application is not particularly verbose the rotation may not\r
363 happen for some time.\r
364 \r
365 To enable online and on-demand rotation, set AppRotateOnline to a non-zero\r
366 value.\r
367 \r
368 Note that online rotation requires NSSM to intercept the application's I/O\r
369 and create the output files on its behalf.  This is more complex and\r
370 error-prone than simply redirecting the I/O streams before launching the\r
371 application.  Therefore online rotation is not enabled by default.\r
372 \r
373 \r
374 Environment variables\r
375 ---------------------\r
376 NSSM can replace or append to the managed application's environment.  Two\r
377 multi-valued string (REG_MULTI_SZ) registry values are recognised under\r
378 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
379 \r
380 AppEnvironment defines a list of environment variables which will override\r
381 the service's environment.  AppEnvironmentExtra defines a list of\r
382 environment variables which will be added to the service's environment.\r
383 \r
384 Each entry in the list should be of the form KEY=VALUE.  It is possible to\r
385 omit the VALUE but the = symbol is mandatory.\r
386 \r
387 Environment variables listed in both AppEnvironment and AppEnvironmentExtra\r
388 are subject to normal expansion, so it is possible, for example, to update the\r
389 system path by setting "PATH=C:\bin;%PATH%" in AppEnvironmentExtra.  Variables\r
390 are expanded in the order in which they appear, so if you want to include the\r
391 value of one variable in another variable you should declare the dependency\r
392 first.\r
393 \r
394 Because variables defined in AppEnvironment override the existing\r
395 environment it is not possible to refer to any variables which were previously\r
396 defined.\r
397 \r
398 For example, the following AppEnvironment block:\r
399 \r
400       PATH=C:\Windows\System32;C:\Windows\r
401       PATH=C:\bin;%PATH%\r
402 \r
403 Would result in a PATH of "C:\bin;C:\Windows\System32;C:\Windows" as expected.\r
404 \r
405 Whereas the following AppEnvironment block:\r
406 \r
407       PATH=C:\bin;%PATH%\r
408 \r
409 Would result in a path containing only C:\bin and probably cause the\r
410 application to fail to start.\r
411 \r
412 Most people will want to use AppEnvironmentExtra exclusively.  srvany only\r
413 supports AppEnvironment.\r
414 \r
415 As of version 2.25, NSSM parses AppEnvironment and AppEnvironmentExtra\r
416 itself, before reading any other registry values.  As a result it is now\r
417 possible to refer to custom environment variables in Application,\r
418 AppDirectory and other parameters.\r
419 \r
420 \r
421 Merged service environment\r
422 --------------------------\r
423 All Windows services can be passed additional environment variables by\r
424 creating a multi-valued string (REG_MULTI_SZ) registry value named\r
425 HLKM\SYSTEM\CurrentControlSet\Services\<service>\Environment.\r
426 \r
427 The contents of this environment block will be merged into the system\r
428 environment before the service starts.\r
429 \r
430 Note, however, that the merged environment will be sorted alphabetically\r
431 before being processed.  This means that in practice you cannot set,\r
432 for example, DIR=%PROGRAMFILES% in the Environment block because the\r
433 environment passed to the service will not have defined %PROGRAMFILES%\r
434 by the time it comes to define %DIR%.  Environment variables defined in\r
435 AppEnvironmentExtra do not suffer from this limitation.\r
436 \r
437 As of version 2.25, NSSM can get and set the Environment block using\r
438 commands similar to:\r
439 \r
440     nssm get <servicename> Environment\r
441 \r
442 It is worth reiterating that the Environment block is available to all\r
443 Windows services, not just NSSM services.\r
444 \r
445 \r
446 Service startup environment\r
447 ---------------------------\r
448 The environment NSSM passes to the application depends on how various\r
449 registry values are configured.  The following flow describes how the\r
450 environment is modified.\r
451 \r
452 By default:\r
453     The service inherits the system environment.\r
454 \r
455 If <service>\Environment is defined:\r
456     The contents of Environment are MERGED into the environment.\r
457 \r
458 If <service>\Parameters\AppEnvironment is defined:\r
459     The service inherits the environment specified in AppEnvironment.\r
460 \r
461 If <service>\Parameters\AppEnvironmentExtra is defined:\r
462     The contents of AppEnvironmentExtra are APPENDED to the environment.\r
463 \r
464 Note that AppEnvironment overrides the system environment and the\r
465 merged Environment block.  Note also that AppEnvironmentExtra is\r
466 guaranteed to be appended to the startup environment if it is defined.\r
467 \r
468 \r
469 Event hooks\r
470 -----------\r
471 NSSM can run user-configurable commands in response to application events.\r
472 These commands are referred to as "hooks" below.\r
473 \r
474 All hooks are optional.  Any hooks which are run will be launched with the\r
475 environment configured for the service.  NSSM will place additional\r
476 variables into the environment which hooks can query to learn how and why\r
477 they were called.\r
478 \r
479 Hooks are categorised by Event and Action.  Some hooks are run synchronously\r
480 and some are run asynchronously.  Hooks prefixed with an *asterisk are run\r
481 synchronously.  NSSM will wait for these hooks to complete before continuing\r
482 its work.  Note, however, that ALL hooks are subject to a deadline after which\r
483 they will be killed, regardless of whether they are run asynchronously\r
484 or not.\r
485 \r
486   Event: Start - Triggered when the service is requested to start.\r
487    *Action: Pre - Called before NSSM attempts to launch the application.\r
488     Action: Post - Called after the application successfully starts.\r
489 \r
490   Event: Stop - Triggered when the service is requested to stop.\r
491    *Action: Pre - Called before NSSM attempts to kill the application.\r
492 \r
493   Event: Exit - Triggered when the application exits.\r
494    *Action: Post - Called after NSSM has cleaned up the application.\r
495 \r
496   Event: Rotate - Triggered when online log rotation is requested.\r
497    *Action: Pre - Called before NSSM rotates logs.\r
498     Action: Post - Called after NSSM rotates logs.\r
499 \r
500   Event: Power\r
501     Action: Change - Called when the system power status has changed.\r
502     Action: Resume - Called when the system has resumed from standby.\r
503 \r
504 Note that there is no Stop/Post hook.  This is because Exit/Post is called\r
505 when the application exits, regardless of whether it did so in response to\r
506 a service shutdown request.  Stop/Pre is only called before a graceful\r
507 shutdown attempt.\r
508 \r
509 NSSM sets the environment variable NSSM_HOOK_VERSION to a positive number.\r
510 Hooks can check the value of the number to determine which other environment\r
511 variables are available to them.\r
512 \r
513 If NSSM_HOOK_VERSION is 1 or greater, these variables are provided:\r
514 \r
515   NSSM_EXE - Path to NSSM itself.\r
516   NSSM_CONFIGURATION - Build information for the NSSM executable,\r
517     eg 64-bit debug.\r
518   NSSM_VERSION - Version of the NSSM executable.\r
519   NSSM_BUILD_DATE - Build date of NSSM.\r
520   NSSM_PID - Process ID of the running NSSM executable.\r
521   NSSM_DEADLINE - Deadline number of milliseconds after which NSSM will\r
522     kill the hook if it is still running.\r
523   NSSM_SERVICE_NAME - Name of the service controlled by NSSM.\r
524   NSSM_SERVICE_DISPLAYNAME - Display name of the service.\r
525   NSSM_COMMAND_LINE - Command line used to launch the application.\r
526   NSSM_APPLICATION_PID - Process ID of the primary application process.\r
527     May be blank if the process is not running.\r
528   NSSM_EVENT - Event class triggering the hook.\r
529   NSSM_ACTION - Event action triggering the hook.\r
530   NSSM_TRIGGER - Service control triggering the hook.  May be blank if\r
531     the hook was not triggered by a service control, eg Exit/Post.\r
532   NSSM_LAST_CONTROL - Last service control handled by NSSM.\r
533   NSSM_START_REQUESTED_COUNT - Number of times the application was\r
534     requested to start.\r
535   NSSM_START_COUNT - Number of times the application successfully started.\r
536   NSSM_THROTTLE_COUNT - Number of times the application ran for less than\r
537     the throttle period.  Reset to zero on successful start or when the\r
538     service is explicitly unpaused.\r
539   NSSM_EXIT_COUNT - Number of times the application exited.\r
540   NSSM_EXITCODE - Exit code of the application.  May be blank if the\r
541     application is still running or has not started yet.\r
542   NSSM_RUNTIME - Number of milliseconds for which the NSSM executable has\r
543     been running.\r
544   NSSM_APPLICATION_RUNTIME - Number of milliseconds for which the\r
545     application has been running since it was last started.  May be blank\r
546     if the application has not been started yet.\r
547 \r
548 Future versions of NSSM may provide more environment variables, in which\r
549 case NSSM_HOOK_VERSION will be set to a higher number.\r
550 \r
551 Hooks are configured by creating string (REG_EXPAND_SZ) values in the\r
552 registry named after the hook action and placed under\r
553 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppEvents\<event>.\r
554 \r
555 For example the service could be configured to restart when the system\r
556 resumes from standby by setting AppEvents\Power\Resume to:\r
557 \r
558     %NSSM_EXE% restart %NSSM_SERVICE_NAME%\r
559 \r
560 Note that NSSM will abort the startup of the application if a Start/Pre hook\r
561 returns exit code of 99.\r
562 \r
563 A service will normally run hooks in the following order:\r
564 \r
565   Start/Pre\r
566   Start/Post\r
567   Stop/Pre\r
568   Exit/Post\r
569 \r
570 If the application crashes and is restarted by NSSM, the order might be:\r
571 \r
572   Start/Pre\r
573   Start/Post\r
574   Exit/Post\r
575   Start/Pre\r
576   Start/Post\r
577   Stop/Pre\r
578   Exit/Post\r
579 \r
580 \r
581 If NSSM is redirecting stdout or stderr it can be configured to redirect\r
582 the output of any hooks it runs.  Set AppRedirectHooks to 1 to enable\r
583 that functionality.  A hook can of course redirect its own I/O independently\r
584 of NSSM.\r
585 \r
586 \r
587 Managing services using the GUI\r
588 -------------------------------\r
589 NSSM can edit the settings of existing services with the same GUI that is\r
590 used to install them.  Run\r
591 \r
592     nssm edit <servicename>\r
593 \r
594 to bring up the GUI.\r
595 \r
596 NSSM offers limited editing capabilities for services other than those which\r
597 run NSSM itself.  When NSSM is asked to edit a service which does not have\r
598 the App* registry settings described above, the GUI will allow editing only\r
599 system settings such as the service display name and description.\r
600 \r
601 \r
602 Managing services using the command line\r
603 ----------------------------------------\r
604 NSSM can retrieve or set individual service parameters from the command line.\r
605 In general the syntax is as follows, though see below for exceptions.\r
606 \r
607     nssm get <servicename> <parameter>\r
608 \r
609     nssm set <servicename> <parameter> <value>\r
610 \r
611 Parameters can also be reset to their default values.\r
612 \r
613     nssm reset <servicename> <parameter>\r
614 \r
615 The parameter names recognised by NSSM are the same as the registry entry\r
616 names described above, eg AppDirectory.\r
617 \r
618 NSSM offers limited editing capabilities for Services other than those which\r
619 run NSSM itself.  The parameters recognised are as follows:\r
620 \r
621   Description: Service description.\r
622   DisplayName: Service display name.\r
623   Environment: Service merged environment.\r
624   ImagePath: Path to the service executable.\r
625   ObjectName: User account which runs the service.\r
626   Name: Service key name.\r
627   Start: Service startup type.\r
628   Type: Service type.\r
629 \r
630 These correspond to the registry values under the service's key\r
631 HKLM\SYSTEM\CurrentControlSet\Services\<service>.\r
632 \r
633 \r
634 Note that NSSM will concatenate all arguments passed on the command line\r
635 with spaces to form the value to set.  Thus the following two invocations\r
636 would have the same effect.\r
637 \r
638     nssm set <servicename> Description "NSSM managed service"\r
639 \r
640     nssm set <servicename> Description NSSM managed service\r
641 \r
642 \r
643 Non-standard parameters\r
644 -----------------------\r
645 The AppEnvironment, AppEnvironmentExtra and Environment parameters\r
646 recognise an additional argument when querying the environment.  The\r
647 following syntax will print all extra environment variables configured\r
648 for a service\r
649 \r
650     nssm get <servicename> AppEnvironmentExtra\r
651 \r
652 whereas the syntax below will print only the value of the CLASSPATH\r
653 variable if it is configured in the environment block, or the empty string\r
654 if it is not configured.\r
655 \r
656     nssm get <servicename> AppEnvironmentExtra CLASSPATH\r
657 \r
658 When setting an environment block, each variable should be specified as a\r
659 KEY=VALUE pair in separate command line arguments.  For example:\r
660 \r
661     nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes TEMP=C:\Temp\r
662 \r
663 Alternatively the KEY can be prefixed with a + or - symbol to respectively\r
664 add or remove a pair from the block.\r
665 \r
666 The following two lines set CLASSPATH and TEMP:\r
667 \r
668     nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes\r
669     nssm set <servicename> AppEnvironment +TEMP=C:\Temp\r
670 \r
671 If the key is already present, specifying +KEY will override the value\r
672 while preserving the order of keys:\r
673 \r
674     nssm set <servicename> AppEnvironment +CLASSPATH=C:\NewClasses\r
675 \r
676 The following syntax removes a single variable from the block while\r
677 leaving any other variables in place.\r
678 \r
679     nssm set <servicename> AppEnvironment -TEMP\r
680 \r
681 Specifying -KEY=VALUE will remove the variable only if the existing\r
682 value matches.\r
683 \r
684 The following syntax would not remove TEMP=C:\Temp\r
685 \r
686     nssm set <servicename> AppEnvironment -TEMP=C:\Work\Temporary\r
687 \r
688 The + and - symbols are valid characters in environment variables.\r
689 The syntax :KEY=VALUE is equivalent to KEY=VALUE and can be used to\r
690 set variables which start with +/- or to explicitly reset the block in\r
691 a script:\r
692 \r
693     nssm set <servicename> AppEnvironment :CLASSPATH=C:\Classes\r
694     nssm set <servicename> AppEnvironment +TEMP=C:\Temp\r
695 \r
696 \r
697 The AppExit parameter requires an additional argument specifying the exit\r
698 code to get or set.  The default action can be specified with the string\r
699 Default.\r
700 \r
701 For example, to get the default exit action for a service you should run\r
702 \r
703     nssm get <servicename> AppExit Default\r
704 \r
705 To get the exit action when the application exits with exit code 2, run\r
706 \r
707     nssm get <servicename> AppExit 2\r
708 \r
709 Note that if no explicit action is configured for a specified exit code,\r
710 NSSM will print the default exit action.\r
711 \r
712 To set configure the service to stop when the application exits with an\r
713 exit code of 2, run\r
714 \r
715     nssm set <servicename> AppExit 2 Exit\r
716 \r
717 \r
718 The AppPriority parameter is used to set the priority class of the\r
719 managed application.  Valid priorities are as follows:\r
720 \r
721   REALTIME_PRIORITY_CLASS\r
722   HIGH_PRIORITY_CLASS\r
723   ABOVE_NORMAL_PRIORITY_CLASS\r
724   NORMAL_PRIORITY_CLASS\r
725   BELOW_NORMAL_PRIORITY_CLASS\r
726   IDLE_PRIORITY_CLASS\r
727 \r
728 \r
729 The DependOnGroup and DependOnService parameters are used to query or set\r
730 the dependencies for the service.  When setting dependencies, each service\r
731 or service group (preceded with the + symbol) should be specified in\r
732 separate command line arguments.  For example:\r
733 \r
734     nssm set <servicename> DependOnService RpcSs LanmanWorkstation\r
735 \r
736 Alternatively the dependency name can be prefixed with a + or - symbol to\r
737 respectively add or remove a dependency.\r
738 \r
739 The following two lines set dependencies on RpcSs and LanmanWorkstation:\r
740 \r
741     nssm set <servicename> DependOnService RpcSs\r
742     nssm set <servicename> DependOnService +LanmanWorkstation\r
743 \r
744 The follwing syntax removes the dependency on RpcSs:\r
745 \r
746     nssm set <servicename> DependOnService -RpcSs\r
747 \r
748 Service groups should, strictly speaking, be prefixed with the + symbol.\r
749 To specify a single dependency on a group, the + symbol can be prefixed\r
750 with the : symbol.\r
751 \r
752 The following lines are equivalent, and each set a dependency ONLY on\r
753 NetBIOSGroup:\r
754 \r
755     nssm set <servicename> DependOnGroup NetBIOSGroup\r
756     nssm set <servicename> DependOnGroup :NetBIOSGroup\r
757     nssm set <servicename> DependOnGroup :+NetBIOSGroup\r
758 \r
759 Whereas these lines add to any existing dependencies:\r
760 \r
761     nssm set <servicename> DependOnGroup +NetBIOSGroup\r
762     nssm set <servicename> DependOnGroup ++NetBIOSGroup\r
763 \r
764 \r
765 The Name parameter can only be queried, not set.  It returns the service's\r
766 registry key name.  This may be useful to know if you take advantage of\r
767 the fact that you can substitute the service's display name anywhere where\r
768 the syntax calls for <servicename>.\r
769 \r
770 \r
771 The ObjectName parameter requires an additional argument only when setting\r
772 a username.  The additional argument is the password of the user.\r
773 \r
774 To retrieve the username, run\r
775 \r
776     nssm get <servicename> ObjectName\r
777 \r
778 To set the username and password, run\r
779 \r
780     nssm set <servicename> ObjectName <username> <password>\r
781 \r
782 Note that the rules of argument concatenation still apply.  The following\r
783 invocation is valid and will have the expected effect.\r
784 \r
785     nssm set <servicename> ObjectName <username> correct horse battery staple\r
786 \r
787 The following well-known usernames do not need a password.  The password\r
788 parameter can be omitted when using them:\r
789 \r
790   "LocalSystem" aka "System" aka "NT Authority\System"\r
791   "LocalService" aka "Local Service" aka "NT Authority\Local Service"\r
792   "NetworkService" aka "Network Service" aka "NT Authority\Network Service"\r
793 \r
794 \r
795 The Start parameter is used to query or set the startup type of the service.\r
796 Valid service startup types are as follows:\r
797 \r
798   SERVICE_AUTO_START: Automatic startup at boot.\r
799   SERVICE_DELAYED_START: Delayed startup at boot.\r
800   SERVICE_DEMAND_START: Manual service startup.\r
801   SERVICE_DISABLED: The service is disabled.\r
802 \r
803 Note that SERVICE_DELAYED_START is not supported on versions of Windows prior\r
804 to Vista.  NSSM will set the service to automatic startup if delayed start is\r
805 unavailable.\r
806 \r
807 \r
808 The Type parameter is used to query or set the service type.  NSSM recognises\r
809 all currently documented service types but will only allow setting one of two\r
810 types:\r
811 \r
812   SERVICE_WIN32_OWN_PROCESS: A standalone service.  This is the default.\r
813   SERVICE_INTERACTIVE_PROCESS: A service which can interact with the desktop.\r
814 \r
815 Note that a service may only be configured as interactive if it runs under\r
816 the LocalSystem account.  The safe way to configure an interactive service\r
817 is in two stages as follows.\r
818 \r
819     nssm reset <servicename> ObjectName\r
820     nssm set <servicename> Type SERVICE_INTERACTIVE_PROCESS\r
821 \r
822 \r
823 Controlling services using the command line\r
824 -------------------------------------------\r
825 NSSM offers rudimentary service control features.\r
826 \r
827     nssm start <servicename>\r
828 \r
829     nssm restart <servicename>\r
830 \r
831     nssm stop <servicename>\r
832 \r
833     nssm status <servicename>\r
834 \r
835 \r
836 Removing services using the GUI\r
837 -------------------------------\r
838 NSSM can also remove services.  Run\r
839 \r
840     nssm remove <servicename>\r
841 \r
842 to remove a service.  You will prompted for confirmation before the service \r
843 is removed.  Try not to remove essential system services...\r
844 \r
845 \r
846 Removing service using the command line\r
847 ---------------------------------------\r
848 To remove a service without confirmation from the GUI, run\r
849 \r
850     nssm remove <servicename> confirm\r
851 \r
852 Try not to remove essential system services...\r
853 \r
854 \r
855 Logging\r
856 -------\r
857 NSSM logs to the Windows event log.  It registers itself as an event log source\r
858 and uses unique event IDs for each type of message it logs.  New versions may\r
859 add event types but existing event IDs will never be changed.\r
860 \r
861 Because of the way NSSM registers itself you should be aware that you may not\r
862 be able to replace the NSSM binary if you have the event viewer open and that\r
863 running multiple instances of NSSM from different locations may be confusing if\r
864 they are not all the same version.\r
865 \r
866 \r
867 Listing managed services\r
868 ------------------------\r
869 The following command will print the names of all services managed by NSSM:\r
870 \r
871     nssm list\r
872 \r
873 \r
874 Showing processes started by a service\r
875 --------------------------------------\r
876 The following command will print the process ID and executable path of\r
877 processes started by a given service:\r
878 \r
879     nssm processes <servicename>\r
880 \r
881 \r
882 Exporting service configuration\r
883 -------------------------------\r
884 NSSM can dump commands which would recreate the configuration of a service.\r
885 The output can be pasted into a batch script to back up the service or\r
886 transfer to another computer.\r
887 \r
888     nssm dump <servicename>\r
889 \r
890 Because the service configuration may contain characters which need to be\r
891 quoted or escaped from the command prompt, NSSM tries hard to produce\r
892 output which will work correctly when run as a script, by adding quotes\r
893 and caret escapes as appropriate.\r
894 \r
895 To facilitate copying a service, the dump command accepts a second\r
896 argument which specifies the name of the service to be used in the output.\r
897 \r
898     nssm dump <servicename> <newname>\r
899 \r
900 Lines in the dump will reference the <newname> service while showing the\r
901 configuration of <servicename>.\r
902 \r
903 \r
904 Example usage\r
905 -------------\r
906 To install an Unreal Tournament server:\r
907 \r
908     nssm install UT2004 c:\games\ut2004\system\ucc.exe server\r
909 \r
910 To run the server as the "games" user:\r
911 \r
912     nssm set UT2004 ObjectName games password\r
913 \r
914 To configure the server to log to a file:\r
915 \r
916     nssm set UT2004 AppStdout c:\games\ut2004\service.log\r
917 \r
918 To restrict the server to a single CPU:\r
919 \r
920     nssm set UT2004 AppAffinity 0\r
921 \r
922 To remove the server:\r
923 \r
924     nssm remove UT2004 confirm\r
925 \r
926 To find out the service name of a service with a display name:\r
927 \r
928     nssm get "Background Intelligent Transfer Service" Name\r
929 \r
930 \r
931 Building NSSM from source\r
932 -------------------------\r
933 NSSM is known to compile with Visual Studio 2008 and later.  Older Visual\r
934 Studio releases may or may not work if you install an appropriate SDK and\r
935 edit the nssm.vcproj and nssm.sln files to set a lower version number.\r
936 They are known not to work with default settings.\r
937 \r
938 NSSM will also compile with Visual Studio 2010 but the resulting executable\r
939 will not run on versions of Windows older than XP SP2.  If you require\r
940 compatiblity with older Windows releases you should change the Platform\r
941 Toolset to v90 in the General section of the project's Configuration\r
942 Properties.\r
943 \r
944 \r
945 Credits\r
946 -------\r
947 Thanks to Bernard Loh for finding a bug with service recovery.\r
948 Thanks to Benjamin Mayrargue (www.softlion.com) for adding 64-bit support.\r
949 Thanks to Joel Reingold for spotting a command line truncation bug.\r
950 Thanks to Arve Knudsen for spotting that child processes of the monitored\r
951 application could be left running on service shutdown, and that a missing\r
952 registry value for AppDirectory confused NSSM.\r
953 Thanks to Peter Wagemans and Laszlo Keresztfalvi for suggesting throttling\r
954 restarts.\r
955 Thanks to Eugene Lifshitz for finding an edge case in CreateProcess() and for\r
956 advising how to build messages.mc correctly in paths containing spaces.\r
957 Thanks to Rob Sharp for pointing out that NSSM did not respect the\r
958 AppEnvironment registry value used by srvany.\r
959 Thanks to Szymon Nowak for help with Windows 2000 compatibility.\r
960 Thanks to François-Régis Tardy and Gildas le Nadan for French translation.\r
961 Thanks to Emilio Frini for spotting that French was inadvertently set as\r
962 the default language when the user's display language was not translated.\r
963 Thanks to Riccardo Gusmeroli and Marco Certelli for Italian translation.\r
964 Thanks to Eric Cheldelin for the inspiration to generate a Control-C event\r
965 on shutdown.\r
966 Thanks to Brian Baxter for suggesting how to escape quotes from the command\r
967 prompt.\r
968 Thanks to Russ Holmann for suggesting that the shutdown timeout be configurable.\r
969 Thanks to Paul Spause for spotting a bug with default registry entries.\r
970 Thanks to BUGHUNTER for spotting more GUI bugs.\r
971 Thanks to Doug Watson for suggesting file rotation.\r
972 Thanks to Арслан Сайдуганов for suggesting setting process priority.\r
973 Thanks to Robert Middleton for suggestion and draft implementation of process\r
974 affinity support.\r
975 Thanks to Andrew RedzMax for suggesting an unconditional restart delay.\r
976 Thanks to Bryan Senseman for noticing that applications with redirected stdout\r
977 and/or stderr which attempt to read from stdin would fail.\r
978 Thanks to Czenda Czendov for help with Visual Studio 2013 and Server 2012R2.\r
979 Thanks to Alessandro Gherardi for reporting and draft fix of the bug whereby\r
980 the second restart of the application would have a corrupted environment.\r
981 Thanks to Hadrien Kohl for suggesting to disable the console window's menu.\r
982 Thanks to Allen Vailliencourt for noticing bugs with configuring the service to\r
983 run under a local user account.\r
984 Thanks to Sam Townsend for noticing a regression with TerminateProcess().\r
985 Thanks to Barrett Lewis for suggesting the option to skip terminating the\r
986 application's child processes.\r
987 Thanks to Miguel Angel Terrón for suggesting copy/truncate rotation.\r
988 Thanks to Yuriy Lesiuk for suggesting setting the environment before querying\r
989 the registry for parameters.\r
990 Thanks to Gerald Haider for noticing that installing a service with NSSM in a\r
991 path containing spaces was technically a security vulnerability.\r
992 Thanks to Scott Ware for reporting a crash saving the environment on XP 32-bit.\r
993 Thanks to Stefan and Michael Scherer for reporting a bug writing the event messages source.\r
994 Thanks to Paul Baxter for help with Visual Studio 2015.\r
995 Thanks to Mathias Breiner for help with Visual Studio and some registry fixes.\r
996 Thanks to David Bremner for general tidyups.\r
997 Thanks to Nabil Redmann for suggesting redirecting hooks' output.\r
998 Thanks to Bader Aldurai for suggesting the process tree.\r
999 \r
1000 Licence\r
1001 -------\r
1002 NSSM is public domain.  You may unconditionally use it and/or its source code \r
1003 for any purpose you wish.\r