NSSM: The Non-Sucking Service Manager\r
-Version 2.21, 2013-11-24\r
+Version 2.24, 2014-08-31\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
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
+type, log on details and dependencies.\r
\r
Since version 2.22, NSSM can manage existing services.\r
\r
+Since version 2.25, NSSM can execute commands in response to service events.\r
+\r
+Since version 2.25, NSSM can list services it manages.\r
+\r
\r
Usage\r
-----\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
+To skip applying the above stop methods to all processes in the application's\r
+process tree, applying them only to the original application process, set the\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppKillProcessTree\r
+registry value, which should be of type REG_DWORD, to 0.\r
+\r
\r
Console window\r
--------------\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
+If AppRotateDelay is non-zero, NSSM will pause for the given number of\r
+milliseconds after rotation.\r
+\r
+If AppStdoutCopyAndTruncate or AppStderrCopyAndTruncate are non-zero, the\r
+stdout (or stderr respectively) file will be rotated by first taking a copy\r
+of the file then truncating the original file to zero size. This allows\r
+NSSM to rotate files which are held open by other processes, preventing the\r
+usual MoveFile() from succeeding. Note that the copy process may take some\r
+time if the file is large, and will temporarily consume twice as much disk\r
+space as the original file. Note also that applications reading the log file\r
+may not notice that the file size changed. Using this option in conjunction\r
+with AppRotateDelay may help in that case.\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
Most people will want to use AppEnvironmentExtra exclusively. srvany only\r
supports AppEnvironment.\r
\r
+As of version 2.25, NSSM parses AppEnvironment and AppEnvironmentExtra\r
+itself, before reading any other registry values. As a result it is now\r
+possible to refer to custom environment variables in Application,\r
+AppDirectory and other parameters.\r
+\r
+\r
+Merged service environment\r
+--------------------------\r
+All Windows services can be passed additional environment variables by\r
+creating a multi-valued string (REG_MULTI_SZ) registry value named\r
+HLKM\SYSTEM\CurrentControlSet\Services\<service>\Environment.\r
+\r
+The contents of this environment block will be merged into the system\r
+environment before the service starts.\r
+\r
+Note, however, that the merged environment will be sorted alphabetically\r
+before being processed. This means that in practice you cannot set,\r
+for example, DIR=%PROGRAMFILES% in the Environment block because the\r
+environment passed to the service will not have defined %PROGRAMFILES%\r
+by the time it comes to define %DIR%. Environment variables defined in\r
+AppEnvironmentExtra do not suffer from this limitation.\r
+\r
+As of version 2.25, NSSM can get and set the Environment block using\r
+commands similar to:\r
+\r
+ nssm get <servicename> Environment\r
+\r
+It is worth reiterating that the Environment block is available to all\r
+Windows services, not just NSSM services.\r
+\r
+\r
+Service startup environment\r
+---------------------------\r
+The environment NSSM passes to the application depends on how various\r
+registry values are configured. The following flow describes how the\r
+environment is modified.\r
+\r
+By default:\r
+ The service inherits the system environment.\r
+\r
+If <service>\Environment is defined:\r
+ The contents of Environment are MERGED into the environment.\r
+\r
+If <service>\Parameters\AppEnvironment is defined:\r
+ The service inherits the environment specified in AppEnvironment.\r
+\r
+If <service>\Parameters\AppEnvironmentExtra is defined:\r
+ The contents of AppEnvironmentExtra are APPENDED to the environment.\r
+\r
+Note that AppEnvironment overrides the system environment and the\r
+merged Environment block. Note also that AppEnvironmentExtra is\r
+guaranteed to be appended to the startup environment if it is defined.\r
+\r
+\r
+Event hooks\r
+-----------\r
+NSSM can run user-configurable commands in response to application events.\r
+These commands are referred to as "hooks" below.\r
+\r
+All hooks are optional. Any hooks which are run will be launched with the\r
+environment configured for the service. NSSM will place additional\r
+variables into the environment which hooks can query to learn how and why\r
+they were called.\r
+\r
+Hooks are categorised by Event and Action. Some hooks are run synchronously\r
+and some are run asynchronously. Hooks prefixed with an *asterisk are run\r
+synchronously. NSSM will wait for these hooks to complete before continuing\r
+its work. Note, however, that ALL hooks are subject to a deadline after which\r
+they will be killed, regardless of whether they are run asynchronously\r
+or not.\r
+\r
+ Event: Start - Triggered when the service is requested to start.\r
+ *Action: Pre - Called before NSSM attempts to launch the application.\r
+ Action: Post - Called after the application successfully starts.\r
+\r
+ Event: Stop - Triggered when the service is requested to stop.\r
+ *Action: Pre - Called before NSSM attempts to kill the application.\r
+\r
+ Event: Exit - Triggered when the application exits.\r
+ *Action: Post - Called after NSSM has cleaned up the application.\r
+\r
+ Event: Rotate - Triggered when online log rotation is requested.\r
+ *Action: Pre - Called before NSSM rotates logs.\r
+ Action: Post - Called after NSSM rotates logs.\r
+\r
+ Event: Power\r
+ Action: Change - Called when the system power status has changed.\r
+ Action: Resume - Called when the system has resumed from standby.\r
+\r
+Note that there is no Stop/Post hook. This is because Exit/Post is called\r
+when the application exits, regardless of whether it did so in response to\r
+a service shutdown request. Stop/Pre is only called before a graceful\r
+shutdown attempt.\r
+\r
+NSSM sets the environment variable NSSM_HOOK_VERSION to a positive number.\r
+Hooks can check the value of the number to determine which other environment\r
+variables are available to them.\r
+\r
+If NSSM_HOOK_VERSION is 1 or greater, these variables are provided:\r
+\r
+ NSSM_EXE - Path to NSSM itself.\r
+ NSSM_CONFIGURATION - Build information for the NSSM executable,\r
+ eg 64-bit debug.\r
+ NSSM_VERSION - Version of the NSSM executable.\r
+ NSSM_BUILD_DATE - Build date of NSSM.\r
+ NSSM_PID - Process ID of the running NSSM executable.\r
+ NSSM_DEADLINE - Deadline number of milliseconds after which NSSM will\r
+ kill the hook if it is still running.\r
+ NSSM_SERVICE_NAME - Name of the service controlled by NSSM.\r
+ NSSM_SERVICE_DISPLAYNAME - Display name of the service.\r
+ NSSM_COMMAND_LINE - Command line used to launch the application.\r
+ NSSM_APPLICATION_PID - Process ID of the primary application process.\r
+ May be blank if the process is not running.\r
+ NSSM_EVENT - Event class triggering the hook.\r
+ NSSM_ACTION - Event action triggering the hook.\r
+ NSSM_TRIGGER - Service control triggering the hook. May be blank if\r
+ the hook was not triggered by a service control, eg Exit/Post.\r
+ NSSM_LAST_CONTROL - Last service control handled by NSSM.\r
+ NSSM_START_REQUESTED_COUNT - Number of times the application was\r
+ requested to start.\r
+ NSSM_START_COUNT - Number of times the application successfully started.\r
+ NSSM_THROTTLE_COUNT - Number of times the application ran for less than\r
+ the throttle period. Reset to zero on successful start or when the\r
+ service is explicitly unpaused.\r
+ NSSM_EXIT_COUNT - Number of times the application exited.\r
+ NSSM_EXITCODE - Exit code of the application. May be blank if the\r
+ application is still running or has not started yet.\r
+ NSSM_RUNTIME - Number of milliseconds for which the NSSM executable has\r
+ been running.\r
+ NSSM_APPLICATION_RUNTIME - Number of milliseconds for which the\r
+ application has been running since it was last started. May be blank\r
+ if the application has not been started yet.\r
+\r
+Future versions of NSSM may provide more environment variables, in which\r
+case NSSM_HOOK_VERSION will be set to a higher number.\r
+\r
+Hooks are configured by creating string (REG_EXPAND_SZ) values in the\r
+registry named after the hook action and placed under\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppEvents\<event>.\r
+\r
+For example the service could be configured to restart when the system\r
+resumes from standby by setting AppEvents\Power\Resume to:\r
+\r
+ %NSSM_EXE% restart %NSSM_SERVICE_NAME%\r
+\r
+Note that NSSM will abort the startup of the application if a Start/Pre hook\r
+returns exit code of 99.\r
+\r
+A service will normally run hooks in the following order:\r
+\r
+ Start/Pre\r
+ Start/Post\r
+ Stop/Pre\r
+ Exit/Post\r
+\r
+If the application crashes and is restarted by NSSM, the order might be:\r
+\r
+ Start/Pre\r
+ Start/Post\r
+ Exit/Post\r
+ Start/Pre\r
+ Start/Post\r
+ Stop/Pre\r
+ Exit/Post\r
+\r
\r
Managing services using the GUI\r
-------------------------------\r
\r
Description: Service description.\r
DisplayName: Service display name.\r
+ Environment: Service merged environment.\r
ImagePath: Path to the service executable.\r
ObjectName: User account which runs the service.\r
Name: Service key name.\r
IDLE_PRIORITY_CLASS\r
\r
\r
+The DependOnGroup and DependOnService parameters are used to query or set\r
+the dependencies for the service. When setting dependencies, each service\r
+or service group (preceded with the + symbol) should be specified in\r
+separate command line arguments. For example:\r
+\r
+ nssm set <servicename> DependOnService RpcSs LanmanWorkstation\r
+\r
+\r
The Name parameter can only be queried, not set. It returns the service's\r
registry key name. This may be useful to know if you take advantage of\r
the fact that you can substitute the service's display name anywhere where\r
parameter can be omitted when using them:\r
\r
"LocalSystem" aka "System" aka "NT Authority\System"\r
- "Local Service" aka "NT Authority\Local Service"\r
- "Network Service" aka "NT Authority\Network Service"\r
+ "LocalService" aka "Local Service" aka "NT Authority\Local Service"\r
+ "NetworkService" aka "Network Service" aka "NT Authority\Network Service"\r
\r
\r
The Start parameter is used to query or set the startup type of the service.\r
they are not all the same version.\r
\r
\r
+Listing managed services\r
+------------------------\r
+The following command will print the names of all services managed by NSSM:\r
+\r
+ nssm list\r
+\r
+\r
Example usage\r
-------------\r
To install an Unreal Tournament server:\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 François-Régis Tardy and Gildas le Nadan 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 Riccardo Gusmeroli and Marco Certelli 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\r
Thanks to Bryan Senseman for noticing that applications with redirected stdout\r
and/or stderr which attempt to read from stdin would fail.\r
Thanks to Czenda Czendov for help with Visual Studio 2013 and Server 2012R2.\r
+Thanks to Alessandro Gherardi for reporting and draft fix of the bug whereby\r
+the second restart of the application would have a corrupted environment.\r
+Thanks to Hadrien Kohl for suggesting to disable the console window's menu.\r
+Thanks to Allen Vailliencourt for noticing bugs with configuring the service to\r
+run under a local user account.\r
+Thanks to Sam Townsend for noticing a regression with TerminateProcess().\r
+Thanks to Barrett Lewis for suggesting the option to skip terminating the\r
+application's child processes.\r
+Thanks to Miguel Angel Terrón for suggesting copy/truncate rotation.\r
+Thanks to Yuriy Lesiuk for suggesting setting the environment before querying\r
+the registry for parameters.\r
+Thanks to Gerald Haider for noticing that installing a service with NSSM in a\r
+path containing spaces was technically a security vulnerability.\r
+Thanks to Scott Ware for reporting a crash saving the environment on XP 32-bit.\r
+Thanks to Stefan and Michael Scherer for reporting a bug writing the event messages source.\r
+Thanks to Paul Baxter for help with Visual Studio 2015.\r
+Thanks to Mathias Breiner for help with Visual Studio and some registry fixes.\r
+Thanks to David Bremner for general tidyups.\r
\r
Licence\r
-------\r
git://git.iain.cx/iain / nssm.git / blobdiff