README.txt

   1 NSSM: The Non-Sucking Service Manager\r
   2 Version 2.21, 2013-11-24\r
   3 \r
   4 NSSM is a service helper program similar to srvany and cygrunsrv.  It can \r
   5 start any application as an NT service and will restart the service if it \r
   6 fails for any reason.\r
   7 \r
   8 NSSM also has a graphical service installer and remover.\r
   9 \r
  10 Full documentation can be found online at\r
  11 \r
  12                               http://nssm.cc/\r
  13 \r
  14 Since version 2.0, the GUI can be bypassed by entering all appropriate \r
  15 options on the command line.\r
  16 \r
  17 Since version 2.1, NSSM can be compiled for x64 platforms.\r
  18 Thanks Benjamin Mayrargue.\r
  19 \r
  20 Since version 2.2, NSSM can be configured to take different actions\r
  21 based on the exit code of the managed application.\r
  22 \r
  23 Since version 2.3, NSSM logs to the Windows event log more elegantly.\r
  24 \r
  25 Since version 2.5, NSSM respects environment variables in its parameters.\r
  26 \r
  27 Since version 2.8, NSSM tries harder to shut down the managed application\r
  28 gracefully and throttles restart attempts if the application doesn't run\r
  29 for a minimum amount of time.\r
  30 \r
  31 Since version 2.11, NSSM respects srvany's AppEnvironment parameter.\r
  32 \r
  33 Since version 2.13, NSSM is translated into French.\r
  34 Thanks François-Régis Tardy.\r
  35 \r
  36 Since version 2.15, NSSM is translated into Italian.\r
  37 Thanks Riccardo Gusmeroli.\r
  38 \r
  39 Since version 2.17, NSSM can try to shut down console applications by\r
  40 simulating a Control-C keypress.  If they have installed a handler routine\r
  41 they can clean up and shut down gracefully on receipt of the event.\r
  42 \r
  43 Since version 2.17, NSSM can redirect the managed application's I/O streams\r
  44 to an arbitrary path.\r
  45 \r
  46 Since version 2.18, NSSM can be configured to wait a user-specified amount\r
  47 of time for the application to exit when shutting down.\r
  48 \r
  49 Since version 2.19, many more service options can be configured with the\r
  50 GUI installer as well as via the registry.\r
  51 \r
  52 Since version 2.19, NSSM can add to the service's environment by setting\r
  53 AppEnvironmentExtra in place of or in addition to the srvany-compatible\r
  54 AppEnvironment.\r
  55 \r
  56 Since version 2.22, NSSM can rotate existing output files when redirecting I/O.\r
  57 \r
  58 Since version 2.22, NSSM can set service display name, description, startup\r
  59 type and log on details.\r
  60 \r
  61 \r
  62 Usage\r
  63 -----\r
  64 In the usage notes below, arguments to the program may be written in angle \r
  65 brackets and/or square brackets.  <string> means you must insert the \r
  66 appropriate string and [<string>] means the string is optional.  See the \r
  67 examples below...\r
  68 \r
  69 \r
  70 Installation using the GUI\r
  71 --------------------------\r
  72 To install a service, run\r
  73 \r
  74     nssm install <servicename>\r
  75 \r
  76 You will be prompted to enter the full path to the application you wish \r
  77 to run and any command line options to pass to that application.\r
  78 \r
  79 Use the system service manager (services.msc) to control advanced service \r
  80 properties such as startup method and desktop interaction.  NSSM may \r
  81 support these options at a later time...\r
  82 \r
  83 \r
  84 Installation using the command line\r
  85 -----------------------------------\r
  86 To install a service, run\r
  87 \r
  88     nssm install <servicename> <application> [<options>]\r
  89 \r
  90 NSSM will then attempt to install a service which runs the named application \r
  91 with the given options (if you specified any).\r
  92 \r
  93 Don't forget to enclose paths in "quotes" if they contain spaces!\r
  94 \r
  95 If you want to include quotes in the options you will need to """quote""" the\r
  96 quotes.\r
  97 \r
  98 \r
  99 Managing the service\r
 100 --------------------\r
 101 NSSM will launch the application listed in the registry when you send it a \r
 102 start signal and will terminate it when you send a stop signal.  So far, so \r
 103 much like srvany.  But NSSM is the Non-Sucking service manager and can take \r
 104 action if/when the application dies.\r
 105 \r
 106 With no configuration from you, NSSM will try to restart itself if it notices\r
 107 that the application died but you didn't send it a stop signal.  NSSM will\r
 108 keep trying, pausing between each attempt, until the service is successfully\r
 109 started or you send it a stop signal.\r
 110 \r
 111 NSSM will pause an increasingly longer time between subsequent restart attempts\r
 112 if the service fails to start in a timely manner, up to a maximum of four\r
 113 minutes.  This is so it does not consume an excessive amount of CPU time trying\r
 114 to start a failed application over and over again.  If you identify the cause\r
 115 of the failure and don't want to wait you can use the Windows service console\r
 116 (where the service will be shown in Paused state) to send a continue signal to\r
 117 NSSM and it will retry within a few seconds.\r
 118 \r
 119 By default, NSSM defines "a timely manner" to be within 1500 milliseconds.\r
 120 You can change the threshold for the service by setting the number of\r
 121 milliseconds as a REG_DWORD value in the registry at\r
 122 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppThrottle.\r
 123 \r
 124 NSSM will look in the registry under\r
 125 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppExit for\r
 126 string (REG_EXPAND_SZ) values corresponding to the exit code of the application.\r
 127 If the application exited with code 1, for instance, NSSM will look for a\r
 128 string value under AppExit called "1" or, if it does not find it, will\r
 129 fall back to the AppExit (Default) value.  You can find out the exit code\r
 130 for the application by consulting the system event log.  NSSM will log the\r
 131 exit code when the application exits.\r
 132 \r
 133 Based on the data found in the registry, NSSM will take one of three actions:\r
 134 \r
 135 If the value data is "Restart" NSSM will try to restart the application as\r
 136 described above.  This is its default behaviour.\r
 137 \r
 138 If the value data is "Ignore" NSSM will not try to restart the application\r
 139 but will continue running itself.  This emulates the (usually undesirable)\r
 140 behaviour of srvany.  The Windows Services console would show the service\r
 141 as still running even though the application has exited.\r
 142 \r
 143 If the value data is "Exit" NSSM will exit gracefully.  The Windows Services\r
 144 console would show the service as stopped.  If you wish to provide\r
 145 finer-grained control over service recovery you should use this code and\r
 146 edit the failure action manually.  Please note that Windows versions prior\r
 147 to Vista will not consider such an exit to be a failure.  On older versions\r
 148 of Windows you should use "Suicide" instead.\r
 149 \r
 150 If the value data is "Suicide" NSSM will simulate a crash and exit without\r
 151 informing the service manager.  This option should only be used for\r
 152 pre-Vista systems where you wish to apply a service recovery action.  Note\r
 153 that if the monitored application exits with code 0, NSSM will only honour a\r
 154 request to suicide if you explicitly configure a registry key for exit code 0.\r
 155 If only the default action is set to Suicide NSSM will instead exit gracefully.\r
 156 \r
 157 \r
 158 Stopping the service\r
 159 --------------------\r
 160 When stopping a service NSSM will attempt several different methods of killing\r
 161 the monitored application, each of which can be disabled if necessary.\r
 162 \r
 163 First NSSM will attempt to generate a Control-C event and send it to the\r
 164 application's console.  Batch scripts or console applications may intercept\r
 165 the event and shut themselves down gracefully.  GUI applications do not have\r
 166 consoles and will not respond to this method.\r
 167 \r
 168 Secondly NSSM will enumerate all windows created by the application and send\r
 169 them a WM_CLOSE message, requesting a graceful exit.\r
 170 \r
 171 Thirdly NSSM will enumerate all threads created by the application and send\r
 172 them a WM_QUIT message, requesting a graceful exit.  Not all applications'\r
 173 threads have message queues; those which do not will not respond to this\r
 174 method.\r
 175 \r
 176 Finally NSSM will call TerminateProcess() to request that the operating\r
 177 system forcibly terminate the application.  TerminateProcess() cannot be\r
 178 trapped or ignored, so in most circumstances the application will be killed.\r
 179 However, there is no guarantee that it will have a chance to perform any\r
 180 tidyup operations before it exits.\r
 181 \r
 182 Any or all of the methods above may be disabled.  NSSM will look for the\r
 183 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters\AppStopMethodSkip\r
 184 registry value which should be of type REG_DWORD set to a bit field describing\r
 185 which methods should not be applied.\r
 186 \r
 187   If AppStopMethodSkip includes 1, Control-C events will not be generated.\r
 188   If AppStopMethodSkip includes 2, WM_CLOSE messages will not be posted.\r
 189   If AppStopMethodSkip includes 4, WM_QUIT messages will not be posted.\r
 190   If AppStopMethodSkip includes 8, TerminateProcess() will not be called.\r
 191 \r
 192 If, for example, you knew that an application did not respond to Control-C\r
 193 events and did not have a thread message queue, you could set AppStopMethodSkip\r
 194 to 5 and NSSM would not attempt to use those methods to stop the application.\r
 195 \r
 196 Take great care when including 8 in the value of AppStopMethodSkip.  If NSSM\r
 197 does not call TerminateProcess() it is possible that the application will not\r
 198 exit when the service stops.\r
 199 \r
 200 By default NSSM will allow processes 1500ms to respond to each of the methods\r
 201 described above before proceeding to the next one.  The timeout can be\r
 202 configured on a per-method basis by creating REG_DWORD entries in the\r
 203 registry under HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
 204 \r
 205   AppStopMethodConsole\r
 206   AppStopMethodWindow\r
 207   AppStopMethodThreads\r
 208 \r
 209 Each value should be set to the number of milliseconds to wait.  Please note\r
 210 that the timeout applies to each process in the application's process tree,\r
 211 so the actual time to shutdown may be longer than the sum of all configured\r
 212 timeouts if the application spawns multiple subprocesses.\r
 213 \r
 214 \r
 215 I/O redirection\r
 216 ---------------\r
 217 NSSM can redirect the managed application's I/O to any path capable of being\r
 218 opened by CreateFile().  This enables, for example, capturing the log output\r
 219 of an application which would otherwise only write to the console or accepting\r
 220 input from a serial port.\r
 221 \r
 222 NSSM will look in the registry under\r
 223 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for the keys\r
 224 corresponding to arguments to CreateFile().  All are optional.  If no path is\r
 225 given for a particular stream it will not be redirected.  If a path is given\r
 226 but any of the other values are omitted they will be receive sensible defaults.\r
 227 \r
 228   AppStdin: Path to receive input.\r
 229   AppStdout: Path to receive output.\r
 230   AppStderr: Path to receive error output.\r
 231 \r
 232 Parameters for CreateFile() are providing with the "AppStdinShareMode",\r
 233 "AppStdinCreationDisposition" and "AppStdinFlagsAndAttributes" values (and\r
 234 analogously for stdout and stderr).\r
 235 \r
 236 In general, if you want the service to log its output, set AppStdout and\r
 237 AppStderr to the same path, eg C:\Users\Public\service.log, and it should\r
 238 work.  Remember, however, that the path must be accessible to the user\r
 239 running the service.\r
 240 \r
 241 \r
 242 File rotation\r
 243 -------------\r
 244 When using I/O redirection, NSSM can rotate existing output files prior to\r
 245 opening stdout and/or stderr.  An existing file will be renamed with a\r
 246 suffix based on the file's last write time, to millisecond precision.  For\r
 247 example, the file nssm.log might be rotated to nssm-20131221T113939.457.log.\r
 248 \r
 249 NSSM will look in the registry under\r
 250 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters for REG_DWORD\r
 251 entries which control how rotation happens.\r
 252 \r
 253 If AppRotateFiles is missing or set to 0, rotation is disabled.  Any non-zero\r
 254 value enables rotation.\r
 255 \r
 256 If AppRotateSeconds is non-zero, a file will not be rotated if its last write\r
 257 time is less than the given number of seconds in the past.\r
 258 \r
 259 If AppRotateBytes is non-zero, a file will not be rotated if it is smaller\r
 260 than the given number of bytes.  64-bit file sizes can be handled by setting\r
 261 a non-zero value of AppRotateBytesHigh.\r
 262 \r
 263 Rotation is independent of the CreateFile() parameters used to open the files.\r
 264 They will be rotated regardless of whether NSSM would otherwise have appended\r
 265 or replaced them.\r
 266 \r
 267 \r
 268 Environment variables\r
 269 ---------------------\r
 270 NSSM can replace or append to the managed application's environment.  Two\r
 271 multi-valued string (REG_MULTI_SZ) registry values are recognised under\r
 272 HKLM\SYSTEM\CurrentControlSet\Services\<service>\Parameters.\r
 273 \r
 274 AppEnvironment defines a list of environment variables which will override\r
 275 the service's environment.  AppEnvironmentExtra defines a list of\r
 276 environment variables which will be added to the service's environment.\r
 277 \r
 278 Each entry in the list should be of the form KEY=VALUE.  It is possible to\r
 279 omit the VALUE but the = symbol is mandatory.\r
 280 \r
 281 srvany only supports AppEnvironment.\r
 282 \r
 283 \r
 284 Removing services using the GUI\r
 285 -------------------------------\r
 286 NSSM can also remove services.  Run\r
 287 \r
 288     nssm remove <servicename>\r
 289 \r
 290 to remove a service.  You will prompted for confirmation before the service \r
 291 is removed.  Try not to remove essential system services...\r
 292 \r
 293 \r
 294 Removing service using the command line\r
 295 ---------------------------------------\r
 296 To remove a service without confirmation from the GUI, run\r
 297 \r
 298     nssm remove <servicename> confirm\r
 299 \r
 300 Try not to remove essential system services...\r
 301 \r
 302 \r
 303 Logging\r
 304 -------\r
 305 NSSM logs to the Windows event log.  It registers itself as an event log source\r
 306 and uses unique event IDs for each type of message it logs.  New versions may\r
 307 add event types but existing event IDs will never be changed.\r
 308 \r
 309 Because of the way NSSM registers itself you should be aware that you may not\r
 310 be able to replace the NSSM binary if you have the event viewer open and that\r
 311 running multiple instances of NSSM from different locations may be confusing if\r
 312 they are not all the same version.\r
 313 \r
 314 \r
 315 Example usage\r
 316 -------------\r
 317 To install an Unreal Tournament server:\r
 318 \r
 319     nssm install UT2004 c:\games\ut2004\system\ucc.exe server\r
 320 \r
 321 To remove the server:\r
 322 \r
 323     nssm remove UT2004 confirm\r
 324 \r
 325 \r
 326 Building NSSM from source\r
 327 -------------------------\r
 328 NSSM is known to compile with Visual Studio 2008.  Older Visual Studio\r
 329 releases may or may not work.\r
 330 \r
 331 NSSM will also compile with Visual Studio 2010 but the resulting executable\r
 332 will not run on versions of Windows older than XP SP2.  If you require\r
 333 compatiblity with older Windows releases you should change the Platform\r
 334 Toolset to v90 in the General section of the project's Configuration\r
 335 Properties.\r
 336 \r
 337 \r
 338 Credits\r
 339 -------\r
 340 Thanks to Bernard Loh for finding a bug with service recovery.\r
 341 Thanks to Benjamin Mayrargue (www.softlion.com) for adding 64-bit support.\r
 342 Thanks to Joel Reingold for spotting a command line truncation bug.\r
 343 Thanks to Arve Knudsen for spotting that child processes of the monitored\r
 344 application could be left running on service shutdown, and that a missing\r
 345 registry value for AppDirectory confused NSSM.\r
 346 Thanks to Peter Wagemans and Laszlo Keresztfalvi for suggesting throttling restarts.\r
 347 Thanks to Eugene Lifshitz for finding an edge case in CreateProcess() and for\r
 348 advising how to build messages.mc correctly in paths containing spaces.\r
 349 Thanks to Rob Sharp for pointing out that NSSM did not respect the\r
 350 AppEnvironment registry value used by srvany.\r
 351 Thanks to Szymon Nowak for help with Windows 2000 compatibility.\r
 352 Thanks to François-Régis Tardy for French translation.\r
 353 Thanks to Emilio Frini for spotting that French was inadvertently set as\r
 354 the default language when the user's display language was not translated.\r
 355 Thanks to Riccardo Gusmeroli for Italian translation.\r
 356 Thanks to Eric Cheldelin for the inspiration to generate a Control-C event\r
 357 on shutdown.\r
 358 Thanks to Brian Baxter for suggesting how to escape quotes from the command prompt.\r
 359 Thanks to Russ Holmann for suggesting that the shutdown timeout be configurable.\r
 360 Thanks to Paul Spause for spotting a bug with default registry entries.\r
 361 Thanks to BUGHUNTER for spotting more GUI bugs.\r
 362 Thanks to Doug Watson for suggesting file rotation.\r
 363 \r
 364 Licence\r
 365 -------\r
 366 NSSM is public domain.  You may unconditionally use it and/or its source code \r
 367 for any purpose you wish.\r