Go to main content

man pages section 1: User Commands

Exit Print View

Updated: July 2017

erlsrv (1)


erlsrv - Run the Erlang emulator as a service on Windows NT(R)


Please see following description for synopsis


erlsrv(1)                        User Commands                       erlsrv(1)

       erlsrv - Run the Erlang emulator as a service on Windows NT(R)

       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

       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-

       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-

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

         * 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

         * 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

           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

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

              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-

              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

       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

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

       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
                                     (DWORD) 2)){
               ** Actually set the control handler
               SetConsoleCtrlHandler(&service_aware_handler, TRUE);

       See attributes(5) for descriptions of the following attributes:

       |Availability   | runtime/erlang   |
       |Stability      | Uncommitted      |
       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).

       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-

       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)