doc/manpages/dinit-service.5

   1 .TH DINIT-SERVICE "5" "June 2017" "Dinit 0.07" "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 \fBrun-as\fR = \fIuser-id\fR
  88 Specifies which user to run the process(es) for this service as. The group id
  89 for the process will also be set to the primary group of the specified user.
  90 .TP
  91 \fBrestart\fR = {yes | true | no | false}
  92 Indicates whether the service should automatically restart if it stops for
  93 any reason (including unexpected process termination, service dependency
  94 stopping, or user-initiated service stop).
  95 .TP
  96 \fBsmooth-recovery\fR = {yes | true | no | false}
  97 Applies only to \fBprocess\fR and \fBbgprocess\fR services. When set true/yes,
  98 an automatic process restart can be performed without first stopping any
  99 dependent services. This setting is meaningless if the \fBrestart\fR setting
 100 is set to false.
 101 .TP
 102 \fBrestart-delay\fR = \fIXXX.YYYY\fR
 103 Specifies the minimum time between automatic restarts. Enforcing a sensible
 104 minimum prevents Dinit from consuming a large number of process cycles in
 105 case a process continuously fails immediately after it is started. The
 106 default is 0.2 (200 milliseconds).
 107 .TP
 108 \fBrestart-limit-interval\fR = \fIXXX.YYYY\fR
 109 Sets the interval, in seconds, over which restarts are limited. If a process
 110 automatically restarts more than a certain number of times (specified by the
 111 \fBrestart-limit-count\fR setting) in this time interval, it will not restart
 112 again. The default value is 10 seconds.
 113 .TP
 114 \fBrestart-limit-count\fR = \fINNN\fR
 115 Specifies the maximum number of times that a service can automatically restart
 116 over the interval specified by \fBrestart-limit-interval\fR. Specify a value
 117 of 0 to disable the restart limit.
 118 .TP
 119 \fBstart-timeout\fR = \fIXXX.YYY\fR
 120 Specifies the time in seconds allowed for the service to start. If the
 121 service takes longer than this, its process group is sent a SIGINT signal
 122 and enters the "stopping" state (this may be subject to a stop timeout, as
 123 specified via \fBstop-timeout\fR, after which the process group will be
 124 terminated via SIGKILL). The timeout period begins only when all dependencies
 125 have been stopped. The default timeout is 60 seconds. Specify a value of 0 to
 126 allow unlimited start time.
 127 .TP
 128 \fBstop-timeout\fR = \fIXXX.YYY\fR
 129 Specifies the time in seconds allowed for the service to stop. If the
 130 service takes longer than this, its process group is sent a SIGKILL signal
 131 which should cause it to terminate immediately. The timeout period begins
 132 only when all dependent services have already stopped. The default
 133 timeout is 10 seconds. Specify a value of 0 to allow unlimited stop time.
 134 .TP
 135 \fBpid-file\fR = \fIpath-to-file\fR
 136 For \fBbgprocess\fR type services only; specifies the path of the file where
 137 daemon will write its process ID before detaching. Dinit will read the
 138 contents of this file when starting the service, once the initial process
 139 exits, will supervise the process with the discovered process ID, and may
 140 send signals to the process ID to stop the service; if Dinit runs as a
 141 privileged user the path should therefore not be writable by unprivileged
 142 users.
 143 .TP
 144 \fBdepends-on\fR = \fIservice-name\fR
 145 This service depends on the named service. Starting this service will start
 146 the named service; the command to start this service will not be executed
 147 until the named service has started. If the named service is stopped then
 148 this service will also be stopped.
 149 .TP
 150 \fBdepends-ms\fR = \fIservice-name\fR
 151 This service has a "milestone" dependcy on the named service. Starting this
 152 service will start the named service; the command to start this service will
 153 not be executed until the named service has started. If the named service is
 154 stopped then the dependency is dropped until this service is next started.
 155 .TP
 156 \fBwaits-for\fR = \fIservice-name\fR
 157 When this service is started, wait for the named service to finish starting
 158 (or to fail starting) before commencing the start procedure for this service.
 159 Starting this service will automatically start the named service. If the
 160 named service fails to start, this service will start as usual (subject to
 161 other dependencies being met).
 162 .TP
 163 \fBsocket-listen\fR = \fIsocket-path\fR
 164 Pre-open a socket for the service and pass it to the service using the
 165 \fBsystemd\fR activation protocol. This by itself does not give so called
 166 "socket activation", but does allow that any process trying to connect to the
 167 specified socket will be able to do so, even before the service is properly
 168 prepared to accept connections.
 169 .TP
 170 \fBsocket-permissions\fR = \fIoctal-permissions-mask\fR
 171 Gives the permissions for the socket specified using \fBsocket-listen\fR.
 172 Normally this will be 600 (user access only), 660 (user and group
 173 access), or 666 (all users). The default is 666.
 174 .TP
 175 \fBsocket-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
 176 Specifies the user that should own the activation socket. If
 177 \fBsocket-uid\fR is specified without also specifying \fBsocket-gid\fR, then
 178 the socket group is the primary group of the specified user (as found in the
 179 system user database, normally \fI/etc/passwd\fR). If the socket owner is not
 180 specified, the socket will be owned by the user id of the Dinit process.
 181 .TP
 182 \fBsocket-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
 183 Specifies the group of the activation socket. See discussion of
 184 \fBsocket-uid\fR.
 185 .TP
 186 \fBtermsignal\fR = {HUP | INT | QUIT | USR1 | USR2}
 187 Specifies an additional signal to send to the process when requesting it
 188 to terminate (applies to 'process' services only). SIGTERM is always
 189 sent along with the specified signal, unless the \fBnosigterm\fR option is
 190 specified via the \fBoptions\fR parameter.
 191 .TP
 192 \fBlogfile\fR = \fIlog-file-path\fR
 193 Specifies the log file for the service. Output from the service process
 194 will go this file.
 195 .TP
 196 \fBoptions\fR = \fIoption\fR...
 197 Specifies various options for this service. See the \fBOPTIONS\fR section.
 198 .\"
 199 .SS OPTIONS
 200 .\"
 201 These options are specified via the \fBoptions\fR parameter.
 202 .\"
 203 .TP
 204 \fBno-sigterm\fR
 205 specifies that the TERM signal should not be send to the process to terminate
 206 it. (Another signal can be specified using the \fBtermsignal\fR setting; if no
 207 other signal is specified, no signal will be sent, which usually means that
 208 the service will not terminate).
 209 .TP
 210 \fBruns-on-console\fR
 211 specifies that this service uses the console; its input and output should be
 212 directed to the console (or precisely, to the device to which Dinit's standard
 213 output stream is connected). A service running on the console prevents other
 214 services from running on the console (they will queue for the console).
 215
 216 The \fIinterrupt\fR key (normally control-C) will be active for process / scripted
 217 services that run on the console. Handling of an interrupt is determined by
 218 the service process, but typically will cause it to terminate.
 219 .TP
 220 \fBstarts-on-console\fR
 221 specifies that this service uses the console during service startup. This is
 222 implied by \fBruns-on-console\fR, but can be specified separately for services
 223 that need the console while they start but not afterwards.
 224
 225 This setting is not applicable to regular \fBprocess\fR services, but can be
 226 used for \fBscripted\fR and \fBbgprocess\fR services. It allows for
 227 interrupting startup via the \fIinterrupt\fR key (normally control-C). This is
 228 useful to allow filesystem checks to be interrupted/skipped.
 229 .TP
 230 \fBstarts-rwfs\fR
 231 this service mounts the root filesystem read/write (or at least mounts the
 232 normal writable filesystems for the system). This prompts Dinit to create its
 233 control socket, if it has not already managed to do so.
 234 .TP
 235 \fBstarts-log\fR
 236 this service starts the system log daemon. Dinit will begin logging via the
 237 \fI/dev/log\fR socket.
 238 .TP
 239 \fBpass-cs-fd\fR
 240 pass an open Dinit control socket to the process when launching it (the
 241 \fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of
 242 the socket). This allows the service to issue commands to Dinit even if the
 243 regular control socket is not available yet.
 244
 245 Using this option has security implications! The service which receives the
 246 control socket must close it before launching any untrusted processes. You
 247 should not use this option unless the service is designed to receive a Dinit
 248 control socket.
 249 .TP
 250 \fBstart-interruptible\fR
 251 this service can have its startup interrupted (cancelled) if it becomes inactive
 252 while still starting, by sending it the SIGINT signal. This is meaningful only
 253 for \fBbgprocess\fR and \fBscripted\fR services.
 254 .RE
 255 .LP
 256 The next section contains example service descriptions including some of the
 257 parameters and options described above.
 258 .\"
 259 .SS EXAMPLES
 260 .LP
 261 Here is an example service description for the \fBmysql\fR database server.
 262 It has a dependency on the \fBrcboot\fR service (not shown) which is
 263 expected to have set up the system to a level suitable for basic operation.
 264
 265 .RS
 266 .nf
 267 .gcolor blue
 268 .ft CR
 269 # mysqld service
 270 type = process
 271 command = /usr/bin/mysqld --user=mysql
 272 logfile = /var/log/mysqld.log
 273 smooth-recovery = true
 274 restart = false
 275 depends-on = rcboot # Basic system services must be ready
 276 .ft
 277 .gcolor
 278 .RE
 279 .fi
 280 .LP
 281 Here is an examples for a filesystem check "service", run by a script
 282 (\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the
 283 system, but the control socket may not have been created, so it uses the
 284 \fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control
 285 commands to Dinit. It runs on the console, so that output is visible and
 286 the process can be interrupted using control-C.
 287
 288 .RS
 289 .nf
 290 .gcolor blue
 291 .ft CR
 292 # rootfscheck service
 293 type = scripted
 294 command = /etc/dinit.d/rootfscheck.sh
 295 restart = false
 296 options = starts-on-console pass-cs-fd
 297 depends-on = early-filesystems  # /proc and /dev
 298 depends-on = device-node-daemon
 299 .ft
 300 .gcolor
 301 .fi
 302 .RE
 303
 304 More examples are provided with the Dinit distribution.
 305 .\"
 306 .SH AUTHOR
 307 Dinit, and this manual, were written by Davin McCall.