123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465 |
- changequote(`@@@',`$$$')dnl
- @@@.TH DINIT-SERVICE "5" "$$$MONTH YEAR@@@" "Dinit $$$VERSION@@@" "Dinit \- service management system"
- .SH NAME
- Dinit service description files
- .\"
- .SH SYNOPSIS
- .\"
- .ft CR
- /etc/dinit.d/\fIservice-name\fR, $HOME/dinit.d/\fIservice-name\fR
- .ft
- .\"
- .SH DESCRIPTION
- .\"
- The service description files for \fBDinit\fR each describe a service. The name
- of the file corresponds to the name of the service it describes.
- .LP
- Service description files specify the various attributes of a service. A
- service description file is named after the service it represents, and is
- a plain-text file with simple key-value format. The description files are
- located in a service description directory; by default, the system process
- searches \fI/etc/dinit.d\fR, \fI/usr/local/lib/dinit.d\fR and
- \fI/lib/dinit.d\fR, while a user process searches \fI$HOME/dinit.d\fR.
- .LP
- All services have a \fItype\fR and a set of \fIdependencies\fR. Service
- types are discussed in the following subsection. If a service depends on
- another service, then starting the first service causes the second to start
- also; depending on the type of dependency, if the second service fails to
- start, the dependent may have its startup aborted. For a service which will
- represent a running process, the process is not generally launched until the
- dependencies are all satisfied. If a service has a hard dependency on another
- which becomes stopped, the dependent service must also stop. A service
- process will not be signaled to terminate until the service's dependents have stopped.
- .\"
- .SS SERVICE TYPES
- .\"
- There are four basic types of service:
- .IP \(bu
- \fBProcess\fR services. This kind of service runs as a single process; starting
- the service simply requires starting the process; stopping the service is
- accomplished by stopping the process (via sending it a signal).
- .IP \(bu
- \fBBgprocess\fR services ("background process" services). This kind of
- service is similar to a regular process service, but the process daemonizes
- or otherwise forks from the original process which starts it, and the
- process ID is written to a file. Dinit can read the process ID from the
- file and, if it is running as the system init process, can supervise it.
- .IP \(bu
- \fBScripted\fR services are services which are started and stopped by a
- command (which need not actually be a script, despite the name). They can
- not be supervised.
- .IP \(bu
- \fBInternal\fR services do not run as an external process at all. They can
- be started and stopped without any external action. They are useful for
- grouping other services (via service dependencies).
- .\"
- .SS SERVICE PROPERTIES
- .\"
- This section described the various service properties that can be specified
- in a service description file. Each line of the file can specify a single
- property value, expressed as "\fIproperty-name\fR = \fIvalue\fR". Comments
- begin with a hash mark (#) and extend to the end of the line (they must be
- separated from setting values by at least one whitespace character). Values
- are interpreted literally, except that:
- .\"
- .IP \(bu
- White space (comprised of spaces, tabs, etc) is collapsed to a single space.
- .IP \(bu
- Double quotes (") can be used around all or part of a property value, to
- prevent whitespace collapse and prevent interpretation of other special
- characters (such as "#") inside the quotes. The quote characters are not
- considered part of the parameter value.
- .IP \(bu
- A backslash (\\) can be used to escape the next character, causing it to
- lose any special meaning and become part of the property value. A double
- backslash (\\\\) is collapsed to a single backslash within the parameter
- value.
- .LP
- The following properties can be specified:
- .TP
- \fBtype\fR = {process | bgprocess | scripted | internal}
- Specifies the service type.
- .TP
- \fBcommand\fR = \fIcommand-string\fR
- Specifies the command, including command-line arguments, for starting the
- process. Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR
- services.
- .TP
- \fBstop\-command\fR = \fIcommand-string\fR
- Specifies the command to stop the service. Applicable only to \fBscripted\fR
- services.
- .TP
- \fBworking-dir\fR = \fIdirectory\fR
- Specifies the working directory for this service. For a scripted service, this
- affects both the start command and the stop command.
- .TP
- \fBrun\-as\fR = \fIuser-id\fR
- Specifies which user to run the process(es) for this service as. Specify as a
- username or numeric ID. If specified by name, the group for the process will
- also be set to the primary group of the specified user.
- .TP
- \fBrestart\fR = {yes | true | no | false}
- Indicates whether the service should automatically restart if it stops for
- any reason (including unexpected process termination, service dependency
- stopping, or user-initiated service stop).
- .TP
- \fBsmooth\-recovery\fR = {yes | true | no | false}
- Applies only to \fBprocess\fR and \fBbgprocess\fR services. When set true/yes,
- an automatic process restart can be performed without first stopping any
- dependent services. This setting is meaningless if the \fBrestart\fR setting
- is set to false.
- .TP
- \fBrestart\-delay\fR = \fIXXX.YYYY\fR
- Specifies the minimum time between automatic restarts. Enforcing a sensible
- minimum prevents Dinit from consuming a large number of process cycles in
- case a process continuously fails immediately after it is started. The
- default is 0.2 (200 milliseconds).
- .TP
- \fBrestart\-limit\-interval\fR = \fIXXX.YYYY\fR
- Sets the interval, in seconds, over which restarts are limited. If a process
- automatically restarts more than a certain number of times (specified by the
- \fBrestart-limit-count\fR setting) in this time interval, it will not restart
- again. The default value is 10 seconds.
- .TP
- \fBrestart\-limit\-count\fR = \fINNN\fR
- Specifies the maximum number of times that a service can automatically restart
- over the interval specified by \fBrestart\-limit\-interval\fR. Specify a value
- of 0 to disable the restart limit.
- .TP
- \fBstart\-timeout\fR = \fIXXX.YYY\fR
- Specifies the time in seconds allowed for the service to start. If the
- service takes longer than this, its process group is sent a SIGINT signal
- and enters the "stopping" state (this may be subject to a stop timeout, as
- specified via \fBstop\-timeout\fR, after which the process group will be
- terminated via SIGKILL). The timeout period begins only when all dependencies
- have been stopped. The default timeout is 60 seconds. Specify a value of 0 to
- allow unlimited start time.
- .TP
- \fBstop\-timeout\fR = \fIXXX.YYY\fR
- Specifies the time in seconds allowed for the service to stop. If the
- service takes longer than this, its process group is sent a SIGKILL signal
- which should cause it to terminate immediately. The timeout period begins
- only when all dependent services have already stopped. The default
- timeout is 10 seconds. Specify a value of 0 to allow unlimited stop time.
- .TP
- \fBpid\-file\fR = \fIpath-to-file\fR
- For \fBbgprocess\fR type services only; specifies the path of the file where
- daemon will write its process ID before detaching. Dinit will read the
- contents of this file when starting the service, once the initial process
- exits, will supervise the process with the discovered process ID, and may
- send signals to the process ID to stop the service; if Dinit runs as a
- privileged user the path should therefore not be writable by unprivileged
- users.
- .TP
- \fBdepends\-on\fR = \fIservice-name\fR
- This service depends on the named service. Starting this service will start
- the named service; the command to start this service will not be executed
- until the named service has started. If the named service is stopped then
- this service will also be stopped.
- .TP
- \fBdepends\-ms\fR = \fIservice-name\fR
- This service has a "milestone" dependency on the named service. Starting this
- service will start the named service; this service will not start until the
- named service has started, and will fail to start if the named service does
- not start. Once the named service reaches the started state, however, the
- dependency is effectively dropped until this service is next started.
- .TP
- \fBwaits\-for\fR = \fIservice-name\fR
- When this service is started, wait for the named service to finish starting
- (or to fail starting) before commencing the start procedure for this service.
- Starting this service will automatically start the named service. If the
- named service fails to start, this service will start as usual (subject to
- other dependencies being met).
- .TP
- \fBwaits\-for.d\fR = \fIdirectory-path\fR
- For each file name in \fIdirectory-path\fR which does not begin with a dot,
- add a \fBwaits-for\fR dependency to the service with the same name. Note that
- contents of files in the specified directory are not significant; expected
- usage is to have symbolic links to the associated service description files,
- but this is not required. Failure to read the directory contents, or to find
- any of the services named within, is not considered fatal.
- The directory path, if not absolute, is relative to the directory containing
- the service description file.
- .TP
- \fBchain-to\fR = \fIservice-name\fR
- When this service terminates (i.e. starts successfully, and then stops of its
- own accord), the named service should be started. Note that the named service
- is not loaded until that time; naming an invalid service will not cause this
- service to fail to load.
- This can be used for a service that supplies an interactive "recovery mode"
- for another service; once the user exits the recovery shell, the primary
- service (as named via this setting) will then start. It also supports
- multi-stage system startup where later service description files reside on
- a separate filesystem that is mounted during the first stage; such service
- descriptions will not be found at initial start, and so cannot be started
- directly, but can be chained via this directive.
- The chain is not executed if the initial service was explicitly stopped, stopped
- due to a dependency stopping (for any reason), if it will restart (including due
- to a dependent restarting), or if its process terminates abnormally or with an
- exit status indicating an error.
- .TP
- \fBsocket\-listen\fR = \fIsocket-path\fR
- Pre-open a socket for the service and pass it to the service using the
- \fBsystemd\fR activation protocol. This by itself does not give so called
- "socket activation", but does allow that any process trying to connect to the
- specified socket will be able to do so, even before the service is properly
- prepared to accept connections.
- .TP
- \fBsocket\-permissions\fR = \fIoctal-permissions-mask\fR
- Gives the permissions for the socket specified using \fBsocket-listen\fR.
- Normally this will be 600 (user access only), 660 (user and group
- access), or 666 (all users). The default is 666.
- .TP
- \fBsocket\-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
- Specifies the user (name or numeric ID) that should own the activation socket. If
- \fBsocket\-uid\fR is specified as a name without also specifying \fBsocket-gid\fR, then
- the socket group is the primary group of the specified user (as found in the
- system user database, normally \fI/etc/passwd\fR). If the \fBsocket\-uid\fR setting is
- not provided, the socket will be owned by the user id of the \fBdinit\fR process.
- .TP
- \fBsocket\-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
- Specifies the group of the activation socket. See discussion of
- \fBsocket\-uid\fR.
- .TP
- \fBterm\-signal\fR = {HUP | INT | QUIT | USR1 | USR2 | KILL}
- Specifies an additional signal to send to the process when requesting it
- to terminate (applies to 'process' services only). SIGTERM is always
- sent along with the specified signal, unless the \fBno\-sigterm\fR option is
- specified via the \fBoptions\fR parameter.
- .TP
- \fBready\-notification\fR = {\fBpipefd:\fR\fIfd-number\fR | \fBpipevar:\fR\fIenv-var-name\fR}
- Specifies the mechanism, if any, by which a process service will notify that it is ready
- (successfully started). If not specified, a process service is considered started as soon as it
- has begun execution. The two options are:
- .RS
- .IP \(bu
- \fBpipefd:\fR\fIfd-number\fR \(em the service will write a message to the specified file descriptor,
- which \fBdinit\fR sets up as the write end of a pipe before execution. This mechanism is compatible
- with the S6 supervision suite.
- .IP \(bu
- \fBpipevar:\fR\fIenv-var-name\fR \(em the service will write a message to file descriptor identified
- using the contents of the specified environment variable, which will be set by \fBdinit\fR before
- execution to a file descriptor (chosen arbitrarily) attached to the write end of a pipe.
- .RE
- .TP
- \fBlogfile\fR = \fIlog-file-path\fR
- Specifies the log file for the service. Output from the service process
- will go this file.
- .TP
- \fBoptions\fR = \fIoption\fR...
- Specifies various options for this service. See the \fBOPTIONS\fR section. This
- directive can be specified multiple times to set additional options.
- .TP
- \fBload-options\fR = \fIload_option\fR...
- Specifies options for interpreting other settings when loading this service
- description. Currently there is only one available option, \fBsub-vars\fR,
- which specifies that command line arguments in the form of \fB$NAME\fR should
- be replaced with the contents of the environment variable with the specified
- name. Note that no word-splitting is performed and the variable value always
- becomes a single argument; if the variable is not defined, it is replaced with
- an empty (zero-length) argument.
- .TP
- \fBinittab-id\fR = \fIid-string\fR
- When this service is started, if this setting (or the \fBinittab-line\fR setting) has a
- specified value, an entry will be created in the system "utmp" database which tracks
- processes and logged-in users. Typically this database is used by the "who" command to
- list logged-in users. The entry will be cleared when the service terminates.
- The \fBinittab-id\fR setting specifies the "inittab id" to be written in the entry for
- the process. The value is normally quite meaningless. However, it should be distinct
- (or unset) for separate processes. It is typically limited to a very short length.
- The "utmp" database is mostly a historical artifact. Access to it on some systems is
- prone to denial-of-service by unprivileged users. It is therefore recommended that this
- setting not be used. However, "who" and similar utilities may not work correctly without
- this setting (or \fBinittab-line\fR) enabled appropriately.
- This setting has no effect if Dinit was not built with support for writing to the "utmp"
- database.
- .TP
- \fBinittab-line\fR = \fItty-name-string\fR
- This specifies the tty line that will be written to the "utmp" database when this service
- is started. Normally, for a terminal login service, it would match the terminal device name
- on which the login process runs, without the "/dev/" prefix.
- See the description of the \fBinittab-id\fR setting for details.
- .TP
- \fBrlimit-nofile\fR = \fIresource-limits\fR
- Specifies the number of file descriptors that a process may have open simultaneously. See the
- \fBRESOURCE LIMITS\fR section.
- .TP
- \fBrlimit-core\fR = \fIresource-limits\fR
- Specifies the maximum size of the core dump file that will be generated for the process if it
- crashes (in a way that would result in a core dump). See the \fBRESOURCE LIMITS\fR section.
- .TP
- \fBrlimit-data\fR = \fIresource-limits\fR
- Specifies the maximum size of the data segment for the process, including statically allocated
- data and heap allocations. Precise meaning may vary between operating systems. See the
- \fBRESOURCE LIMITS\fR section.
- .TP
- \fBrlimit-addrspace\fR = \fIresource-limits\fR
- Specifies the maximum size of the address space of the process. See the \fBRESOURCE LIMITS\fR
- section. Note that some operating systems (notably OpenBSD) do not support this limit; the
- setting will be ignored on such systems.
- .\"
- .SS OPTIONS
- .\"
- These options are specified via the \fBoptions\fR parameter.
- .\"
- .TP
- \fBno\-sigterm\fR
- Specifies that the TERM signal should not be send to the process to terminate
- it. (Another signal can be specified using the \fBtermsignal\fR setting; if no
- other signal is specified, no signal will be sent, which usually means that
- the service will not terminate).
- .TP
- \fBruns\-on\-console\fR
- Specifies that this service uses the console; its input and output should be
- directed to the console (or precisely, to the device to which Dinit's standard
- output stream is connected). A service running on the console prevents other
- services from running on the console (they will queue for the console).
- The \fIinterrupt\fR key (normally control-C) will be active for process / scripted
- services that run on the console. Handling of an interrupt is determined by
- the service process, but typically will cause it to terminate.
- .TP
- \fBstarts\-on\-console\fR
- Specifies that this service uses the console during service startup. This is
- implied by \fBruns-on-console\fR, but can be specified separately for services
- that need the console while they start but not afterwards.
- This setting is not applicable to regular \fBprocess\fR services, but can be
- used for \fBscripted\fR and \fBbgprocess\fR services. It allows for
- interrupting startup via the \fIinterrupt\fR key (normally control-C). This is
- useful to allow filesystem checks to be interrupted/skipped.
- This option is implied by \fBruns\-on\-console\fR, and is mutually exclusive
- with \fBshares\-console\fR; setting this option, or setting \fBruns\-on\-console\fR,
- unsets \fBshares\-console\fR.
- .TP
- \fBshares\-console\fR
- Specifies that this service should be given access to the console (input and output
- will be connected to the console), but that it should not exclusively hold the
- console and not delay the start of services with \fBstarts\-on\-console\fR.
- This is mutually exclusive with both \fBstarts\-on\-console\fR and \fBruns\-on\-console\fR;
- setting this option unsets both those options.
- .TP
- \fBstarts-rwfs\fR
- This service mounts the root filesystem read/write (or at least mounts the
- normal writable filesystems for the system). This prompts Dinit to create its
- control socket, if it has not already managed to do so.
- .TP
- \fBstarts-log\fR
- This service starts the system log daemon. Dinit will begin logging via the
- \fI/dev/log\fR socket.
- .TP
- \fBpass-cs-fd\fR
- Pass an open Dinit control socket to the process when launching it (the
- \fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of
- the socket). This allows the service to issue commands to Dinit even if the
- regular control socket is not available yet.
- Using this option has security implications! The service which receives the
- control socket must close it before launching any untrusted processes. You
- should not use this option unless the service is designed to receive a Dinit
- control socket.
- .TP
- \fBstart-interruptible\fR
- This service can have its startup interrupted (cancelled) if it becomes inactive
- while still starting, by sending it the SIGINT signal. This is meaningful only
- for \fBbgprocess\fR and \fBscripted\fR services.
- .TP
- \fBskippable\fR
- For scripted services, indicates that if the service startup process terminates
- via an interrupt signal (SIGINT), then the service should be considered started.
- Note that if the interrupt was issued by Dinit to cancel startup, the service
- will instead be considered stopped.
- .TP
- \fBsignal-process-only\fR
- Signal the service process only, rather than its entire process group, whenever
- sending it a signal for any reason.
- .RE
- .LP
- The next section contains example service descriptions including some of the
- parameters and options described above.
- .\"
- .SS RESOURCE LIMITS
- .\"
- There are several settings for specifying process resource limits: \fBrlmit-nofile\fR,
- \fBrlimit-core\fR, \fBrlimit-data\fR and \fBrlimit-addrspace\fR. See the descriptions
- of each above. These settings place a limit on resource usage directly by the process.
- Note that resource limits are inherited by subprocesses, but that usage of a resource
- and subprocess are counted separately (in other words, a process can effectively bypass
- its resource limits by spawning a subprocess and allocating further resources within it).
- Resources have both a \fIhard\fR and \fIsoft\fR limit. The soft limit is the effective
- limit, but note that a process can raise its soft limit up to the hard limit for any
- given resource. Therefore the soft limit acts more as a sanity-check; a process can
- exceed the soft limit only by deliberately raising it first.
- Resource limits are specified in the following format:
- .RS
- \fIsoft-limit\fR:\fIhard-limit\fR
- .RE
- Either the soft limit or the hard limit can be omitted (in which case it will be unchanged).
- A limit can be specified as a dash, `\fB-\fR', in which case the limit will be removed. If
- only one value is specified with no colon separator, it affects both the soft and hard limit.
- .\"
- .SS EXAMPLES
- .LP
- Here is an example service description for the \fBmysql\fR database server.
- It has a dependency on the \fBrcboot\fR service (not shown) which is
- expected to have set up the system to a level suitable for basic operation.
- .RS
- .nf
- .gcolor blue
- .ft CR
- # mysqld service
- type = process
- command = /usr/bin/mysqld --user=mysql
- logfile = /var/log/mysqld.log
- smooth-recovery = true
- restart = false
- depends-on = rcboot # Basic system services must be ready
- .ft
- .gcolor
- .RE
- .fi
- .LP
- Here is an examples for a filesystem check "service", run by a script
- (\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the
- system, but the control socket may not have been created, so it uses the
- \fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control
- commands to Dinit. It runs on the console, so that output is visible and
- the process can be interrupted using control-C, in which case the check is
- skipped but dependent services continue to start.
- .RS
- .nf
- .gcolor blue
- .ft CR
- # rootfscheck service
- type = scripted
- command = /etc/dinit.d/rootfscheck.sh
- restart = false
- options = starts-on-console pass-cs-fd
- options = start-interruptible skippable
- depends-on = early-filesystems # /proc and /dev
- depends-on = device-node-daemon
- .ft
- .gcolor
- .fi
- .RE
- More examples are provided with the Dinit distribution.
- .\"
- .SH AUTHOR
- Dinit, and this manual, were written by Davin McCall.
- $$$dnl
|