\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
\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
supports AppEnvironment.\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
NSSM can edit the settings of existing services with the same GUI that is\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
\r
Licence\r
-------\r
git://git.iain.cx/iain / nssm.git / blobdiff