\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
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
+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
application. Therefore online rotation is not enabled by default.\r
\r
\r
+Timestamping output\r
+-------------------\r
+When redirecting output, NSSM can prefix each line of output with a\r
+millisecond-precision timestamp, for example:\r
+\r
+ 2016-09-06 10:17:09.451 Pipeline main started\r
+\r
+To enable timestamp prefixing, set AppTimestampLog to a non-zero value.\r
+\r
+The prefix applies to both stdout and stderr. Prefixing requires\r
+intercepting the application's I/O in the same way that online rotation\r
+does. If log rotation and timestamp prefixing are both enabled, the\r
+rotation will be online.\r
+\r
+\r
Environment variables\r
---------------------\r
NSSM can replace or append to the managed application's environment. Two\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
\r
%NSSM_EXE% restart %NSSM_SERVICE_NAME%\r
\r
+To set a hook on the command line, use\r
+\r
+ nssm set <servicename> AppEvents <event>/<action> <command>\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
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
NSSM can edit the settings of existing services with the same GUI that is\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
"LocalSystem" aka "System" aka "NT Authority\System"\r
"LocalService" aka "Local Service" aka "NT Authority\Local Service"\r
"NetworkService" aka "Network Service" aka "NT Authority\Network Service"\r
+ Virtual service account "NT Service\<servicename>"\r
\r
\r
The Start parameter is used to query or set the startup type of the service.\r
\r
nssm status <servicename>\r
\r
+ nssm statuscode <servicename>\r
+\r
+The output of "nssm status" and "nssm statuscode" is a string\r
+representing the service state, eg SERVICE_RUNNING.\r
+\r
+The exit code of "nssm status" will be 0 if the status was\r
+succesfully retrieved. If the exit code is not zero there was\r
+an error.\r
+\r
+The exit code of "nssm statuscode" will be the numeric value\r
+of the service state, eg 4 for SERVICE_RUNNING. Zero is not a\r
+valid service state code. If the exit code is zero there was\r
+an error.\r
+\r
\r
Removing services using the GUI\r
-------------------------------\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
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
+Thanks to Christian Long for suggesting virtual accounts.\r
+Thanks to Marcin Lewandowski for spotting a bug appending to large files.\r
+Thanks to Nicolas Ducrocq for suggesting timestamping redirected output.\r
+Thanks to Meang Akira Tanaka for suggestion and initial implementation of\r
+the statuscode command.\r
\r
Licence\r
-------\r
git://git.iain.cx/iain / nssm.git / blobdiff