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