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