dinit-service.5.m4 33 KB

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