aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erlsrv.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erlsrv.xml')
-rw-r--r--erts/doc/src/erlsrv.xml405
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>
+