dinitctl.8.m4 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366
  1. changequote(`@@@',`$$$')dnl
  2. @@@.TH DINITCTL "8" "$$$MONTH YEAR@@@" "Dinit $$$VERSION@@@" "Dinit \- service management system"
  3. .SH NAME
  4. dinitctl \- control services supervised by Dinit
  5. .\"
  6. .SH SYNOPSIS
  7. .\"
  8. .PD 0
  9. .nh
  10. .HP
  11. .B dinitctl
  12. [\fIoptions\fR] \fBstart\fR [\fB\-\-no\-wait\fR] [\fB\-\-pin\fR] \fIservice-name\fR
  13. .HP
  14. .B dinitctl
  15. [\fIoptions\fR] \fBstop\fR [\fB\-\-no\-wait\fR] [\fB\-\-pin\fR] [\fB\-\-ignore\-unstarted\fR] \fIservice-name\fR
  16. .HP
  17. .B dinitctl
  18. [\fIoptions\fR] \fBstatus\fR \fIservice-name\fR
  19. .HP
  20. .B dinitctl
  21. [\fIoptions\fR] \fBis\-started\fR \fIservice-name\fR
  22. .HP
  23. .B dinitctl
  24. [\fIoptions\fR] \fBis\-failed\fR \fIservice-name\fR
  25. .HP
  26. .B dinitctl
  27. [\fIoptions\fR] \fBrestart\fR [\fB\-\-no\-wait\fR] [\fB\-\-ignore\-unstarted\fR] \fIservice-name\fR
  28. .HP
  29. .B dinitctl
  30. [\fIoptions\fR] \fBwake\fR [\fB\-\-no\-wait\fR] \fIservice-name\fR
  31. .HP
  32. .B dinitctl
  33. [\fIoptions\fR] \fBrelease\fR [\fB\-\-ignore\-unstarted\fR] \fIservice-name\fR
  34. .HP
  35. .B dinitctl
  36. [\fIoptions\fR] \fBunpin\fR \fIservice-name\fR
  37. .HP
  38. .B dinitctl
  39. [\fIoptions\fR] \fBunload\fR \fIservice-name\fR
  40. .HP
  41. .B dinitctl
  42. [\fIoptions\fR] \fBreload\fR \fIservice-name\fR
  43. .HP
  44. .B dinitctl
  45. [\fIoptions\fR] \fBlist\fR
  46. .HP
  47. .B dinitctl
  48. [\fIoptions\fR] \fBshutdown\fR
  49. .HP
  50. .B dinitctl
  51. [\fIoptions\fR] \fBadd-dep\fR \fIdependency-type\fR \fIfrom-service\fR \fIto-service\fR
  52. .HP
  53. .B dinitctl
  54. [\fIoptions\fR] \fBrm-dep\fR \fIdependency-type\fR \fIfrom-service\fR \fIto-service\fR
  55. .HP
  56. .B dinitctl
  57. [\fIoptions\fR] \fBenable\fR [\fB\-\-from\fR \fIfrom-service\fR] \fIto-service\fR
  58. .HP
  59. .B dinitctl
  60. [\fIoptions\fR] \fBdisable\fR [\fB\-\-from\fR \fIfrom-service\fR] \fIto-service\fR
  61. .HP
  62. .B dinitctl
  63. [\fIoptions\fR] \fBtrigger\fR \fIservice-name\fR
  64. .HP
  65. .B dinitctl
  66. [\fIoptions\fR] \fBuntrigger\fR \fIservice-name\fR
  67. .HP
  68. .B dinitctl
  69. [\fIoptions\fR] \fBsetenv\fR [\fIname\fR[=\fIvalue\fR] \fI...\fR]
  70. .HP
  71. .B dinitctl
  72. [\fIoptions\fR] \fBcatlog\fR [\fB--clear\fR] \fIservice-name\fR
  73. .HP
  74. .B dinitctl
  75. [\fIoptions\fR] \fBsignal\fR { \fIsignal-id\fR \fIservice-name\fR | \fB\-\-list\fR | \fB-l\fR }
  76. .\"
  77. .PD
  78. .hy
  79. .\"
  80. .SH DESCRIPTION
  81. .\"
  82. \fBdinitctl\fR is a utility to control services being managed by the
  83. \fBdinit\fR daemon.
  84. It allows starting and stopping services, and listing service status, amongst other actions.
  85. It functions by issuing commands to the daemon via a control socket.
  86. .\"
  87. .SH GENERAL OPTIONS
  88. .TP
  89. \fB\-\-help\fR
  90. Display brief help text and then exit.
  91. .TP
  92. \fB\-\-version\fR
  93. Display version and then exit.
  94. .TP
  95. \fB\-s\fR, \fB\-\-system\fR
  96. Control the system init process (this is the default when run as root).
  97. This option determines the default path to the control socket used to communicate with the \fBdinit\fR daemon
  98. process (it does not override the \fB\-p\fR option).
  99. .TP
  100. \fB\-u\fR, \fB\-\-user\fR
  101. Control the user init process (this is the default when not run as root).
  102. This option determines the default path to the control socket used to communicate with the \fBdinit\fR daemon process
  103. (it does not override the \fB\-p\fR option).
  104. .TP
  105. \fB\-\-socket\-path\fR \fIsocket-path\fR, \fB\-p\fR \fIsocket-path\fR
  106. Specify the path to the socket used for communicating with the service manager daemon.
  107. When not specified, the value from the \fBDINIT_SOCKET_PATH\fR environment variable is used, with
  108. the default path (as documented for \fBdinit\fR(8)) used if the variable is unset.
  109. .TP
  110. \fB\-\-use\-passed\-cfd\fR
  111. Instead of attempting to open a socket connection to the service daemon,
  112. use a pre-opened connection that has been passed to the dinitctl process from its parent
  113. via an open file descriptor.
  114. The file descriptor with the connection is identified by the contents of the DINIT_CS_FD
  115. environment variable.
  116. .TP
  117. \fB\-\-quiet\fR
  118. Suppress status output, except for errors.
  119. .TP
  120. \fB\-\-offline\fR, \fB\-o\fR
  121. Work "offline", without communicating with the \fBdinit\fR daemon.
  122. This is applicable only for the \fBenable\fR and \fBdisable\fR subcommands.
  123. .TP
  124. \fB\-\-services\-dir\fR \fIdir\fP, \fB\-d\fR \fIdir\fP
  125. Specifies \fIdir\fP as the directory containing service description files (can
  126. be given multiple times to specify multiple service directories).
  127. Default directories are not searched for services when this option is provided.
  128. This option is ignored when \fB\-\-offline\fR (\fB\-o\fR) is not also specified (otherwise,
  129. \fBdinitctl\fR can query the \fBdinit\fR daemon for the service description directories).
  130. .\"
  131. .SH COMMAND OPTIONS
  132. .TP
  133. \fB\-\-no\-wait\fR
  134. Do not wait for issued command to complete; exit immediately.
  135. .TP
  136. \fB\-\-pin\fR
  137. Pin the service in the requested state. The service will not leave the state until it is unpinned.
  138. .sp
  139. A service that is pinned stopped cannot be marked active, that is, start commands issued to the
  140. service have no effect.
  141. Dependents (via hard dependency relationships) of the pinned service will be unable to start.
  142. .sp
  143. A service that is pinned started cannot be stopped, however its explicit activation can be removed
  144. (eg via the \fBstop\fR or \fBrelease\fR commands).
  145. Once unpinned, a service which is not explicitly activated, and which has no active dependents,
  146. will automatically stop. If a pinned-started service fails to start, the pin is removed.
  147. .sp
  148. Note that a pin takes effect while the service is starting/stopping, before it reaches the target
  149. state. Stopping or restarting a service that is pinned started and which is already starting or
  150. started is not possible.
  151. Similarly, starting a service which is pinned stopped and which is stopping or stopped is not possible.
  152. .TP
  153. \fB\-\-force\fR
  154. Stop the service even if it will require stopping other services which depend on the specified service.
  155. When applied to the \fBrestart\fR command, this will cause the dependent services to also be restarted.
  156. .TP
  157. \fB\-\-ignore\-unstarted\fR
  158. If the service is not started or doesn't exist, ignore the command and return an exit code indicating
  159. success.
  160. .TP
  161. \fB\-\-clear\fR
  162. Clear the log buffer for the service after displaying it.
  163. .TP
  164. \fIservice-name\fR
  165. Specifies the name of the service to which the command applies.
  166. .\"
  167. .SH COMMAND DESCRIPTIONS
  168. .\"
  169. .TP
  170. \fBstart\fR
  171. Start the specified service.
  172. The service is marked as explicitly activated and will not be stopped automatically if its dependents stop.
  173. If the service is currently stopping it will generally continue to stop before it is then restarted.
  174. .TP
  175. \fBstop\fR
  176. Stop the specified service, and remove explicit activation.
  177. If the service has (non-soft) dependents, an error will be displayed and no further action taken,
  178. unless the \fB\-\-force\fR option is used.
  179. If the service is pinned started (and not already stopped or stopping) an error will be displayed
  180. and no further action taken.
  181. .sp
  182. The \fBrestart\fR option (see \fBdinit-service\fR(5)) applied to the stopped service will not cause the
  183. service to restart when it is stopped via this command (that is, this command inhibits automatic restart).
  184. This also applies to any dependents that must also be stopped at the same time.
  185. .sp
  186. Any pending \fBstart\fR orders (including for restarts) are cancelled,
  187. though a service which is starting will continue its startup before then stopping (unless the service is
  188. configured to have an interruptible startup or is otherwise at a stage of startup which can be safely
  189. interrupted).
  190. .TP
  191. \fBstatus\fR
  192. Give a status report on the specified service.
  193. This will show the current state (and target state, if different), and information such as process
  194. ID (pid) if applicable.
  195. If the service is stopped for any reason other than a normal stop, the reason for the service
  196. stopping will be displayed (along with any further relevant information, if available).
  197. .TP
  198. \fBis\-started\fR
  199. Check if the specified service is currently started.
  200. Any other state (including if the service is currently starting or stopping) will exit without returning success.
  201. Unless \fB\-\-quiet\fR is specified, the current service status (STOPPED, STARTING, STARTED, STOPPING)
  202. will be printed to standard output.
  203. .TP
  204. \fBis\-failed\fR
  205. Check if the specified service is currently failed.
  206. The service counts as failed if it is known it is currently stopped either because of startup
  207. failure, timeout or dependency failure.
  208. Any other state, including protocol and parse errors, will exit without returning success.
  209. Unless \fB\-\-quiet\fR is specified, the current service status (STOPPED, STARTING, STARTED, STOPPING)
  210. will be printed to standard output.
  211. .TP
  212. \fBrestart\fR
  213. Restart the specified service. The service will be stopped and then restarted, without affecting explicit
  214. activation status.
  215. .TP
  216. \fBwake\fR
  217. Start the specified service.
  218. The service will not be marked explicitly activated, and so will stop if all the dependents stop.
  219. .TP
  220. \fBrelease\fR
  221. Clear the explicit activation mark from a service (the service will then stop if it has no active dependents).
  222. .TP
  223. \fBunpin\fR
  224. Remove start- and stop- pins from a service.
  225. If a started service is not explicitly activated and has no active dependents, it will stop.
  226. If a started service has a dependency service which is stopping, it will stop.
  227. If a stopped service has a dependent service which is starting, it will start.
  228. Otherwise, any pending start/stop commands will be carried out.
  229. .TP
  230. \fBunload\fR
  231. Completely unload a service.
  232. This can only be done if the service is stopped and has no loaded dependents (i.e. dependents must
  233. be unloaded before their dependencies).
  234. .TP
  235. \fBreload\fR
  236. Attempt to reload a service description.
  237. This is intended as a convenience for making simple changes to a service, without having to stop,
  238. remove dependencies to and unload the service. However it is not completely equivalent to doing a
  239. proper unload/reload; some altered settings may not take effect until the service is restarted,
  240. and some cannot be changed at all while the service is running.
  241. .sp
  242. In particular, the type of a running service cannot be changed; nor can the \fBinittab-id\fR, \fBinittab-line\fR,
  243. or \fBpid-file\fR settings, or the \fBruns-on-console\fR or \fBshares-console\fR flags.
  244. If any hard dependencies are added to a running service, the dependencies must already be started.
  245. .TP
  246. \fBlist\fR
  247. List loaded services and their state.
  248. Before each service, one of the following state indicators is displayed:
  249. .sp
  250. .EX
  251. \m[blue][{+}\ \ \ \ \ ]\m[]\fR \[em] service has started.
  252. \m[blue][{\ }<<\ \ \ ]\m[]\fR \[em] service is starting.
  253. \m[blue][\ \ \ <<{\ }]\m[]\fR \[em] service is starting, will stop once started.
  254. \m[blue][{\ }>>\ \ \ ]\m[]\fR \[em] service is stopping, will start once stopped.
  255. \m[blue][\ \ \ >>{\ }]\m[]\fR \[em] service is stopping.
  256. \m[blue][\ \ \ \ \ {-}]\m[]\fR \[em] service has stopped.
  257. .EE
  258. .sp
  259. The '<<' and '>>' symbols represent a transition state (starting and stopping respectively); curly braces
  260. indicate the target state (left: started, right: stopped); square brackets are used if the service
  261. is marked active (target state will always be started if this is the case).
  262. .sp
  263. An 's' in place of '+' means that the service startup was skipped (possible only if the service is
  264. configured as skippable).
  265. An 'X' in place of '-' means that the service failed to start, or that the
  266. service process unexpectedly terminated with an error status or signal while running.
  267. .sp
  268. Additional information, if available, will be printed after the service name: whether the service owns,
  269. or is waiting to acquire, the console; the process ID; the exit status or signal that caused termination.
  270. .TP
  271. \fBshutdown\fR
  272. Stop all services (without restart) and terminate Dinit.
  273. If issued to the system instance of Dinit, this will also shut down the system.
  274. .TP
  275. \fBadd-dep\fR
  276. Add a dependency between two services.
  277. The \fIdependency-type\fR must be one of \fBneed\fR, \fBmilestone\fR or \fBwaits-for\fR.
  278. Note that adding a \fBneed\fR dependency requires that the service states are consistent with the
  279. dependency (i.e. if the "from" service is started, the "to" service must also be started).
  280. Circular dependency chains may not be created.
  281. .sp
  282. (deprecated) The \fIdependency-type\fR \fBregular\fR is an old alias of \fBneed\fR.
  283. .TP
  284. \fBrm-dep\fR
  285. Remove a dependency between two services.
  286. The \fIdependency-type\fR must be one of \fBneed\fR, \fBmilestone\fR or \fBwaits-for\fR.
  287. If the "to" service is not otherwise active it may be stopped as a result of removing the dependency.
  288. .TP
  289. \fBenable\fR
  290. Persistently enable a \fBwaits-for\fR dependency between two services.
  291. This is much like \fBadd-dep\fR but it also starts the dependency if the dependent is started
  292. (without explicit activation, so the dependency will stop if the dependent stops), and it creates
  293. a symbolic link in the directory specified via the \fBwaits-for.d\fR directive in the service
  294. description (there must be only one such directive) so that the dependency will survive between
  295. sessions.
  296. .sp
  297. If the \fB--from\fR option is not used to specify the dependent, the dependency is created from the
  298. \fBboot\fR service by default.
  299. .TP
  300. \fBdisable\fR
  301. Permanently disable a \fBwaits-for\fR dependency between two services.
  302. This is the complement of the \fBenable\fR command; see the description above for more information.
  303. .sp
  304. Note that the \fBdisable\fR command affects only the dependency specified (or implied).
  305. It has no other effect, and a service that is "disabled" may still be started if it is a dependency of
  306. another started service.
  307. .TP
  308. \fBtrigger\fR
  309. Mark the specified service (which must be a \fItriggered\fR service) as having its external trigger set.
  310. This will allow the service to finish starting.
  311. .TP
  312. \fBuntrigger\fR
  313. Clear the trigger for the specified service (which must be a \fItriggered\fR service).
  314. This will delay the service from starting, until the trigger is set.
  315. If the service has already started, this will have no immediate effect.
  316. .TP
  317. \fBsetenv\fR
  318. Export one or more variables into the activation environment.
  319. The value can be provided on the command line or retrieved from the environment \fBdinitctl\fR is
  320. called in.
  321. Any subsequently started or restarted service will have these environment variables available.
  322. This is particularly useful for user services that need access to session information.
  323. .TP
  324. \fBcatlog\fR
  325. Show the contents of the log buffer for the named service.
  326. This is possible only if the log type of the service is set to \fBbuffer\fR.
  327. If the log is truncated or appears incomplete, a warning message follows the output.
  328. If the \fB\-\-clear\fR option is specified, the buffer is cleared after displaying its contents.
  329. .TP
  330. \fBsignal\fR
  331. Send a signal to the process associated with the specified service.
  332. The \fIsignal-id\fR can either be specified as an integer or signal name (standard POSIX name
  333. minus the \fBSIG\fR- prefix; a limited selection of signal names are recognised, including
  334. \fBTERM\fR, \fBHUP\fR, and \fBKILL\fR).
  335. The \fB--list\fR (\fB-l\fR) option can be used (without \fIsignal-id\fR and \fIservice-name\fR)
  336. to list the full set of supported signal names.
  337. .\"
  338. .SH SERVICE OPERATION
  339. .\"
  340. Normally, services are only started if they have been explicitly activated (\fBstart\fR command) or if
  341. a started service depends on them.
  342. Therefore, starting a service also starts all services that the first depends on; stopping the
  343. same service then also stops the dependency services, unless they are also required by another
  344. explicitly activated service or have been explicitly activated themselves.
  345. .LP
  346. A service can be pinned in either the started or stopped state.
  347. This is mainly intended to be used to prevent automated stop or start of a service, including
  348. via a dependency or dependent service, during a manual administrative procedure.
  349. .LP
  350. Stopping a service manually will prevent it (and its dependents) from automatically restarting (i.e. it
  351. will override the \fBrestart\fR setting in the service configuration).
  352. .\"
  353. .SH ENVIRONMENT VARIABLES
  354. .\"
  355. The following environment variables may control \fBdinitctl\fR's operation:
  356. .TP
  357. \fBDINIT_SOCKET_PATH\fR
  358. The path to the socket used to communicate with the \fBdinit\fR(8) daemon. May be overridden by certain
  359. command line options. If not set, and not overridden, the \fBdinit\fR defaults are used.
  360. .\"
  361. .SH SEE ALSO
  362. \fBdinit\fR(8), \fBdinit-service\fR(5), \fB$$$SHUTDOWN_PREFIX@@@shutdown(8)\fR.
  363. .\"
  364. .SH AUTHOR
  365. Dinit, and this manual, were written by Davin McCall.
  366. $$$dnl