man pages section 1: User Commands

Exit Print View

Updated: July 2014
 
 

erlsrv (1)

Name

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

Synopsis

Please see following description for synopsis

Description




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  sub-
     sequent  versions  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 ser-
     vices.

     Note that erlsrv is not a general service utility  for  Win-
     dows, 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 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 (R).

     The processes created by the service can, as opposed to nor-
     mal  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  TerminatePro-
         cess), but this action can specify any Erlang shell com-
         mand 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  emula-
         tor  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 what-
         ever  parameters  are  registered for the service at the
         occasion) when it stops. If  the  emulator  stops  again



Ericsson AB         Last change: erts 5.9.3.1                   1






User Commands                                           erlsrv(1)



         within 10 seconds, it is not restarted to avoid an infi-
         nite 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 man-
         ually restarted.

         On a system where release handling is used, this  should
         always  be  set to ignore. Use heart to restart the ser-
         vice 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  emula-
         tor.  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 spec-
         ified 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  direc-
         tory  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 pri-
         ority 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  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 dis-
         tributed, 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



Ericsson AB         Last change: erts 5.9.3.1                   2






User Commands                                           erlsrv(1)



         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 spec-
         ified  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 automat-
         ically  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 pro-
         duction. 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).

       * 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 service is renamed.  Erlsrv  generates  a  unique
         internal  name  when  a service is created, it is recom-
         mended 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 ser-
         vice.

       * Comment:  A  textual comment describing the service. Not
         mandatory, but shows up as the  service  description  in
         the Windows(R) service manager.




Ericsson AB         Last change: erts 5.9.3.1                   3






User Commands                                           erlsrv(1)



     The naming of the service in a system that uses release han-
     dling 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 ser-
          vice 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 emula-
              tor 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 sys-
              tem 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 envi-
              ronment 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).



Ericsson AB         Last change: erts 5.9.3.1                   4






User Commands                                           erlsrv(1)



            -w[orkdir] [<directory>]:
              The  initial working directory of the Erlang emula-
              tor. Default is the system directory.

            -p[riority] [{low|high|realtime}]:
              The priority of the Erlang emulator. The default is
              the Windows(R) 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.

            -i[nternalservicename] [<internal name>]:
              Only allowed for add. Specifies a Windows(R) inter-
              nal service name for the service, which by  default
              is set to something unique (prefixed with the orig-
              inal service name) by erlsrv when adding a new ser-
              vice.  Specifying this is a purely cosmethic action
              and is not recommended if release handling is to be
              performed.  The  internal  service  name  cannot be
              changed once the service is created.  The  internal
              name  is  not to be confused with the ordinary ser-
              vice 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  descrip-
              tion in the Windows(R) service manager.

     erlsrv  {start  |  start_disabled | stop | disable | enable}
     <service-name>

          These commands are only added for convenience, the nor-
          mal way to manipulate the state of a service is through



Ericsson AB         Last change: erts 5.9.3.1                   5






User Commands                                           erlsrv(1)



          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 temporarily 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 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 sup-
          plied, 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 erl-
     srv.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%




Ericsson AB         Last change: erts 5.9.3.1                   6






User Commands                                           erlsrv(1)



     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  cor-
     rectly  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 sys-
     tem when the interactive user logs off. This is done in dif-
     ferent  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 pro-
     grams) uses the win32 function SetConsoleCtrlHandler to reg-
     ister  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_QUERYENDSES-
     SION to the default window procedure. Here is a brief  exam-
     ple 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;
         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



Ericsson AB         Last change: erts 5.9.3.1                   7






User Commands                                           erlsrv(1)



     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-direc-
     tory, not in the bin-directory  directly  under  the  Erlang
     root. The reasons for this are the subtle problem of upgrad-
     ing 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)

     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/download/otp_src_R15B03-1.tar.gz

     Further  information about this software can be found on the
     open source community website at http://www.erlang.org/.













Ericsson AB         Last change: erts 5.9.3.1                   8