erlsrv - Run the Erlang emulator as a service on Windows NT(R)
Please see following description for synopsis
erlsrv(1) 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 subsequent ver-
sions 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
services.
Note that erlsrv is not a general service utility for Windows, 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 ser-
vices.
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 normal ser-
vices, 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 TerminateProcess), but this action can
specify any Erlang shell command that will be executed in the emu-
lator 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 man-
ager.
* 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 whatever parameters are regis-
tered for the service at the occasion) when it stops. If the emula-
tor stops again within 10 seconds, it is not restarted to avoid an
infinite 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 manually restarted.
On a system where release handling is used, this should always 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 should be set to a pro-
gram similar to start_erl.exe.
* Env: Specifies an additional 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, has to be
on a local drive (there are no network drives mounted when a ser-
vice starts). Default working directory for services is %System-
Drive%%SystemPath%. Debug log files will be placed in this direc-
tory.
* 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 priority could be used if two Erlang nodes
should reside on one dedicated system and one should have prece-
dence 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 distributed, 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 should be sent to a
"debug log". The log file is named <servicename>.debug or <service-
name>.debug.<N>, where <N> is an integer between 1 and 99. The log-
file is placed in the working directory of the service (as speci-
fied 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 automatically
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 production. It
is only a convenient way to debug Erlang services during develop-
ment. 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 ser-
vice is renamed. Erlsrv 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.
The internal service name can be seen in the Windows(R) service
manager 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(R) service
manager.
The naming of the service in a system that uses release handling 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 service
respectively. The simplest form of an add command would be com-
pletely 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 myser-
vice -prio -arg sets the default priority and removes all argu-
ments).
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 emulator 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 direc-
tory 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 environ-
ment 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 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 below).
-w[orkdir] [<directory>]:
The initial working directory of the Erlang emulator.
Default is the system directory.
-p[riority] [{low|high|realtime}]:
The priority of the Erlang emulator. The default is the Win-
dows(R) default priority.
{-sn[ame] | -n[ame]} [<node-name>]:
The node-name of the Erlang machine, distribution is manda-
tory. 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 argu-
ments. Remember that the services cookie file is not neces-
sarily 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) internal ser-
vice name for the service, which by default is set to some-
thing unique (prefixed with the original service name) by
erlsrv when adding a new service. Specifying this is a
purely cosmethic action and is not recommended if release
handling is to be performed. The internal service name can-
not 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 will show upp as the service description in the Win-
dows(R) 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 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 tempo-
rarily 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 regis-
tered 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 supplied, 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 erlsrv.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%
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 below).
PORT PROGRAMS
When a program runs in the service context, it has to handle the con-
trol events that is sent to every program in the system when the inter-
active user logs off. This is done in different ways for programs run-
ning in the console subsystem and programs running as window applica-
tions. An application which runs in the console subsystem (normal for
port programs) uses the win32 function SetConsoleCtrlHandler to regis-
ter 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_QUERYENDSESSION to the default window
procedure. Here is a brief example in C of how to set the console con-
trol 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 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-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 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 signifi-
cant (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/down-
load/otp_src_17.5.tar.gz
Further information about this software can be found on the open source
community website at http://www.erlang.org/.
Ericsson AB erts 6.4 erlsrv(1)