erlsrv
(1)
Name
erlsrv - Run the Erlang emulator as a service on Windows
NT(R)
Synopsis
Please see following description for synopsis
Description
User Commands erlsrv(1)
NAME
erlsrv - Run the Erlang emulator as a service on Windows
NT(R)
DESCRIPTION
This utility is specific to Windows NT/2000/XP(R) (and sub-
sequent 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(R) services applet in a manner similar to other ser-
vices.
Note that erlsrv is not a general service utility for Win-
dows, but designed for embedded Erlang systems.
As well as being the actual service, erlsrv also provides a
command line interface for registering, changing, starting
and stopping services.
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 (R).
The processes created by the service can, as opposed to nor-
mal 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.
The following parameters may be specified for each Erlang
service:
* StopAction: This tells erlsrv how to stop the Erlang
emulator. Default is to kill it (Win32 TerminatePro-
cess), but this action can specify any Erlang shell com-
mand 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 emula-
tor is not stopped, it will report a running state to
the service manager.
* OnFail: This can be either of reboot, restart,
restart_always or ignore (the default). In case of
reboot, 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 what-
ever parameters are registered for the service at the
occasion) when it stops. If the emulator stops again
Ericsson AB Last change: erts 5.9.3.1 1
User Commands erlsrv(1)
within 10 seconds, it is not restarted to avoid an infi-
nite loop which could completely hang the NT system.
restart_always 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 man-
ually restarted.
On a system where release handling is used, this should
always be set to ignore. Use heart to restart the ser-
vice 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 should be set
to a program similar to start_erl.exe.
* Env: Specifies an additional environment for the emula-
tor. 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 spec-
ified in the service.
* WorkDir: 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 direc-
tory for services is %SystemDrive%%SystemPath%. Debug
log files will be placed in this directory.
* Priority: The process priority of the emulator, this can
be one of realtime, high, low or default (the default).
Real-time priority is not recommended, the machine will
possibly be inaccessible to interactive users. High pri-
ority 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 interac-
tive performance should not be affected by the emulator
process.
* SName or Name: Specifies the short or long node-name of
the Erlang emulator. The Erlang services are always dis-
tributed, default is to use the service name as (short)
node-name.
* DebugType: Can be one of none (default), new, reuse or
console. Specifies that output from the Erlang shell
Ericsson AB Last change: erts 5.9.3.1 2
User Commands erlsrv(1)
should be sent to a "debug log". The log file is named
<servicename>.debug or <servicename>.debug.<N>, where
<N> is an integer between 1 and 99. The log-file is
placed in the working directory of the service (as spec-
ified in WorkDir). The reuse option always reuses the
same log file (<servicename>.debug) and the new option
uses a separate log file for every invocation of the
service (<servicename>.debug.<N>). The console option
opens an interactive Windows(R) console window for the
Erlang shell of the service. The console option automat-
ically disables the StopAction and a service started
with an interactive console window will not survive
logouts, OnFail actions do not work with debug-consoles
either. If no DebugType is specified (none), the output
of the Erlang shell is discarded.
The consoleDebugType is not in any way intended for pro-
duction. It is only a convenient way to debug Erlang
services during development. The new and reuse 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 DebugType is intended for debugging
only. Logs during production are better produced with
the standard Erlang logging facilities.
* Args: Additional arguments passed to the emulator
startup program erl.exe (or start_erl.exe). Arguments
that cannot be specified here are -noinput (StopActions
would not work), -name and -sname (they are specified in
any way. The most common use is for specifying cookies
and flags to be passed to init:boot() (-s).
* InternalServiceName: Specifies the Windows(R) internal
service name (not the display name, which is the one
erlsrv uses to identify the service).
This internal name can not be changed, it is fixed even
if the service is renamed. Erlsrv generates a unique
internal name when a service is created, it is recom-
mended to keep to the defaut if release-handling is to
be used for the application.
The internal service name can be seen in the Windows(R)
service manager if viewing Properties for an erlang ser-
vice.
* Comment: A textual comment describing the service. Not
mandatory, but shows up as the service description in
the Windows(R) service manager.
Ericsson AB Last change: erts 5.9.3.1 3
User Commands erlsrv(1)
The naming of the service in a system that uses release han-
dling has to follow the convention NodeName_Release, where
NodeName is the first part of the Erlang nodename (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 adds or modifies a Erlang ser-
vice 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.
Every option can be given without parameters, in which
case the default value is applied. Values to the
options are supplied only when the default should not
be used (i.e. erlsrv set myservice -prio -arg sets the
default priority and removes all arguments).
The following service options are currently available:
-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}]:
Specifies the action to take when the Erlang emula-
tor stops unexpectedly. Default is to ignore.
-m[achine] [<erl-command>]:
The complete path to the Erlang emulator, never use
the werl program for this. Default is the erl.exe
in the same directory as erlsrv.exe. When release
handling is used, this should be set to a program
similar to start_erl.exe.
-e[nv] [<variable>[=<value>]] ...:
Edits the environment block for the service. Every
environment variable specified will add to the sys-
tem 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 envi-
ronment block is automatically sorted. Any number
of -env options can be specified in one command.
Default is to use the system environment block
unmodified (except for two additions, see below).
Ericsson AB Last change: erts 5.9.3.1 4
User Commands erlsrv(1)
-w[orkdir] [<directory>]:
The initial working directory of the Erlang emula-
tor. Default is the system directory.
-p[riority] [{low|high|realtime}]:
The priority of the Erlang emulator. The default is
the Windows(R) default priority.
{-sn[ame] | -n[ame]} [<node-name>]:
The node-name of the Erlang machine, distribution
is mandatory. Default is -sname <service name>.
-d[ebugtype] [{new|reuse|console}]:
Specifies where shell output should be sent,
default is that shell output is discarded. To be
used only for debugging.
-ar[gs] [<limited erl arguments>]:
Additional arguments to the Erlang emulator, avoid
-noinput, -noshell and -sname/-name. 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.
-i[nternalservicename] [<internal name>]:
Only allowed for add. Specifies a Windows(R) inter-
nal service name for the service, which by default
is set to something unique (prefixed with the orig-
inal service name) by erlsrv when adding a new ser-
vice. Specifying this is a purely cosmethic 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 ser-
vice 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 will show upp as the service descrip-
tion in the Windows(R) service manager.
erlsrv {start | start_disabled | stop | disable | enable}
<service-name>
These commands are only added for convenience, the nor-
mal way to manipulate the state of a service is through
Ericsson AB Last change: erts 5.9.3.1 5
User Commands erlsrv(1)
the control panels services applet. The start and stop
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.
The start_disabled command operates on a service
regardless of if it's enabled/disabled or
started/stopped. It does this by first enabling it
(regardless of if it's enabled or not), then starting
it (if it's not already started) and then disabling it.
The result will be a disabled but started service,
regardless of its earlier 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>
This command removes the service completely with all
its registered options. It will be stopped before it is
removed.
erlsrv list [<service-name>]
If no service name is supplied, a brief listing of all
Erlang services is presented. If a service-name is sup-
plied, all options for that service are presented.
erlsrv help
ENVIRONMENT
The environment of an Erlang machine started as a service
will contain two special variables, ERLSRV_SERVICE_NAME,
which is the name of the service that started the machine
and ERLSRV_EXECUTABLE which is the full path to the erl-
srv.exe 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:
@echo off
%ERLSRV_EXECUTABLE% stop %ERLSRV_SERVICE_NAME%
%ERLSRV_EXECUTABLE% start %ERLSRV_SERVICE_NAME%
Ericsson AB Last change: erts 5.9.3.1 6
User Commands erlsrv(1)
This command file is then set as heart command.
The environment variables can also be used to detect that we
are running as a service and make port programs react cor-
rectly to the control events generated on logout (see
below).
PORT PROGRAMS
When a program runs in the service context, it has to handle
the control events that is sent to every program in the sys-
tem when the interactive user logs off. This is done in dif-
ferent 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 pro-
grams) uses the win32 function SetConsoleCtrlHandler to reg-
ister a control handler that returns TRUE in answer to the
CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT events. Other
applications just forward WM_ENDSESSION and WM_QUERYENDSES-
SION to the default window procedure. Here is a brief exam-
ple 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);
}
}
ATTRIBUTES
See attributes(5) for descriptions of the following
Ericsson AB Last change: erts 5.9.3.1 7
User Commands erlsrv(1)
attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/erlang |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
NOTES
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.
Note that the program resides in the emulators bin-direc-
tory, not in the bin-directory directly under the Erlang
root. The reasons for this are the subtle problem of upgrad-
ing 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 easily manipulate the Erlang services, 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. It is also worth mentioning again that the name of
the service is significant (see above).
SEE ALSO
start_erl(1), release_handler(3)
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://www.erlang.org/download/otp_src_R15B03-1.tar.gz
Further information about this software can be found on the
open source community website at http://www.erlang.org/.
Ericsson AB Last change: erts 5.9.3.1 8