\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
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
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
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 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
\r
Licence\r
-------\r
git://git.iain.cx/iain / nssm.git / blobdiff