oneechanhax/phunix
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Man pages for new system configuration.

Browse Source
This commit is contained in:
Cristiano Giuffrida 2010-07-13 11:45:41 +00:00
parent 1ecdac623a
commit 60549b67be
3 changed files with 380 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
man/man5/Makefile
View File

@ -1,7 +1,7 @@
MAN= configfile.5 crontab.5 dhcp.conf.5 dir.5 ethers.5 \ MAN= configfile.5 crontab.5 dhcp.conf.5 dir.5 ethers.5 \
fstab.5 hosts.5 httpd.conf.5 http_status.5 keymap.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 \ 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 whatis.5
.include <bsd.man.mk> .include <bsd.man.mk>

176
man/man5/system.conf.5 Normal file
View 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>

218
man/man8/service.8
View File

@ -1,14 +1,22 @@
.TH SERVICE 8 .TH SERVICE 8
.SH NAME .SH NAME
service \- Start or stop an operating system server or device driver. service \- Manage an operating system service.
.SH SYNOPSIS .SH SYNOPSIS
.PP .PP
\fBservice up\fR \fI<service>\fR [\fB-args\fR \fIargs\fR] \fBservice [-c -r -n -p] (up|run|edit|update)\fR \fI<binary|self>\fR
[\fB-dev\fR \fIspecial\fR] [\fB-period\fR \fIticks\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 .PP
\fBservice down\fR \fI<pid>\fR \fBservice down\fR \fI<label>\fR
.PP .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 .PP
\fBservice shutdown\fR \fBservice shutdown\fR
.br .br
@ -24,26 +32,206 @@ service \- Start or stop an operating system server or device driver.
.. ..
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
Tells the reincarnation server to start or stop a system service, such as a The \fBservice\fR utility instructs the reincarnation server (\fBRS\fR)
server or device driver. The device driver will be automatically restarted when to perform an action for a given system service (an OS server
it unexpectedly exits, e.g., if it is killed because of a bad pointer. or device driver). The action may concern an existing system service
Starting requires an absolute path to the binary to be executed. (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 .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 .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 .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 Starts a new system service identified by the given \fI<binary>\fR,
sequence. 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 .SH EXAMPLES
.EX "service up /sbin/is -period 5HZ" "Start the IS server and check its status every 5 seconds." .EX "service up /sbin/is -period 5HZ" "Start the IS server and check its status every 5 seconds."
.br .br
.EX "service up /usr/sbin/dp8390 -args DPETH0=pci" "Start the DP8390 ethernet driver, passing one argument." .EX "service up /usr/sbin/dp8390 -args DPETH0=pci" "Start the DP8390 ethernet driver, passing one argument."
.br .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 .br
.SH "SEE ALSO" .SH "SEE ALSO"
.PP .PP
.BR system.conf (5),
.BR boot (8), .BR boot (8),
.BR monitor (8) .BR monitor (8).
.SH AUTHOR
Cristiano Giuffrida <giuffrida@cs.vu.nl>