X-Git-Url: http://git.iain.cx/?a=blobdiff_plain;f=README.txt;h=2158741ce032cb10f9fe65a70544fa0943713df6;hb=caaaa1208f29647987173f7d9bc1aa75b58757b7;hp=e9443409514e8103e604832b6658ebfaa5d5ae1a;hpb=f7f20a0b3ecbb0e1a2eb59f95b50f0625b37c671;p=nssm.git diff --git a/README.txt b/README.txt index e944340..2158741 100644 --- a/README.txt +++ b/README.txt @@ -66,6 +66,10 @@ type, log on details and dependencies. Since version 2.22, NSSM can manage existing services. +Since version 2.25, NSSM can execute commands in response to service events. + +Since version 2.25, NSSM can list services it manages. + Usage ----- @@ -329,7 +333,7 @@ a non-zero value of AppRotateBytesHigh. If AppRotateDelay is non-zero, NSSM will pause for the given number of milliseconds after rotation. -If AppStdoutCopyAndTruncate or AppStdErrCopyAndTruncate are non-zero, the +If AppStdoutCopyAndTruncate or AppStderrCopyAndTruncate are non-zero, the stdout (or stderr respectively) file will be rotated by first taking a copy of the file then truncating the original file to zero size. This allows NSSM to rotate files which are held open by other processes, preventing the @@ -404,6 +408,177 @@ application to fail to start. Most people will want to use AppEnvironmentExtra exclusively. srvany only supports AppEnvironment. +As of version 2.25, NSSM parses AppEnvironment and AppEnvironmentExtra +itself, before reading any other registry values. As a result it is now +possible to refer to custom environment variables in Application, +AppDirectory and other parameters. + + +Merged service environment +-------------------------- +All Windows services can be passed additional environment variables by +creating a multi-valued string (REG_MULTI_SZ) registry value named +HLKM\SYSTEM\CurrentControlSet\Services\\Environment. + +The contents of this environment block will be merged into the system +environment before the service starts. + +Note, however, that the merged environment will be sorted alphabetically +before being processed. This means that in practice you cannot set, +for example, DIR=%PROGRAMFILES% in the Environment block because the +environment passed to the service will not have defined %PROGRAMFILES% +by the time it comes to define %DIR%. Environment variables defined in +AppEnvironmentExtra do not suffer from this limitation. + +As of version 2.25, NSSM can get and set the Environment block using +commands similar to: + + nssm get Environment + +It is worth reiterating that the Environment block is available to all +Windows services, not just NSSM services. + + +Service startup environment +--------------------------- +The environment NSSM passes to the application depends on how various +registry values are configured. The following flow describes how the +environment is modified. + +By default: + The service inherits the system environment. + +If \Environment is defined: + The contents of Environment are MERGED into the environment. + +If \Parameters\AppEnvironment is defined: + The service inherits the environment specified in AppEnvironment. + +If \Parameters\AppEnvironmentExtra is defined: + The contents of AppEnvironmentExtra are APPENDED to the environment. + +Note that AppEnvironment overrides the system environment and the +merged Environment block. Note also that AppEnvironmentExtra is +guaranteed to be appended to the startup environment if it is defined. + + +Event hooks +----------- +NSSM can run user-configurable commands in response to application events. +These commands are referred to as "hooks" below. + +All hooks are optional. Any hooks which are run will be launched with the +environment configured for the service. NSSM will place additional +variables into the environment which hooks can query to learn how and why +they were called. + +Hooks are categorised by Event and Action. Some hooks are run synchronously +and some are run asynchronously. Hooks prefixed with an *asterisk are run +synchronously. NSSM will wait for these hooks to complete before continuing +its work. Note, however, that ALL hooks are subject to a deadline after which +they will be killed, regardless of whether they are run asynchronously +or not. + + Event: Start - Triggered when the service is requested to start. + *Action: Pre - Called before NSSM attempts to launch the application. + Action: Post - Called after the application successfully starts. + + Event: Stop - Triggered when the service is requested to stop. + *Action: Pre - Called before NSSM attempts to kill the application. + + Event: Exit - Triggered when the application exits. + *Action: Post - Called after NSSM has cleaned up the application. + + Event: Rotate - Triggered when online log rotation is requested. + *Action: Pre - Called before NSSM rotates logs. + Action: Post - Called after NSSM rotates logs. + + Event: Power + Action: Change - Called when the system power status has changed. + Action: Resume - Called when the system has resumed from standby. + +Note that there is no Stop/Post hook. This is because Exit/Post is called +when the application exits, regardless of whether it did so in response to +a service shutdown request. Stop/Pre is only called before a graceful +shutdown attempt. + +NSSM sets the environment variable NSSM_HOOK_VERSION to a positive number. +Hooks can check the value of the number to determine which other environment +variables are available to them. + +If NSSM_HOOK_VERSION is 1 or greater, these variables are provided: + + NSSM_EXE - Path to NSSM itself. + NSSM_CONFIGURATION - Build information for the NSSM executable, + eg 64-bit debug. + NSSM_VERSION - Version of the NSSM executable. + NSSM_BUILD_DATE - Build date of NSSM. + NSSM_PID - Process ID of the running NSSM executable. + NSSM_DEADLINE - Deadline number of milliseconds after which NSSM will + kill the hook if it is still running. + NSSM_SERVICE_NAME - Name of the service controlled by NSSM. + NSSM_SERVICE_DISPLAYNAME - Display name of the service. + NSSM_COMMAND_LINE - Command line used to launch the application. + NSSM_APPLICATION_PID - Process ID of the primary application process. + May be blank if the process is not running. + NSSM_EVENT - Event class triggering the hook. + NSSM_ACTION - Event action triggering the hook. + NSSM_TRIGGER - Service control triggering the hook. May be blank if + the hook was not triggered by a service control, eg Exit/Post. + NSSM_LAST_CONTROL - Last service control handled by NSSM. + NSSM_START_REQUESTED_COUNT - Number of times the application was + requested to start. + NSSM_START_COUNT - Number of times the application successfully started. + NSSM_THROTTLE_COUNT - Number of times the application ran for less than + the throttle period. Reset to zero on successful start or when the + service is explicitly unpaused. + NSSM_EXIT_COUNT - Number of times the application exited. + NSSM_EXITCODE - Exit code of the application. May be blank if the + application is still running or has not started yet. + NSSM_RUNTIME - Number of milliseconds for which the NSSM executable has + been running. + NSSM_APPLICATION_RUNTIME - Number of milliseconds for which the + application has been running since it was last started. May be blank + if the application has not been started yet. + +Future versions of NSSM may provide more environment variables, in which +case NSSM_HOOK_VERSION will be set to a higher number. + +Hooks are configured by creating string (REG_EXPAND_SZ) values in the +registry named after the hook action and placed under +HKLM\SYSTEM\CurrentControlSet\Services\\Parameters\AppEvents\. + +For example the service could be configured to restart when the system +resumes from standby by setting AppEvents\Power\Resume to: + + %NSSM_EXE% restart %NSSM_SERVICE_NAME% + +Note that NSSM will abort the startup of the application if a Start/Pre hook +returns exit code of 99. + +A service will normally run hooks in the following order: + + Start/Pre + Start/Post + Stop/Pre + Exit/Post + +If the application crashes and is restarted by NSSM, the order might be: + + Start/Pre + Start/Post + Exit/Post + Start/Pre + Start/Post + Stop/Pre + Exit/Post + + +If NSSM is redirecting stdout or stderr it can be configured to redirect +the output of any hooks it runs. Set AppRedirectHooks to 1 to enable +that functionality. A hook can of course redirect its own I/O independently +of NSSM. + Managing services using the GUI ------------------------------- @@ -441,6 +616,7 @@ run NSSM itself. The parameters recognised are as follows: Description: Service description. DisplayName: Service display name. + Environment: Service merged environment. ImagePath: Path to the service executable. ObjectName: User account which runs the service. Name: Service key name. @@ -622,6 +798,13 @@ running multiple instances of NSSM from different locations may be confusing if they are not all the same version. +Listing managed services +------------------------ +The following command will print the names of all services managed by NSSM: + + nssm list + + Example usage ------------- To install an Unreal Tournament server: @@ -706,6 +889,16 @@ Thanks to Sam Townsend for noticing a regression with TerminateProcess(). Thanks to Barrett Lewis for suggesting the option to skip terminating the application's child processes. Thanks to Miguel Angel Terrón for suggesting copy/truncate rotation. +Thanks to Yuriy Lesiuk for suggesting setting the environment before querying +the registry for parameters. +Thanks to Gerald Haider for noticing that installing a service with NSSM in a +path containing spaces was technically a security vulnerability. +Thanks to Scott Ware for reporting a crash saving the environment on XP 32-bit. +Thanks to Stefan and Michael Scherer for reporting a bug writing the event messages source. +Thanks to Paul Baxter for help with Visual Studio 2015. +Thanks to Mathias Breiner for help with Visual Studio and some registry fixes. +Thanks to David Bremner for general tidyups. +Thanks to Nabil Redmann for suggesting redirecting hooks' output. Licence -------