The R13B03 release.OTP_R13B03

1 files changed, 405 insertions, 0 deletions

diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml
new file mode 100644
index 0000000000..93db56fc7c
--- /dev/null
+++ b/erts/doc/src/erlsrv.xml
@@ -0,0 +1,405 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE comref SYSTEM "comref.dtd">
+
+<comref>
+  <header>
+    <copyright>
+      <year>1998</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>erlsrv</title>
+    <prepared>Patrik Nyblom</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>98-04-29</date>
+    <rev></rev>
+    <file>erlsrv.xml</file>
+  </header>
+  <com>erlsrv</com>
+  <comsummary>Run the Erlang emulator as a service on Windows NT&reg;</comsummary>
+  <description>
+    <p>This utility is specific to Windows NT/2000/XP&reg; (and subsequent versions of Windows) It allows Erlang
+      emulators to run as services on the Windows system, allowing embedded
+      systems to start without any user needing to log in. The
+      emulator started in this way can be manipulated through the
+      Windows&reg; services applet in a manner similar to other
+      services.</p>
+    <p>Note that erlsrv is not a general service utility for Windows, but designed for embedded Erlang systems.</p> 
+    <p>As well as being the actual service, erlsrv also provides a
+      command line interface for registering, changing, starting and
+      stopping services.</p>
+    <p>To manipulate services, the logged in user should have
+      Administrator privileges on the machine. The Erlang machine
+      itself is (default) run as the local administrator. This can be
+      changed with the Services applet in Windows &reg;.</p>
+    <p>The processes created by the service can, as opposed to normal
+      services, be "killed" with the task manager. Killing a emulator
+      that is started by a service will trigger the "OnFail" action
+      specified for that service, which may be a reboot.</p>
+    <p>The following parameters may be specified for each Erlang
+      service:</p>
+    <list type="bulleted">
+      <item>
+        <p><c><![CDATA[StopAction]]></c>: This tells <c><![CDATA[erlsrv]]></c> how to stop
+          the Erlang emulator. Default is to kill it (Win32
+          TerminateProcess), but this action can specify any Erlang
+          shell command that will be executed in the emulator to make
+          it stop. The emulator is expected to stop within 30 seconds
+          after the command is issued in the shell. If the emulator is
+          not stopped, it will report a running state to the service
+          manager.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[OnFail]]></c>: This can be either of <c><![CDATA[reboot]]></c>,
+          <c><![CDATA[restart]]></c>, <c><![CDATA[restart_always]]></c> or <c><![CDATA[ignore]]></c> (the
+          default). In case of <c><![CDATA[reboot]]></c>, the NT system is
+          rebooted whenever the emulator stops (a more simple form of
+          watchdog), this could be useful for less critical systems,
+          otherwise use the heart functionality to accomplish
+          this. The restart value makes the Erlang emulator be
+          restarted (with whatever parameters are registered for the
+          service at the occasion) when it stops. If the emulator
+          stops again within 10 seconds, it is not restarted to avoid
+          an infinite loop which could completely hang the NT
+          system. <c><![CDATA[restart_always]]></c> is similar to restart, but
+          does not try to detect cyclic restarts, it is expected that
+          some other mechanism is present to avoid the problem.  The
+          default (ignore) just reports the service as stopped to the
+          service manager whenever it fails, it has to be manually
+          restarted.</p>
+        <p>On a system where release handling is
+          used, this should always be set to <c><![CDATA[ignore]]></c>. Use
+          <c><![CDATA[heart]]></c> to restart the service on failure instead.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[Machine]]></c>: The location of the Erlang
+          emulator. The default is the <c><![CDATA[erl.exe]]></c> located in the
+          same directory as erlsrv.exe. Do not specify <c><![CDATA[werl.exe]]></c>
+          as this emulator, it will not work.</p>
+        <p>If the system
+          uses release handling, this should be set to a program
+          similar to <c><![CDATA[start_erl.exe]]></c>.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[Env]]></c>: Specifies an <em>additional</em> environment
+          for the emulator. The environment variables specified
+          here are added to the system wide environment block that is
+          normally present when a service starts up. Variables present
+          in both the system wide environment and in the service
+          environment specification will be set to the value specified
+          in the service.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[WorkDir]]></c>: The working directory for the Erlang
+          emulator, has to be on a local drive (there are no network
+          drives mounted when a service starts). Default working
+          directory for services is <c><![CDATA[%SystemDrive%%SystemPath%]]></c>.
+          Debug log files will be placed in this directory.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[Priority]]></c>: The process priority of the emulator,
+          this can be one of <c><![CDATA[realtime]]></c>, <c><![CDATA[high]]></c>, <c><![CDATA[low]]></c>
+          or <c><![CDATA[default]]></c> (the default). Real-time priority is not
+          recommended, the machine will possibly be inaccessible to
+          interactive users. High priority could be used if two Erlang
+          nodes should reside on one dedicated system and one should
+          have precedence over the other. Low process priority may be
+          used if interactive performance should not be affected by
+          the emulator process.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[SName or Name]]></c>: Specifies the short or long
+          node-name of the Erlang emulator. The Erlang services are
+          always distributed, default is to use the service name as
+          (short) node-name.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[DebugType]]></c>: Can be one of <c><![CDATA[none]]></c> (default),
+          <c><![CDATA[new]]></c>, <c><![CDATA[reuse]]></c> or <c><![CDATA[console]]></c>.
+          Specifies that output from the Erlang shell should be
+          sent to a "debug log". The log file is named
+          &lt;servicename&gt;<c><![CDATA[.debug]]></c> or
+          &lt;servicename&gt;<c><![CDATA[.debug.]]></c>&lt;N&gt;, where &lt;N&gt; is
+          an integer between 1 and 99. The log-file is placed in the
+          working directory of the service (as specified in WorkDir). The
+          <c><![CDATA[reuse]]></c> option always reuses the same log file
+          (&lt;servicename&gt;<c><![CDATA[.debug]]></c>) and the <c><![CDATA[new]]></c> option
+          uses a separate log file for every invocation of the service
+          (&lt;servicename&gt;<c><![CDATA[.debug.]]></c>&lt;N&gt;). The <c><![CDATA[console]]></c>
+          option opens an interactive Windows&reg; console window for
+          the Erlang shell of the service. The <c><![CDATA[console]]></c> option 
+          automatically
+          disables the <c><![CDATA[StopAction]]></c> and a service started with an
+          interactive console window will not survive logouts, 
+          <c><![CDATA[OnFail]]></c> actions do not work with debug-consoles either.
+          If no <c><![CDATA[DebugType]]></c> is specified (<c><![CDATA[none]]></c>), the
+          output of the Erlang shell is discarded.</p>
+        <p>The <c><![CDATA[console]]></c><c><![CDATA[DebugType]]></c> is <em>not in any way</em>
+          intended for production. It is <em>only</em> a convenient way to
+          debug Erlang services during development. The <c><![CDATA[new]]></c> and
+          <c><![CDATA[reuse]]></c> options might seem convenient to have in a
+          production system, but one has to take into account that the
+          logs will grow indefinitely during the systems lifetime and
+          there is no way, short of restarting the service, to
+          truncate those logs. In short, the <c><![CDATA[DebugType]]></c> is
+          intended for debugging only. Logs during production are
+          better produced with the standard Erlang logging
+          facilities.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[Args]]></c>: Additional arguments passed to the
+          emulator startup program <c><![CDATA[erl.exe]]></c> (or
+          <c><![CDATA[start_erl.exe]]></c>).  Arguments that cannot be specified
+          here are <c><![CDATA[-noinput]]></c> (StopActions would not work),
+          <c><![CDATA[-name]]></c> and <c><![CDATA[-sname]]></c> (they are specified in any
+          way. The most common use is for specifying cookies and flags
+          to be passed to init:boot() (<c><![CDATA[-s]]></c>).</p>
+      </item>
+      <item>
+        <p><c><![CDATA[InternalServiceName]]></c>: Specifies the Windows&reg; internal service name (not the display name, which is the one <c>erlsrv</c> uses to identify the service).</p>
+	<p>This internal name can not be changed, it is fixed even if the service is renamed. <c>Erlsrv</c> generates a unique internal name when a service is created, it is recommended to keep to the defaut if release-handling is to be used for the application.</p>
+	<p>The internal service name can be seen in the Windows&reg; service manager if viewing <c>Properties</c> for an erlang service.</p>
+      </item>
+      <item>
+        <p><c><![CDATA[Comment]]></c>: A textual comment describing the service. Not mandatory, but shows up as the service description in the Windows&reg; service manager.</p>
+      </item>
+    </list>
+    <p>      <marker id="001"></marker>
+ The naming of the service in a system that
+      uses release handling has to follow the convention
+      <em>NodeName</em>_<em>Release</em>, where <em>NodeName</em> is
+      the first part of the Erlang nodename (up to, but not including
+      the "@") and <em>Release</em> is the current release of the
+      application.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>erlsrv {set | add} &lt;service-name> [&lt;service options>]</name>
+      <fsummary>Add or modify an Erlang service</fsummary>
+      <desc>
+        <p>The set and add commands adds or modifies a Erlang service
+          respectively.  The simplest form of an add command would be
+          completely without options in which case all default values
+          (described above) apply. The service name is mandatory.</p>
+        <p>Every option can be given without parameters, in which case
+          the default value is applied. Values to the options are
+          supplied <em>only</em> when the default should not be used
+          (i.e. <c><![CDATA[erlsrv set myservice -prio -arg]]></c> sets the
+          default priority and removes all arguments).</p>
+        <p>The following service options are currently available:</p>
+        <taglist>
+          <tag>-st[opaction] [&lt;erlang shell command&gt;]</tag>
+          <item>Defines the StopAction, the command given to the Erlang
+           shell when the service is stopped. Default is none.</item>
+          <tag>-on[fail] [{reboot | restart | restart_always}]</tag>
+          <item>Specifies the action to take when the Erlang emulator
+           stops unexpectedly. Default is to ignore.</item>
+          <tag>-m[achine] [&lt;erl-command&gt;]</tag>
+          <item>The complete path to the Erlang emulator, never use the
+           werl program for this. Default is the <c><![CDATA[erl.exe]]></c> in the
+           same directory as <c><![CDATA[erlsrv.exe]]></c>. When release handling
+           is used, this should be set to a program similar to
+          <c><![CDATA[start_erl.exe]]></c>.</item>
+          <tag>-e[nv] [&lt;variable&gt;[=&lt;value&gt;]] ...</tag>
+          <item>Edits the environment block for the service. Every
+           environment variable specified will add to the system
+           environment block. If a variable specified here has the same
+           name as a system wide environment variable, the specified
+           value overrides the system wide.  Environment variables are
+           added to this list by specifying
+           &lt;variable&gt;=&lt;value&gt; and deleted from the list by
+           specifying &lt;variable&gt; alone. The environment block is
+           automatically sorted. Any number of <c><![CDATA[-env]]></c> options can
+           be specified in one command. Default is to use the system
+           environment block unmodified (except for two additions, see
+          <seealso marker="#002">below</seealso>).</item>
+          <tag>-w[orkdir] [&lt;directory&gt;]</tag>
+          <item>The initial working directory of the Erlang
+           emulator. Default is the system directory.</item>
+          <tag>-p[riority] [{low|high|realtime}]</tag>
+          <item>The priority of the Erlang emulator. The default is the
+           Windows&reg; default priority.</item>
+          <tag>{-sn[ame] | -n[ame]} [&lt;node-name&gt;]</tag>
+          <item>The node-name of the Erlang machine, distribution is
+           mandatory. Default is <c><![CDATA[-sname <service name>]]></c>.
+          </item>
+          <tag>-d[ebugtype] [{new|reuse|console}]</tag>
+          <item>Specifies where shell output should be sent,
+           default is that shell output is discarded. 
+           To be used only for debugging.</item>
+          <tag>-ar[gs] [&lt;limited erl arguments&gt;]</tag>
+          <item>Additional arguments to the Erlang emulator, avoid
+          <c><![CDATA[-noinput]]></c>, <c><![CDATA[-noshell]]></c> and
+          <c><![CDATA[-sname]]></c>/<c><![CDATA[-name]]></c>. Default is no additional
+           arguments. Remember that the services cookie file is not
+           necessarily the same as the interactive users. The service
+           runs as the local administrator. All arguments should be given
+           together in one string, use double quotes (") to give an
+           argument string containing spaces and use quoted quotes (\\")
+           to give an quote within the argument string if
+           necessary.</item>
+	   <tag>-i[nternalservicename] [&lt;internal name&gt;]</tag>
+           <item><em>Only</em> allowed for <c>add</c>. Specifies a
+           Windows&reg; internal service name for the service, which by
+           default is set to something unique (prefixed with the
+           original service name) by erlsrv when adding a new
+           service. Specifying this is a purely cosmethic action and is
+           <em>not</em> recommended if release handling is to be
+           performed. The internal service name cannot be changed once
+           the service is created. The internal name is <em>not</em> to 
+	   be confused with the ordinary service name, which is the name 
+	   used to identify a service to erlsrv.</item>
+	   <tag>-c[omment] [&lt;short description&gt;]</tag>
+           <item>Specifies a textual comment describing the
+           service. This comment will show upp as the service description
+           in the Windows&reg; service manager.</item>
+        </taglist>
+      </desc>
+    </func>
+    <func>
+      <name>erlsrv {start | stop | disable | enable} &lt;service-name></name>
+      <fsummary>Manipulate the current service status.</fsummary>
+      <desc>
+        <p>These commands are only added for convenience, the normal
+          way to manipulate the state of a service is through the
+          control panels services applet. The <c><![CDATA[start]]></c> and
+          <c><![CDATA[stop]]></c> commands communicates
+          with the service manager for stopping and starting a
+          service. The commands wait until the service is actually
+          stopped or started. When disabling a service, it is not
+          stopped, the disabled state will not take effect until the
+          service actually is stopped. Enabling a service sets it in
+          automatic mode, that is started at boot. This command cannot
+          set the service to manual.  </p>
+      </desc>
+    </func>
+    <func>
+      <name>erlsrv remove &lt;service-name&gt;</name>
+      <fsummary>Remove the service.</fsummary>
+      <desc>
+        <p>This command removes the service completely with all its registered
+          options. It will be stopped before it is removed.</p>
+      </desc>
+    </func>
+    <func>
+      <name>erlsrv list [&lt;service-name&gt;]</name>
+      <fsummary>List all Erlang services or all options for one service.</fsummary>
+      <desc>
+        <p>If no service name is supplied, a brief listing of all Erlang services
+          is presented. If a service-name is supplied, all options for that
+          service are presented.</p>
+      </desc>
+    </func>
+    <func>
+      <name>erlsrv help</name>
+      <fsummary>Display a brief help text</fsummary>
+    </func>
+  </funcs>
+
+  <section>
+    <title>ENVIRONMENT</title>
+    <p>      <marker id="002"></marker>
+The environment of an Erlang machine started
+      as a service will contain two special variables,
+      <c><![CDATA[ERLSRV_SERVICE_NAME]]></c>, which is the name of the service that
+      started the machine and <c><![CDATA[ERLSRV_EXECUTABLE]]></c> which is the
+      full path to the <c><![CDATA[erlsrv.exe]]></c> that can be used to manipulate
+      the service. This will come in handy when defining a heart command for
+      your service. A command file for restarting a service will
+      simply look like this:</p>
+    <code type="none"><![CDATA[
+@echo off
+%ERLSRV_EXECUTABLE% stop %ERLSRV_SERVICE_NAME%
+%ERLSRV_EXECUTABLE% start %ERLSRV_SERVICE_NAME%    ]]></code>
+    <p>This command file is then set as heart command.</p>
+    <p>The environment variables can also be used to detect that we
+      are running as a service and make port programs react correctly
+      to the control events generated on logout (see below).</p>
+  </section>
+
+  <section>
+    <title>PORT PROGRAMS</title>
+    <p>When a program runs in
+      the service context, it has to handle the control events that is
+      sent to every program in the system when the interactive user
+      logs off. This is done in different ways for programs running in
+      the console subsystem and programs running as window
+      applications. An application which runs in the console subsystem
+      (normal for port programs) uses the win32 function
+      <c><![CDATA[SetConsoleCtrlHandler]]></c> to a control handler that returns
+      TRUE in answer to the <c><![CDATA[CTRL_LOGOFF_EVENT]]></c>. Other
+      applications just forward <c><![CDATA[WM_ENDSESSION]]></c> and
+      <c><![CDATA[WM_QUERYENDSESSION]]></c> to the default window procedure. Here
+      is a brief example in C of how to set the console control
+      handler:</p>
+    <code type="none"><![CDATA[
+#include <windows.h>
+/* 
+** A Console control handler that ignores the log off events,
+** and lets the default handler take care of other events.
+*/   
+BOOL WINAPI service_aware_handler(DWORD ctrl){
+    if(ctrl == CTRL_LOGOFF_EVENT)
+\011return TRUE;
+    return FALSE;
+}
+
+void initialize_handler(void){
+    char buffer[2];
+    /* 
+     * We assume we are running as a service if this  
+     * environment variable is defined
+     */
+    if(GetEnvironmentVariable("ERLSRV_SERVICE_NAME",buffer,
+                              (DWORD) 2)){
+\011/*
+\011** Actually set the control handler
+\011*/
+\011SetConsoleCtrlHandler(&service_aware_handler, TRUE);
+    }
+}    ]]></code>
+  </section>
+
+  <section>
+    <title>NOTES</title>
+    <p>Even though the options are described in a Unix-like format, the case of
+      the options or commands is not relevant, and the "/" character for options
+      can be used as well as the "-" character. </p>
+    <p>Note that the program resides in the emulators
+      <c><![CDATA[bin]]></c>-directory, not in the <c><![CDATA[bin]]></c>-directory directly under
+      the Erlang root. The reasons for this are the subtle problem of
+      upgrading the emulator on a running system, where a new version of
+      the runtime system should not need to overwrite existing (and probably
+      used) executables.</p>
+    <p>To easily manipulate the Erlang services, put
+      the <c><![CDATA[<erlang_root>\\erts-<version>\\bin]]></c> directory in
+      the path instead of <c><![CDATA[<erlang_root>\\bin]]></c>. The erlsrv program
+      can be found from inside Erlang by using the
+      <c><![CDATA[os:find_executable/1]]></c> Erlang function.</p>
+    <p>For release handling to work, use <c><![CDATA[start_erl]]></c> as the Erlang
+      machine. It is also worth mentioning again that the name of the 
+      service is significant (see <seealso marker="#001">above</seealso>).</p>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>start_erl(1), release_handler(3)</p>
+  </section>
+</comref>
+