Describe startup environment in the README.

[nssm.git] / README.txt

diff --git a/README.txt b/README.txt
index f48a7f1..224af93 100644 (file)
--- a/README.txt
+++ b/README.txt
@@ -406,6 +406,59 @@ application to fail to start.
 Most people will want to use AppEnvironmentExtra exclusively.  srvany only\r
 supports AppEnvironment.\r
 \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
 \r
 Event hooks\r
 -----------\r


@@ -555,6 +608,7 @@ run NSSM itself.  The parameters recognised are as follows:
 \r
   Description: Service description.\r
   DisplayName: Service display name.\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
   ImagePath: Path to the service executable.\r
   ObjectName: User account which runs the service.\r
   Name: Service key name.\r