custom message type for VM_INFO

[minix3.git] / commands / service / service.8

.TH SERVICE 8
.SH NAME
service \- Manage an operating system service.
.SH SYNOPSIS
.PP
\fBservice [-b -c -n -p -r] (up|run|edit|update)\fR \fI<binary|self>\fR
[\fB-args\fR \fI<args>\fR] [\fB-dev\fR \fI<special>\fR]
[\fB-period\fR \fI<ticks>\fR]
[\fB-script\fR \fI<path>\fR] [\fB-label\fR \fI<name>\fR]
[\fB-config\fR \fI<path>\fR] [\fB-state\fR \fI<state>\fR]
[\fB-maxtime\fR \fI<time>\fR]
.PP
\fBservice down\fR \fI<label>\fR
.PP
\fBservice refresh\fR \fI<label>\fR
.PP
\fBservice restart\fR \fI<label>\fR
.PP
\fBservice clone\fR \fI<label>\fR
.PP
\fBservice shutdown\fR
.br
.de FL
.TP
\\fB\\$1\\fR
\\$2
..
.de EX
.TP
\\fB\\$1\\fR
\\$2
..
.SH DESCRIPTION
.PP
The \fBservice\fR utility instructs the reincarnation server (\fBRS\fR)
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 \fBup\fR and \fBrun\fR).
.br
.de FL
.TP
\\fB\\$1\\fR
\\$2
..
.de EX
.TP
\\fB\\$1\\fR
\\$2
..
.SH ACTIONS
.PP
.SS
\fBservice up\fR \fI<binary>\fR
.PP
.PP
Starts a new system service identified by the given \fI<binary>\fR,
which must be specified using an absolute path. When the service
unexpectedly exits (for example, as a result of a crash or a panic), \fBRS\fR
will intercept the event and restart the service automatically.
If the service fails to restart, \fBRS\fR will automatically bring
it down allowing for graceful degradation of service. If a critical
system service fails to restart, \fBRS\fR will immediately resort to
a system-wide panic. The \fBup\fR action takes the following options:
.TP
.BI \-b "          "
disable the usage of binary exponential restart time in \fBRS\fR.
.TP
.BI \-c "          "
\fBRS\fR normally relies on the binary on the disk to restart a
system service. The
.B \-c
option instructs \fBRS\fR 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).
.TP
.BI \-n "          "
by default, \fBRS\fR performs blocking startup of the system service. As
a result, the \fBup\fR action does not terminate until the system service
completes initialization.
The
.B \-n
option changes the default behavior by performing non-blocking startup
and thus terminating the \fBup\fR action immediately without waiting for
the service to complete initialization.
.TP
.BI \-p "          "
instructs \fBRS\fR 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. \fBPM\fR).
.TP
.BI \-r "          "
when saving an in-memory copy, instructs \fBRS\fR to reuse and share the copy
of an existing service with the same program name, if available.
.TP
.BI \-args " <args>"
specifies the command line arguments to use to run the program
given by \fI<binary>\fR. The default is to use no arguments.
.TP
.BI \-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.
.TP
.BI \-period " <ticks>"
specifies the period to use for the system service.
When a period is specified, \fBRS\fR sends a ping request to
the system service after every period. If the response does not arrive
in time, \fBRS\fR 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.
.TP
.BI \-script " <path>"
specifies the recovery script to associate to the system service. When a
recovery script is used, \fBRS\fR will not attempt to restart the service
upon termination. \fBRS\fR will instead invoke the script and
delegate the recovery process to it. The script may perform several
operations, including instructing \fBRS\fR to restart the service
(\fBrestart\fR action) or bring it down (\fBdown\fR  action).
The default is to associate no recovery script to the service.
.TP
.BI \-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.
.TP
.BI \-config " <path>"
specifies the absolute path of the system configuration file with the settings
of the system service. See
.IR system.conf (5)
for the syntax to use in the system configuration file.
The default is to use the global system configuration file \fB/etc/system.conf\fR.
.PP
.SS
\fBservice run\fR \fI<binary>\fR
.PP
.PP
Runs a new system service identified by the given \fI<binary>\fR,
which must be specified using an absolute path. Similar to
\fBservice up\fR \fI<binary>\fR, but instructs \fBRS\fR not to
restart the service upon termination. This action is currently a shorthand
for \fBservice up\fR \fI<binary>\fR \fB-script\fR \fI/etc/rs.single\fR, 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.
.PP
.SS
\fBservice edit\fR \fI<binary>\fR [\fB-label\fR \fI<name>\fR]
.PP
.PP
Edits settings of an existing system service identified by the given
label \fI<name>\fR. This action can be used to dynamically update the
properties of any system service, including those contained in the
boot image (e.g. \fBVM\fR). 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 \fBup\fR action.
.PP
.SS
\fBservice update\fR \fI<binary|self>\fR
.PP
.PP
Live updates an existing system service with a new version identified by the
given \fI<binary>\fR, 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 \fI<self>\fR is specified as
an argument instead, \fBRS\fR 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 \fI<name>\fR
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 \fBup\fR action and the
following additional options:
.TP
.BI \-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.
.TP
.BI \-maxtime " <time>"
specifies the maximum amount time for the service to prepare
for the update. The default is 0 (unlimited).
.PP
.SS
\fBservice down\fR \fI<label>\fR
.PP
.PP
Stops an existing system service identified by the given \fI<label>\fR. \fBRS\fR
will bring down the service without attempting to restart it. Critical system
services cannot be shut down.
.PP
.SS
\fBservice refresh\fR \fI<label>\fR
.PP
.PP
Refreshes an existing system service identified by the given \fI<label>\fR.
\fBRS\fR will kill the service and attempt to restart it.
.PP
.SS
\fBservice restart\fR \fI<label>\fR
.PP
.PP
Restarts an existing terminated system service identified by the
given \fI<label>\fR. This action can only be used from a recovery script.
.PP
.SS
\fBservice clone\fR \fI<label>\fR
.PP
.PP
Clones an existing system service to create a replica \fBRS\fR will use
to restart the service upon termination.
.PP
.SS
\fBservice shutdown\fR
.PP
.PP
Tells \fBRS\fR the system is about to shutdown and no system service should
be restarted upon termination.
.PP
.SH EXAMPLES
.TP 20
.B service up /sbin/is -period 5HZ
# Start the IS server and check its status every 5 seconds.
.br
.TP 20
.B service up /usr/sbin/dp8390 -args DPETH0=pci
# Start the DP8390 ethernet driver, passing one argument.
.br
.TP 20
.B service down lance
# Stop the system service with label lance.
.br
.SH "SEE ALSO"
.PP
.BR system.conf (5),
.BR boot (8),
.BR monitor (8).
.SH AUTHOR
Cristiano Giuffrida <giuffrida@cs.vu.nl>