-.TH DINIT-SERVICE "5" "June 2017" "Dinit 0.08" "Dinit \- service management system"
+.TH DINIT-SERVICE "5" "June 2018" "Dinit 0.2.0" "Dinit \- service management system"
.SH NAME
Dinit service description files
.\"
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 the service description directory (which defaults to
-\fI/etc/dinit.d\fR for the system process).
+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
Specifies the command to stop the service. Applicable only to \fBscripted\fR
services.
.TP
-\fBrun-as\fR = \fIuser-id\fR
+\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. The group id
for the process will also be set to the primary group of the specified user.
.TP
any reason (including unexpected process termination, service dependency
stopping, or user-initiated service stop).
.TP
-\fBsmooth-recovery\fR = {yes | true | no | false}
+\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
+\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
+\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
+\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
+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
+\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
+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
+\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
+\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
privileged user the path should therefore not be writable by unprivileged
users.
.TP
-\fBdepends-on\fR = \fIservice-name\fR
+\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" dependcy 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 the dependency is dropped until this service is next started.
+\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
+\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
-\fBsocket-listen\fR = \fIsocket-path\fR
+\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
+\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}
+\fBsocket\-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
Specifies the user that should own the activation socket. If
-\fBsocket-uid\fR is specified without also specifying \fBsocket-gid\fR, then
+\fBsocket\-uid\fR is specified 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 socket owner is not
specified, the socket will be owned by the user id of the Dinit process.
.TP
-\fBsocket-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
+\fBsocket\-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
Specifies the group of the activation socket. See discussion of
-\fBsocket-uid\fR.
+\fBsocket\-uid\fR.
.TP
\fBtermsignal\fR = {HUP | INT | QUIT | USR1 | USR2}
Specifies an additional signal to send to the process when requesting it
.TP
\fBoptions\fR = \fIoption\fR...
Specifies various options for this service. See the \fBOPTIONS\fR section.
+.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.
.\"
.SS OPTIONS
.\"
These options are specified via the \fBoptions\fR parameter.
.\"
.TP
-\fBno-sigterm\fR
+\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
+\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 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
+\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.
projects / oweals / dinit.git / blobdiff