doc/manpages/dinit-service.5

   1 .TH DINIT-SERVICE "5" "June 2017" "Dinit 0.08" "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" dependcy on the named service. Starting this
 156 service will start the named service; the command to start this service will
 157 not be executed until the named service has started. If the named service is
 158 stopped then the dependency is dropped until this service is next started.
 159 .TP
 160 \fBwaits-for\fR = \fIservice-name\fR
 161 When this service is started, wait for the named service to finish starting
 162 (or to fail starting) before commencing the start procedure for this service.
 163 Starting this service will automatically start the named service. If the
 164 named service fails to start, this service will start as usual (subject to
 165 other dependencies being met).
 166 .TP
 167 \fBsocket-listen\fR = \fIsocket-path\fR
 168 Pre-open a socket for the service and pass it to the service using the
 169 \fBsystemd\fR activation protocol. This by itself does not give so called
 170 "socket activation", but does allow that any process trying to connect to the
 171 specified socket will be able to do so, even before the service is properly
 172 prepared to accept connections.
 173 .TP
 174 \fBsocket-permissions\fR = \fIoctal-permissions-mask\fR
 175 Gives the permissions for the socket specified using \fBsocket-listen\fR.
 176 Normally this will be 600 (user access only), 660 (user and group
 177 access), or 666 (all users). The default is 666.
 178 .TP
 179 \fBsocket-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
 180 Specifies the user that should own the activation socket. If
 181 \fBsocket-uid\fR is specified without also specifying \fBsocket-gid\fR, then
 182 the socket group is the primary group of the specified user (as found in the
 183 system user database, normally \fI/etc/passwd\fR). If the socket owner is not
 184 specified, the socket will be owned by the user id of the Dinit process.
 185 .TP
 186 \fBsocket-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
 187 Specifies the group of the activation socket. See discussion of
 188 \fBsocket-uid\fR.
 189 .TP
 190 \fBtermsignal\fR = {HUP | INT | QUIT | USR1 | USR2}
 191 Specifies an additional signal to send to the process when requesting it
 192 to terminate (applies to 'process' services only). SIGTERM is always
 193 sent along with the specified signal, unless the \fBnosigterm\fR option is
 194 specified via the \fBoptions\fR parameter.
 195 .TP
 196 \fBlogfile\fR = \fIlog-file-path\fR
 197 Specifies the log file for the service. Output from the service process
 198 will go this file.
 199 .TP
 200 \fBoptions\fR = \fIoption\fR...
 201 Specifies various options for this service. See the \fBOPTIONS\fR section.
 202 .\"
 203 .SS OPTIONS
 204 .\"
 205 These options are specified via the \fBoptions\fR parameter.
 206 .\"
 207 .TP
 208 \fBno-sigterm\fR
 209 specifies that the TERM signal should not be send to the process to terminate
 210 it. (Another signal can be specified using the \fBtermsignal\fR setting; if no
 211 other signal is specified, no signal will be sent, which usually means that
 212 the service will not terminate).
 213 .TP
 214 \fBruns-on-console\fR
 215 specifies that this service uses the console; its input and output should be
 216 directed to the console (or precisely, to the device to which Dinit's standard
 217 output stream is connected). A service running on the console prevents other
 218 services from running on the console (they will queue for the console).
 219
 220 The \fIinterrupt\fR key (normally control-C) will be active for process / scripted
 221 services that run on the console. Handling of an interrupt is determined by
 222 the service process, but typically will cause it to terminate.
 223 .TP
 224 \fBstarts-on-console\fR
 225 specifies that this service uses the console during service startup. This is
 226 implied by \fBruns-on-console\fR, but can be specified separately for services
 227 that need the console while they start but not afterwards.
 228
 229 This setting is not applicable to regular \fBprocess\fR services, but can be
 230 used for \fBscripted\fR and \fBbgprocess\fR services. It allows for
 231 interrupting startup via the \fIinterrupt\fR key (normally control-C). This is
 232 useful to allow filesystem checks to be interrupted/skipped.
 233 .TP
 234 \fBstarts-rwfs\fR
 235 this service mounts the root filesystem read/write (or at least mounts the
 236 normal writable filesystems for the system). This prompts Dinit to create its
 237 control socket, if it has not already managed to do so.
 238 .TP
 239 \fBstarts-log\fR
 240 this service starts the system log daemon. Dinit will begin logging via the
 241 \fI/dev/log\fR socket.
 242 .TP
 243 \fBpass-cs-fd\fR
 244 pass an open Dinit control socket to the process when launching it (the
 245 \fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of
 246 the socket). This allows the service to issue commands to Dinit even if the
 247 regular control socket is not available yet.
 248
 249 Using this option has security implications! The service which receives the
 250 control socket must close it before launching any untrusted processes. You
 251 should not use this option unless the service is designed to receive a Dinit
 252 control socket.
 253 .TP
 254 \fBstart-interruptible\fR
 255 this service can have its startup interrupted (cancelled) if it becomes inactive
 256 while still starting, by sending it the SIGINT signal. This is meaningful only
 257 for \fBbgprocess\fR and \fBscripted\fR services.
 258 .RE
 259 .LP
 260 The next section contains example service descriptions including some of the
 261 parameters and options described above.
 262 .\"
 263 .SS EXAMPLES
 264 .LP
 265 Here is an example service description for the \fBmysql\fR database server.
 266 It has a dependency on the \fBrcboot\fR service (not shown) which is
 267 expected to have set up the system to a level suitable for basic operation.
 268
 269 .RS
 270 .nf
 271 .gcolor blue
 272 .ft CR
 273 # mysqld service
 274 type = process
 275 command = /usr/bin/mysqld --user=mysql
 276 logfile = /var/log/mysqld.log
 277 smooth-recovery = true
 278 restart = false
 279 depends-on = rcboot # Basic system services must be ready
 280 .ft
 281 .gcolor
 282 .RE
 283 .fi
 284 .LP
 285 Here is an examples for a filesystem check "service", run by a script
 286 (\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the
 287 system, but the control socket may not have been created, so it uses the
 288 \fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control
 289 commands to Dinit. It runs on the console, so that output is visible and
 290 the process can be interrupted using control-C.
 291
 292 .RS
 293 .nf
 294 .gcolor blue
 295 .ft CR
 296 # rootfscheck service
 297 type = scripted
 298 command = /etc/dinit.d/rootfscheck.sh
 299 restart = false
 300 options = starts-on-console pass-cs-fd
 301 depends-on = early-filesystems  # /proc and /dev
 302 depends-on = device-node-daemon
 303 .ft
 304 .gcolor
 305 .fi
 306 .RE
 307
 308 More examples are provided with the Dinit distribution.
 309 .\"
 310 .SH AUTHOR
 311 Dinit, and this manual, were written by Davin McCall.