doc/manpages/dinitctl.8.m4

   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 .B dinitctl
   9 [\fIoptions\fR] \fBstart\fR [\fB\-\-no\-wait\fR] [\fB\-\-pin\fR] \fIservice-name\fR
  10 .br
  11 .B dinitctl
  12 [\fIoptions\fR] \fBstop\fR [\fB\-\-no\-wait\fR] [\fB\-\-pin\fR] \fIservice-name\fR
  13 .br
  14 .B dinitctl
  15 [\fIoptions\fR] \fBrestart\fR [\fB\-\-no\-wait\fR] \fIservice-name\fR
  16 .br
  17 .B dinitctl
  18 [\fIoptions\fR] \fBwake\fR [\fB\-\-no\-wait\fR] \fIservice-name\fR
  19 .br
  20 .B dinitctl
  21 [\fIoptions\fR] \fBrelease\fR \fIservice-name\fR
  22 .br
  23 .B dinitctl
  24 [\fIoptions\fR] \fBunpin\fR \fIservice-name\fR
  25 .br
  26 .B dinitctl
  27 [\fIoptions\fR] \fBunload\fR \fIservice-name\fR
  28 .br
  29 .B dinitctl
  30 [\fIoptions\fR] \fBreload\fR \fIservice-name\fR
  31 .br
  32 .B dinitctl
  33 [\fIoptions\fR] \fBlist\fR
  34 .br
  35 .B dinitctl
  36 [\fIoptions\fR] \fBshutdown\fR
  37 .br
  38 .B dinitctl
  39 [\fIoptions\fR] \fBadd-dep\fR \fIdependency-type\fR \fIfrom-service\fR \fIto-service\fR
  40 .br
  41 .B dinitctl
  42 [\fIoptions\fR] \fBrm-dep\fR \fIdependency-type\fR \fIfrom-service\fR \fIto-service\fR
  43 .br
  44 .B dinitctl
  45 [\fIoptions\fR] \fBenable\fR [\fB\-\-from\fR \fIfrom-service\fR] \fIto-service\fR
  46 .br
  47 .B dinitctl
  48 [\fIoptions\fR] \fBdisable\fR [\fB\-\-from\fR \fIfrom-service\fR] \fIto-service\fR
  49 .\"
  50 .SH DESCRIPTION
  51 .\"
  52 \fBdinitctl\fR is a utility to control services being managed by the
  53 \fBdinit\fR daemon. It allows starting and stopping services, and listing
  54 service status, amongst other actions. It functions by issuing commands to the daemon
  55 via a control socket.
  56 .\"
  57 .SH GENERAL OPTIONS
  58 .TP
  59 \fB\-\-help\fR
  60 Display brief help text and then exit.
  61 .TP
  62 \fB\-s\fR, \fB\-\-system\fR
  63 Control the system init process (this is the default unless run as a non-root user). This option
  64 determines the default path to the control socket used to communicate with the \fBdinit\fR daemon
  65 process (it does not override the \fB\-s\fR option).
  66 .TP
  67 \fB\-u\fR, \fB\-\-user\fR
  68 Control the user init process (this is the default when not run as root). This option determines
  69 the default path to the control socket used to communicate with the \fBdinit\fR daemon process
  70 (it does not override the \fB\-s\fR option).
  71 .TP
  72 \fB\-\-socket\-path\fR \fIsocket-path\fR, \fB\-p\fR \fIsocket-path\fR
  73 Specify the path to the socket used for communicating with the service manager daemon.
  74 .TP
  75 \fB\-\-quiet\fR
  76 Suppress status output, except for errors.
  77 .\"
  78 .SH COMMAND OPTIONS
  79 .TP
  80 \fB\-\-no\-wait\fR
  81 Do not wait for issued command to complete; exit immediately.
  82 .TP
  83 \fB\-\-pin\fR
  84 Pin the service in the requested state. The service will not leave the state until it is unpinned, although
  85 start/stop commands will be "remembered" while the service is pinned.
  86 .TP
  87 \fB\-\-force\fR
  88 Stop the service even if it will require stopping other services which depend on the specified service.
  89 .TP
  90 \fIservice-name\fR
  91 Specifies the name of the service to which the command applies.
  92 .TP
  93 \fBstart\fR
  94 Start the specified service. The service is marked as explicitly activated and will not be stopped
  95 automatically if its dependents stop. If the service is currently stopping it will generally continue
  96 to stop before it is then restarted.
  97 .TP
  98 \fBstop\fR
  99 Stop the specified service, and remove explicit activation. If the service has (non-soft) dependents, an
 100 error will be displayed unless the \fB\-\-force\fR option is used.
 101
 102 A service with any dependents via soft dependencies will have these dependency links broken when it stops.
 103
 104 The \fBrestart\fR option applied to the stopped service will not by itself cause the service to restart
 105 when it is stopped via this command. However, a dependent which is configured to restart may
 106 cause the service itself to restart as a result.
 107
 108 Any pending \fBstart\fR orders are cancelled,
 109 though a service which is starting will continue its startup before then stopping (unless the service is
 110 configured to have an interruptible startup or is otherwise at a stage of startup which can be safely
 111 interrupted).
 112 .TP
 113 \fBrestart\fR
 114 Restart the specified service. The service will be stopped and then restarted, without affecting explicit
 115 activation status or dependency links from dependents.
 116 .TP
 117 \fBwake\fR
 118 Start the specified service after reattaching dependency links from all active dependents of the specified
 119 service. The service will not be marked explicitly activated, and so will stop if the dependents stop.
 120 .TP
 121 \fBrelease\fR
 122 Clear the explicit activation mark from a service (the service will then stop if it has no active dependents).
 123 .TP
 124 \fBunpin\fR
 125 Remove start- and stop- pins from a service. If a started service is not explicitly activated and
 126 has no active dependents, it will stop. If a started service has a dependency service which is stopping,
 127 it will stop. If a stopped service has a dependent service which is starting, it will start. Otherwise,
 128 any pending start/stop commands will be carried out.
 129 .TP
 130 \fBunload\fR
 131 Completely unload a service. This can only be done if the service is stopped and has no loaded dependents
 132 (i.e. dependents must be unloaded before their dependencies).
 133 .TP
 134 \fBreload\fR
 135 Attempt to reload a service description. This is intended as a convenience for making simple changes to a
 136 service, without having to stop, remove dependencies to and unload the service. However it is not completely
 137 equivalent to doing a proper unload/reload; some altered settings may not take effect until the service is
 138 restarted, and some cannot be changed at all while the service is running.
 139
 140 In particular, the type of a running service cannot be changed; nor can the \fBinittab-id\fR, \fBinittab-line\fR,
 141 or \fBpid-file\fR settings, or the \fBruns-on-console\fR or \fBshares-console\fR flags. If any hard dependencies
 142 are added to a running service, the dependencies must already be started.
 143 .TP
 144 \fBlist\fR
 145 List loaded services and their state. Before each service, one of the following state indicators is
 146 displayed:
 147
 148 .RS
 149 .nf
 150 \f[C]\m[blue][{+}\ \ \ \ \ ]\m[]\fR \[em] service has started.
 151 \f[C]\m[blue][{\ }<<\ \ \ ]\m[]\fR \[em] service is starting.
 152 \f[C]\m[blue][\ \ \ <<{\ }]\m[]\fR \[em] service is starting, will stop once started.
 153 \f[C]\m[blue][{\ }>>\ \ \ ]\m[]\fR \[em] service is stopping, will start once stopped.
 154 \f[C]\m[blue][\ \ \ >>{\ }]\m[]\fR \[em] service is stopping.
 155 \f[C]\m[blue][\ \ \ \ \ {-}]\m[]\fR \[em] service has stopped.
 156 .fi
 157
 158 The << and >> symbols represent a transition state (starting and stopping respectively); curly braces
 159 indicate the desired state (left: started, right: stopped). An 's' in place of '+' means that service
 160 startup was skipped (possible only if the service is configured as skippable). An 'X' in place of '-'
 161 means that the service failed to start, or that the service process unexpectedly terminated with an
 162 error status or signal while running.
 163
 164 Additional information, if available, will be printed after the service name: whether the service owns,
 165 or is waiting to acquire, the console; the process ID; the exit status or signal that caused termination.
 166 .RE
 167 .TP
 168 \fBshutdown\fR
 169 Stop all services (without restart) and terminate Dinit. If issued to the system instance of Dinit,
 170 this will also shut down the system.
 171 .TP
 172 \fBadd-dep\fR
 173 Add a dependency between two services. The \fIdependency-type\fR must be one of \fBregular\fR,
 174 \fBmilestone\fR or \fBwaits-for\fR. Note that adding a regular dependency requires that the service
 175 states are consistent with the dependency (i.e. if the "from" service is started, the "to" service
 176 must also be started). Circular dependency chains may not be created.
 177 .TP
 178 \fBrm-dep\fR
 179 Remove a dependency between two services. The \fIdependency-type\fR must be one of \fBregular\fR,
 180 \fBmilestone\fR or \fBwaits-for\fR. If the "to" service is not otherwise active it may be stopped
 181 as a result of removing the dependency.
 182 .TP
 183 \fBenable\fR
 184 Permanently enable a \fBwaits-for\fR dependency between two services. This is much like \fBadd-dep\fR
 185 but it also starts the dependency if the dependent is started (without explicit activation, so the
 186 dependency will stop if the dependent stops), and it creates a symbolic link in the directory
 187 specified via the \fBwaits-for.d\fR directive in the service description (there must be only one such
 188 directive). The dependency should therefore be persistent.
 189
 190 If the \fB--from\fR option is not used to specify the dependent, the dependency is created from the
 191 \fBboot\fR service by default.
 192 .TP
 193 \fBdisable\fR
 194 Permanently disable a \fBwaits-for\fR dependency between two services. This is the complement of the
 195 \fBenable\fR command; see the description above for more information.
 196 .\"
 197 .SH SERVICE OPERATION
 198 .\"
 199 Normally, services are only started if they have been explicitly activated (\fBstart\fR command) or if
 200 a started service depends on them. Therefore, starting a service also starts all services that the first
 201 depends on; stopping the same service then also stops the dependency services, unless they are also
 202 required by another explicitly activated service.
 203 .LP
 204 A service can be pinned in either the started or stopped state. This is mainly intended to be used to
 205 prevent automated stop or start of a service, including via a dependency or dependent service, during
 206 a manual administrative procedure.
 207 .LP
 208 Stopping a service does not in general prevent it from restarting. A service configured to restart
 209 automatically, or with a dependent service configured to do so, will restart immediately after stopping
 210 unless pinned.
 211 .\"
 212 .SH SEE ALSO
 213 \fBdinit\fR(8).
 214 .\"
 215 .SH AUTHOR
 216 Dinit, and this manual, were written by Davin McCall.
 217 $$$dnl