dinit.8.m4 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
  1. changequote(`@@@',`$$$')dnl
  2. @@@.TH DINIT "8" "$$$MONTH YEAR@@@" "Dinit $$$VERSION@@@" "Dinit \- service management system"
  3. .SH NAME
  4. dinit \- supervise processes and manage services
  5. .\"
  6. .SH SYNOPSIS
  7. .\"
  8. .nh
  9. .\"
  10. .HP
  11. .B dinit
  12. [OPTION]... [\fIservice-name\fR]...
  13. .\"
  14. .hy
  15. .\"
  16. .SH DESCRIPTION
  17. .\"
  18. \fBDinit\fR is a process supervisor and service manager which can also
  19. function as a system \fBinit\fR process.
  20. It has a small but functional feature set, offering service dependency handling, parallel startup,
  21. automatic rate-limited restart of failing processes, and service control functions.
  22. .LP
  23. Dinit can be run as a system instance (when run as the root user or when
  24. specified via command line parameter) or as a user instance.
  25. This affects the default paths used to locate certain files.
  26. .LP
  27. When run as PID 1, the first process, Dinit by default acts as a system manager and
  28. shuts down or reboots the system on request (including on receipt of certain signals).
  29. This is currently fully supported only on Linux.
  30. See \fBRUNNING AS SYSTEM MANAGER / PRIMARY INIT\fR.
  31. .LP
  32. Dinit reads service descriptions from files located in a service
  33. description directory, normally one of \fI/etc/dinit.d\fR, \fI/run/dinit.d\fR,
  34. \fI/usr/local/lib/dinit.d\fR and \fI/lib/dinit.d\fR for the system instance
  35. or \fI$XDG_CONFIG_HOME/dinit.d\fR, \fI$HOME/.config/dinit.d\fR, \fI/etc/dinit.d/user\fR,
  36. \fI/usr/lib/dinit.d/user\fR and \fI/usr/local/lib/dinit.d/user\fR when run as a user process.
  37. See \fBSERVICE DESCRIPTION FILES\fR for details of the service description format.
  38. .\"
  39. .SH OPTIONS
  40. .TP
  41. \fB\-d\fR \fIdir\fP, \fB\-\-services\-dir\fR \fIdir\fP
  42. Specifies \fIdir\fP as the directory containing service definition files.
  43. This can be specified multiple times for multiple service directories.
  44. The default directories are not searched for services when this option is provided.
  45. .sp
  46. If not specified, the default for the user instance is \fI$XDG_CONFIG_HOME/dinit.d\fR,
  47. \fI$HOME/.config/dinit.d\fR, \fI/etc/dinit.d/user\fR, \fI/usr/lib/dinit.d/user\fR and
  48. \fI/usr/local/lib/dinit.d/user\fR or, for the system instance, each of \fI/etc/dinit.d\fR, \fI/run/dinit.d/\fR,
  49. \fI/usr/local/lib/dinit.d\fR, and \fI/lib/dinit.d\fR (searched in that order).
  50. .TP
  51. \fB\-e\fR \fIfile\fP, \fB\-\-env\-file\fR \fIfile\fP
  52. Read initial environment from \fIfile\fP.
  53. For the system init process, the default is \fI/etc/dinit/environment\fR; see \fBFILES\fR.
  54. .TP
  55. \fB\-p\fR \fIpath\fP, \fB\-\-socket\-path\fR \fIpath\fP
  56. Specifies \fIpath\fP as the path to the control socket used to listen for
  57. commands from the \fBdinitctl\fR program.
  58. The default for the system service manager is usually \fI/dev/dinitctl\fR (but can be configured at build time).
  59. For a user service manager the default is either \fI$XDG_RUNTIME_DIR/dinitctl\fR
  60. or \fI$HOME/.dinitctl\fR, depending on whether \fI$XDG_RUNTIME_DIR\fR is set.
  61. .TP
  62. \fB\-F\fR \fIfd\fP, \fB\-\-ready\-fd\fR \fIfd\fP
  63. Specifies \fIfd\fP as the file descriptor number to report readiness to.
  64. Readiness means that the control socket is open and the service manager is
  65. ready to accept commands (e.g. via \fBdinitctl\fR). It does not mean that
  66. services are finished starting yet. The path to the currently open control
  67. socket is written on the file descriptor.
  68. .TP
  69. \fB\-l\fR \fIpath\fP, \fB\-\-log\-file\fR \fIpath\fP
  70. Species \fIpath\fP as the path to the log file, to which Dinit will log status
  71. and error messages.
  72. Using this option inhibits logging via the syslog facility, however, all logging messages are
  73. duplicated as usual to the console (as long as \fB\-\-quiet\fR has not also been specified).
  74. Note that when running as the system init, Dinit will continue if it cannot open the specified
  75. file, and will attempt to open it again once the root file system is writable.
  76. If not running as the system init and the file cannot be opened, Dinit will immediately exit
  77. with an error.
  78. .TP
  79. \fB\-s\fR, \fB\-\-system\fR
  80. Run as the system service manager.
  81. This is the default if invoked as the root user.
  82. This option affects the default service definition directory and control socket path.
  83. .TP
  84. \fB\-m\fR, \fB\-\-system\-mgr\fR
  85. Run as the system manager (perform operations directly related to machine startup
  86. and shutdown).
  87. This is the default when running as process ID 1.
  88. The main user-visible effect of this option is to invoke the \fB$$$SHUTDOWN_PREFIX@@@shutdown\fR program when a shutdown is
  89. requested (and after all services have stopped), and to provide some basic support
  90. for system recovery in case the \fBboot\fR service (or other specified service)
  91. cannot be started.
  92. .TP
  93. \fB\-u\fR, \fB\-\-user\fR
  94. Run as a user service manager.
  95. This is the opposite of \fB\-\-system\fR, and is the default if not invoked as the root user.
  96. .TP
  97. \fB\-o\fR, \fB\-\-container\fR
  98. Run in "container mode", i.e. do not perform system management functions (such
  99. as shutdown/reboot).
  100. The \fBdinit\fR daemon will simply exit rather than executing the \fB$$$SHUTDOWN_PREFIX@@@shutdown\fR program.
  101. .TP
  102. \fB\-q\fR, \fB\-\-quiet\fR
  103. Run with no output to the terminal/console.
  104. This disables service status messages and sets the log level for the console log to \fBnone\fR.
  105. To re-enable (some) output, use the \fB\-\-console\-level\fR option after this option.
  106. .TP
  107. \fB\-b\fR \fIpath\fR, \fB\-\-cgroup\-path\fR \fIpath\fR
  108. Specify the path to resolve relative cgroup paths against.
  109. If service description settings contain relative cgroup paths, they will be resolved relative to
  110. this path.
  111. This option is only available if \fBdinit\fR is built with cgroups support.
  112. .TP
  113. \fB\-\-help\fR
  114. Display brief help text and then exit.
  115. .TP
  116. \fB\-\-version\fR
  117. Display version number and then exit.
  118. .TP
  119. [\fB\-t\fR] \fIservice-name\fR, [\fB\-\-service\fR] \fIservice-name\fR
  120. Specifies the name of a service that should be started (along with its
  121. dependencies).
  122. If none are specified, defaults to \fIboot\fR (which requires that a suitable service description
  123. for the \fIboot\fR service exists). Multiple services can be specified in which case they will each
  124. be started.
  125. .sp
  126. \fBNote:\fR on Linux, if \fBdinit\fR is running as PID 1 and with UID 0, it may ignore "naked"
  127. service names (without preceding \fB\-\-service\fR/\fB\-t\fR) provided on the command line.
  128. See the \fBCOMMAND LINE FROM KERNEL\fR section.
  129. .TP
  130. \fB\-\-console\-level\fR \fIlevel\fR
  131. Specify the minimum log level of messages that should be logged to the console.
  132. From highest to lowest, the levels are \fBerror\fR, \fBwarn\fR, \fBinfo\fR and \fBdebug\fR.
  133. Use a level of \fBnone\fR to suppress all messages.
  134. Note that unless \fB\-\-quiet\fR (\fB\-q\fR) is also specified, service state change messages
  135. (service started, stopped etc) are always output.
  136. .TP
  137. \fB\-\-log\-level\fR \fIlevel\fR
  138. Specify the minimum log level of messages that should be sent to the primary log (syslog facility
  139. or file).
  140. From highest to lowest, the levels are \fBerror\fR, \fBwarn\fR, \fBinfo\fR and \fBdebug\fR.
  141. Use a level of \fBnone\fR to suppress all messages.
  142. .\"
  143. .SH SERVICE DESCRIPTION FILES
  144. .\"
  145. Service description files specify the parameters of each service.
  146. They are named for the service they describe, and are found in one of several directories
  147. (including \fI/etc/dinit.d\fR) for a system instance or \fI$XDG_CONFIG_HOME/dinit.d\fR and
  148. \fI$HOME/.config/dinit.d\fR for a user instance (see also \fB\-\-services\-dir\fR option).
  149. .LP
  150. Service description files are read by Dinit on an "as needed" basis.
  151. Once loaded, a service description is never automatically unloaded (even if the service
  152. stops or fails).
  153. A service description can however be unloaded (if the service is stopped) or reloaded
  154. (with some limitations) via \fBdinitctl\fR(8) using the \fBunload\fR and \fBreload\fR subcommands
  155. respectively.
  156. .LP
  157. See \fBdinit-service\fR(5) for details of the format and available parameters.
  158. .\"
  159. .SH SPECIAL SERVICE NAMES
  160. .\"
  161. There are two service names that are "special" to Dinit.
  162. .LP
  163. The \fIboot\fR service is the service that Dinit starts by default, if no
  164. other service names are provided when it is started.
  165. .LP
  166. The \fIrecovery\fR service is a service that Dinit will offer to start if
  167. boot appears to fail (that is, if all services stop without a shutdown command
  168. having been issued), when Dinit is running as system manager.
  169. .\"
  170. .SH OPERATION
  171. .\"
  172. On starting, Dinit starts the initial service(s) as specified on the command line.
  173. Starting a service also causes the dependencies of that service to start, and any service
  174. processes will not be launched until the dependencies are satisfied.
  175. Similarly, stopping a service first stops any dependent services.
  176. .LP
  177. During execution, Dinit accepts commands via a control socket which is created
  178. by Dinit when it starts.
  179. This can be used to order that a service be started or stopped, to determine service status, or to
  180. make certain configuration changes.
  181. See \fBdinitctl\fR(8) for details.
  182. Dinit attempts to check for the existence of an already-active socket first, and will refuse to
  183. start if one exists.
  184. Unfortunately, this check cannot be done atomically, and should not be relied upon generally as a
  185. means to avoid starting two instances of dinit.
  186. .LP
  187. Process-based services are monitored and, if the process terminates, the service may be stopped or
  188. the process may be re-started, according to the configuration in the service description.
  189. .LP
  190. Once all services stop, the \fBdinit\fR daemon will itself terminate (or, if
  191. running as system manager, will perform the appropriate type of system shutdown).
  192. .\"
  193. .SS CHARACTER SET HANDLING
  194. .\"
  195. Dinit does no character set translation.
  196. Dinit's own output is in the execution character set as determined at compilation, as is the interpretation of input.
  197. Service names (and other user-defined inputs) are interpreted as byte sequences and are output as they were read.
  198. In general, modern systems use the UTF-8 character set universally and no problems will arise;
  199. however, systems configured to use other character sets may see odd behaviour if the input
  200. character set does not match the output character set, or if either input or output character sets
  201. are not a superset of the execution character set.
  202. .\"
  203. .SS RUNNING AS SYSTEM MANAGER / PRIMARY INIT
  204. .\"
  205. Running as the system manager (primary \fBinit\fR) is currently supported only on
  206. Linux.
  207. When run as process ID 1, the \fBdinit\fR daemon by default assumes responsibility for
  208. system shutdown and restart (partially relying on external utilities which are
  209. part of the Dinit distribution).
  210. .LP
  211. When not running as a system manager, \fBdinit\fR assumes responsibility only for
  212. service management.
  213. System shutdown or restart need to be handled by the primary \fBinit\fR, which should start
  214. \fBdinit\fR on normal startup, and terminate \fBdinit\fR before shutdown, by signalling it and
  215. waiting for it to terminate after stopping services (possibly by invoking \fBdinitctl shutdown\fR).
  216. .\"
  217. .SH LOGGING
  218. Dinit "logs" via two mechanisms simultaneously: the "console" (standard output, not necessarily associated
  219. with an actual console if \fBdinit\fR was started with output directed elsewhere) and the "main log facility"
  220. which is the syslog facility by default but which may be directed to a file.
  221. Various options are available to control the types and "levels" of message that will be sent to each facility,
  222. and the destination of the main facility.
  223. The levels available (from low to high) are \fBdebug\fR, \fBnotice\fR, \fBwarn\fR, and \fBerror\fR.
  224. Selecting a particular log level for facility will cause the facility to receive messages of that level and higher.
  225. The special level \fBnone\fR inhibits a facility from receiving any messages.
  226. Service status messages (service started or stopped) have a nominal level of \fBnotice\fR, except for failure
  227. which has a level of \fBerror\fR or \fBwarn\fR in case of transitive failure (due to a dependency).
  228. These messages are, by default, always issued to the console regardless of level, unless the \fB\-\-quiet\fR
  229. (\fB\-q\fR) option has been used.
  230. To debug boot issues it may be useful to use \fB\-q\fR (which also sets the level to \fBnone\fR) and then
  231. also reset the level via the \fB\-\-console\-level\fR option to either \fBwarn\fR or \fBerror\fR.
  232. This will reduce noise in the output from successful service startup.
  233. .\"
  234. .SH COMMAND LINE FROM KERNEL
  235. .LP
  236. When running as PID 1, \fBdinit\fR may process the command line differently, to compensate for kernel behaviour.
  237. .LP
  238. On Linux, kernel command line options that are not recognised by the kernel will be passed on to \fBdinit\fR.
  239. However, bugs in some kernel versions may cause some options that are recognised to also be passed to \fBdinit\fR.
  240. Also, boot managers may insert command-line options such as "\fBauto\fR" (which indicates an "unattended" boot).
  241. Therefore, \fBdinit\fR ignores all "word like" options other than "\fBsingle\fR", which it treats as
  242. the name of the service to start (thus allowing "single user mode", assuming that a suitable service description exists).
  243. Options beginning with "\fB--\fR" will not be recognised by the kernel and will be passed to (and processed by) \fBdinit\fR;
  244. for example \fB\-\-quiet\fR can be used to suppress console output. Options containing "=" that are unrecognised by the
  245. kernel (or some that are, due to bugs) are passed to init via the environment rather than via the command line.
  246. .LP
  247. There are several ways to work around this.
  248. Service names following the \fB\-\-container\fR (\fB\-o\fR) or \fB\-\-system\-mgr\fR (\fB\-m\fR) options are not ignored.
  249. Also, the \fB\-\-service\fR (\fB\-t\fR) option can be used to force a service name to be recognised regardless of operating mode.
  250. .\"
  251. .SH FILES
  252. .\"
  253. .TP
  254. \fI/etc/dinit/environment\fR
  255. Default location of the environment file for Dinit when run as a system
  256. instance (for user instances there is no default).
  257. Values are specified as \fINAME\fR=\fIVALUE\fR, one per line, and add to and replace variables present
  258. in the environment when Dinit started (the "original environment").
  259. Lines beginning with a hash character (#) are ignored.
  260. .IP
  261. The following special commands can be used (each on a single line):
  262. .RS
  263. .TP
  264. \fB!clear\fR
  265. Clears the environment completely (prevents inheritance of any variables from the original environment).
  266. .TP
  267. \fB!unset\fR \fIvar-name\fR...
  268. Unsets the specified variables.
  269. Any previously specified value for these variables is forgotten, and they will not inherit any
  270. value from the original environment.
  271. .TP
  272. \fB!import\fR \fIvar-name\fR...
  273. Imports the value of the named variables from the original environment, overriding the effect of any
  274. value set previously as well as the effect of previous \fB!unset\fR and \fB!clear\fR commands.
  275. .RE
  276. .TP
  277. \fI/etc/dinit.d\fR, \fI/run/dinit.d\fR, \fI/usr/local/lib/dinit.d\fR, \fI/lib/dinit.d\fR
  278. Default locations for service description files. The directories are searched in the order listed.
  279. .TP
  280. \fI$XDG_CONFIG_HOME/dinit.d\fR, \fI$HOME/.config/dinit.d\fR
  281. Default location for service description files for user instances. The directories are searched in the order listed.
  282. .\"
  283. .SH SIGNALS
  284. .LP
  285. When run as a system manager, SIGINT stops all services and performs a reboot (on Linux, this signal can be
  286. generated using the control-alt-delete key combination); SIGTERM stops services and halts the system; and
  287. SIGQUIT performs an immediate shutdown with no service rollback.
  288. .LP
  289. When run as a user process or system service manager only, SIGINT and SIGTERM both stop services
  290. and exit Dinit; SIGQUIT exits Dinit immediately.
  291. .\"
  292. .SH SEE ALSO
  293. .\"
  294. \fBdinitctl\fR(8), \fBdinit-service\fR(5), \fBdinitcheck\fR(8), \fB$$$SHUTDOWN_PREFIX@@@shutdown(8)\fR.
  295. .\"
  296. .SH AUTHOR
  297. Dinit, and this manual, were written by Davin McCall.
  298. $$$dnl