Manpages

NAME

erlsrv − Run the Erlang emulator as a service on Windows NT®

DESCRIPTION

This utility is specific to Windows NT® It allows Erlang emulators to run as services on the NT 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 NT® 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 NT®.

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:

On a system where release handling is used, this should always be set to ignore. Use heart to restart the service on failure instead.

If the system uses release handling, this should be set to a program similar to start_erl.exe.

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 NT® 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.

-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)

AUTHOR

Patrik Nyblom - support [AT] erlang.se