doc/manpages/dinit-service.5

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