diff options
Diffstat (limited to 'erts/doc/src/erlsrv.xml')
| -rw-r--r-- | erts/doc/src/erlsrv.xml | 405 |
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®</comsummary> + <description> + <p>This utility is specific to Windows NT/2000/XP® (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® 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 ®.</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 + <servicename><c><![CDATA[.debug]]></c> or + <servicename><c><![CDATA[.debug.]]></c><N>, where <N> 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 + (<servicename><c><![CDATA[.debug]]></c>) and the <c><![CDATA[new]]></c> option + uses a separate log file for every invocation of the service + (<servicename><c><![CDATA[.debug.]]></c><N>). The <c><![CDATA[console]]></c> + option opens an interactive Windows® 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® 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® 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® 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} <service-name> [<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] [<erlang shell command>]</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] [<erl-command>]</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] [<variable>[=<value>]] ...</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 + <variable>=<value> and deleted from the list by + specifying <variable> 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] [<directory>]</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® default priority.</item> + <tag>{-sn[ame] | -n[ame]} [<node-name>]</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] [<limited erl arguments>]</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] [<internal name>]</tag> + <item><em>Only</em> allowed for <c>add</c>. Specifies a + Windows® 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] [<short description>]</tag> + <item>Specifies a textual comment describing the + service. This comment will show upp as the service description + in the Windows® service manager.</item> + </taglist> + </desc> + </func> + <func> + <name>erlsrv {start | stop | disable | enable} <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 <service-name></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 [<service-name>]</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> + |