erlsrv - Run the Erlang emulator as a service on Windows
Please see following description for synopsis
erlsrv(1) User Commands erlsrv(1)
NAME
erlsrv - Run the Erlang emulator as a service on Windows
DESCRIPTION
This utility is specific to Windows NT/2000/XP (and later 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 on. The emulator started in this way can be manipulated through the
Windows services applet in a manner similar to other services.
Notice that erlsrv is not a general service utility for Windows, but
designed for embedded Erlang systems.
erlsrv also provides a command-line interface for registering, chang-
ing, starting, and stopping services.
To manipulate services, the logged on user is to 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.
The processes created by the service can, as opposed to normal ser-
vices, be "killed" with the task manager. Killing an emulator that is
started by a service triggers the "OnFail" action specified for that
service, which can be a reboot.
The following parameters can be specified for each Erlang service:
StopAction:
Tells erlsrv 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
reports a running state to the service manager.
OnFail:
Can be one of the following:
reboot:
The Windows system is rebooted whenever the emulator stops (a
more simple form of watchdog). This can be useful for less criti-
cal systems, otherwise use the heart functionality to accomplish
this.
restart:
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 hang the Windows system.
restart_always:
Similar to restart, but does not try to detect cyclic restarts;
it is expected that some other mechanism is present to avoid the
problem.
ignore (the default):
Reports the service as stopped to the service manager whenever it
fails; it must be manually restarted.
On a system where release handling is used, this is always to be
set to ignore. Use heart to restart the service on failure instead.
Machine:
The location of the Erlang emulator. The default is the erl.exe
located in the same directory as erlsrv.exe. Do not specify
werl.exe as this emulator, it will not work.
If the system uses release handling, this is to be set to a program
similar to start_erl.exe.
Env:
Specifies an extra 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.
WorkDir:
The working directory for the Erlang emulator. Must be on a local
drive (no network drives are mounted when a service starts).
Default working directory for services is %SystemDrive%%System-
Path%. Debug log files will be placed in this directory.
Priority:
The process priority of the emulator. Can be one of the following:
realtime:
Not recommended, as the machine will possibly be inaccessible to
interactive users.
high:
Can be used if two Erlang nodes are to reside on one dedicated
system and one is to have precedence over the other.
low:
Can be used if interactive performance is not to be affected by
the emulator process.
default (the default>:
SName or Name:
Specifies the short or long node name of the Erlang emulator. The
Erlang services are always distributed. Default is to use the ser-
vice name as (short) nodename.
DebugType:
Specifies that output from the Erlang shell is to be sent to a
"debug log". The log file is named <servicename>.debug or <service-
name>.debug.<N>, where <N> is an integer from 1 through 99. The log
file is placed in the working directory of the service (as speci-
fied in WorkDir).
Can be one of the following:
new:
Uses a separate log file for every invocation of the service
(<servicename>.debug.<N>).
reuse:
Reuses the same log file (<servicename>.debug).
console:
Opens an interactive Windows console window for the Erlang shell
of the service. Automatically disables the StopAction. A service
started with an interactive console window does not survive
logouts. OnFail actions do not work with debug consoles either.
none (the default):
The output of the Erlang shell is discarded.
Note:
The console option is not intended for production. It is only a con-
venient way to debug Erlang services during development.
The new and reuse options might seem convenient in a production sys-
tem, but consider that the logs grow indefinitely during the system
lifetime and cannot be truncated, except if the service is restarted.
In short, the DebugType is intended for debugging only. Logs during
production are better produced with the standard Erlang logging
facilities.
Args:
Passes extra arguments to the emulator startup program erl.exe (or
start_erl.exe). Arguments that cannot be specified here are -noin-
put (StopActions would not work), -name, and -sname (they are spec-
ified in any way). The most common use is for specifying cookies
and flags to be passed to init:boot() (-s).
InternalServiceName:
Specifies the Windows-internal service name (not the display name,
which is the one erlsrv uses to identify the service).
This internal name cannot be changed, it is fixed even if the ser-
vice is renamed. erlsrv generates a unique internal name when a
service is created. It is recommended to keep to the default if
release handling is to be used for the application.
The internal service name can be seen in the Windows service man-
ager if viewing Properties for an Erlang service.
Comment:
A textual comment describing the service. Not mandatory, but shows
up as the service description in the Windows service manager.
The naming of the service in a system that uses release handling must
follow the convention NodeName_Release, where NodeName is the first
part of the Erlang node name (up to, but not including the "@") and
Release is the current release of the application.
EXPORTS
erlsrv {set | add} <service-name> [<service options>]
The set and add commands modifies or adds an Erlang service,
respectively. The simplest form of an add command is without any
options in which case all default values (described above)
apply. The service name is mandatory.
Every option can be specified without parameters, the default
value is then applied. Values to the options are supplied only
when the default is not to be used. For example, erlsrv set
myservice -prio -arg sets the default priority and removes all
arguments.
Service options:
-st[opaction] [<erlang shell command>]:
Defines the StopAction, the command given to the Erlang
shell when the service is stopped. Default is none.
-on[fail] [{reboot | restart | restart_always}]:
The action to take when the Erlang emulator stops unexpect-
edly. Default is to ignore.
-m[achine] [<erl-command>]:
The complete path to the Erlang emulator. Never use the werl
program for this. Defaults to the erl.exe in the same direc-
tory as erlsrv.exe. When release handling is used, this is
to be set to a program similar to start_erl.exe.
-e[nv] [<variable>[=<value>]] ...:
Edits the environment block for the service. Every environ-
ment variable specified is added to the system environment
block. If a variable specified here has the same name as a
system-wide environment variable, the specified value over-
rides 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 -env options
can be specified in one command. Default is to use the sys-
tem environment block unmodified (except for two additions,
see section Environment below).
-w[orkdir] [<directory>]:
The initial working directory of the Erlang emulator.
Defaults to the system directory.
-p[riority] [{low|high|realtime}]:
The priority of the Erlang emulator. Default to the Windows
default priority.
{-sn[ame] | -n[ame]} [<node-name>]:
The node name of the Erlang machine. Distribution is manda-
tory. Defaults to -sname <service name>.
-d[ebugtype] [{new|reuse|console}]:
Specifies where shell output is to be sent. Default is that
shell output is discarded. To be used only for debugging.
-ar[gs] [<limited erl arguments>]:
Extra arguments to the Erlang emulator. Avoid -noinput,
-noshell, and -sname/-name. Default is no extra arguments.
Remember that the services cookie file is not necessarily
the same as the interactive users. The service runs as the
local administrator. Specify all arguments together in one
string, use double quotes (") to specify an argument string
containing spaces, and use quoted quotes (\") to specify a
quote within the argument string if necessary.
-i[nternalservicename] [<internal name>]:
Only allowed for add. 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 cos-
methic action and is not recommended if release handling is
to be performed. The internal service name cannot be changed
once the service is created. The internal name is not to be
confused with the ordinary service name, which is the name
used to identify a service to erlsrv.
-c[omment] [<short description>]:
Specifies a textual comment describing the service. This
comment shows up as the service description in the Windows
service manager.
erlsrv {start | start_disabled | stop | disable | enable} <service-
name>
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 start and stop commands communicates with the service man-
ager for starting and stopping a service. The commands wait
until the service is started or stopped. When disabling a ser-
vice, it is not stopped, the disabled state does not take effect
until the service is stopped. Enabling a service sets it in
automatic mode, which is started at boot. This command cannot
set the service to manual.
The start_disabled command operates on a service regardless of
if it is enabled/disabled or started/stopped. It does this by
first enabling it (regardless of if it is enabled or not), then
starting it (if not already started), and then disabling it. The
result is a disabled but started service, regardless of its ear-
lier state. This is useful for starting services temporarily
during a release upgrade. The difference between using
start_disabled and the sequence enable, start, and disable is
that all other erlsrv commands are locked out during the
sequence of operations in start_disable, making the operation
atomic from an erlsrv user's point of view.
erlsrv remove <service-name>
Removes the service completely with all its registered options.
It is stopped before it is removed.
erlsrv list [<service-name>]
If no service name is specified, a brief listing of all Erlang
services is presented. If a service name is supplied, all
options for that service are presented.
erlsrv help
Displays a brief help text.
ENVIRONMENT
The environment of an Erlang machine started as a service contains two
special variables:
ERLSRV_SERVICE_NAME:
The name of the service that started the machine.
ERLSRV_EXECUTABLE:
The full path to the erlsrv.exe, which can be used to manipulate
the service. This comes in handy when defining a heart command for
your service.
A command file for restarting a service looks as follows:
@echo off
%ERLSRV_EXECUTABLE% stop %ERLSRV_SERVICE_NAME%
%ERLSRV_EXECUTABLE% start %ERLSRV_SERVICE_NAME%
This command file is then set as heart command.
The environment variables can also be used to detect that we are run-
ning as a service and make port programs react correctly to the control
events generated on logout (see the next section).
PORT PROGRAMS
When a program runs in the service context, it must handle the control
events that are sent to every program in the system when the interac-
tive user logs off. This is done in different ways for programs running
in the console subsystem and programs running as window applications.
An application running in the console subsystem (normal for port pro-
grams) uses the win32 function SetConsoleCtrlHandler to register a con-
trol handler that returns true in answer to the CTRL_LOGOFF_EVENT and
CTRL_SHUTDOWN_EVENT events. Other applications only forward WM_ENDSES-
SION and WM_QUERYENDSESSION to the default window procedure.
A brief example in C of how to set the console control handler:
#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)
return TRUE;
if(ctrl == CTRL_SHUTDOWN_EVENT)
return 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)){
/*
** Actually set the control handler
*/
SetConsoleCtrlHandler(&service_aware_handler, TRUE);
}
}
NOTES
Although the options are described in a Unix-like format, the case of
the options or commands is not relevant, and both character "/" and "-"
can be used for options.
Notice that the program resides in the emulator's bin directory, not in
the bin 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.
To manipulate the Erlang services easily, put the
<erlang_root>\erts-<version>\bin directory in the path instead of
<erlang_root>\bin. The erlsrv program can be found from inside Erlang
by using the os:find_executable/1 Erlang function.
For release handling to work, use start_erl as the Erlang machine. As
stated above, the service name is significant.
SEE ALSO
start_erl(1), release_handler(3)
Ericsson AB erts 12.2 erlsrv(1)