NSSM: The Non-Sucking Service Manager\r
-Version 2.22, 2014-05-16\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
\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
+Since version 2.25, NSSM can dump the configuration of services it manages.\r
+\r
+Since version 2.25, NSSM can show the processes managed by a service.\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
+If NSSM is redirecting stdout or stderr it can be configured to redirect\r
+the output of any hooks it runs. Set AppRedirectHooks to 1 to enable\r
+that functionality. A hook can of course redirect its own I/O independently\r
+of NSSM.\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
\r
Non-standard parameters\r
-----------------------\r
-The AppEnvironment and AppEnvironmentExtra parameters recognise an\r
-additional argument when querying the environment. The following syntax\r
-will print all extra environment variables configured for a service\r
+The AppEnvironment, AppEnvironmentExtra and Environment parameters\r
+recognise an additional argument when querying the environment. The\r
+following syntax will print all extra environment variables configured\r
+for a service\r
\r
nssm get <servicename> AppEnvironmentExtra\r
\r
\r
nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes TEMP=C:\Temp\r
\r
+Alternatively the KEY can be prefixed with a + or - symbol to respectively\r
+add or remove a pair from the block.\r
+\r
+The following two lines set CLASSPATH and TEMP:\r
+\r
+ nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes\r
+ nssm set <servicename> AppEnvironment +TEMP=C:\Temp\r
+\r
+If the key is already present, specifying +KEY will override the value\r
+while preserving the order of keys:\r
+\r
+ nssm set <servicename> AppEnvironment +CLASSPATH=C:\NewClasses\r
+\r
+The following syntax removes a single variable from the block while\r
+leaving any other variables in place.\r
+\r
+ nssm set <servicename> AppEnvironment -TEMP\r
+\r
+Specifying -KEY=VALUE will remove the variable only if the existing\r
+value matches.\r
+\r
+The following syntax would not remove TEMP=C:\Temp\r
+\r
+ nssm set <servicename> AppEnvironment -TEMP=C:\Work\Temporary\r
+\r
+The + and - symbols are valid characters in environment variables.\r
+The syntax :KEY=VALUE is equivalent to KEY=VALUE and can be used to\r
+set variables which start with +/- or to explicitly reset the block in\r
+a script:\r
+\r
+ nssm set <servicename> AppEnvironment :CLASSPATH=C:\Classes\r
+ nssm set <servicename> AppEnvironment +TEMP=C:\Temp\r
+\r
\r
The AppExit parameter requires an additional argument specifying the exit\r
code to get or set. The default action can be specified with the string\r
\r
nssm set <servicename> DependOnService RpcSs LanmanWorkstation\r
\r
+Alternatively the dependency name can be prefixed with a + or - symbol to\r
+respectively add or remove a dependency.\r
+\r
+The following two lines set dependencies on RpcSs and LanmanWorkstation:\r
+\r
+ nssm set <servicename> DependOnService RpcSs\r
+ nssm set <servicename> DependOnService +LanmanWorkstation\r
+\r
+The follwing syntax removes the dependency on RpcSs:\r
+\r
+ nssm set <servicename> DependOnService -RpcSs\r
+\r
+Service groups should, strictly speaking, be prefixed with the + symbol.\r
+To specify a single dependency on a group, the + symbol can be prefixed\r
+with the : symbol.\r
+\r
+The following lines are equivalent, and each set a dependency ONLY on\r
+NetBIOSGroup:\r
+\r
+ nssm set <servicename> DependOnGroup NetBIOSGroup\r
+ nssm set <servicename> DependOnGroup :NetBIOSGroup\r
+ nssm set <servicename> DependOnGroup :+NetBIOSGroup\r
+\r
+Whereas these lines add to any existing dependencies:\r
+\r
+ nssm set <servicename> DependOnGroup +NetBIOSGroup\r
+ nssm set <servicename> DependOnGroup ++NetBIOSGroup\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
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
+To see all services on the system, not just NSSM's, use list all:\r
+\r
+ nssm list all\r
+\r
+\r
+Showing processes started by a service\r
+--------------------------------------\r
+The following command will print the process ID and executable path of\r
+processes started by a given service:\r
+\r
+ nssm processes <servicename>\r
+\r
+Note that if 32-bit NSSM is run on a 64-bit system running an older version of\r
+Windows than Vista it will not be able to query the paths of 64-bit processes.\r
+\r
+\r
+Exporting service configuration\r
+-------------------------------\r
+NSSM can dump commands which would recreate the configuration of a service.\r
+The output can be pasted into a batch script to back up the service or\r
+transfer to another computer.\r
+\r
+ nssm dump <servicename>\r
+\r
+Because the service configuration may contain characters which need to be\r
+quoted or escaped from the command prompt, NSSM tries hard to produce\r
+output which will work correctly when run as a script, by adding quotes\r
+and caret escapes as appropriate.\r
+\r
+To facilitate copying a service, the dump command accepts a second\r
+argument which specifies the name of the service to be used in the output.\r
+\r
+ nssm dump <servicename> <newname>\r
+\r
+Lines in the dump will reference the <newname> service while showing the\r
+configuration of <servicename>.\r
+\r
+\r
Example usage\r
-------------\r
To install an Unreal Tournament server:\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
+Thanks to Nabil Redmann for suggesting redirecting hooks' output.\r
+Thanks to Bader Aldurai for suggesting the process tree.\r
\r
Licence\r
-------\r
git://git.iain.cx/iain / nssm.git / blobdiff