NSSM: The Non-Sucking Service Manager\r
-Version 2.0, 2006-09-09\r
+Version 2.21, 2013-11-24\r
\r
NSSM is a service helper program similar to srvany and cygrunsrv. It can \r
start any application as an NT service and will restart the service if it \r
\r
NSSM also has a graphical service installer and remover.\r
\r
+Full documentation can be found online at\r
+\r
+ http://nssm.cc/\r
+\r
Since version 2.0, the GUI can be bypassed by entering all appropriate \r
options on the command line.\r
\r
+Since version 2.1, NSSM can be compiled for x64 platforms.\r
+Thanks Benjamin Mayrargue.\r
+\r
+Since version 2.2, NSSM can be configured to take different actions\r
+based on the exit code of the managed application.\r
+\r
+Since version 2.3, NSSM logs to the Windows event log more elegantly.\r
+\r
+Since version 2.5, NSSM respects environment variables in its parameters.\r
+\r
+Since version 2.8, NSSM tries harder to shut down the managed application\r
+gracefully and throttles restart attempts if the application doesn't run\r
+for a minimum amount of time.\r
+\r
+Since version 2.11, NSSM respects srvany's AppEnvironment parameter.\r
+\r
+Since version 2.13, NSSM is translated into French.\r
+Thanks François-Régis Tardy.\r
+\r
+Since version 2.15, NSSM is translated into Italian.\r
+Thanks Riccardo Gusmeroli.\r
+\r
+Since version 2.17, NSSM can try to shut down console applications by\r
+simulating a Control-C keypress. If they have installed a handler routine\r
+they can clean up and shut down gracefully on receipt of the event.\r
+\r
+Since version 2.17, NSSM can redirect the managed application's I/O streams\r
+to an arbitrary path.\r
+\r
+Since version 2.18, NSSM can be configured to wait a user-specified amount\r
+of time for the application to exit when shutting down.\r
+\r
+Since version 2.19, many more service options can be configured with the\r
+GUI installer as well as via the registry.\r
+\r
+Since version 2.19, NSSM can add to the service's environment by setting\r
+AppEnvironmentExtra in place of or in addition to the srvany-compatible\r
+AppEnvironment.\r
+\r
+Since version 2.22, NSSM can rotate existing output files when redirecting I/O.\r
+\r
+Since version 2.22, NSSM can set service display name, description, startup\r
+type and log on details.\r
+\r
\r
Usage\r
-----\r
\r
Don't forget to enclose paths in "quotes" if they contain spaces!\r
\r
+If you want to include quotes in the options you will need to """quote""" the\r
+quotes.\r
+\r
\r
Managing the service\r
--------------------\r
NSSM will launch the application listed in the registry when you send it a \r
start signal and will terminate it when you send a stop signal. So far, so \r
-much like srvany. But NSSM is the Non-Sucking service manager and will take \r
+much like srvany. But NSSM is the Non-Sucking service manager and can take \r
action if/when the application dies.\r
\r
-NSSM will try to restart itself if it notices that the application died but \r
-you didn't send it a stop signal. NSSM will keep trying, pausing 30 seconds \r
-between each attempt, until the service is successfully started or you send \r
-it a stop signal.\r
+With no configuration from you, NSSM will try to restart itself if it notices\r
+that the application died but you didn't send it a stop signal. NSSM will\r
+keep trying, pausing between each attempt, until the service is successfully\r
+started or you send it a stop signal.\r
+\r
+NSSM will pause an increasingly longer time between subsequent restart attempts\r
+if the service fails to start in a timely manner, up to a maximum of four\r
+minutes. This is so it does not consume an excessive amount of CPU time trying\r
+to start a failed application over and over again. If you identify the cause\r
+of the failure and don't want to wait you can use the Windows service console\r
+(where the service will be shown in Paused state) to send a continue signal to\r
+NSSM and it will retry within a few seconds.\r
+\r
+By default, NSSM defines "a timely manner" to be within 1500 milliseconds.\r
+You can change the threshold for the service by setting the number of\r
+milliseconds as a REG_DWORD value in the registry at\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppThrottle.\r
+\r
+NSSM will look in the registry under\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppExit for\r
+string (REG_EXPAND_SZ) values corresponding to the exit code of the application.\r
+If the application exited with code 1, for instance, NSSM will look for a\r
+string value under AppExit called "1" or, if it does not find it, will\r
+fall back to the AppExit (Default) value. You can find out the exit code\r
+for the application by consulting the system event log. NSSM will log the\r
+exit code when the application exits.\r
+\r
+Based on the data found in the registry, NSSM will take one of three actions:\r
+\r
+If the value data is "Restart" NSSM will try to restart the application as\r
+described above. This is its default behaviour.\r
+\r
+If the value data is "Ignore" NSSM will not try to restart the application\r
+but will continue running itself. This emulates the (usually undesirable)\r
+behaviour of srvany. The Windows Services console would show the service\r
+as still running even though the application has exited.\r
+\r
+If the value data is "Exit" NSSM will exit gracefully. The Windows Services\r
+console would show the service as stopped. If you wish to provide\r
+finer-grained control over service recovery you should use this code and\r
+edit the failure action manually. Please note that Windows versions prior\r
+to Vista will not consider such an exit to be a failure. On older versions\r
+of Windows you should use "Suicide" instead.\r
+\r
+If the value data is "Suicide" NSSM will simulate a crash and exit without\r
+informing the service manager. This option should only be used for\r
+pre-Vista systems where you wish to apply a service recovery action. Note\r
+that if the monitored application exits with code 0, NSSM will only honour a\r
+request to suicide if you explicitly configure a registry key for exit code 0.\r
+If only the default action is set to Suicide NSSM will instead exit gracefully.\r
+\r
+\r
+Stopping the service\r
+--------------------\r
+When stopping a service NSSM will attempt several different methods of killing\r
+the monitored application, each of which can be disabled if necessary.\r
+\r
+First NSSM will attempt to generate a Control-C event and send it to the\r
+application's console. Batch scripts or console applications may intercept\r
+the event and shut themselves down gracefully. GUI applications do not have\r
+consoles and will not respond to this method.\r
+\r
+Secondly NSSM will enumerate all windows created by the application and send\r
+them a WM_CLOSE message, requesting a graceful exit.\r
+\r
+Thirdly NSSM will enumerate all threads created by the application and send\r
+them a WM_QUIT message, requesting a graceful exit. Not all applications'\r
+threads have message queues; those which do not will not respond to this\r
+method.\r
+\r
+Finally NSSM will call TerminateProcess() to request that the operating\r
+system forcibly terminate the application. TerminateProcess() cannot be\r
+trapped or ignored, so in most circumstances the application will be killed.\r
+However, there is no guarantee that it will have a chance to perform any\r
+tidyup operations before it exits.\r
+\r
+Any or all of the methods above may be disabled. NSSM will look for the\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppStopMethodSkip\r
+registry value which should be of type REG_DWORD set to a bit field describing\r
+which methods should not be applied.\r
+\r
+ If AppStopMethodSkip includes 1, Control-C events will not be generated.\r
+ If AppStopMethodSkip includes 2, WM_CLOSE messages will not be posted.\r
+ If AppStopMethodSkip includes 4, WM_QUIT messages will not be posted.\r
+ If AppStopMethodSkip includes 8, TerminateProcess() will not be called.\r
+\r
+If, for example, you knew that an application did not respond to Control-C\r
+events and did not have a thread message queue, you could set AppStopMethodSkip\r
+to 5 and NSSM would not attempt to use those methods to stop the application.\r
+\r
+Take great care when including 8 in the value of AppStopMethodSkip. If NSSM\r
+does not call TerminateProcess() it is possible that the application will not\r
+exit when the service stops.\r
+\r
+By default NSSM will allow processes 1500ms to respond to each of the methods\r
+described above before proceeding to the next one. The timeout can be\r
+configured on a per-method basis by creating REG_DWORD entries in the\r
+registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
+\r
+ AppStopMethodConsole\r
+ AppStopMethodWindow\r
+ AppStopMethodThreads\r
+\r
+Each value should be set to the number of milliseconds to wait. Please note\r
+that the timeout applies to each process in the application's process tree,\r
+so the actual time to shutdown may be longer than the sum of all configured\r
+timeouts if the application spawns multiple subprocesses.\r
+\r
+\r
+I/O redirection\r
+---------------\r
+NSSM can redirect the managed application's I/O to any path capable of being\r
+opened by CreateFile(). This enables, for example, capturing the log output\r
+of an application which would otherwise only write to the console or accepting\r
+input from a serial port.\r
+\r
+NSSM will look in the registry under\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for the keys\r
+corresponding to arguments to CreateFile(). All are optional. If no path is\r
+given for a particular stream it will not be redirected. If a path is given\r
+but any of the other values are omitted they will be receive sensible defaults.\r
+\r
+ AppStdin: Path to receive input.\r
+ AppStdout: Path to receive output.\r
+ AppStderr: Path to receive error output.\r
+\r
+Parameters for CreateFile() are providing with the "AppStdinShareMode",\r
+"AppStdinCreationDisposition" and "AppStdinFlagsAndAttributes" values (and\r
+analogously for stdout and stderr).\r
+\r
+In general, if you want the service to log its output, set AppStdout and\r
+AppStderr to the same path, eg C:\Users\Public\service.log, and it should\r
+work. Remember, however, that the path must be accessible to the user\r
+running the service.\r
+\r
+\r
+File rotation\r
+-------------\r
+When using I/O redirection, NSSM can rotate existing output files prior to\r
+opening stdout and/or stderr. An existing file will be renamed with a\r
+suffix based on the file's last write time, to millisecond precision. For\r
+example, the file nssm.log might be rotated to nssm-20131221T113939.457.log.\r
+\r
+NSSM will look in the registry under\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for REG_DWORD\r
+entries which control how rotation happens.\r
+\r
+If AppRotateFiles is missing or set to 0, rotation is disabled. Any non-zero\r
+value enables rotation.\r
+\r
+If AppRotateSeconds is non-zero, a file will not be rotated if its last write\r
+time is less than the given number of seconds in the past.\r
+\r
+If AppRotateBytes is non-zero, a file will not be rotated if it is smaller\r
+than the given number of bytes. 64-bit file sizes can be handled by setting\r
+a non-zero value of AppRotateBytesHigh.\r
+\r
+Rotation is independent of the CreateFile() parameters used to open the files.\r
+They will be rotated regardless of whether NSSM would otherwise have appended\r
+or replaced them.\r
+\r
+\r
+Environment variables\r
+---------------------\r
+NSSM can replace or append to the managed application's environment. Two\r
+multi-valued string (REG_MULTI_SZ) registry values are recognised under\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
+\r
+AppEnvironment defines a list of environment variables which will override\r
+the service's environment. AppEnvironmentExtra defines a list of\r
+environment variables which will be added to the service's environment.\r
+\r
+Each entry in the list should be of the form KEY=VALUE. It is possible to\r
+omit the VALUE but the = symbol is mandatory.\r
+\r
+srvany only supports AppEnvironment.\r
\r
\r
Removing services using the GUI\r
Try not to remove essential system services...\r
\r
\r
+Logging\r
+-------\r
+NSSM logs to the Windows event log. It registers itself as an event log source\r
+and uses unique event IDs for each type of message it logs. New versions may\r
+add event types but existing event IDs will never be changed.\r
+\r
+Because of the way NSSM registers itself you should be aware that you may not\r
+be able to replace the NSSM binary if you have the event viewer open and that\r
+running multiple instances of NSSM from different locations may be confusing if\r
+they are not all the same version.\r
+\r
+\r
Example usage\r
-------------\r
To install an Unreal Tournament server:\r
\r
Building NSSM from source\r
-------------------------\r
-NSSM is known to compile with Visual Studio 6 and Visual Studio 2005.\r
+NSSM is known to compile with Visual Studio 2008. Older Visual Studio\r
+releases may or may not work.\r
+\r
+NSSM will also compile with Visual Studio 2010 but the resulting executable\r
+will not run on versions of Windows older than XP SP2. If you require\r
+compatiblity with older Windows releases you should change the Platform\r
+Toolset to v90 in the General section of the project's Configuration\r
+Properties.\r
\r
\r
+Credits\r
+-------\r
+Thanks to Bernard Loh for finding a bug with service recovery.\r
+Thanks to Benjamin Mayrargue (www.softlion.com) for adding 64-bit support.\r
+Thanks to Joel Reingold for spotting a command line truncation bug.\r
+Thanks to Arve Knudsen for spotting that child processes of the monitored\r
+application could be left running on service shutdown, and that a missing\r
+registry value for AppDirectory confused NSSM.\r
+Thanks to Peter Wagemans and Laszlo Keresztfalvi for suggesting throttling restarts.\r
+Thanks to Eugene Lifshitz for finding an edge case in CreateProcess() and for\r
+advising how to build messages.mc correctly in paths containing spaces.\r
+Thanks to Rob Sharp for pointing out that NSSM did not respect the\r
+AppEnvironment registry value used by srvany.\r
+Thanks to Szymon Nowak for help with Windows 2000 compatibility.\r
+Thanks to François-Régis Tardy for French translation.\r
+Thanks to Emilio Frini for spotting that French was inadvertently set as\r
+the default language when the user's display language was not translated.\r
+Thanks to Riccardo Gusmeroli for Italian translation.\r
+Thanks to Eric Cheldelin for the inspiration to generate a Control-C event\r
+on shutdown.\r
+Thanks to Brian Baxter for suggesting how to escape quotes from the command prompt.\r
+Thanks to Russ Holmann for suggesting that the shutdown timeout be configurable.\r
+Thanks to Paul Spause for spotting a bug with default registry entries.\r
+Thanks to BUGHUNTER for spotting more GUI bugs.\r
+Thanks to Doug Watson for suggesting file rotation.\r
+\r
Licence\r
-------\r
NSSM is public domain. You may unconditionally use it and/or its source code \r