AppEnvironmentExtra in place of or in addition to the srvany-compatible\r
AppEnvironment.\r
\r
+Since version 2.22, NSSM can rotate existing output files when redirecting I/O.\r
+\r
+Since version 2.22, NSSM can set service display name, description, startup\r
+type and log on details.\r
+\r
+Since version 2.22, NSSM can manage existing services.\r
+\r
\r
Usage\r
-----\r
-In the usage notes below, arguments to the program may be written in angle \r
-brackets and/or square brackets. <string> means you must insert the \r
-appropriate string and [<string>] means the string is optional. See the \r
+In the usage notes below, arguments to the program may be written in angle\r
+brackets and/or square brackets. <string> means you must insert the\r
+appropriate string and [<string>] means the string is optional. See the\r
examples below...\r
\r
+Note that everywhere <servicename> appears you may substitute the\r
+service's display name.\r
+\r
\r
Installation using the GUI\r
--------------------------\r
running the service.\r
\r
\r
+File rotation\r
+-------------\r
+When using I/O redirection, NSSM can rotate existing output files prior to\r
+opening stdout and/or stderr. An existing file will be renamed with a\r
+suffix based on the file's last write time, to millisecond precision. For\r
+example, the file nssm.log might be rotated to nssm-20131221T113939.457.log.\r
+\r
+NSSM will look in the registry under\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for REG_DWORD\r
+entries which control how rotation happens.\r
+\r
+If AppRotateFiles is missing or set to 0, rotation is disabled. Any non-zero\r
+value enables rotation.\r
+\r
+If AppRotateSeconds is non-zero, a file will not be rotated if its last write\r
+time is less than the given number of seconds in the past.\r
+\r
+If AppRotateBytes is non-zero, a file will not be rotated if it is smaller\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
+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
+\r
+\r
Environment variables\r
---------------------\r
NSSM can replace or append to the managed application's environment. Two\r
srvany only supports AppEnvironment.\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
+used to install them. Run\r
+\r
+ nssm edit <servicename>\r
+\r
+to bring up the GUI.\r
+\r
+NSSM offers limited editing capabilities for services other than those which\r
+run NSSM itself. When NSSM is asked to edit a service which does not have\r
+the App* registry settings described above, the GUI will allow editing only\r
+system settings such as the service display name and description.\r
+\r
+\r
+Managing services using the command line\r
+----------------------------------------\r
+NSSM can retrieve or set individual service parameters from the command line.\r
+In general the syntax is as follows, though see below for exceptions.\r
+\r
+ nssm get <servicename> <parameter>\r
+\r
+ nssm set <servicename> <parameter> <value>\r
+\r
+Parameters can also be reset to their default values.\r
+\r
+ nssm reset <servicename> <parameter>\r
+\r
+The parameter names recognised by NSSM are the same as the registry entry\r
+names described above, eg AppDirectory.\r
+\r
+NSSM offers limited editing capabilities for Services other than those which\r
+run NSSM itself. The parameters recognised are as follows:\r
+\r
+ Description: Service description.\r
+ DisplayName: Service display name.\r
+ ImagePath: Path to the service executable.\r
+ ObjectName: User account which runs the service.\r
+ Name: Service key name.\r
+ Start: Service startup type.\r
+ Type: Service type.\r
+\r
+These correspond to the registry values under the service's key\r
+HKLM\SYSTEM\CurrentControlSet\Services\<service>.\r
+\r
+\r
+Note that NSSM will concatenate all arguments passed on the command line\r
+with spaces to form the value to set. Thus the following two invocations\r
+would have the same effect.\r
+\r
+ nssm set <servicename> Description "NSSM managed service"\r
+\r
+ nssm set <servicename> Description NSSM managed service\r
+\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
+\r
+ nssm get <servicename> AppEnvironmentExtra\r
+\r
+whereas the syntax below will print only the value of the CLASSPATH\r
+variable if it is configured in the environment block, or the empty string\r
+if it is not configured.\r
+\r
+ nssm get <servicename> AppEnvironmentExtra CLASSPATH\r
+\r
+When setting an environment block, each variable should be specified as a\r
+KEY=VALUE pair in separate command line arguments. For example:\r
+\r
+ nssm set <servicename> AppEnvironment CLASSPATH=C:\Classes 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
+Default.\r
+\r
+For example, to get the default exit action for a service you should run\r
+\r
+ nssm get <servicename> AppExit Default\r
+\r
+To get the exit action when the application exits with exit code 2, run\r
+\r
+ nssm get <servicename> AppExit 2\r
+\r
+Note that if no explicit action is configured for a specified exit code,\r
+NSSM will print the default exit action.\r
+\r
+To set configure the service to stop when the application exits with an\r
+exit code of 2, run\r
+\r
+ nssm set <servicename> AppExit 2 Exit\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
+the fact that you can substitute the service's display name anywhere where\r
+the syntax calls for <servicename>.\r
+\r
+\r
+The ObjectName parameter requires an additional argument only when setting\r
+a username. The additional argument is the password of the user.\r
+\r
+To retrieve the username, run\r
+\r
+ nssm get <servicename> ObjectName\r
+\r
+To set the username and password, run\r
+\r
+ nssm set <servicename> ObjectName <username> <password>\r
+\r
+Note that the rules of argument concatenation still apply. The following\r
+invocation is valid and will have the expected effect.\r
+\r
+ nssm set <servicename> ObjectName <username> correct horse battery staple\r
+\r
+\r
+The Start parameter is used to query or set the startup type of the service.\r
+Valid service startup types are as follows:\r
+\r
+ SERVICE_AUTO_START: Automatic startup at boot.\r
+ SERVICE_DELAYED_START: Delayed startup at boot.\r
+ SERVICE_DEMAND_START: Manual service startup.\r
+ SERVICE_DISABLED: The service is disabled.\r
+\r
+Note that SERVICE_DELAYED_START is not supported on versions of Windows prior\r
+to Vista. NSSM will set the service to automatic startup if delayed start is\r
+unavailable.\r
+\r
+\r
+The Type parameter is used to query or set the service type. NSSM recognises\r
+all currently documented service types but will only allow setting one of two\r
+types:\r
+\r
+ SERVICE_WIN32_OWN_PROCESS: A standalone service. This is the default.\r
+ SERVICE_INTERACTIVE_PROCESS: A service which can interact with the desktop.\r
+\r
+Note that a service may only be configured as interactive if it runs under\r
+the LocalSystem account. The safe way to configure an interactive service\r
+is in two stages as follows.\r
+\r
+ nssm reset <servicename> ObjectName\r
+ nssm set <servicename> Type SERVICE_INTERACTIVE_PROCESS\r
+\r
+\r
+Controlling services using the command line\r
+-------------------------------------------\r
+NSSM offers rudimentary service control features.\r
+\r
+ nssm start <servicename>\r
+\r
+ nssm stop <servicename>\r
+\r
+ nssm status <servicename>\r
+\r
+\r
Removing services using the GUI\r
-------------------------------\r
NSSM can also remove services. Run\r
\r
nssm install UT2004 c:\games\ut2004\system\ucc.exe server\r
\r
+To run the server as the "games" user:\r
+\r
+ nssm set UT2004 ObjectName games password\r
+\r
+To configure the server to log to a file:\r
+\r
+ nssm set UT2004 AppStdout c:\games\ut2004\service.log\r
+\r
To remove the server:\r
\r
nssm remove UT2004 confirm\r
\r
+To find out the service name of a service with a display name:\r
+\r
+ nssm get "Background Intelligent Transfer Service" Name\r
+\r
\r
Building NSSM from source\r
-------------------------\r
-NSSM is known to compile with Visual Studio 6, Visual Studio 2005 and Visual\r
-Studio 2008.\r
+NSSM is known to compile with Visual Studio 2008 and later. Older Visual\r
+Studio releases may or may not work if you install an appropriate SDK and\r
+edit the nssm.vcproj and nssm.sln files to set a lower version number.\r
+They are known not to work with default settings.\r
\r
NSSM will also compile with Visual Studio 2010 but the resulting executable\r
-will not run on versions of Windows older than XP SP2.\r
+will not run on versions of Windows older than XP SP2. If you require\r
+compatiblity with older Windows releases you should change the Platform\r
+Toolset to v90 in the General section of the project's Configuration\r
+Properties.\r
\r
\r
Credits\r
Thanks to Russ Holmann for suggesting that the shutdown timeout be configurable.\r
Thanks to Paul Spause for spotting a bug with default registry entries.\r
Thanks to BUGHUNTER for spotting more GUI bugs.\r
+Thanks to Doug Watson for suggesting file rotation.\r
\r
Licence\r
-------\r