From: Davin McCall Date: Wed, 14 Jun 2017 17:07:03 +0000 (+0100) Subject: Man page updates. X-Git-Tag: v0.06~70 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=557bef09e961fbeb14c15514e893c76a52f257ce;p=oweals%2Fdinit.git Man page updates. Man pages should be section 8, not section 1. Add "list" command info to dinitctl manpage. --- diff --git a/doc/manpages/Makefile b/doc/manpages/Makefile index a1f4ef9..8235e4d 100644 --- a/doc/manpages/Makefile +++ b/doc/manpages/Makefile @@ -1,3 +1,3 @@ install: mkdir -p "$(DESTDIR)/usr/share/man/man1" - cp dinit.1 dinitctl.1 "$(DESTDIR)/usr/share/man/man1" + cp dinit.8 dinitctl.8 "$(DESTDIR)/usr/share/man/man1" diff --git a/doc/manpages/dinit.1 b/doc/manpages/dinit.1 deleted file mode 100644 index 406a185..0000000 --- a/doc/manpages/dinit.1 +++ /dev/null @@ -1,315 +0,0 @@ -.TH DINIT "1" "June 2017" "Dinit 0.06" "Dinit \- service management system" -.SH NAME -dinit \- supervise processes and manage services -.\" -.SH SYNOPSIS -.\" -.B dinit -[\-s] [\-d \fIdir\fR] [\-p \fIpath\fR] [\fIservice-name\fR] -.\" -.SH DESCRIPTION -.\" -\fBDinit\fR is a process supervisor and service manager which can also -function as a system \fBinit\fR process. It has a small but functional -feature set, offering service dependency handling, parallel startup, -automatic rate-limited restart of failing processes, and service control -functions. -.LP -Dinit reads service descriptions from files located in the service -description directory, normally \fI/etc/dinit.d\fR for the system instance -or \fI$HOME/dinit.d\fR when run as a user process. See \fBSERVICE -DESCRIPTION FILES\fR for details. -.\" -.SH OPTIONS -.TP -\fB\-d\fR \fIdir\fP, \fB\-\-services\-dir\fR \fIdir\fP -Specifies \fIdir\fP as the directory containing service definition files. -.TP -\fB\-p\fR \fIpath\fP, \fB\-\-socket-path\fR \fIpath\fP -Species \fIpath\fP as the path to the control socket used to listen for -commands from the \fBdinitctl\fR program. -.TP -\fB\-s\fR, \fB\-\-system\fR -Run as the system init process. This is the default if invoked as PID 1. -This option affects the default service definition directory and -control socket path. -.TP -\fB\-\-help\fR -display this help and exit -.TP -\fIservice-name\fR -Specifies the name of the service that should be started (along with its -dependencies). If not specified, defaults to \fIboot\fR (which requires -that a suitable service description for the \fIboot\fR service exists). -.\" -.SH SERVICE DESCRIPTION FILES -.\" -Service description files specify the various attributes of a service. A -service description file is named after the service it represents, and is -a plain-text file with simple key-value format. The description files are -located in the service description directory (which defaults to -\fI/etc/dinit.d\fR for the system process). -.LP -All services have a \fItype\fR and a set of \fIdependencies\fR. Service -types are discussed in the following subsection. If a service depends on -another service, then starting the first service causes the second to start -also (and the second service must complete its startup before the first -is considered started). Similarly, if one service depends on another which -becomes stopped, the first service must also stop. -.LP -Service description files are read by Dinit on an "as needed" basis. Once a -service description has been read there is no way (yet) to alter it. -.\" -.SS SERVICE TYPES -.\" -There are four basic types of service: -.IP \(bu -\fBProcess\fR services. This kind of service runs as a single process; starting -the service simply requires starting the process; stopping the service is -accomplished by stopping the process (via sending it a signal). -.IP \(bu -\fBBgprocess\fR services ("background process" services). This kind of -service is similar to a regular process service, but the process daemonizes -or otherwise forks from the original process which starts it, and the -process ID is written to a file. Dinit can read the process ID from the -file and, if it is running as the system init process, can supervise it. -.IP \(bu -\fBScripted\fR services are services which are started and stopped by a -command (which need not actually be a script, despite the name). They can -not be supervised. -.IP \(bu -\fBInternal\fR services do not run as an external process at all. They can -be started and stopped without any external action. They are useful for -grouping other services (via service dependencies). -.\" -.SS SERVICE PROPERTIES -.\" -This section described the various service properties that can be specified -in a service description file. Each line of the file can specify a single -property value, expressed as "\fIproperty-name\fR = \fIvalue\fR". Comments -begin with a hash mark (#) and extend to the end of the line (they must be -separated from setting values by at least one whitespace character). Values -are interpreted literally, except that: -.\" -.IP \(bu -White space (comprised of spaces, tabs, etc) is collapsed to a single space. -.IP \(bu -Double quotes (") can be used around all or part of a property value, to -prevent whitespace collapse and prevent interpretation of other special -characters (such as "#") inside the quotes. The quote characters are not -considered part of the parameter value. -.IP \(bu -A backslash (\\) can be used to escape the next character, causing it to -lose any special meaning and become part of the property value. A double -backslash (\\\\) is collapsed to a single backslash within the parameter -value. -.LP -The following properties can be specified: -.TP -\fBtype\fR = {process | bgprocess | scripted | internal} -Specifies the service type. -.TP -\fBcommand\fR = \fIcommand-string\fR -Specifies the command, including command-line arguments, for starting the -process. Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR -services. -.TP -\fBstop\-command\fR = \fIcommand-string\fR -Specifies the command to stop the service. Applicable only to \fBscripted\fR -services. -.TP -\fBrestart\fR = {yes | true | no | false} -Indicates whether the service should automatically restart if it stops for -any reason (including unexpected process termination, service dependency -stopping, or user-initiated service stop). -.TP -\fBsmooth-recovery\fR = {yes | true | no | false} -Applies only to \fBprocess\fR and \fBbgprocess\fR services. When set true/yes, -an automatic process restart can be performed without first stopping any -dependent services. This setting is meaningless if the \fBrestart\fR setting -is set to false. -.TP -\fBrestart-delay\fR = \fIXXX.YYYY\fR -Specifies the minimum time between automatic restarts. Enforcing a sensible -minimum prevents Dinit from consuming a large number of process cycles in -case a process continuously fails immediately after it is started. The -default is 0.2 (200 milliseconds). -.TP -\fBrestart-limit-interval\fR = \fIXXX.YYYY\fR -Sets the interval, in seconds, over which restarts are limited. If a process -automatically restarts more than a certain number of times (specified by the -\fBrestart-limit-count\fR setting) in this time interval, it will not restart -again. The default value is 10 seconds. -.TP -\fBrestart-limit-count\fR = \fINNN\fR -Specifies the maximum number of times that a service can automatically restart -over the interval specified by \fBrestart-limit-interval\fR. Specify a value -of 0 to disable the restart limit. -.TP -\fBpid-file\fR = \fIpath-to-file\fR -For \fBbgprocess\fR type services only; specifies the path of the file where -daemon will write its process ID before detaching. Dinit will read the -contents of this file when starting the service, once the initial process -exits, will supervise the process with the discovered process ID, and may -send signals to the process ID to stop the service; if Dinit runs as a -privileged user the path should therefore not be writable by unprivileged -users. -.TP -\fBdepends-on\fR = \fIservice-name\fR -This service depends on the named service. Starting this service will start -the named service; the command to start this service will not be executed -until the named service has started. If the named service is stopped then -this service will also be stopped. -.TP -\fBwaits-for\fR = \fIservice-name\fR -When this service is started, wait for the named service to finish starting -(or to fail starting) before commencing the start procedure for this service. -Starting this service will automatically start the named service. If the -named service fails to start, this service will start as usual (subject to -other dependencies being met). -.TP -\fBsocket-listen\fR = \fIsocket-path\fR -Pre-open a socket for the service and pass it to the service using the -\fBsystemd\fR activation protocol. This by itself does not give so called -"socket activation", but does allow that any process trying to connect to the -specified socket will be able to do so, even before the service is properly -prepared to accept connections. -.TP -\fBsocket-permissions\fR = \fIoctal-permissions-mask\fR -Gives the permissions for the socket specified using \fBsocket-listen\fR. -Normally this will be 600 (user access only), 660 (user and group -access), or 666 (all users). The default is 666. -.TP -\fBsocket-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR} -Specifies the user that should own the activation socket. If -\fBsocket-uid\fR is specified without also specifying \fBsocket-gid\fR, then -the socket group is the primary group of the specified user (as found in the -system user database, normally \fI/etc/passwd\fR). If the socket owner is not -specified, the socket will be owned by the user id of the Dinit process. -.TP -\fBsocket-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR} -Specifies the group of the activation socket. See discussion of -\fBsocket-uid\fR. -.TP -\fBtermsignal\fR = {HUP | INT | QUIT | USR1 | USR2} -Specifies an additional signal to send to the process when requesting it -to terminate (applies to 'process' services only). SIGTERM is always -sent along with the specified signal, unless the \fBnosigterm\fR option is -specified via the \fBoptions\fR parameter. -.TP -\fBoptions\fR = {runs\-on\-console | nosigterm | starts\-rwfs | starts\-log}... -Specifies various options for this service: -.RS -.TP -\fBno-sigterm\fR -specifies that the TERM signal should not be send to the process to terminate -it. (Another signal can be specified using the \fBtermsignal\fR setting; if no -other signal is specified, no signal will be sent, which usually means that -the service will not terminate). -.TP -\fBruns-on-console\fR -specifies that this service uses the console; its input and output should be -directed to the console (or precisely, to the device to which Dinit's standard -output stream is connected). A service running on the console prevents other -services from running on the console (they will queue for the console). - -The \fIinterrupt\fR key (normally control-C) will be active for process / scripted -services that run on the console. Handling of an interrupt is determined by -the service process, but typically will cause it to terminate. -.TP -\fBstarts-on-console\fR -specifies that this service uses the console during service startup. This is -implied by \fBruns-on-console\fR, but can be specified separately for services -that need the console while they start but not afterwards. - -This setting is not applicable to regular \fBprocess\fR services, but can be -used for \fBscripted\fR and \fBbgprocess\fR services. It allows for -interrupting startup via the \fIinterrupt\fR key (normally control-C). This is -useful to allow filesystem checks to be interrupted/skipped. -.TP -\fBstarts-rwfs\fR -this service mounts the root filesystem read/write (or at least mounts the -normal writable filesystems for the system). This prompts Dinit to create its -control socket, if it has not already managed to do so. -.TP -\fBstarts-log\fR -this service starts the system log daemon. Dinit will begin logging via the -\fI/dev/log\fR socket. -.TP -\fBpass-cs-fd\fR -pass an open Dinit control socket to the process when launching it (the -\fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of -the socket). This allows the service to issue commands to Dinit even if the -regular control socket is not available yet. - -Using this option has security implications! The service which receives the -control socket must close it before launching any untrusted processes. You -should not use this option unless the service is designed to receive a Dinit -control socket. -.RE -.TP -\fBlogfile\fR = \fIlog-file-path\fR -Specifies the log file for the service. Output from the service process -will go this file. -.LP -The next section contains example service descriptions including some of the -parameters and options described above. -.\" -.SS EXAMPLES -.LP -Here is an example service description for the \fBmysql\fR database server. -It has a dependency on the \fBrcboot\fR service (not shown) which is -expected to have set up the system to a level suitable for basic operation. - -.RS -.nf -.gcolor yellow -# mysqld service -type = process -command = /usr/bin/mysqld --user=mysql -logfile = /var/log/mysqld.log -smooth-recovery = true -restart = false -depends-on = rcboot # Basic system services must be ready -.gcolor -.RE -.fi -.LP -Here is an examples for a filesystem check "service", run by a script -(\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the -system, but the control socket may not have been created, so it uses the -\fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control -commands to Dinit. It runs on the console, so that output is visible and -the process can be interrupted using control-C. - -.RS -.nf -.gcolor yellow -# rootfscheck service -type = scripted -command = /etc/dinit.d/rootfscheck.sh -restart = false -options = starts-on-console pass-cs-fd -depends-on = early-filesystems # /proc and /dev -depends-on = device-node-daemon -.gcolor -.fi -.RE - -More examples are provided with the Dinit distribution. -.\" -.SH SIGNALS -.LP -When run as a system process, SIGINT stops all services and performs a reboot (on Linux, this signal can be -generated using the control-alt-delete key combination); SIGTERM stops services and halts the system; and -SIGQUIT performs an immediate shutdown with no service rollback. -LP -When run as a user process, SIGINT and SIGTERM both stop services and exit Dinit; SIGQUIT exits Dinit -immediately. -.\" -.SH SEE ALSO -.\" -\fBdinitctl\fR(1). -.\" -.SH AUTHOR -Dinit, and this manual, were written by Davin McCall. diff --git a/doc/manpages/dinit.8 b/doc/manpages/dinit.8 new file mode 100644 index 0000000..fff23ea --- /dev/null +++ b/doc/manpages/dinit.8 @@ -0,0 +1,319 @@ +.TH DINIT "8" "June 2017" "Dinit 0.06" "Dinit \- service management system" +.SH NAME +dinit \- supervise processes and manage services +.\" +.SH SYNOPSIS +.\" +.B dinit +[\-s] [\-d \fIdir\fR] [\-p \fIpath\fR] [\fIservice-name\fR] +.\" +.SH DESCRIPTION +.\" +\fBDinit\fR is a process supervisor and service manager which can also +function as a system \fBinit\fR process. It has a small but functional +feature set, offering service dependency handling, parallel startup, +automatic rate-limited restart of failing processes, and service control +functions. +.LP +Dinit reads service descriptions from files located in the service +description directory, normally \fI/etc/dinit.d\fR for the system instance +or \fI$HOME/dinit.d\fR when run as a user process. See \fBSERVICE +DESCRIPTION FILES\fR for details. +.\" +.SH OPTIONS +.TP +\fB\-d\fR \fIdir\fP, \fB\-\-services\-dir\fR \fIdir\fP +Specifies \fIdir\fP as the directory containing service definition files. +.TP +\fB\-p\fR \fIpath\fP, \fB\-\-socket-path\fR \fIpath\fP +Species \fIpath\fP as the path to the control socket used to listen for +commands from the \fBdinitctl\fR program. +.TP +\fB\-s\fR, \fB\-\-system\fR +Run as the system init process. This is the default if invoked as PID 1. +This option affects the default service definition directory and +control socket path. +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fIservice-name\fR +Specifies the name of the service that should be started (along with its +dependencies). If not specified, defaults to \fIboot\fR (which requires +that a suitable service description for the \fIboot\fR service exists). +.\" +.SH SERVICE DESCRIPTION FILES +.\" +Service description files specify the various attributes of a service. A +service description file is named after the service it represents, and is +a plain-text file with simple key-value format. The description files are +located in the service description directory (which defaults to +\fI/etc/dinit.d\fR for the system process). +.LP +All services have a \fItype\fR and a set of \fIdependencies\fR. Service +types are discussed in the following subsection. If a service depends on +another service, then starting the first service causes the second to start +also (and the second service must complete its startup before the first +is considered started). Similarly, if one service depends on another which +becomes stopped, the first service must also stop. +.LP +Service description files are read by Dinit on an "as needed" basis. Once a +service description has been read there is no way (yet) to alter it. +.\" +.SS SERVICE TYPES +.\" +There are four basic types of service: +.IP \(bu +\fBProcess\fR services. This kind of service runs as a single process; starting +the service simply requires starting the process; stopping the service is +accomplished by stopping the process (via sending it a signal). +.IP \(bu +\fBBgprocess\fR services ("background process" services). This kind of +service is similar to a regular process service, but the process daemonizes +or otherwise forks from the original process which starts it, and the +process ID is written to a file. Dinit can read the process ID from the +file and, if it is running as the system init process, can supervise it. +.IP \(bu +\fBScripted\fR services are services which are started and stopped by a +command (which need not actually be a script, despite the name). They can +not be supervised. +.IP \(bu +\fBInternal\fR services do not run as an external process at all. They can +be started and stopped without any external action. They are useful for +grouping other services (via service dependencies). +.\" +.SS SERVICE PROPERTIES +.\" +This section described the various service properties that can be specified +in a service description file. Each line of the file can specify a single +property value, expressed as "\fIproperty-name\fR = \fIvalue\fR". Comments +begin with a hash mark (#) and extend to the end of the line (they must be +separated from setting values by at least one whitespace character). Values +are interpreted literally, except that: +.\" +.IP \(bu +White space (comprised of spaces, tabs, etc) is collapsed to a single space. +.IP \(bu +Double quotes (") can be used around all or part of a property value, to +prevent whitespace collapse and prevent interpretation of other special +characters (such as "#") inside the quotes. The quote characters are not +considered part of the parameter value. +.IP \(bu +A backslash (\\) can be used to escape the next character, causing it to +lose any special meaning and become part of the property value. A double +backslash (\\\\) is collapsed to a single backslash within the parameter +value. +.LP +The following properties can be specified: +.TP +\fBtype\fR = {process | bgprocess | scripted | internal} +Specifies the service type. +.TP +\fBcommand\fR = \fIcommand-string\fR +Specifies the command, including command-line arguments, for starting the +process. Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR +services. +.TP +\fBstop\-command\fR = \fIcommand-string\fR +Specifies the command to stop the service. Applicable only to \fBscripted\fR +services. +.TP +\fBrestart\fR = {yes | true | no | false} +Indicates whether the service should automatically restart if it stops for +any reason (including unexpected process termination, service dependency +stopping, or user-initiated service stop). +.TP +\fBsmooth-recovery\fR = {yes | true | no | false} +Applies only to \fBprocess\fR and \fBbgprocess\fR services. When set true/yes, +an automatic process restart can be performed without first stopping any +dependent services. This setting is meaningless if the \fBrestart\fR setting +is set to false. +.TP +\fBrestart-delay\fR = \fIXXX.YYYY\fR +Specifies the minimum time between automatic restarts. Enforcing a sensible +minimum prevents Dinit from consuming a large number of process cycles in +case a process continuously fails immediately after it is started. The +default is 0.2 (200 milliseconds). +.TP +\fBrestart-limit-interval\fR = \fIXXX.YYYY\fR +Sets the interval, in seconds, over which restarts are limited. If a process +automatically restarts more than a certain number of times (specified by the +\fBrestart-limit-count\fR setting) in this time interval, it will not restart +again. The default value is 10 seconds. +.TP +\fBrestart-limit-count\fR = \fINNN\fR +Specifies the maximum number of times that a service can automatically restart +over the interval specified by \fBrestart-limit-interval\fR. Specify a value +of 0 to disable the restart limit. +.TP +\fBpid-file\fR = \fIpath-to-file\fR +For \fBbgprocess\fR type services only; specifies the path of the file where +daemon will write its process ID before detaching. Dinit will read the +contents of this file when starting the service, once the initial process +exits, will supervise the process with the discovered process ID, and may +send signals to the process ID to stop the service; if Dinit runs as a +privileged user the path should therefore not be writable by unprivileged +users. +.TP +\fBdepends-on\fR = \fIservice-name\fR +This service depends on the named service. Starting this service will start +the named service; the command to start this service will not be executed +until the named service has started. If the named service is stopped then +this service will also be stopped. +.TP +\fBwaits-for\fR = \fIservice-name\fR +When this service is started, wait for the named service to finish starting +(or to fail starting) before commencing the start procedure for this service. +Starting this service will automatically start the named service. If the +named service fails to start, this service will start as usual (subject to +other dependencies being met). +.TP +\fBsocket-listen\fR = \fIsocket-path\fR +Pre-open a socket for the service and pass it to the service using the +\fBsystemd\fR activation protocol. This by itself does not give so called +"socket activation", but does allow that any process trying to connect to the +specified socket will be able to do so, even before the service is properly +prepared to accept connections. +.TP +\fBsocket-permissions\fR = \fIoctal-permissions-mask\fR +Gives the permissions for the socket specified using \fBsocket-listen\fR. +Normally this will be 600 (user access only), 660 (user and group +access), or 666 (all users). The default is 666. +.TP +\fBsocket-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR} +Specifies the user that should own the activation socket. If +\fBsocket-uid\fR is specified without also specifying \fBsocket-gid\fR, then +the socket group is the primary group of the specified user (as found in the +system user database, normally \fI/etc/passwd\fR). If the socket owner is not +specified, the socket will be owned by the user id of the Dinit process. +.TP +\fBsocket-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR} +Specifies the group of the activation socket. See discussion of +\fBsocket-uid\fR. +.TP +\fBtermsignal\fR = {HUP | INT | QUIT | USR1 | USR2} +Specifies an additional signal to send to the process when requesting it +to terminate (applies to 'process' services only). SIGTERM is always +sent along with the specified signal, unless the \fBnosigterm\fR option is +specified via the \fBoptions\fR parameter. +.TP +\fBoptions\fR = {runs\-on\-console | nosigterm | starts\-rwfs | starts\-log}... +Specifies various options for this service: +.RS +.TP +\fBno-sigterm\fR +specifies that the TERM signal should not be send to the process to terminate +it. (Another signal can be specified using the \fBtermsignal\fR setting; if no +other signal is specified, no signal will be sent, which usually means that +the service will not terminate). +.TP +\fBruns-on-console\fR +specifies that this service uses the console; its input and output should be +directed to the console (or precisely, to the device to which Dinit's standard +output stream is connected). A service running on the console prevents other +services from running on the console (they will queue for the console). + +The \fIinterrupt\fR key (normally control-C) will be active for process / scripted +services that run on the console. Handling of an interrupt is determined by +the service process, but typically will cause it to terminate. +.TP +\fBstarts-on-console\fR +specifies that this service uses the console during service startup. This is +implied by \fBruns-on-console\fR, but can be specified separately for services +that need the console while they start but not afterwards. + +This setting is not applicable to regular \fBprocess\fR services, but can be +used for \fBscripted\fR and \fBbgprocess\fR services. It allows for +interrupting startup via the \fIinterrupt\fR key (normally control-C). This is +useful to allow filesystem checks to be interrupted/skipped. +.TP +\fBstarts-rwfs\fR +this service mounts the root filesystem read/write (or at least mounts the +normal writable filesystems for the system). This prompts Dinit to create its +control socket, if it has not already managed to do so. +.TP +\fBstarts-log\fR +this service starts the system log daemon. Dinit will begin logging via the +\fI/dev/log\fR socket. +.TP +\fBpass-cs-fd\fR +pass an open Dinit control socket to the process when launching it (the +\fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of +the socket). This allows the service to issue commands to Dinit even if the +regular control socket is not available yet. + +Using this option has security implications! The service which receives the +control socket must close it before launching any untrusted processes. You +should not use this option unless the service is designed to receive a Dinit +control socket. +.RE +.TP +\fBlogfile\fR = \fIlog-file-path\fR +Specifies the log file for the service. Output from the service process +will go this file. +.LP +The next section contains example service descriptions including some of the +parameters and options described above. +.\" +.SS EXAMPLES +.LP +Here is an example service description for the \fBmysql\fR database server. +It has a dependency on the \fBrcboot\fR service (not shown) which is +expected to have set up the system to a level suitable for basic operation. + +.RS +.nf +.gcolor blue +.ft CR +# mysqld service +type = process +command = /usr/bin/mysqld --user=mysql +logfile = /var/log/mysqld.log +smooth-recovery = true +restart = false +depends-on = rcboot # Basic system services must be ready +.ft +.gcolor +.RE +.fi +.LP +Here is an examples for a filesystem check "service", run by a script +(\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the +system, but the control socket may not have been created, so it uses the +\fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control +commands to Dinit. It runs on the console, so that output is visible and +the process can be interrupted using control-C. + +.RS +.nf +.gcolor blue +.ft CR +# rootfscheck service +type = scripted +command = /etc/dinit.d/rootfscheck.sh +restart = false +options = starts-on-console pass-cs-fd +depends-on = early-filesystems # /proc and /dev +depends-on = device-node-daemon +.ft +.gcolor +.fi +.RE + +More examples are provided with the Dinit distribution. +.\" +.SH SIGNALS +.LP +When run as a system process, SIGINT stops all services and performs a reboot (on Linux, this signal can be +generated using the control-alt-delete key combination); SIGTERM stops services and halts the system; and +SIGQUIT performs an immediate shutdown with no service rollback. +LP +When run as a user process, SIGINT and SIGTERM both stop services and exit Dinit; SIGQUIT exits Dinit +immediately. +.\" +.SH SEE ALSO +.\" +\fBdinitctl\fR(8). +.\" +.SH AUTHOR +Dinit, and this manual, were written by Davin McCall. diff --git a/doc/manpages/dinitctl.1 b/doc/manpages/dinitctl.1 deleted file mode 100644 index 36e0c49..0000000 --- a/doc/manpages/dinitctl.1 +++ /dev/null @@ -1,92 +0,0 @@ -.TH DINITCTL "1" "June 2017" "Dinit 0.06" "Dinit \- service management system" -.SH NAME -dinitctl \- control services supervised by Dinit -.\" -.SH SYNOPSIS -.\" -.B dinitctl -[\-s] [\-\-quiet] start [\-\-no\-wait] [\-\-pin] [\fIservice-name\fR] -.br -.B dinitctl -[\-s] [\-\-quiet] stop [\-\-no\-wait] [\-\-pin] [\fIservice-name\fR] -.br -.B dinitctl -[\-s] [\-\-quiet] wake [\-\-no\-wait] [\fIservice-name\fR] -.br -.B dinitctl -[\-s] [\-\-quiet] release [\fIservice-name\fR] -.br -.B dinitctl -[\-s] [\-\-quiet] unpin [\fIservice-name\fR] -.br -.B dinitctl -[\-s] list -.\" -.SH DESCRIPTION -.\" -\fBdinitctl\fR is a utility to control services being managed by the -\fBdinit\fR daemon. It allows starting and stopping services, and listing -service status. -.\" -.SH OPTIONS -.TP -\fB\-\-help\fR -display this help and exit -.TP -\fB\-\-no\-wait\fR -Do not wait for issued command to complete; exit immediately. -.TP -\fB\-\-pin\fR -Pin the service in the requested state. The service will not leave the state until it is unpinned, although -start/stop commands will be "remembered" while the service is pinned. -.TP -\fB\-s\fR, \fB\-\-system\fR -Control the system init process. The default is to control the user process. This option selects -the path to the control socket used to communicate with the \fBdinit\fR daemon process. -.TP -\fIservice-name\fR -Specifies the name of the service to which the command applies. -.TP -\fBstart\fR -Start the specified service. The service is marked as explicitly activated and will not be stopped -automatically if its dependents stop. If the service is currently stopping it will generally continue -to stop before it is then restarted. -.TP -\fBstop\fR -Stop the specified service, and remove explicit activation. The service will stop, but may restart -immediately if it or any dependents are configured to restart. Any pending \fBstart\fR orders are cancelled, -though a service which is starting might continue its startup before then stopping. -.TP -\fBwake\fR -Start the specified service, but do not mark it as explicitly activated if it is not already so -marked. -.TP -\fBrelease\fR -Clear the explicit activation mark from a service (service will then stop if it has no active dependents). -.TP -\fBunpin\fR -Remove start- and stop- pins from a service. If a started service is not explicitly activated and -has no active dependents, it will stop. If a started service has a dependency service which is stopping, -it will stop. If a stopped service has a dependent service which is starting, it will start. Otherwise, -any pending start/stop commands will be carried out. -.\" -.SH SERVICE OPERATION -.\" -Normally, services are only started if they have been explicitly activated (\fBstart\fR command) or if -a started service depends on them. Therefore, starting a service also starts all services that the first -depends on; stopping the same service then also stops the dependency services, unless they are also -required by another explicitly activated service. -.LP -A service can be pinned in either the started or stopped state. This is mainly intended to be used to -prevent automated stop or start of a service, including via a dependency or dependent service, during -a manual administrative procedure. -.LP -Stopping a service does not in general prevent it from restarting. A service configured to restart -automatically, or with a dependent service configured to do so, will restart immediately after stopping -unless pinned. -.\" -.SH SEE ALSO -\fBdinit\fR(1). -.\" -.SH AUTHOR -Dinit, and this manual, were written by Davin McCall. diff --git a/doc/manpages/dinitctl.8 b/doc/manpages/dinitctl.8 new file mode 100644 index 0000000..2ce2851 --- /dev/null +++ b/doc/manpages/dinitctl.8 @@ -0,0 +1,110 @@ +.TH DINITCTL "8" "June 2017" "Dinit 0.06" "Dinit \- service management system" +.SH NAME +dinitctl \- control services supervised by Dinit +.\" +.SH SYNOPSIS +.\" +.B dinitctl +[\-s] [\-\-quiet] start [\-\-no\-wait] [\-\-pin] [\fIservice-name\fR] +.br +.B dinitctl +[\-s] [\-\-quiet] stop [\-\-no\-wait] [\-\-pin] [\fIservice-name\fR] +.br +.B dinitctl +[\-s] [\-\-quiet] wake [\-\-no\-wait] [\fIservice-name\fR] +.br +.B dinitctl +[\-s] [\-\-quiet] release [\fIservice-name\fR] +.br +.B dinitctl +[\-s] [\-\-quiet] unpin [\fIservice-name\fR] +.br +.B dinitctl +[\-s] list +.\" +.SH DESCRIPTION +.\" +\fBdinitctl\fR is a utility to control services being managed by the +\fBdinit\fR daemon. It allows starting and stopping services, and listing +service status. +.\" +.SH OPTIONS +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-no\-wait\fR +Do not wait for issued command to complete; exit immediately. +.TP +\fB\-\-pin\fR +Pin the service in the requested state. The service will not leave the state until it is unpinned, although +start/stop commands will be "remembered" while the service is pinned. +.TP +\fB\-s\fR, \fB\-\-system\fR +Control the system init process. The default is to control the user process. This option selects +the path to the control socket used to communicate with the \fBdinit\fR daemon process. +.TP +\fIservice-name\fR +Specifies the name of the service to which the command applies. +.TP +\fBstart\fR +Start the specified service. The service is marked as explicitly activated and will not be stopped +automatically if its dependents stop. If the service is currently stopping it will generally continue +to stop before it is then restarted. +.TP +\fBstop\fR +Stop the specified service, and remove explicit activation. The service will stop, but may restart +immediately if it or any dependents are configured to restart. Any pending \fBstart\fR orders are cancelled, +though a service which is starting might continue its startup before then stopping. +.TP +\fBwake\fR +Start the specified service, but do not mark it as explicitly activated if it is not already so +marked. +.TP +\fBrelease\fR +Clear the explicit activation mark from a service (service will then stop if it has no active dependents). +.TP +\fBunpin\fR +Remove start- and stop- pins from a service. If a started service is not explicitly activated and +has no active dependents, it will stop. If a started service has a dependency service which is stopping, +it will stop. If a stopped service has a dependent service which is starting, it will start. Otherwise, +any pending start/stop commands will be carried out. +.TP +\fBlist\fR +List loaded services and their state. Before each service, one of the following state indicators is +displayed: + +.RS +.nf +\f[CR]\m[blue][{+} ]\m[]\fR service has started. +\f[CR]\m[blue][{ }<< ]\m[]\fR service is starting. +\f[CR]\m[blue][ <<{ }]\m[]\fR service is starting, will stop once started. +\f[CR]\m[blue][{ }>> ]\m[]\fR service is stopping, will start once stopped. +\f[CR]\m[blue][ >>{ }]\m[]\fR service is stopping. +\f[CR]\m[blue][ {-}]\m[]\fR service has stopped. +.fi + +The << and >> symbols represent a transition state (starting and stopping respectively); curly braces +indicate the desired state (left: started, right: stopped). +.RE +.\" +.SH SERVICE OPERATION +.\" +Normally, services are only started if they have been explicitly activated (\fBstart\fR command) or if +a started service depends on them. Therefore, starting a service also starts all services that the first +depends on; stopping the same service then also stops the dependency services, unless they are also +required by another explicitly activated service. +.LP +A service can be pinned in either the started or stopped state. This is mainly intended to be used to +prevent automated stop or start of a service, including via a dependency or dependent service, during +a manual administrative procedure. +.LP +Stopping a service does not in general prevent it from restarting. A service configured to restart +automatically, or with a dependent service configured to do so, will restart immediately after stopping +unless pinned. +.\" +.SH SEE ALSO +\fBdinit\fR(8). +.\" +.SH AUTHOR +Dinit, and this manual, were written by Davin McCall.