Man pages for new system configuration.
This commit is contained in:
Cristiano Giuffrida
parent
1ecdac623a
commit
60549b67be
@ -1,7 +1,7 @@
|
||||
MAN= configfile.5 crontab.5 dhcp.conf.5 dir.5 ethers.5 \
|
||||
fstab.5 hosts.5 httpd.conf.5 http_status.5 keymap.5 \
|
||||
passwd.5 resolv.conf.5 resolver.5 rhosts.5 statvfs.5 serv.access.5 \
|
||||
syslog.conf.5 termcap.5 ttytab.5 TZ.5 tzfile.5 utmp.5 \
|
||||
system.conf.5 syslog.conf.5 termcap.5 ttytab.5 TZ.5 tzfile.5 utmp.5 \
|
||||
whatis.5
|
||||
|
||||
.include <bsd.man.mk>
|
||||
|
||||
176
man/man5/system.conf.5
Normal file
176
man/man5/system.conf.5
Normal file
@ -0,0 +1,176 @@
|
||||
.TH SYSTEM.CONF 5
|
||||
.SH NAME
|
||||
system.conf \- operating system service configuration
|
||||
.SH SYNOPSIS
|
||||
.B /etc/system.conf
|
||||
.SH DESCRIPTION
|
||||
.de SP
|
||||
.if t .sp 0.4
|
||||
.if n .sp
|
||||
..
|
||||
The file
|
||||
.B /etc/system.conf
|
||||
is the global system configuration file that contains the
|
||||
configuration for all the primary system services. This is the file
|
||||
that the \fBservice\fR utility uses by default. Custom configuration
|
||||
files with the same format can be specified on a per-service basis. See
|
||||
.BR service (8)
|
||||
for more details.
|
||||
|
||||
This page is a summary of all the elements that can be found in this
|
||||
configuration file.
|
||||
.PP
|
||||
The syntax used is that of the common configuration file described in
|
||||
.BR configfile (5).
|
||||
.PP
|
||||
The \fBservice\fR utility scans the configuration file from beginning to end
|
||||
to gather information about a specific system service when starting or
|
||||
updating the properties of a service.
|
||||
The file contains a collection of service entries of the form:
|
||||
|
||||
.nf
|
||||
\fBservice\fR \fI<program_name>\fR
|
||||
\fB{\fR
|
||||
\fI[option 1]\fR
|
||||
\fI[option 2]\fR
|
||||
...
|
||||
\fI[option N]\fR
|
||||
\fB};\fR
|
||||
.fi
|
||||
.PP
|
||||
where \fI<program_name>\fR is the name of the program used to start the
|
||||
given system service. In each service entry, the following options can
|
||||
be used:
|
||||
.PP
|
||||
\fBuid\fR \fI<uid|user name>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the user id or the user name to use to run the system service.
|
||||
Many system services run with root privileges (uid \fB0\fR).
|
||||
The default user is service (uid \fB12\fR).
|
||||
.RE
|
||||
.PP
|
||||
\fBipc\fR \fI<ALL|ALL_SYS|NONE|label1 label2...labelN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the list of ipc targets (processes and kernel) the system service can
|
||||
talk to. \fIALL\fR allows all the possible targets, \fIALL_SYS\fR is similar but
|
||||
excludes user processes. When an explicit list is given, each target
|
||||
must be identified by its label (assigned to the corresponding system service).
|
||||
Exceptions are user processes (use pseudo-label \fIUSER\fR) and
|
||||
the kernel for kernel calls (use pseudo-label \fISYSTEM\fR). The default is
|
||||
\fIALL_SYS\fR.
|
||||
.RE
|
||||
.PP
|
||||
\fBsystem\fR \fI<ALL|BASIC|NONE|kcall1 kcall2...kcallN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the list of kernel calls the system service is allowed to call.
|
||||
\fIALL\fR allows all the kernel calls, \fIBASIC\fR only allows basic kernel
|
||||
calls (see macro \fBSYS_BASIC_CALLS\fR in \fB<minix/com.h>\fR),
|
||||
\fINONE\fR allows no kernel call. This option only makes sense if the
|
||||
option \fBipc\fR includes the kernel as a valid target.
|
||||
The default is \fIBASIC\fR.
|
||||
.RE
|
||||
.PP
|
||||
\fBvm\fR \fI<ALL|BASIC|NONE|vmcall1 vmcall2...vmcallN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the list of VM calls the system service is allowed to call.
|
||||
\fIALL\fR allows all the VM calls, \fIBASIC\fR only allows basic VM
|
||||
calls (see macro \fBVM_BASIC_CALLS\fR in \fB<minix/com.h>\fR),
|
||||
\fINONE\fR allows no VM call. This option only makes sense if the
|
||||
option \fBipc\fR includes VM as a valid target.
|
||||
The default is \fIBASIC\fR.
|
||||
.RE
|
||||
.PP
|
||||
\fBio\fR \fI<ALL|NONE|baseaddr1 baseaddr2:length2...baseaddrN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the list of I/O ranges the system service is allowed to use.
|
||||
\fIALL\fR allows all the possible I/O ranges, \fINONE\fR allows no I/O range
|
||||
at all. When an explicit list is given, each range is identified by a base
|
||||
address and an optional length. When no length is given, length \fB1\fR is
|
||||
assumed. The default is \fINONE\fR.
|
||||
.RE
|
||||
.PP
|
||||
\fBirq\fR \fI<ALL|NONE|irq1 irq2...irqN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the list of IRQs the system service is allowed to use.
|
||||
\fIALL\fR allows all the possible IRQs, \fINONE\fR allows no IRQ
|
||||
at all. An explicit list of IRQ numbers may be given.
|
||||
The default is \fINONE\fR.
|
||||
.RE
|
||||
.PP
|
||||
\fBsigmgr\fR \fI<SELF|label>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the signal manager the system service is assigned to. The signal
|
||||
manager intercepts all the termination and non-termination signals
|
||||
(including signal generated by runtime exceptions, e.g. SIGSEGV) on behalf
|
||||
of the service and reacts accordingly. \fISELF\fR allows the service to
|
||||
become its own signal manager. This option should be used with care,
|
||||
since a lethal signal for the service will immediately trigger a
|
||||
kernel panic. A separate system service that acts as the designated signal
|
||||
manager must be specified using its label. The default is specified in
|
||||
\fB<minix/priv.h>\fR (see macro \fBDSRV_SM\fR).
|
||||
.RE
|
||||
.PP
|
||||
\fBscheduler\fR \fI<KERNEL|label>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the scheduler the system service is assigned to. The scheduler
|
||||
implements the scheduling policy for the system service. \fIKERNEL\fR allows
|
||||
the service to be scheduled directly by the kernel. A separate system
|
||||
service that acts as the designated scheduler must be specified
|
||||
using its label. The default is specified in
|
||||
\fB<minix/priv.h>\fR (see macro \fBDSRV_SCH\fR).
|
||||
.RE
|
||||
.PP
|
||||
\fBpriority\fR \fI<priority_queue>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the priority queue the scheduler must assign the service to.
|
||||
The default is specified in \fB<minix/priv.h>\fR (see macro \fBDSRV_Q\fR).
|
||||
.RE
|
||||
.PP
|
||||
\fBquantum\fR \fI<quantum_size_ms>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the quantum size (ms) the scheduler must consider the service for.
|
||||
The default is specified in \fB<minix/priv.h>\fR (see macro \fBDSRV_QT\fR).
|
||||
.RE
|
||||
.PP
|
||||
\fBpci device\fR \fI<vid/did>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the PCI device IDs the system service is allowed to use
|
||||
(only used for device drivers).
|
||||
The default is to allow no PCI device IDs.
|
||||
.RE
|
||||
.PP
|
||||
\fBpci class\fR \fI<class1/mask1 class2/mask2...classN/maskN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the PCI classes the system service is allowed to use
|
||||
(only used for device drivers).
|
||||
The default is to allow no PCI classes.
|
||||
.RE
|
||||
.PP
|
||||
\fBcontrol\fR \fI<label1 label2...labelN>\fR\fB;\fR
|
||||
.PP
|
||||
.RS
|
||||
specifies the list of system services (identified by their labels) that are
|
||||
allowed to control the system service. A controller service can ask RS
|
||||
to perform privileged actions like immediately restarting the service.
|
||||
The default is to allow no controller services.
|
||||
.RE
|
||||
.PP
|
||||
.SH "SEE ALSO"
|
||||
.BR configfile (5),
|
||||
.BR service (8),
|
||||
.BR boot (8).
|
||||
.SH AUTHOR
|
||||
Cristiano Giuffrida <giuffrida@cs.vu.nl>
|
||||
|
||||
@ -1,14 +1,22 @@
|
||||
.TH SERVICE 8
|
||||
.SH NAME
|
||||
service \- Start or stop an operating system server or device driver.
|
||||
service \- Manage an operating system service.
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
\fBservice up\fR \fI<service>\fR [\fB-args\fR \fIargs\fR]
|
||||
[\fB-dev\fR \fIspecial\fR] [\fB-period\fR \fIticks\fR]
|
||||
\fBservice [-c -r -n -p] (up|run|edit|update)\fR \fI<binary|self>\fR
|
||||
[\fB-args\fR \fI<args>\fR] [\fB-dev\fR \fI<special>\fR]
|
||||
[\fB-devstyle\fR \fI<style>\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<pid>\fR
|
||||
\fBservice down\fR \fI<label>\fR
|
||||
.PP
|
||||
\fBservice refresh\fR \fI<pid>\fR
|
||||
\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
|
||||
@ -24,26 +32,206 @@ service \- Start or stop an operating system server or device driver.
|
||||
..
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Tells the reincarnation server to start or stop a system service, such as a
|
||||
server or device driver. The device driver will be automatically restarted when
|
||||
it unexpectedly exits, e.g., if it is killed because of a bad pointer.
|
||||
Starting requires an absolute path to the binary to be executed.
|
||||
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
|
||||
When an optional period is specified, the reincarnation server sends a status request to the system service after every period. If there the response does not arrive in time, the reincarnation server will kill the misbehaving process and restart a new one. The period must be specified in ticks, but can be appended with HZ to make it seconds.
|
||||
.SS
|
||||
\fBservice up\fR \fI<binary>\fR
|
||||
.PP
|
||||
Stopping a system service requires the process id of a running system service. Issuing a kill command from the shell will not work, since the reincarnation server interprets this as an unexpected exit and will automatically restart a fresh copy of the process. The clean way to restart a process is using the refresh option of the service utility.
|
||||
.PP
|
||||
If the system is to be shutdown, the reincarnation server should know about this event to prevent it from restarting services that are killed during the shutdown
|
||||
sequence.
|
||||
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 \-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 \-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 \-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 \-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 \-devstyle " <style>"
|
||||
specifies the device style to associate to the system service (used only for
|
||||
device drivers). The list of supported device styles is available in
|
||||
the header file \fB<minix/dmap.h>\fR.
|
||||
The default is to associate no device style (\fBSTYLE_NDEV\fR) 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
|
||||
and the device style 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
|
||||
.EX "service up /sbin/is -period 5HZ" "Start the IS server and check its status every 5 seconds."
|
||||
.br
|
||||
.EX "service up /usr/sbin/dp8390 -args DPETH0=pci" "Start the DP8390 ethernet driver, passing one argument."
|
||||
.br
|
||||
.EX "service down 117" "Stop the system service with process id 117."
|
||||
.EX "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)
|
||||
.BR monitor (8).
|
||||
.SH AUTHOR
|
||||
Cristiano Giuffrida <giuffrida@cs.vu.nl>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user