doc/manpages/dinit-service.5

   1 .TH DINIT-SERVICE "5" "June 2018" "Dinit 0.2.0" "Dinit \- service management system"
   2 .SH NAME
   3 Dinit service description files
   4 .\"
   5 .SH SYNOPSIS
   6 .\"
   7 .ft CR
   8 /etc/dinit.d/\fIservice-name\fR, $HOME/dinit.d/\fIservice-name\fR
   9 .ft
  10 .\"
  11 .SH DESCRIPTION
  12 .\"
  13 The service description files for \fBDinit\fR each describe a service. The name
  14 of the file corresponds to the name of the service it describes.
  15 .LP
  16 Service description files specify the various attributes of a service. A
  17 service description file is named after the service it represents, and is
  18 a plain-text file with simple key-value format. The description files are
  19 located in a service description directory; by default, the system process
  20 searches \fI/etc/dinit.d\fR, \fI/usr/local/lib/dinit.d\fR and
  21 \fI/lib/dinit.d\fR, while a user process searches \fI$HOME/dinit.d\fR.
  22 .LP
  23 All services have a \fItype\fR and a set of \fIdependencies\fR. Service
  24 types are discussed in the following subsection. If a service depends on
  25 another service, then starting the first service causes the second to start
  26 also (and the second service must complete its startup before the first
  27 is considered started). Similarly, if one service depends on another which
  28 becomes stopped, the first service must also stop.
  29 .\"
  30 .SS SERVICE TYPES
  31 .\"
  32 There are four basic types of service:
  33 .IP \(bu
  34 \fBProcess\fR services. This kind of service runs as a single process; starting
  35 the service simply requires starting the process; stopping the service is
  36 accomplished by stopping the process (via sending it a signal).
  37 .IP \(bu
  38 \fBBgprocess\fR services ("background process" services). This kind of
  39 service is similar to a regular process service, but the process daemonizes
  40 or otherwise forks from the original process which starts it, and the
  41 process ID is written to a file. Dinit can read the process ID from the
  42 file and, if it is running as the system init process, can supervise it.
  43 .IP \(bu
  44 \fBScripted\fR services are services which are started and stopped by a
  45 command (which need not actually be a script, despite the name). They can
  46 not be supervised.
  47 .IP \(bu
  48 \fBInternal\fR services do not run as an external process at all. They can
  49 be started and stopped without any external action. They are useful for
  50 grouping other services (via service dependencies).
  51 .\"
  52 .SS SERVICE PROPERTIES
  53 .\"
  54 This section described the various service properties that can be specified
  55 in a service description file. Each line of the file can specify a single
  56 property value, expressed as "\fIproperty-name\fR = \fIvalue\fR". Comments
  57 begin with a hash mark (#) and extend to the end of the line (they must be
  58 separated from setting values by at least one whitespace character). Values
  59 are interpreted literally, except that:
  60 .\"
  61 .IP \(bu
  62 White space (comprised of spaces, tabs, etc) is collapsed to a single space.
  63 .IP \(bu
  64 Double quotes (") can be used around all or part of a property value, to
  65 prevent whitespace collapse and prevent interpretation of other special
  66 characters (such as "#") inside the quotes. The quote characters are not
  67 considered part of the parameter value.
  68 .IP \(bu
  69 A backslash (\\) can be used to escape the next character, causing it to
  70 lose any special meaning and become part of the property value. A double
  71 backslash (\\\\) is collapsed to a single backslash within the parameter
  72 value.
  73 .LP
  74 The following properties can be specified:
  75 .TP
  76 \fBtype\fR = {process | bgprocess | scripted | internal}
  77 Specifies the service type.
  78 .TP
  79 \fBcommand\fR = \fIcommand-string\fR
  80 Specifies the command, including command-line arguments, for starting the
  81 process. Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR
  82 services.
  83 .TP
  84 \fBstop\-command\fR = \fIcommand-string\fR
  85 Specifies the command to stop the service. Applicable only to \fBscripted\fR
  86 services.
  87 .TP
  88 \fBworking-dir\fR = \fIdirectory\fR
  89 Specifies the working directory for this service. For a scripted service, this
  90 affects both the start command and the stop command.
  91 .TP
  92 \fBrun\-as\fR = \fIuser-id\fR
  93 Specifies which user to run the process(es) for this service as. The group id
  94 for the process will also be set to the primary group of the specified user.
  95 .TP
  96 \fBrestart\fR = {yes | true | no | false}
  97 Indicates whether the service should automatically restart if it stops for
  98 any reason (including unexpected process termination, service dependency
  99 stopping, or user-initiated service stop).
 100 .TP
 101 \fBsmooth\-recovery\fR = {yes | true | no | false}
 102 Applies only to \fBprocess\fR and \fBbgprocess\fR services. When set true/yes,
 103 an automatic process restart can be performed without first stopping any
 104 dependent services. This setting is meaningless if the \fBrestart\fR setting
 105 is set to false.
 106 .TP
 107 \fBrestart\-delay\fR = \fIXXX.YYYY\fR
 108 Specifies the minimum time between automatic restarts. Enforcing a sensible
 109 minimum prevents Dinit from consuming a large number of process cycles in
 110 case a process continuously fails immediately after it is started. The
 111 default is 0.2 (200 milliseconds).
 112 .TP
 113 \fBrestart\-limit\-interval\fR = \fIXXX.YYYY\fR
 114 Sets the interval, in seconds, over which restarts are limited. If a process
 115 automatically restarts more than a certain number of times (specified by the
 116 \fBrestart-limit-count\fR setting) in this time interval, it will not restart
 117 again. The default value is 10 seconds.
 118 .TP
 119 \fBrestart\-limit\-count\fR = \fINNN\fR
 120 Specifies the maximum number of times that a service can automatically restart
 121 over the interval specified by \fBrestart\-limit\-interval\fR. Specify a value
 122 of 0 to disable the restart limit.
 123 .TP
 124 \fBstart\-timeout\fR = \fIXXX.YYY\fR
 125 Specifies the time in seconds allowed for the service to start. If the
 126 service takes longer than this, its process group is sent a SIGINT signal
 127 and enters the "stopping" state (this may be subject to a stop timeout, as
 128 specified via \fBstop\-timeout\fR, after which the process group will be
 129 terminated via SIGKILL). The timeout period begins only when all dependencies
 130 have been stopped. The default timeout is 60 seconds. Specify a value of 0 to
 131 allow unlimited start time.
 132 .TP
 133 \fBstop\-timeout\fR = \fIXXX.YYY\fR
 134 Specifies the time in seconds allowed for the service to stop. If the
 135 service takes longer than this, its process group is sent a SIGKILL signal
 136 which should cause it to terminate immediately. The timeout period begins
 137 only when all dependent services have already stopped. The default
 138 timeout is 10 seconds. Specify a value of 0 to allow unlimited stop time.
 139 .TP
 140 \fBpid\-file\fR = \fIpath-to-file\fR
 141 For \fBbgprocess\fR type services only; specifies the path of the file where
 142 daemon will write its process ID before detaching. Dinit will read the
 143 contents of this file when starting the service, once the initial process
 144 exits, will supervise the process with the discovered process ID, and may
 145 send signals to the process ID to stop the service; if Dinit runs as a
 146 privileged user the path should therefore not be writable by unprivileged
 147 users.
 148 .TP
 149 \fBdepends\-on\fR = \fIservice-name\fR
 150 This service depends on the named service. Starting this service will start
 151 the named service; the command to start this service will not be executed
 152 until the named service has started. If the named service is stopped then
 153 this service will also be stopped.
 154 .TP
 155 \fBdepends\-ms\fR = \fIservice-name\fR
 156 This service has a "milestone" dependency on the named service. Starting this
 157 service will start the named service; this service will not start until the
 158 named service has started, and will fail to start if the named service does
 159 not start. Once the named service reaches the started state, however, the
 160 dependency is effectively dropped until this service is next started.
 161 .TP
 162 \fBwaits\-for\fR = \fIservice-name\fR
 163 When this service is started, wait for the named service to finish starting
 164 (or to fail starting) before commencing the start procedure for this service.
 165 Starting this service will automatically start the named service. If the
 166 named service fails to start, this service will start as usual (subject to
 167 other dependencies being met).
 168 .TP
 169 \fBsocket\-listen\fR = \fIsocket-path\fR
 170 Pre-open a socket for the service and pass it to the service using the
 171 \fBsystemd\fR activation protocol. This by itself does not give so called
 172 "socket activation", but does allow that any process trying to connect to the
 173 specified socket will be able to do so, even before the service is properly
 174 prepared to accept connections.
 175 .TP
 176 \fBsocket\-permissions\fR = \fIoctal-permissions-mask\fR
 177 Gives the permissions for the socket specified using \fBsocket-listen\fR.
 178 Normally this will be 600 (user access only), 660 (user and group
 179 access), or 666 (all users). The default is 666.
 180 .TP
 181 \fBsocket\-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
 182 Specifies the user that should own the activation socket. If
 183 \fBsocket\-uid\fR is specified without also specifying \fBsocket-gid\fR, then
 184 the socket group is the primary group of the specified user (as found in the
 185 system user database, normally \fI/etc/passwd\fR). If the socket owner is not
 186 specified, the socket will be owned by the user id of the Dinit process.
 187 .TP
 188 \fBsocket\-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
 189 Specifies the group of the activation socket. See discussion of
 190 \fBsocket\-uid\fR.
 191 .TP
 192 \fBtermsignal\fR = {HUP | INT | QUIT | USR1 | USR2}
 193 Specifies an additional signal to send to the process when requesting it
 194 to terminate (applies to 'process' services only). SIGTERM is always
 195 sent along with the specified signal, unless the \fBnosigterm\fR option is
 196 specified via the \fBoptions\fR parameter.
 197 .TP
 198 \fBlogfile\fR = \fIlog-file-path\fR
 199 Specifies the log file for the service. Output from the service process
 200 will go this file.
 201 .TP
 202 \fBoptions\fR = \fIoption\fR...
 203 Specifies various options for this service. See the \fBOPTIONS\fR section.
 204 .TP
 205 \fBload-options\fR = \fIload_option\fR...
 206 Specifies options for interpreting other settings when loading this service
 207 description. Currently there is only one available option, \fBsub-vars\fR,
 208 which specifies that command line arguments in the form of \fB$NAME\fR should
 209 be replaced with the contents of the environment variable with the specified
 210 name. Note that no word-splitting is performed and the variable value always
 211 becomes a single argument; if the variable is not defined, it is replaced with
 212 an empty (zero-length) argument.
 213 .\"
 214 .SS OPTIONS
 215 .\"
 216 These options are specified via the \fBoptions\fR parameter.
 217 .\"
 218 .TP
 219 \fBno\-sigterm\fR
 220 specifies that the TERM signal should not be send to the process to terminate
 221 it. (Another signal can be specified using the \fBtermsignal\fR setting; if no
 222 other signal is specified, no signal will be sent, which usually means that
 223 the service will not terminate).
 224 .TP
 225 \fBruns\-on\-console\fR
 226 specifies that this service uses the console; its input and output should be
 227 directed to the console (or precisely, to the device to which Dinit's standard
 228 output stream is connected). A service running on the console prevents other
 229 services from running on the console (they will queue for the console).
 230
 231 The \fIinterrupt\fR key (normally control-C) will be active for process / scripted
 232 services that run on the console. Handling of an interrupt is determined by
 233 the service process, but typically will cause it to terminate.
 234 .TP
 235 \fBstarts\-on\-console\fR
 236 specifies that this service uses the console during service startup. This is
 237 implied by \fBruns-on-console\fR, but can be specified separately for services
 238 that need the console while they start but not afterwards.
 239
 240 This setting is not applicable to regular \fBprocess\fR services, but can be
 241 used for \fBscripted\fR and \fBbgprocess\fR services. It allows for
 242 interrupting startup via the \fIinterrupt\fR key (normally control-C). This is
 243 useful to allow filesystem checks to be interrupted/skipped.
 244 .TP
 245 \fBstarts-rwfs\fR
 246 this service mounts the root filesystem read/write (or at least mounts the
 247 normal writable filesystems for the system). This prompts Dinit to create its
 248 control socket, if it has not already managed to do so.
 249 .TP
 250 \fBstarts-log\fR
 251 this service starts the system log daemon. Dinit will begin logging via the
 252 \fI/dev/log\fR socket.
 253 .TP
 254 \fBpass-cs-fd\fR
 255 pass an open Dinit control socket to the process when launching it (the
 256 \fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of
 257 the socket). This allows the service to issue commands to Dinit even if the
 258 regular control socket is not available yet.
 259
 260 Using this option has security implications! The service which receives the
 261 control socket must close it before launching any untrusted processes. You
 262 should not use this option unless the service is designed to receive a Dinit
 263 control socket.
 264 .TP
 265 \fBstart-interruptible\fR
 266 this service can have its startup interrupted (cancelled) if it becomes inactive
 267 while still starting, by sending it the SIGINT signal. This is meaningful only
 268 for \fBbgprocess\fR and \fBscripted\fR services.
 269 .RE
 270 .LP
 271 The next section contains example service descriptions including some of the
 272 parameters and options described above.
 273 .\"
 274 .SS EXAMPLES
 275 .LP
 276 Here is an example service description for the \fBmysql\fR database server.
 277 It has a dependency on the \fBrcboot\fR service (not shown) which is
 278 expected to have set up the system to a level suitable for basic operation.
 279
 280 .RS
 281 .nf
 282 .gcolor blue
 283 .ft CR
 284 # mysqld service
 285 type = process
 286 command = /usr/bin/mysqld --user=mysql
 287 logfile = /var/log/mysqld.log
 288 smooth-recovery = true
 289 restart = false
 290 depends-on = rcboot # Basic system services must be ready
 291 .ft
 292 .gcolor
 293 .RE
 294 .fi
 295 .LP
 296 Here is an examples for a filesystem check "service", run by a script
 297 (\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the
 298 system, but the control socket may not have been created, so it uses the
 299 \fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control
 300 commands to Dinit. It runs on the console, so that output is visible and
 301 the process can be interrupted using control-C.
 302
 303 .RS
 304 .nf
 305 .gcolor blue
 306 .ft CR
 307 # rootfscheck service
 308 type = scripted
 309 command = /etc/dinit.d/rootfscheck.sh
 310 restart = false
 311 options = starts-on-console pass-cs-fd
 312 depends-on = early-filesystems  # /proc and /dev
 313 depends-on = device-node-daemon
 314 .ft
 315 .gcolor
 316 .fi
 317 .RE
 318
 319 More examples are provided with the Dinit distribution.
 320 .\"
 321 .SH AUTHOR
 322 Dinit, and this manual, were written by Davin McCall.