SERVICE(8)

NAME
service - Manage an operating system service.

SYNOPSIS

service [-b -c -n -p -r] (up|run|edit|update) <binary|self> [-args <args>] [-dev <special>] [-period <ticks>] [-script <path>] [-label <name>] [-config <path>] [-state <state>] [-maxtime <time>]

service down <label>

service refresh <label>

service restart <label>

service clone <label>

service shutdown

DESCRIPTION

The service utility instructs the reincarnation server (RS) to perform an action for a given system service (an OS server or device driver). The action may concern an existing system service (SHIFT+F6 to list them all), or a new system service to be started (actions up and run).

ACTIONS

  service up <binary>

Starts a new system service identified by the given <binary>, which must be specified using an absolute path. When the service unexpectedly exits (for example, as a result of a crash or a panic), RS will intercept the event and restart the service automatically. If the service fails to restart, RS will automatically bring it down allowing for graceful degradation of service. If a critical system service fails to restart, RS will immediately resort to a system-wide panic. The up action takes the following options:

-b  disable the usage of binary exponential restart time in RS.

-c  RS normally relies on the binary on the disk to restart a system service. The -c option instructs RS to keep an in-memory copy of the binary and use the copy to restart the service upon termination. This is necessary when the location on the disk may change or if the service itself is required to read the binary from the disk (e.g. the disk driver).

-n  by default, RS performs blocking startup of the system service. As a result, the up action does not terminate until the system service completes initialization. The -n option changes the default behavior by performing non-blocking startup and thus terminating the up action immediately without waiting for the service to complete initialization.

-p  instructs RS to keep a replica of the system service in background and use the replica to restart the service upon termination. This is necessary when the service itself is required to create a working service instance (e.g. PM).

-r  when saving an in-memory copy, instructs RS to reuse and share the copy of an existing service with the same program name, if available.

-args <args>
    specifies the command line arguments to use to run the program given by <binary>. The default is to use no arguments.

-dev <special>
    specifies the device file to associate to the system service (used only for device drivers). The default is to associate no device file to the service.

-period <ticks>
    specifies the period to use for the system service. When a period is specified, RS sends a ping request to the system service after every period. If the response does not arrive in time, RS will kill the misbehaving service and restart a new one. The period must be specified in ticks, but can be appended with HZ to make it seconds. The default is to use no period for the service.

-script <path>
    specifies the recovery script to associate to the system service. When a recovery script is used, RS will not attempt to restart the service upon termination. RS will instead invoke the script and delegate the recovery process to it. The script may perform several operations, including instructing RS to restart the service (restart action) or bring it down (down action). The default is to associate no recovery script to the service.

-label <name>
    specifies the label to use for the system service. The label is used to univoquely identify the system service. The default is to use the program name as the label.

-config <path>
    specifies the absolute path of the system configuration file with the settings of the system service. See system.conf(5) for the syntax to use in the system configuration file. The default is to use the global system configuration file /etc/system.conf.

  service run <binary>

Runs a new system service identified by the given <binary>, which must be specified using an absolute path. Similar to service up <binary>, but instructs RS not to restart the service upon termination. This action is currently a shorthand for service up <binary> -script /etc/rs.single, which uses a recovery script that simply brings down the service upon termination. This action should be only used for short-lived programs that need system service privileges and do not require crash recovery support.

  service edit <binary> [-label <name>]

Edits settings of an existing system service identified by the given label <name>. This action can be used to dynamically update the properties of any system service, including those contained in the boot image (e.g. VM). There are a few exceptions to the properties that can be actually overridden dynamically. For example, the device file associated to the service will no be updated. This action takes the same options supported by the up action.

  service update <binary|self>

Live updates an existing system service with a new version identified by the given <binary>, which must be specified using an absolute path. The existing service will be identified from the label given (if explicitly specified), or from the program name. If <self> is specified as an argument instead, RS will perform a self update of the system service (i.e. an update of the service with its own replica). This is intended for testing purposes. In this case, a label <name> must be explicitly specified. Live update support is still in an early stage of development and is subject to change in future revisions. This action takes all the options supported by the up action and the following additional options:

-state <state>
    specifies the state of the service required by the update. The default is a state in which the service is blocked not processing any work.

-maxtime <time>
    specifies the maximum amount time for the service to prepare for the update. The default is 0 (unlimited).

  service down <label>

Stops an existing system service identified by the given <label>. RS will bring down the service without attempting to restart it. Critical system services cannot be shut down.

  service refresh <label>

Refreshes an existing system service identified by the given <label>. RS will kill the service and attempt to restart it.

  service restart <label>

Restarts an existing terminated system service identified by the given <label>. This action can only be used from a recovery script.

  service clone <label>

Clones an existing system service to create a replica RS will use to restart the service upon termination.

  service shutdown

Tells RS the system is about to shutdown and no system service should be restarted upon termination.

EXAMPLES

service up /sbin/is -period 5HZ
    # Start the IS server and check its status every 5 seconds.

service up /usr/sbin/dp8390 -args DPETH0=pci
    # Start the DP8390 ethernet driver, passing one argument.

service down lance
    # Stop the system service with label lance.

SEE ALSO

system.conf(5), boot(8), monitor(8).

AUTHOR
Cristiano Giuffrida <giuffrida@cs.vu.nl>