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:
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.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.start_erl.exe
.Env
: Specifies a complete environment for the
emulator. Note that this is only interesting if the system wide
environment does not suite the emulator.
The service can not run if certain environment variables does not
exist, You have to find out what environment variables are needed
and add them all to the environment block, otherwise the service
will not start.
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%
.
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.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.
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:
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
.
-env
options can be specified in
one command. Default is an empty environment block.-sname <service name>
.
-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. These commands communicates with the service manager for stopping and starting a service. The commands do not wait until the service is actually stopped or started, but only initiates the operation. 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
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).
start_erl(1), release_handler(3)