erlsrv
COMMAND
erlsrv
COMMAND SUMMARY
Run the Erlang emulator as a service on Windows NT®
DESCRIPTION
This utility is specific to Windows NT/2000/XP® 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.
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 ®.
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.
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 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.
-
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 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. 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 program
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 service starts). Default working
directory 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 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.
-
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
<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 specified 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® 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 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).
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
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 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 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 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 -env options can
be specified in one command. Default is to use the system
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
Windows® 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.
erlsrv {start | 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.
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 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 running 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 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
SetConsoleCtrlHandler to a control handler that returns
TRUE in answer to the CTRL_LOGOFF_EVENT. 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 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;
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
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 significant (see above).
SEE ALSO
start_erl(1), release_handler(3)
erts 5.7.2
Copyright © 1991-2009
Ericsson AB