1 NSSM: The Non-Sucking Service Manager
\r
2 Version 2.24, 2014-08-31
\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
8 NSSM also has a graphical service installer and remover.
\r
10 Full documentation can be found online at
\r
14 Since version 2.0, the GUI can be bypassed by entering all appropriate
\r
15 options on the command line.
\r
17 Since version 2.1, NSSM can be compiled for x64 platforms.
\r
18 Thanks Benjamin Mayrargue.
\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
23 Since version 2.3, NSSM logs to the Windows event log more elegantly.
\r
25 Since version 2.5, NSSM respects environment variables in its parameters.
\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
31 Since version 2.11, NSSM respects srvany's AppEnvironment parameter.
\r
33 Since version 2.13, NSSM is translated into French.
\r
34 Thanks François-Régis Tardy.
\r
36 Since version 2.15, NSSM is translated into Italian.
\r
37 Thanks Riccardo Gusmeroli.
\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
43 Since version 2.17, NSSM can redirect the managed application's I/O streams
\r
44 to an arbitrary path.
\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
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
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
56 Since version 2.22, NSSM can set the managed application's process priority
\r
59 Since version 2.22, NSSM can apply an unconditional delay before restarting
\r
60 an application which has exited.
\r
62 Since version 2.22, NSSM can rotate existing output files when redirecting I/O.
\r
64 Since version 2.22, NSSM can set service display name, description, startup
\r
65 type, log on details and dependencies.
\r
67 Since version 2.22, NSSM can manage existing services.
\r
69 Since version 2.25, NSSM can execute commands in response to service events.
\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
79 Note that everywhere <servicename> appears you may substitute the
\r
80 service's display name.
\r
83 Installation using the GUI
\r
84 --------------------------
\r
85 To install a service, run
\r
87 nssm install <servicename>
\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
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
97 Installation using the command line
\r
98 -----------------------------------
\r
99 To install a service, run
\r
101 nssm install <servicename> <application> [<options>]
\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
106 Don't forget to enclose paths in "quotes" if they contain spaces!
\r
108 If you want to include quotes in the options you will need to """quote""" the
\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
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
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
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
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
146 If AppRestartDelay is missing or invalid, only throttling will be applied.
\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
157 Based on the data found in the registry, NSSM will take one of three actions:
\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
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
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
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
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
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
199 For example, to specify the first; second; third and fifth CPUs, an appropriate
\r
200 AppAffinity would be 0-2,4.
\r
202 If AppAffinity is missing or invalid, NSSM will not attempt to restrict the
\r
203 application to specific CPUs.
\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
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
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
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
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
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
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
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
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
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
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
257 AppStopMethodConsole
\r
258 AppStopMethodWindow
\r
259 AppStopMethodThreads
\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
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
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
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
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
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
296 AppStdin: Path to receive input.
\r
297 AppStdout: Path to receive output.
\r
298 AppStderr: Path to receive error output.
\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
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
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
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
321 If AppRotateFiles is missing or set to 0, rotation is disabled. Any non-zero
\r
322 value enables rotation.
\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
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
331 If AppRotateDelay is non-zero, NSSM will pause for the given number of
\r
332 milliseconds after rotation.
\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
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
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
352 nssm rotate <servicename>
\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
359 To enable online and on-demand rotation, set AppRotateOnline to a non-zero
\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
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
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
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
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
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
392 For example, the following AppEnvironment block:
\r
394 PATH=C:\Windows\System32;C:\Windows
\r
397 Would result in a PATH of "C:\bin;C:\Windows\System32;C:\Windows" as expected.
\r
399 Whereas the following AppEnvironment block:
\r
403 Would result in a path containing only C:\bin and probably cause the
\r
404 application to fail to start.
\r
406 Most people will want to use AppEnvironmentExtra exclusively. srvany only
\r
407 supports AppEnvironment.
\r
412 NSSM can run user-configurable commands in response to application events.
\r
413 These commands are referred to as "hooks" below.
\r
415 All hooks are optional. Any hooks which are run will be launched with the
\r
416 environment configured for the service. NSSM will place additional
\r
417 variables into the environment which hooks can query to learn how and why
\r
420 Hooks are categorised by Event and Action. Some hooks are run synchronously
\r
421 and some are run asynchronously. Hooks prefixed with an *asterisk are run
\r
422 synchronously. NSSM will wait for these hooks to complete before continuing
\r
423 its work. Note, however, that ALL hooks are subject to a deadline after which
\r
424 they will be killed, regardless of whether they are run asynchronously
\r
427 Event: Start - Triggered when the service is requested to start.
\r
428 *Action: Pre - Called before NSSM attempts to launch the application.
\r
429 Action: Post - Called after the application successfully starts.
\r
431 Event: Stop - Triggered when the service is requested to stop.
\r
432 *Action: Pre - Called before NSSM attempts to kill the application.
\r
434 Event: Exit - Triggered when the application exits.
\r
435 *Action: Post - Called after NSSM has cleaned up the application.
\r
437 Event: Rotate - Triggered when online log rotation is requested.
\r
438 *Action: Pre - Called before NSSM rotates logs.
\r
439 Action: Post - Called after NSSM rotates logs.
\r
442 Action: Change - Called when the system power status has changed.
\r
443 Action: Resume - Called when the system has resumed from standby.
\r
445 Note that there is no Stop/Post hook. This is because Exit/Post is called
\r
446 when the application exits, regardless of whether it did so in response to
\r
447 a service shutdown request. Stop/Pre is only called before a graceful
\r
450 NSSM sets the environment variable NSSM_HOOK_VERSION to a positive number.
\r
451 Hooks can check the value of the number to determine which other environment
\r
452 variables are available to them.
\r
454 If NSSM_HOOK_VERSION is 1 or greater, these variables are provided:
\r
456 NSSM_EXE - Path to NSSM itself.
\r
457 NSSM_CONFIGURATION - Build information for the NSSM executable,
\r
459 NSSM_VERSION - Version of the NSSM executable.
\r
460 NSSM_BUILD_DATE - Build date of NSSM.
\r
461 NSSM_PID - Process ID of the running NSSM executable.
\r
462 NSSM_DEADLINE - Deadline number of milliseconds after which NSSM will
\r
463 kill the hook if it is still running.
\r
464 NSSM_SERVICE_NAME - Name of the service controlled by NSSM.
\r
465 NSSM_SERVICE_DISPLAYNAME - Display name of the service.
\r
466 NSSM_COMMAND_LINE - Command line used to launch the application.
\r
467 NSSM_APPLICATION_PID - Process ID of the primary application process.
\r
468 May be blank if the process is not running.
\r
469 NSSM_EVENT - Event class triggering the hook.
\r
470 NSSM_ACTION - Event action triggering the hook.
\r
471 NSSM_TRIGGER - Service control triggering the hook. May be blank if
\r
472 the hook was not triggered by a service control, eg Exit/Post.
\r
473 NSSM_LAST_CONTROL - Last service control handled by NSSM.
\r
474 NSSM_START_REQUESTED_COUNT - Number of times the application was
\r
475 requested to start.
\r
476 NSSM_START_COUNT - Number of times the application successfully started.
\r
477 NSSM_THROTTLE_COUNT - Number of times the application ran for less than
\r
478 the throttle period. Reset to zero on successful start or when the
\r
479 service is explicitly unpaused.
\r
480 NSSM_EXIT_COUNT - Number of times the application exited.
\r
481 NSSM_EXITCODE - Exit code of the application. May be blank if the
\r
482 application is still running or has not started yet.
\r
483 NSSM_RUNTIME - Number of milliseconds for which the NSSM executable has
\r
485 NSSM_APPLICATION_RUNTIME - Number of milliseconds for which the
\r
486 application has been running since it was last started. May be blank
\r
487 if the application has not been started yet.
\r
489 Future versions of NSSM may provide more environment variables, in which
\r
490 case NSSM_HOOK_VERSION will be set to a higher number.
\r
492 Hooks are configured by creating string (REG_EXPAND_SZ) values in the
\r
493 registry named after the hook action and placed under
\r
494 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppEvents\<event>.
\r
496 For example the service could be configured to restart when the system
\r
497 resumes from standby by setting AppEvents\Power\Resume to:
\r
499 %NSSM_EXE% restart %NSSM_SERVICE_NAME%
\r
501 Note that NSSM will abort the startup of the application if a Start/Pre hook
\r
502 returns exit code of 99.
\r
504 A service will normally run hooks in the following order:
\r
511 If the application crashes and is restarted by NSSM, the order might be:
\r
522 Managing services using the GUI
\r
523 -------------------------------
\r
524 NSSM can edit the settings of existing services with the same GUI that is
\r
525 used to install them. Run
\r
527 nssm edit <servicename>
\r
529 to bring up the GUI.
\r
531 NSSM offers limited editing capabilities for services other than those which
\r
532 run NSSM itself. When NSSM is asked to edit a service which does not have
\r
533 the App* registry settings described above, the GUI will allow editing only
\r
534 system settings such as the service display name and description.
\r
537 Managing services using the command line
\r
538 ----------------------------------------
\r
539 NSSM can retrieve or set individual service parameters from the command line.
\r
540 In general the syntax is as follows, though see below for exceptions.
\r
542 nssm get <servicename> <parameter>
\r
544 nssm set <servicename> <parameter> <value>
\r
546 Parameters can also be reset to their default values.
\r
548 nssm reset <servicename> <parameter>
\r
550 The parameter names recognised by NSSM are the same as the registry entry
\r
551 names described above, eg AppDirectory.
\r
553 NSSM offers limited editing capabilities for Services other than those which
\r
554 run NSSM itself. The parameters recognised are as follows:
\r
556 Description: Service description.
\r
557 DisplayName: Service display name.
\r
558 ImagePath: Path to the service executable.
\r
559 ObjectName: User account which runs the service.
\r
560 Name: Service key name.
\r
561 Start: Service startup type.
\r
562 Type: Service type.
\r
564 These correspond to the registry values under the service's key
\r
565 HKLM\SYSTEM\CurrentControlSet\Services\<service>.
\r
568 Note that NSSM will concatenate all arguments passed on the command line
\r
569 with spaces to form the value to set. Thus the following two invocations
\r
570 would have the same effect.
\r
572 nssm set <servicename> Description "NSSM managed service"
\r
574 nssm set <servicename> Description NSSM managed service
\r
577 Non-standard parameters
\r
578 -----------------------
\r
579 The AppEnvironment and AppEnvironmentExtra parameters recognise an
\r
580 additional argument when querying the environment. The following syntax
\r
581 will print all extra environment variables configured for a service
\r
583 nssm get <servicename> AppEnvironmentExtra
\r
585 whereas the syntax below will print only the value of the CLASSPATH
\r
586 variable if it is configured in the environment block, or the empty string
\r
587 if it is not configured.
\r
589 nssm get <servicename> AppEnvironmentExtra CLASSPATH
\r
591 When setting an environment block, each variable should be specified as a
\r
592 KEY=VALUE pair in separate command line arguments. For example:
\r
594 nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes TEMP=C:\Temp
\r
597 The AppExit parameter requires an additional argument specifying the exit
\r
598 code to get or set. The default action can be specified with the string
\r
601 For example, to get the default exit action for a service you should run
\r
603 nssm get <servicename> AppExit Default
\r
605 To get the exit action when the application exits with exit code 2, run
\r
607 nssm get <servicename> AppExit 2
\r
609 Note that if no explicit action is configured for a specified exit code,
\r
610 NSSM will print the default exit action.
\r
612 To set configure the service to stop when the application exits with an
\r
613 exit code of 2, run
\r
615 nssm set <servicename> AppExit 2 Exit
\r
618 The AppPriority parameter is used to set the priority class of the
\r
619 managed application. Valid priorities are as follows:
\r
621 REALTIME_PRIORITY_CLASS
\r
622 HIGH_PRIORITY_CLASS
\r
623 ABOVE_NORMAL_PRIORITY_CLASS
\r
624 NORMAL_PRIORITY_CLASS
\r
625 BELOW_NORMAL_PRIORITY_CLASS
\r
626 IDLE_PRIORITY_CLASS
\r
629 The DependOnGroup and DependOnService parameters are used to query or set
\r
630 the dependencies for the service. When setting dependencies, each service
\r
631 or service group (preceded with the + symbol) should be specified in
\r
632 separate command line arguments. For example:
\r
634 nssm set <servicename> DependOnService RpcSs LanmanWorkstation
\r
637 The Name parameter can only be queried, not set. It returns the service's
\r
638 registry key name. This may be useful to know if you take advantage of
\r
639 the fact that you can substitute the service's display name anywhere where
\r
640 the syntax calls for <servicename>.
\r
643 The ObjectName parameter requires an additional argument only when setting
\r
644 a username. The additional argument is the password of the user.
\r
646 To retrieve the username, run
\r
648 nssm get <servicename> ObjectName
\r
650 To set the username and password, run
\r
652 nssm set <servicename> ObjectName <username> <password>
\r
654 Note that the rules of argument concatenation still apply. The following
\r
655 invocation is valid and will have the expected effect.
\r
657 nssm set <servicename> ObjectName <username> correct horse battery staple
\r
659 The following well-known usernames do not need a password. The password
\r
660 parameter can be omitted when using them:
\r
662 "LocalSystem" aka "System" aka "NT Authority\System"
\r
663 "LocalService" aka "Local Service" aka "NT Authority\Local Service"
\r
664 "NetworkService" aka "Network Service" aka "NT Authority\Network Service"
\r
667 The Start parameter is used to query or set the startup type of the service.
\r
668 Valid service startup types are as follows:
\r
670 SERVICE_AUTO_START: Automatic startup at boot.
\r
671 SERVICE_DELAYED_START: Delayed startup at boot.
\r
672 SERVICE_DEMAND_START: Manual service startup.
\r
673 SERVICE_DISABLED: The service is disabled.
\r
675 Note that SERVICE_DELAYED_START is not supported on versions of Windows prior
\r
676 to Vista. NSSM will set the service to automatic startup if delayed start is
\r
680 The Type parameter is used to query or set the service type. NSSM recognises
\r
681 all currently documented service types but will only allow setting one of two
\r
684 SERVICE_WIN32_OWN_PROCESS: A standalone service. This is the default.
\r
685 SERVICE_INTERACTIVE_PROCESS: A service which can interact with the desktop.
\r
687 Note that a service may only be configured as interactive if it runs under
\r
688 the LocalSystem account. The safe way to configure an interactive service
\r
689 is in two stages as follows.
\r
691 nssm reset <servicename> ObjectName
\r
692 nssm set <servicename> Type SERVICE_INTERACTIVE_PROCESS
\r
695 Controlling services using the command line
\r
696 -------------------------------------------
\r
697 NSSM offers rudimentary service control features.
\r
699 nssm start <servicename>
\r
701 nssm restart <servicename>
\r
703 nssm stop <servicename>
\r
705 nssm status <servicename>
\r
708 Removing services using the GUI
\r
709 -------------------------------
\r
710 NSSM can also remove services. Run
\r
712 nssm remove <servicename>
\r
714 to remove a service. You will prompted for confirmation before the service
\r
715 is removed. Try not to remove essential system services...
\r
718 Removing service using the command line
\r
719 ---------------------------------------
\r
720 To remove a service without confirmation from the GUI, run
\r
722 nssm remove <servicename> confirm
\r
724 Try not to remove essential system services...
\r
729 NSSM logs to the Windows event log. It registers itself as an event log source
\r
730 and uses unique event IDs for each type of message it logs. New versions may
\r
731 add event types but existing event IDs will never be changed.
\r
733 Because of the way NSSM registers itself you should be aware that you may not
\r
734 be able to replace the NSSM binary if you have the event viewer open and that
\r
735 running multiple instances of NSSM from different locations may be confusing if
\r
736 they are not all the same version.
\r
741 To install an Unreal Tournament server:
\r
743 nssm install UT2004 c:\games\ut2004\system\ucc.exe server
\r
745 To run the server as the "games" user:
\r
747 nssm set UT2004 ObjectName games password
\r
749 To configure the server to log to a file:
\r
751 nssm set UT2004 AppStdout c:\games\ut2004\service.log
\r
753 To restrict the server to a single CPU:
\r
755 nssm set UT2004 AppAffinity 0
\r
757 To remove the server:
\r
759 nssm remove UT2004 confirm
\r
761 To find out the service name of a service with a display name:
\r
763 nssm get "Background Intelligent Transfer Service" Name
\r
766 Building NSSM from source
\r
767 -------------------------
\r
768 NSSM is known to compile with Visual Studio 2008 and later. Older Visual
\r
769 Studio releases may or may not work if you install an appropriate SDK and
\r
770 edit the nssm.vcproj and nssm.sln files to set a lower version number.
\r
771 They are known not to work with default settings.
\r
773 NSSM will also compile with Visual Studio 2010 but the resulting executable
\r
774 will not run on versions of Windows older than XP SP2. If you require
\r
775 compatiblity with older Windows releases you should change the Platform
\r
776 Toolset to v90 in the General section of the project's Configuration
\r
782 Thanks to Bernard Loh for finding a bug with service recovery.
\r
783 Thanks to Benjamin Mayrargue (www.softlion.com) for adding 64-bit support.
\r
784 Thanks to Joel Reingold for spotting a command line truncation bug.
\r
785 Thanks to Arve Knudsen for spotting that child processes of the monitored
\r
786 application could be left running on service shutdown, and that a missing
\r
787 registry value for AppDirectory confused NSSM.
\r
788 Thanks to Peter Wagemans and Laszlo Keresztfalvi for suggesting throttling
\r
790 Thanks to Eugene Lifshitz for finding an edge case in CreateProcess() and for
\r
791 advising how to build messages.mc correctly in paths containing spaces.
\r
792 Thanks to Rob Sharp for pointing out that NSSM did not respect the
\r
793 AppEnvironment registry value used by srvany.
\r
794 Thanks to Szymon Nowak for help with Windows 2000 compatibility.
\r
795 Thanks to François-Régis Tardy and Gildas le Nadan for French translation.
\r
796 Thanks to Emilio Frini for spotting that French was inadvertently set as
\r
797 the default language when the user's display language was not translated.
\r
798 Thanks to Riccardo Gusmeroli and Marco Certelli for Italian translation.
\r
799 Thanks to Eric Cheldelin for the inspiration to generate a Control-C event
\r
801 Thanks to Brian Baxter for suggesting how to escape quotes from the command
\r
803 Thanks to Russ Holmann for suggesting that the shutdown timeout be configurable.
\r
804 Thanks to Paul Spause for spotting a bug with default registry entries.
\r
805 Thanks to BUGHUNTER for spotting more GUI bugs.
\r
806 Thanks to Doug Watson for suggesting file rotation.
\r
807 Thanks to Арслан Сайдуганов for suggesting setting process priority.
\r
808 Thanks to Robert Middleton for suggestion and draft implementation of process
\r
810 Thanks to Andrew RedzMax for suggesting an unconditional restart delay.
\r
811 Thanks to Bryan Senseman for noticing that applications with redirected stdout
\r
812 and/or stderr which attempt to read from stdin would fail.
\r
813 Thanks to Czenda Czendov for help with Visual Studio 2013 and Server 2012R2.
\r
814 Thanks to Alessandro Gherardi for reporting and draft fix of the bug whereby
\r
815 the second restart of the application would have a corrupted environment.
\r
816 Thanks to Hadrien Kohl for suggesting to disable the console window's menu.
\r
817 Thanks to Allen Vailliencourt for noticing bugs with configuring the service to
\r
818 run under a local user account.
\r
819 Thanks to Sam Townsend for noticing a regression with TerminateProcess().
\r
820 Thanks to Barrett Lewis for suggesting the option to skip terminating the
\r
821 application's child processes.
\r
822 Thanks to Miguel Angel Terrón for suggesting copy/truncate rotation.
\r
823 Thanks to Yuriy Lesiuk for suggesting setting the environment before querying
\r
824 the registry for parameters.
\r
825 Thanks to Gerald Haider for noticing that installing a service with NSSM in a
\r
826 path containing spaces was technically a security vulnerability.
\r
830 NSSM is public domain. You may unconditionally use it and/or its source code
\r
831 for any purpose you wish.
\r