dinit-service.5.m4 40 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772
  1. changequote(`@@@',`$$$')dnl
  2. @@@.TH DINIT-SERVICE "5" "$$$MONTH YEAR@@@" "Dinit $$$VERSION@@@" "Dinit \- service management system"
  3. .SH NAME
  4. Dinit service description files
  5. .\"
  6. .SH SYNOPSIS
  7. .\"
  8. .ft CR
  9. /etc/dinit.d/\fIservice-name\fR, $XDG_CONFIG_HOME/dinit.d/\fIservice-name\fR
  10. .ft
  11. .\"
  12. .SH DESCRIPTION
  13. .\"
  14. The service description files for \fBDinit\fR each describe a service. The name
  15. of the file corresponds to the name of the service it describes.
  16. .LP
  17. Service description files specify the various attributes of a service. A
  18. service description file is named after the service it represents, and is
  19. a plain-text file with simple key-value format.
  20. The description files are located in a service description directory;
  21. See \fBdinit\fR(8) for more details of the default service description directories,
  22. and how and when service descriptions are loaded.
  23. .LP
  24. All services have a \fItype\fR and a set of \fIdependencies\fR. These are discussed
  25. in the following subsections. The type, dependencies, and other attributes are
  26. specified via property settings, the format of which are documented in the
  27. \fBSERVICE PROPERTIES\fR subsection, which also lists the available properties.
  28. .\"
  29. .SS SERVICE TYPES
  30. .\"
  31. There are five basic types of service:
  32. .IP \(bu
  33. \fBProcess\fR services. This kind of service runs a single supervised process; the process
  34. is started when the service is started and stopped when the service is stopped. If the
  35. process stops this also affects the service state, i.e. the service's started/stopped state is
  36. linked to the state of its associated process.
  37. .IP \(bu
  38. \fBBgprocess\fR services ("background process" services).
  39. This kind of service is similar to a regular process service, but is for a process which
  40. "daemonizes" or otherwise forks from the original process which starts it, and writes its
  41. new process ID to a file.
  42. Dinit will read the process ID from the file and, if running as the system init process or if the
  43. system provides the necessary facilities, can supervise the process just as for a \fBprocess\fR
  44. service.
  45. When starting a \fBbgprocess\fR service, Dinit will not consider the service to be fully started
  46. until the original process forks and terminates.
  47. .IP \(bu
  48. \fBScripted\fR services are services which are started and stopped by executing commands (which
  49. need not actually be scripts, despite the name).
  50. Once a command completes successfully the service is considered started (or stopped, as appropriate)
  51. by Dinit.
  52. .IP \(bu
  53. \fBInternal\fR services do not run as an external process at all.
  54. They can be started and stopped without any external action.
  55. They are useful for grouping other services (via service dependencies).
  56. .IP \(bu
  57. \fbTriggered\fR services are similar to internal processes, but an external trigger is required
  58. before they will start (i.e. Dinit will not consider them as started until the trigger is issued).
  59. The \fBdinitctl trigger\fR command can be used to trigger such a service; see \fBdinitctl\fR(8).
  60. .LP
  61. Independent of their type, the state of services can be linked to other
  62. services via dependency relationships, which are discussed in the next section.
  63. .\"
  64. .SS SERVICE DEPENDENCIES
  65. .\"
  66. A service dependency relationship, broadly speaking, specifies that for one
  67. service to run, another must also be running; when starting a service Dinit will wait until
  68. dependencies are satisfied before starting any processes associated with the service.
  69. The first service is the \fIdependent\fR service and the latter is the \fIdependency\fR
  70. service (we will henceforth generally refer to the the dependency relationship as the
  71. \fIrelationship\fR and use \fIdependency\fR to refer to the service).
  72. A dependency relationship is specified via the properties of the dependent.
  73. There are different relationship types, as follows:
  74. .IP \(bu
  75. A \fBneed\fR (or "hard") relationship specifies that the dependent must wait
  76. for the dependency to be started before it starts, and that the dependency
  77. must remain started while the dependent is started.
  78. Starting the dependent will start the dependency, and stopping the dependency will stop the
  79. dependent. This type of relationship is specified using a \fBdepends-on\fR property.
  80. .IP \(bu
  81. A \fBmilestone\fR relationship specifies that the dependency must
  82. start successfully before the dependent starts.
  83. Starting the dependent will therefore start the dependency.
  84. Once started, the relationship is satisfied; if the dependency then stops, it
  85. has no effect on the dependent.
  86. However, if the dependency fails to start or has its startup cancelled, the dependent will
  87. not start (and will return to the stopped state).
  88. This type of relationship is specified using a \fBdepends-ms\fR property.
  89. .IP \(bu
  90. A \fBwaits-for\fR relationship specifies that the dependency must
  91. start successfully, or fail to start, before the dependent starts.
  92. Starting the dependent will attempt to first start the dependency, but failure will
  93. not prevent the dependent from starting.
  94. If the dependency starts, stopping it will have no effect on the dependent.
  95. This type of relationship is specified using a \fBwaits-for\fR property.
  96. .LP
  97. Note that process-based services always wait for their dependency relationships
  98. to be satisfied (by the dependency starting, or failing to start in case of a waits-for
  99. relationship) before their process is launched.
  100. Conversely, a termination signal will not in general be sent to a service process until
  101. the service has no active dependents.
  102. .LP
  103. Since in general dependencies should remain started so long as their dependent
  104. does, an attachment forms between the two once both are started.
  105. This attachment is released when the dependent stops, and the dependency will then stop, unless
  106. it has other attachments or it has been explicitly started independently.
  107. Attachments between a dependent and dependency are re-created if a dependency
  108. starts (or starts again) while the dependent is still started.
  109. .\"
  110. .SS SERVICE PROPERTIES
  111. .\"
  112. This section described the various service properties that can be specified
  113. in a service description file. The properties specify the type of the service,
  114. dependencies of the service, and other service configuration.
  115. .LP
  116. Each line of the file can specify a single
  117. property value, expressed as `\fIproperty-name\fR = \fIvalue\fR'. Comments
  118. begin with a hash mark (#) and extend to the end of the line (they must be
  119. separated from setting values by at least one whitespace character).
  120. Values are interpreted literally, except that:
  121. .\"
  122. .IP \(bu
  123. White space (comprised of spaces, tabs, etc) is collapsed to a single space, except
  124. leading or trailing white space around the property value, which is stripped.
  125. .IP \(bu
  126. For settings which specify a command with arguments, the value is interpreted as a
  127. series of tokens separated by white space, rather than a single string of characters.
  128. .IP \(bu
  129. Double quotes (") can be used around all or part of a property value, to
  130. prevent whitespace collapse and prevent interpretation of other special
  131. characters (such as "#") inside the quotes.
  132. The quote characters are not considered part of the property value.
  133. White space appearing inside quotes does not act as a delimiter for tokens.
  134. .IP \(bu
  135. A backslash (\\) can be used to escape the next character, causing it to
  136. lose any special meaning and become part of the property value.
  137. A double backslash (\\\\) is collapsed to a single backslash within the parameter value.
  138. White space preceded by a backslash will not separate tokens.
  139. .LP
  140. Setting a property generally overrides any previous setting (from prior lines).
  141. However some properties are set additively; these include dependency relationships and \fBoptions\fR
  142. properties.
  143. .LP
  144. The following properties can be specified:
  145. .TP
  146. \fBtype\fR = {process | bgprocess | scripted | internal | triggered}
  147. Specifies the service type; see the \fBSERVICE TYPES\fR section.
  148. .TP
  149. \fBcommand\fR = \fIcommand-string\fR
  150. Specifies the command, including command-line arguments, for starting the process.
  151. Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR services.
  152. The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
  153. .TP
  154. \fBstop\-command\fR = \fIcommand-string\fR
  155. Specifies the command to stop the service (optional). Applicable to \fBprocess\fR, \fBbgprocess\fR and
  156. \fBscripted\fR services. If specified for \fBprocess\fR or \fBbgprocess\fR services, the "stop
  157. command" will be executed in order to stop the service, instead of signalling the service process.
  158. The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
  159. .TP
  160. \fBworking\-dir\fR = \fIdirectory\fR
  161. Specifies the working directory for this service.
  162. For a scripted service, this affects both the start command and the stop command.
  163. The default is the directory containing the service description.
  164. The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
  165. .TP
  166. \fBrun\-as\fR = \fIuser-id\fR
  167. Specifies which user to run the process(es) for this service as.
  168. Specify as a username or numeric ID.
  169. If specified by name, the group for the process will also be set to the primary
  170. group of the specified user, and supplementary groups will be initialised (unless support
  171. for them is disabled) according to the system's group database.
  172. If specified by number, the group for the process will remain the same as that of the
  173. running \fBdinit\fR process, and all supplementary groups will be dropped (unless support
  174. has been disabled).
  175. .TP
  176. \fBenv\-file\fR = \fIfile\fR
  177. Specifies a file containing value assignments for environment variables, in the same
  178. format recognised by the \fBdinit\fR command's \fB\-\-env\-file\fR option (see \fBdinit\fR(8)).
  179. The file is read when the service is loaded, therefore values from it can be used in variable
  180. substitutions (see \fBVARIABLE SUBSTITUTION\fR).
  181. Variable substitution is not performed on the \fBenv\-file\fR property value itself.
  182. If the path is not absolute, it is resolved relative to the directory containing the service
  183. description.
  184. .TP
  185. \fBrestart\fR = {yes | true | no | false}
  186. Indicates whether the service should automatically restart if it stops, including due to
  187. unexpected process termination or a dependency stopping.
  188. Note that if a service stops due to user request, automatic restart is inhibited.
  189. $$$changequote(`,')dnl
  190. ifelse(DEFAULT_AUTO_RESTART, true,
  191. ``The default is to automatically restart.'',
  192. ``The default is to not automatically restart.'')
  193. changequote(`@@@',`$$$')dnl
  194. @@@.TP
  195. \fBsmooth\-recovery\fR = {yes | true | no | false}
  196. Applies only to \fBprocess\fR and \fBbgprocess\fR services.
  197. When set to true/yes, if the process terminates unexpectedly (i.e. without a stop order having been
  198. issued), an automatic process restart is performed, without first stopping any dependent services
  199. and without the service changing state.
  200. The normal restart restrictions (such as \fBrestart\-limit\-count\fR) apply.
  201. .TP
  202. \fBrestart\-delay\fR = \fIXXX.YYYY\fR
  203. Specifies the minimum time (in seconds) between automatic restarts.
  204. The default is 0.2 (200 milliseconds).
  205. .TP
  206. \fBrestart\-limit\-interval\fR = \fIXXX.YYYY\fR
  207. Sets the interval (in seconds) over which restarts are limited.
  208. If a process automatically restarts more than a certain number of times (specified by the
  209. \fBrestart-limit-count\fR setting) in this time interval, it will not be restarted again.
  210. The default value is 10 seconds.
  211. .TP
  212. \fBrestart\-limit\-count\fR = \fINNN\fR
  213. Specifies the maximum number of times that a service can automatically restart
  214. over the interval specified by \fBrestart\-limit\-interval\fR.
  215. Specify a value of 0 to disable the restart limit.
  216. The default value is 3.
  217. .TP
  218. \fBstart\-timeout\fR = \fIXXX.YYY\fR
  219. Specifies the time in seconds allowed for the service to start.
  220. If the service takes longer than this, its process group is sent a SIGINT signal
  221. and enters the "stopping" state (this may be subject to a stop timeout, as
  222. specified via \fBstop\-timeout\fR, after which the process group will be
  223. terminated via SIGKILL).
  224. The timeout period begins only when all dependencies have been satisfied.
  225. The default value is $$$DEFAULT_START_TIMEOUT@@@.
  226. A value of 0 allows unlimited start time.
  227. .TP
  228. \fBstop\-timeout\fR = \fIXXX.YYY\fR
  229. Specifies the time in seconds allowed for the service to stop.
  230. If the service takes longer than this, its process group is sent a SIGKILL signal
  231. which should cause it to terminate immediately.
  232. The timeout period begins only when all dependent services have already stopped.
  233. The default value is $$$DEFAULT_STOP_TIMEOUT@@@.
  234. A value of 0 allows unlimited stop time.
  235. .TP
  236. \fBpid\-file\fR = \fIpath-to-file\fR
  237. For \fBbgprocess\fR type services only; specifies the path of the file where
  238. daemon will write its process ID before detaching.
  239. Dinit will read the contents of this file when starting the service, once the initial process
  240. exits, and will supervise the process with the discovered process ID.
  241. Dinit may also send signals to the process ID to stop the service; if \fBdinit\fR runs as a
  242. privileged user the path should have appropriate permissions to permit abuse by untrusted
  243. unprivileged processes.
  244. .sp
  245. The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
  246. .TP
  247. \fBdepends\-on\fR = \fIservice-name\fR
  248. This service depends on the named service.
  249. Starting this service will start the named service; the command to start this service will not be executed
  250. until the named service has started.
  251. If the named service stops then this service will also be stopped.
  252. .TP
  253. \fBdepends\-ms\fR = \fIservice-name\fR
  254. This service has a "milestone" dependency on the named service. Starting this
  255. service will start the named service; this service will not start until the
  256. named service has started, and will fail to start if the named service does
  257. not start.
  258. Once the named (dependent) service reaches the started state, however, the
  259. dependency may stop without affecting the dependent service.
  260. .TP
  261. \fBwaits\-for\fR = \fIservice-name\fR
  262. When this service is started, wait for the named service to finish starting
  263. (or to fail starting) before commencing the start procedure for this service.
  264. Starting this service will automatically start the named service.
  265. If the named service fails to start, this service will start as usual (subject to
  266. other dependencies being met).
  267. .TP
  268. \fBwaits\-for.d\fR = \fIdirectory-path\fR
  269. For each file name in \fIdirectory-path\fR which does not begin with a dot,
  270. add a \fBwaits-for\fR dependency to the service with the same name.
  271. Note that contents of files in the specified directory are not significant; expected
  272. usage is to have symbolic links to the associated service description files,
  273. but this is not required.
  274. Failure to read the directory contents, or to find any of the services named within,
  275. is not considered fatal.
  276. .sp
  277. The directory path, if not absolute, is relative to the directory containing the service
  278. description file.
  279. .TP
  280. \fBafter\fR = \fIservice-name\fR
  281. When starting this service, if the named service is also starting, wait for the named service
  282. to finish starting before bringing this service up. This is similar to a \fBwaits\-for\fR
  283. dependency except no dependency relationship is implied; if the named service is not starting,
  284. starting this service will not cause it to start (nor wait for it in that case).
  285. It does not by itself cause the named service to be loaded (if loaded later, the "after"
  286. relationship will be enforced from that point).
  287. .TP
  288. \fBbefore\fR = \fIservice-name\fR
  289. When starting the named service, if this service is also starting, wait for this service
  290. to finish starting before bringing the named service up. This is largely equivalent to specifying
  291. an \fBafter\fR relationship to this service from the named service.
  292. However, it does not by itself cause the named service to be loaded (if loaded later, the "before"
  293. relationship will be enforced from that point).
  294. .TP
  295. \fBchain\-to\fR = \fIservice-name\fR
  296. When this service terminates (i.e. starts successfully, and then stops of its
  297. own accord), the named service should be started.
  298. Note that the named service is not loaded until that time; naming an invalid service will
  299. not cause this service to fail to load.
  300. .sp
  301. This can be used for a service that supplies an interactive "recovery mode"
  302. for another service; once the user exits the recovery shell, the primary
  303. service (as named via this setting) will then start.
  304. It also supports multi-stage system startup where later service description files reside on
  305. a separate filesystem that is mounted during the first stage; such service
  306. descriptions will not be found at initial start, and so cannot be started
  307. directly, but can be chained via this directive.
  308. .sp
  309. The chain is not executed if the initial service was explicitly stopped,
  310. stopped due to a dependency stopping (for any reason), if it will restart
  311. (including due to a dependent restarting), or if its process terminates
  312. abnormally or with an exit status indicating an error.
  313. However, if the \fBalways-chain\fR option is set the chain is started regardless of the
  314. reason and the status of this service termination.
  315. .TP
  316. \fBsocket\-listen\fR = \fIsocket-path\fR
  317. Pre-open a socket for the service and pass it to the service using the
  318. \fBsystemd\fR activation protocol.
  319. This by itself does not give so called "socket activation", but does allow any
  320. process trying to connect to the specified socket to do so immediately after
  321. the service is started (even before the service process is properly prepared
  322. to accept connections).
  323. .sp
  324. The path value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
  325. .TP
  326. \fBsocket\-permissions\fR = \fIoctal-permissions-mask\fR
  327. Gives the permissions for the socket specified using \fBsocket\-listen\fR.
  328. Normally this will be 600 (user access only), 660 (user and group
  329. access), or 666 (all users).
  330. The default is 666.
  331. .TP
  332. \fBsocket\-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
  333. Specifies the user (name or numeric ID) that should own the activation socket.
  334. If \fBsocket\-uid\fR is specified as a name without also specifying \fBsocket\-gid\fR, then
  335. the socket group is the primary group of the specified user (as found in the
  336. system user database, normally \fI/etc/passwd\fR).
  337. If the \fBsocket\-uid\fR setting is not provided, the socket will be owned by the user id of the \fBdinit\fR process.
  338. .TP
  339. \fBsocket\-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
  340. Specifies the group of the activation socket. See discussion of \fBsocket\-uid\fR.
  341. .TP
  342. \fBterm\-signal\fR = {\fBnone\fR | \fIsignal-name\fR}
  343. Specifies the signal to send to the process when requesting it to terminate (applies to `process'
  344. and `bgprocess' services only).
  345. Signal names are specified as the POSIX signal name without the \fBSIG\fR- prefix.
  346. At least \fBHUP\fR, \fBTERM\fR, and \fBKILL\fR are supported (use \fBdinitctl signal \-\-list\fR
  347. for the full list of supported signals).
  348. The default is TERM (the SIGTERM signal).
  349. See also the discussion of \fBstop\-timeout\fR.
  350. .TP
  351. \fBready\-notification\fR = {\fBpipefd:\fR\fIfd-number\fR | \fBpipevar:\fR\fIenv-var-name\fR}
  352. Specifies the mechanism, if any, by which a process service will notify that it is ready
  353. (successfully started).
  354. If not specified, a process service is considered started as soon as it has begun execution.
  355. The two options are:
  356. .RS
  357. .IP \(bu
  358. \fBpipefd:\fR\fIfd-number\fR \(em the service will write a message to the specified file descriptor,
  359. which \fBdinit\fR sets up as the write end of a pipe before execution.
  360. This mechanism is compatible with the S6 supervision suite.
  361. .IP \(bu
  362. \fBpipevar:\fR\fIenv-var-name\fR \(em the service will write a message to file descriptor identified
  363. using the contents of the specified environment variable, which will be set by \fBdinit\fR before
  364. execution to a file descriptor (chosen arbitrarily) attached to the write end of a pipe.
  365. .RE
  366. .TP
  367. \fBlog\-type\fR = {file | buffer | pipe | none}
  368. Specifies how the output of this service is logged.
  369. This setting is valid only for process-based services (including \fBscripted\fR services).
  370. .RS
  371. .IP \(bu
  372. \fBfile\fR: output will be written to a file; see the \fBlogfile\fR setting.
  373. .IP \(bu
  374. \fBbuffer\fR: output will be buffered in memory, up to a limit specified via the
  375. \fBlog\-buffer\-size\fR setting.
  376. The buffer contents can be examined via the \fBdinitctl\fR(8) \fBcatlog\fR subcommand.
  377. .IP \(bu
  378. \fBpipe\fR: output will be written to a pipe, and may be consumed by another service
  379. (see the \fBconsumer\-of\fR setting); note that, if output is not consumed promptly, the pipe buffer
  380. may become full which may cause the service process to stall.
  381. .IP \(bu
  382. \fBnone\fR: output is discarded.
  383. .RE
  384. .IP
  385. The default log type is \fBnone\fR, unless the \fBlogfile\fR setting is specified in which case
  386. the default log type is \fBfile\fR. For \fBpipe\fR (and \fBbuffer\fR, which uses a pipe internally)
  387. note that the pipe created may outlive the service process and be re-used if the service is stopped
  388. and restarted.
  389. .\"
  390. .TP
  391. \fBlogfile\fR = \fIlog-file-path\fR
  392. Specifies the log file for the service.
  393. Output from the service process (standard output and standard error streams) will be appended to this file,
  394. which will be created if it does not already exist. The file ownership and permissions are adjusted
  395. according to the \fBlogfile\-uid\fR, \fBlogfile\-gid\fR and \fBlogfile\-permissions\fR settings.
  396. This setting has no effect if the service is set to run on the console (via the \fBruns\-on\-console\fR,
  397. \fBstarts\-on\-console\fR, or \fBshares\-console\fR options).
  398. The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
  399. Note that if the directory in which the logfile resides does not exist (or is not otherwise accessible to
  400. \fBdinit\fR) when the service is started, the service will not start successfully.
  401. If this settings is specified and \fBlog\-type\fR is not specified or is currently \fBnone\fR, then
  402. the log type will be changed to \fBfile\fR.
  403. .TP
  404. \fBlogfile\-permissions\fR = \fIoctal-permissions-mask\fR
  405. Gives the permissions for the log file specified using \fBlogfile\fR. Normally this will be 600 (user access
  406. only), 640 (also readable by the group), or 644 (readable by all users).
  407. If the log file already exists when the service starts, its permissions will be changed in accordance with
  408. the value of this setting.
  409. The default is value 600 (accessible to only the owning user).
  410. .TP
  411. \fBlogfile\-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
  412. Specifies the user (name or numeric ID) that should own the log file.
  413. If \fBlogfile\-uid\fR is specified as a name without also specifying \fBlogfile\-gid\fR, then
  414. the log file group is the primary group of the specified user (as found in the
  415. system user database, normally \fI/etc/passwd\fR).
  416. If the log file already exists when the service starts, its ownership will be changed in accordance with
  417. the value of this setting.
  418. The default value is the user id of the \fBdinit\fR process.
  419. .TP
  420. \fBlogfile\-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
  421. Specifies the group of the log file. See discussion of \fBlogfile\-uid\fR.
  422. .TP
  423. \fBlog\-buffer\-size\fR = \fIsize-in-bytes\fR
  424. If the log type (see \fBlog\-type\fR) is set to \fBbuffer\fR, this setting controls the maximum
  425. size of the buffer used to store process output. If the buffer becomes full, further output from
  426. the service process will be discarded.
  427. .TP
  428. \fBconsumer\-of\fR = \fIservice-name\fR
  429. Specifies that this service consumes (as its standard input) the output of another service.
  430. For example, this allows this service to act as a logging agent for another service.
  431. The named service must be a process-based service with \fBlog\-type\fR set to \fBpipe\fR.
  432. This setting is only valid for \fBprocess\fR and \fBbgprocess\fR services.
  433. .TP
  434. \fBoptions\fR = \fIoption\fR...
  435. Specifies various options for this service. See the \fBOPTIONS\fR section.
  436. This directive can be specified multiple times to set additional options.
  437. .TP
  438. \fBload\-options\fR = \fIload_option\fR...
  439. Specifies options for interpreting other settings when loading this service description.
  440. Currently there are two available options. One is \fBexport-passwd-vars\fR, which
  441. specifies that the environment variables `\fBUSER\fR', `\fBLOGNAME\fR' (same as
  442. `\fBUSER\fR'), `\fBHOME\fR', `\fBSHELL\fR', `\fBUID\fR', and `\fBGID\fR' should
  443. be exported into the service's load environment (that is, overriding any global
  444. environment including the global environment file, but being overridable by the
  445. service's environment file). The other is \fBexport-service-name\fR, which will
  446. set the environment variable `\fBDINIT_SERVICE\fR' containing the name of the
  447. current service.
  448. .TP
  449. \fBinittab\-id\fR = \fIid-string\fR
  450. When this service is started, if this setting (or the \fBinittab\-line\fR setting) has a
  451. specified value, an entry will be created in the system "utmp" database which tracks
  452. processes and logged-in users.
  453. Typically this database is used by the "who" command to list logged-in users.
  454. The entry will be cleared when the service terminates.
  455. .sp
  456. The \fBinittab\-id\fR setting specifies the "inittab id" to be written in the entry for
  457. the process.
  458. The value is normally quite meaningless.
  459. However, it should be distinct (or unset) for separate processes.
  460. It is typically limited to a very short length.
  461. .sp
  462. The "utmp" database is mostly a historical artifact.
  463. Access to it on some systems is prone to denial-of-service by unprivileged users.
  464. It is therefore recommended that this setting not be used.
  465. However, "who" and similar utilities may not work correctly without this setting
  466. (or \fBinittab\-line\fR) enabled appropriately.
  467. .sp
  468. This setting has no effect if Dinit was not built with support for writing to the "utmp"
  469. database. It applies only to \fBprocess\fR services.
  470. .TP
  471. \fBinittab\-line\fR = \fItty-name-string\fR
  472. This specifies the tty line that will be written to the "utmp" database when this service
  473. is started.
  474. Normally, for a terminal login service, it would match the terminal device name on which
  475. the login process runs, without the "/dev/" prefix.
  476. .sp
  477. See the description of the \fBinittab\-id\fR setting for details.
  478. .TP
  479. \fBrlimit\-nofile\fR = \fIresource-limits\fR
  480. Specifies the number of file descriptors that a process may have open simultaneously.
  481. See the \fBRESOURCE LIMITS\fR section.
  482. .TP
  483. \fBrlimit\-core\fR = \fIresource-limits\fR
  484. Specifies the maximum size of the core dump file that will be generated for the process if it
  485. crashes (in a way that would result in a core dump).
  486. See the \fBRESOURCE LIMITS\fR section.
  487. .TP
  488. \fBrlimit\-data\fR = \fIresource-limits\fR
  489. Specifies the maximum size of the data segment for the process, including statically allocated
  490. data and heap allocations.
  491. Precise meaning may vary between operating systems.
  492. See the \fBRESOURCE LIMITS\fR section.
  493. .TP
  494. \fBrlimit\-addrspace\fR = \fIresource-limits\fR
  495. Specifies the maximum size of the address space of the process.
  496. See the \fBRESOURCE LIMITS\fR section.
  497. Note that some operating systems (notably, OpenBSD) do not support this limit; the
  498. setting will be ignored on such systems.
  499. .TP
  500. \fBrun\-in\-cgroup\fR = \fIcgroup-path\fR
  501. Run the service process(es) in the specified cgroup (see \fBcgroups\fR(7)).
  502. The cgroup is specified as a path; if it has a leading slash, the remainder of the path is
  503. interpreted as relative to \fI/sys/fs/cgroup\fR, and otherwise the entire path is interpreted
  504. relative to the cgroup in which \fBdinit\fR is running (as determined at startup or specified
  505. by options).
  506. The latter can only be used if there is only a single cgroup hierarchy (either the cgroups v2
  507. hierarchy with no cgroups v1 hierarchies, or a single cgroups v1 hierarchy).
  508. .sp
  509. Note that due to the "no internal processes" rule in cgroups v2, a relative path must typically
  510. begin with ".." if cgroups v2 are used.
  511. .sp
  512. The named cgroup must already exist prior to the service starting; it will not be created by
  513. \fBdinit\fR.
  514. .sp
  515. This setting is only available if \fBdinit\fR was built with cgroups support.
  516. .\"
  517. .SS OPTIONS
  518. .\"
  519. These options are specified via the \fBoptions\fR parameter.
  520. .\"
  521. .TP
  522. \fBruns\-on\-console\fR
  523. Specifies that this service uses the console; its input and output should be
  524. directed to the console (or precisely, to the device to which \fBdinit\fR's standard
  525. output stream is connected).
  526. A service running on the console prevents other services from running on the
  527. console (they will queue for the console).
  528. .sp
  529. Proper operation of this option (and related options) assumes that \fBdinit\fR
  530. is itself attached correctly to the console device (or a terminal, in which case
  531. that terminal will be used as the "console").
  532. .sp
  533. The \fIinterrupt\fR key (normally control-C) may be active for process / scripted
  534. services that run on the console, depending on terminal configuration and operating-system
  535. specifics.
  536. The interrupt signal (SIGINT), however, is masked by default (but see \fBunmask\-intr\fR).
  537. .TP
  538. \fBstarts\-on\-console\fR
  539. Specifies that this service uses the console during service startup.
  540. This is identical to \fBruns\-on\-console\fR except that the console will be released
  541. (available for running other services) once the service has started.
  542. It is applicable only for \fBbgprocess\fR and \fBscripted\fR services.
  543. .sp
  544. As for the \fBruns\-on\-console\fR option, the \fIinterrupt\fR key will be enabled
  545. while the service has the console.
  546. .TP
  547. \fBshares\-console\fR
  548. Specifies that this service should be given access to the console (input and output
  549. will be connected to the console), but that it should not exclusively hold the
  550. console. A service given access to the console in this way will not delay the startup of services
  551. which require exclusive access to the console (see \fBstarts\-on\-console\fR,
  552. \fBruns\-on\-console\fR) nor will it be itself delayed if such services are already running.
  553. .sp
  554. This is mutually exclusive with both \fBstarts\-on\-console\fR and \fBruns\-on\-console\fR;
  555. setting this option unsets both those options, and setting either of those options unsets
  556. this option.
  557. .TP
  558. \fBunmask\-intr\fR
  559. For services that run or start on the console, specifies that the terminal interrupt signal
  560. (SIGINT, normally invoked by control-C) should be unmasked.
  561. Handling of an interrupt is determined by the service process, but typically will
  562. cause it to terminate.
  563. This option may therefore be used to allow a service to be terminated by the user via
  564. a keypress combination.
  565. In combination with \fBskippable\fR, it may allow service startup to be skipped.
  566. .sp
  567. A service with this option will typically also have the \fBstart\-interruptible\fR option
  568. set.
  569. .sp
  570. Note that whether an interrupt can be generated, and the key combination required to do so,
  571. depends on the operating system's handling of the console device and, if it is a terminal,
  572. how the terminal is configured; see \fBstty\fR(1).
  573. .sp
  574. Note also that a process may choose to mask or unmask the interrupt signal of its own accord,
  575. once it has started.
  576. Shells, in particular, may unmask the signal; it might not be possible to reliably run a shell
  577. script on the console without allowing a user to interrupt it.
  578. .TP
  579. \fBstarts\-rwfs\fR
  580. This service mounts the root filesystem read/write (or at least mounts the
  581. normal writable filesystems for the system).
  582. This prompts Dinit to attempt to create its control socket, if it has not already managed to do so,
  583. and similarly log boot time to the system \fBwtmp\fR(5) database (if supported) if not yet done.
  584. This option may be specified on multiple services, which may be useful if the \fBwtmp\fR database becomes
  585. writable at a different stage than the control socket location becomes writable, for example.
  586. If the control socket has already been created, this option currently causes Dinit to check that
  587. the socket "file" still exists and re-create it if not. It is not recommended to rely on this
  588. behaviour.
  589. .TP
  590. \fBstarts\-log\fR
  591. This service starts the system log daemon.
  592. Dinit will begin logging via the \fI/dev/log\fR socket.
  593. .TP
  594. \fBpass\-cs\-fd\fR
  595. Pass an open Dinit control socket to the process when launching it (the
  596. \fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of
  597. the socket).
  598. This allows the service to issue commands to Dinit even if the regular control socket is not available yet.
  599. .sp
  600. Using this option has security implications! The service which receives the
  601. control socket must close it before launching any untrusted processes.
  602. You should not use this option unless the service is designed to receive a Dinit
  603. control socket.
  604. .TP
  605. \fBstart\-interruptible\fR
  606. Indicates that this service can have its startup interrupted (cancelled), by sending it the SIGINT signal.
  607. If service state changes such that this service will stop, but it is currently starting, and this option
  608. is set, then Dinit will attempt to interrupt it rather than waiting for its startup to complete.
  609. This is meaningful only for \fBbgprocess\fR and \fBscripted\fR services.
  610. .TP
  611. \fBskippable\fR
  612. For scripted services, indicates that if the service startup process terminates
  613. via an interrupt signal (SIGINT), then the service should be considered started.
  614. Note that if the interrupt was issued by Dinit to cancel startup, the service
  615. will instead be considered stopped.
  616. .sp
  617. This can be combined with options such as \fBstarts\-on\-console\fR to allow
  618. skipping certain non-essential services (such as filesystem checks) using the
  619. \fIinterrupt\fR key (typically control-C).
  620. .TP
  621. \fBsignal\-process-only\fR
  622. Signal the service process only, rather than its entire process group, whenever
  623. sending it a signal for any reason.
  624. .TP
  625. \fBalways\-chain\fR
  626. Alters behaviour of the \fBchain-to\fR property, forcing the chained service to
  627. always start on termination of this service (instead of only when this service
  628. terminates with an exit status indicating success).
  629. .TP
  630. \fBkill\-all\-on\-stop\fR
  631. Before stopping this service, send a TERM signal and then (after a short pause) a
  632. KILL signal to all other processes in the system, forcibly terminating them.
  633. This option is intended to allow system shutdown scripts to run without any possible
  634. interference from "leftover" or orphaned processes (for example, unmounting file systems usually
  635. requires that the file systems are no longer in use).
  636. .sp
  637. This option must be used with care since the signal broadcast does not discriminate and
  638. potentially kills other services (or their shutdown scripts); a strict dependency ordering
  639. is suggested, i.e. every other service should either be a (possibly transitive) dependency or
  640. dependent of the service with this option set.
  641. .sp
  642. This option can be used for scripted and internal services only.
  643. .RE
  644. .\"
  645. .SS RESOURCE LIMITS
  646. .\"
  647. There are several settings for specifying process resource limits: \fBrlimit\-nofile\fR,
  648. \fBrlimit\-core\fR, \fBrlimit\-data\fR and \fBrlimit\-addrspace\fR.
  649. See the descriptions of each above.
  650. These settings place a limit on resource usage directly by the process.
  651. Note that resource limits are inherited by subprocesses, but that usage of a resource
  652. and subprocess are counted separately (in other words, a process can effectively bypass
  653. its resource limits by spawning a subprocess and allocating further resources within it).
  654. .sp
  655. Resources have both a \fIhard\fR and \fIsoft\fR limit.
  656. The soft limit is the effective limit, but note that a process can raise its soft limit up
  657. to the hard limit for any given resource.
  658. Therefore the soft limit acts more as a sanity-check; a process can exceed the soft limit
  659. only by deliberately raising it first.
  660. .sp
  661. Resource limits are specified in the following format:
  662. .sp
  663. .RS
  664. \fIsoft-limit\fR:\fIhard-limit\fR
  665. .RE
  666. .sp
  667. Either the soft limit or the hard limit can be omitted (in which case it will be unchanged).
  668. A limit can be specified as a dash, `\fB\-\fR', in which case the limit will be removed.
  669. If only one value is specified with no colon separator, it affects both the soft and hard limit.
  670. .\"
  671. .SS VARIABLE SUBSTITUTION
  672. .\"
  673. Some service properties specify a path to a file or directory, or a command line.
  674. For these properties, the specified value may contain one or more environment
  675. variable names, each preceded by a single `\fB$\fR' character, as in `\fB$NAME\fR'.
  676. In each case the value of the named environment variable will be substituted.
  677. The name must begin with a non-punctuation, non-space, non-digit character, and ends
  678. before the first control character, space, or punctuation character other than `\fB_\fR'.
  679. To avoid substitution, a single `\fB$\fR' can be escaped with a second, as in `\fB$$\fR'.
  680. .P
  681. Variable substitution also supports a limited subset of shell syntax. You can use curly
  682. braces to enclose the variable, as in `\fB${NAME}\fR'.
  683. Limited parameter expansion is also supported, specifically the forms `\fB${NAME:\-word}\fR'
  684. (substitute `\fBword\fR' if variable is unset or empty), `\fB${NAME\-word}\fR' (substitute
  685. `\fBword\fR' if variable is unset), `\fB${NAME:+word}\fR' (substitute `\fBword\fR' if variable is
  686. set and non\-empty), and `\fB${NAME+word}\fR' (substitute `\fBword\fR' if variable is set).
  687. Unlike in shell expansion, the substituted \fBword\fR does not itself undergo expansion and
  688. cannot contain closing brace characters or whitespace, even if quoted.
  689. .P
  690. Note that by default, command-line variable substitution occurs after splitting the line into
  691. separate arguments and so
  692. a single environment variable cannot be used to add multiple arguments to a command line.
  693. If a designated variable is not defined, it is replaced with an empty (zero-length) string, possibly producing a
  694. zero-length argument.
  695. To alter this behaviour use a slash after \fB$\fR, as in `\fB$/NAME\fR'; the expanded value will then
  696. be split into several arguments separate by whitespace or, if the value is empty or consists only
  697. of whitespace, will collapse (instead of producing an empty or whitespace argument).
  698. .P
  699. Variable substitution occurs when the service is loaded.
  700. Therefore, it is typically not useful for dynamically changing service parameters (including
  701. command line) based on a variable that is inserted into \fBdinit\fR's environment once it is
  702. running (for example via \fBdinitctl setenv\fR).
  703. .P
  704. The effective environment for variable substitution in setting values matches the environment supplied to the process
  705. for a service when it is launched. The priority of environment variables, from highest to lowest, for both is:
  706. .IP \(bu
  707. variables from the service \fBenv\-file\fR
  708. .IP \(bu
  709. variables set by the \fBexport\-passwd\-vars\fR and \fBexport\-service\-name\fR load options
  710. .IP \(bu
  711. the process environment of \fBdinit\fR (which is established on launch by the process environment of the
  712. parent, amended by loading the environment file (if any) as specified in \fBdinit\fR(8), and further
  713. amended via \fBdinitctl setenv\fR commands or equivalent).
  714. .P
  715. Note that since variable substitution is performed on service load, the values seen by a service process may differ from those
  716. used for substitution, if they have been changed in the meantime.
  717. Using environment variable values in service commands and parameters can be used as means to
  718. provide easily-adjustable service configuration, but is not ideal for this purpose and alternatives
  719. should be considered.
  720. .\"
  721. .SH EXAMPLES
  722. .LP
  723. Here is an example service description for the \fBmysql\fR database server.
  724. It has a dependency on the \fBrcboot\fR service (not shown) which is
  725. expected to have set up the system to a level suitable for basic operation.
  726. .sp
  727. .RS
  728. .nf
  729. .gcolor blue
  730. .ft CR
  731. # mysqld service
  732. type = process
  733. command = /usr/bin/mysqld --user=mysql
  734. logfile = /var/log/mysqld.log
  735. smooth-recovery = true
  736. restart = false
  737. depends-on = rcboot # Basic system services must be ready
  738. .ft
  739. .gcolor
  740. .RE
  741. .fi
  742. .LP
  743. Here is an examples for a filesystem check "service", run by a script
  744. (\fI/etc/dinit.d/scripts/rootfscheck.sh\fR).
  745. The script may need to reboot the system, but the control socket may not have been
  746. created, so it uses the \fBpass-cs-fd\fR option to allow the \fBreboot\fR command
  747. to issue control commands to Dinit.
  748. It runs on the console, so that output is visible and the process can be interrupted
  749. using control-C, in which case the check is skipped but dependent services continue to start.
  750. .sp
  751. .RS
  752. .nf
  753. .gcolor blue
  754. .ft CR
  755. # rootfscheck service
  756. type = scripted
  757. command = /etc/dinit.d/scripts/rootfscheck.sh
  758. restart = false
  759. options = starts-on-console pass-cs-fd
  760. options = start-interruptible skippable
  761. depends-on = early-filesystems # /proc and /dev
  762. depends-on = device-node-daemon
  763. .ft
  764. .gcolor
  765. .fi
  766. .RE
  767. .sp
  768. More examples are provided with the Dinit distribution.
  769. .\"
  770. .SH AUTHOR
  771. Dinit, and this manual, were written by Davin McCall.
  772. $$$dnl