From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- erts/doc/src/erlsrv.xml | 405 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 erts/doc/src/erlsrv.xml (limited to 'erts/doc/src/erlsrv.xml') diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml new file mode 100644 index 0000000000..93db56fc7c --- /dev/null +++ b/erts/doc/src/erlsrv.xml @@ -0,0 +1,405 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erlsrv + Patrik Nyblom + + + + + 98-04-29 + + erlsrv.xml +
+ erlsrv + Run the Erlang emulator as a service on Windows NT® + +

This utility is specific to Windows NT/2000/XP® (and subsequent 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® services applet in a manner similar to other + services.

+

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

+ + +

: This tells 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.

+ + +

: This can be either of , + , or (the + default). In case of , 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. 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 . Use + to restart the service on failure instead.

+ + +

: The location of the Erlang + emulator. The default is the located in the + same directory as erlsrv.exe. Do not specify + as this emulator, it will not work.

+

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

+ + +

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

+ + +

: 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 . + Debug log files will be placed in this directory.

+ + +

: The process priority of the emulator, + this can be one of , , + or (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.

+ + +

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

+ + +

: Can be one of (default), + , or . + Specifies that output from the Erlang shell should be + sent to a "debug log". The log file is named + <servicename> or + <servicename><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 + option always reuses the same log file + (<servicename>) and the option + uses a separate log file for every invocation of the service + (<servicename><N>). The + option opens an interactive Windows® console window for + the Erlang shell of the service. The option + automatically + disables the and a service started with an + interactive console window will not survive logouts, + actions do not work with debug-consoles either. + If no is specified (), the + output of the Erlang shell is discarded.

+

The is not in any way + intended for production. It is only a convenient way to + debug Erlang services during development. The and + 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 is + intended for debugging only. Logs during production are + better produced with the standard Erlang logging + facilities.

+ + +

: Additional arguments passed to the + emulator startup program (or + ). Arguments that cannot be specified + here are (StopActions would not work), + and (they are specified in any + way. The most common use is for specifying cookies and flags + to be passed to init:boot() ().

+ + +

: Specifies the Windows® 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 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® service manager if viewing Properties for an erlang service.

+ + +

: A textual comment describing the service. Not mandatory, but shows up as the service description in the Windows® service manager.

+ + +

+ 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>] + Add or modify an Erlang service + +

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. 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 in the + same directory as . When release handling + is used, this should be set to a program similar to + . + -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 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 ]]>. + + -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 + , and + /. 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® internal service name for the service, which by + default is set to something 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 cannot 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 Windows® service manager. + + + + + erlsrv {start | stop | disable | enable} <service-name> + Manipulate the current service status. + +

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 and + 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> + Remove the service. + +

This command removes the service completely with all its registered + options. It will be stopped before it is removed.

+ + + + erlsrv list [<service-name>] + List all Erlang services or all options for one service. + +

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 + Display a brief help text + + + +
+ ENVIRONMENT +

+The environment of an Erlang machine started + as a service will contain two special variables, + , which is the name of the service that + started the machine and which is the + full path to the 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:

+ +

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 + to a control handler that returns + TRUE in answer to the . Other + applications just forward and + to the default window procedure. Here + is a brief example in C of how to set the console control + handler:

+ +/* +** 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) +\011return 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)){ +\011/* +\011** Actually set the control handler +\011*/ +\011SetConsoleCtrlHandler(&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 + -directory, not in the -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 \\erts-\\bin]]> directory in + the path instead of \\bin]]>. The erlsrv program + can be found from inside Erlang by using the + Erlang function.

+

For release handling to work, use 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)

+
+ + -- cgit v1.2.3