doc/manpages/dinitctl.8

   1 .TH DINITCTL "8" "June 2018" "Dinit 0.3.0" "Dinit \- service management system"
   2 .SH NAME
   3 dinitctl \- control services supervised by Dinit
   4 .\"
   5 .SH SYNOPSIS
   6 .\"
   7 .B dinitctl
   8 [\-s] [\-\-quiet] start [\-\-no\-wait] [\-\-pin] [\fIservice-name\fR]
   9 .br
  10 .B dinitctl
  11 [\-s] [\-\-quiet] stop [\-\-no\-wait] [\-\-pin] [\fIservice-name\fR]
  12 .br
  13 .B dinitctl
  14 [\-s] [\-\-quiet] wake [\-\-no\-wait] [\fIservice-name\fR]
  15 .br
  16 .B dinitctl
  17 [\-s] [\-\-quiet] release [\fIservice-name\fR]
  18 .br
  19 .B dinitctl
  20 [\-s] [\-\-quiet] unpin [\fIservice-name\fR]
  21 .br
  22 .B dinitctl
  23 unload [\fIservice-name\fR]
  24 .br
  25 .B dinitctl
  26 [\-s] list
  27 .br
  28 .B dinitctl
  29 [\-s] shutdown
  30 .br
  31 .B dinitctl
  32 [\-s] add-dep [\fIdependency-type\fR] [\fIfrom-service\fR] [\fIto-service\fR]
  33 .br
  34 .B dinitctl
  35 [\-s] rm-dep [\fIdependency-type\fR] [\fIfrom-service\fR] [\fIto-service\fR]
  36 .\"
  37 .SH DESCRIPTION
  38 .\"
  39 \fBdinitctl\fR is a utility to control services being managed by the
  40 \fBdinit\fR daemon. It allows starting and stopping services, and listing
  41 service status.
  42 .\"
  43 .SH OPTIONS
  44 .TP
  45 \fB\-\-help\fR
  46 display this help and exit
  47 .TP
  48 \fB\-\-no\-wait\fR
  49 Do not wait for issued command to complete; exit immediately.
  50 .TP
  51 \fB\-\-pin\fR
  52 Pin the service in the requested state. The service will not leave the state until it is unpinned, although
  53 start/stop commands will be "remembered" while the service is pinned.
  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 \fIservice-name\fR
  60 Specifies the name of the service to which the command applies.
  61 .TP
  62 \fBstart\fR
  63 Start the specified service. The service is marked as explicitly activated and will not be stopped
  64 automatically if its dependents stop. If the service is currently stopping it will generally continue
  65 to stop before it is then restarted.
  66 .TP
  67 \fBstop\fR
  68 Stop the specified service, and remove explicit activation. The service will stop, but may restart
  69 immediately if it or any dependents are configured to restart.  Any pending \fBstart\fR orders are cancelled,
  70 though a service which is starting might continue its startup before then stopping.
  71 .TP
  72 \fBwake\fR
  73 Start the specified service, but do not mark it as explicitly activated if it is not already so
  74 marked.
  75 .TP
  76 \fBrelease\fR
  77 Clear the explicit activation mark from a service (service will then stop if it has no active dependents).
  78 .TP
  79 \fBunpin\fR
  80 Remove start- and stop- pins from a service. If a started service is not explicitly activated and
  81 has no active dependents, it will stop. If a started service has a dependency service which is stopping,
  82 it will stop. If a stopped service has a dependent service which is starting, it will start. Otherwise,
  83 any pending start/stop commands will be carried out.
  84 .TP
  85 \fBunload\fR
  86 Completely unload a service. This can only be done if the service is stopped and has no loaded dependents
  87 (i.e. dependents must be unloaded before their dependencies).
  88 .TP
  89 \fBlist\fR
  90 List loaded services and their state. Before each service, one of the following state indicators is
  91 displayed:
  92
  93 .RS
  94 .nf
  95 \f[C]\m[blue][{+}\ \ \ \ \ ]\m[]\fR \[em] service has started.
  96 \f[C]\m[blue][{\ }<<\ \ \ ]\m[]\fR \[em] service is starting.
  97 \f[C]\m[blue][\ \ \ <<{\ }]\m[]\fR \[em] service is starting, will stop once started.
  98 \f[C]\m[blue][{\ }>>\ \ \ ]\m[]\fR \[em] service is stopping, will start once stopped.
  99 \f[C]\m[blue][\ \ \ >>{\ }]\m[]\fR \[em] service is stopping.
 100 \f[C]\m[blue][\ \ \ \ \ {-}]\m[]\fR \[em] service has stopped.
 101 .fi
 102
 103 The << and >> symbols represent a transition state (starting and stopping respectively); curly braces
 104 indicate the desired state (left: started, right: stopped). An 's' in place of '+' means that service
 105 startup was skipped (possible only if the service is configured as skippable). An 'X' in place of '-'
 106 means that the service failed to start, or that the service process unexpectedly terminated with an
 107 error status or signal while running.
 108
 109 Additional information, if available, will be printed after the service name: whether the service owns,
 110 or is waiting to acquire, the console; the process ID; the exit status or signal that caused termination.
 111 .RE
 112 .TP
 113 \fBshutdown\fR
 114 Stop all services (without restart) and terminate Dinit. If issued to the system instance of Dinit,
 115 this will also shut down the system.
 116 .TP
 117 \fBadd-dep\fR
 118 Add a dependency between two services. The \fIdependency-type\fR must be one of \fBregular\fR,
 119 \fBmilestone\fR or \fBwaits-for\fR. Note that adding a regular dependency requires that the service
 120 states are consistent with the dependency (i.e. if the "from" service is started, the "to" service
 121 must also be started). Circular dependency chains may not be created.
 122 .TP
 123 \fBrm-dep\fR
 124 Remove a dependency between two services. The \fIdependency-type\fR must be one of \fBregular\fR,
 125 \fBmilestone\fR or \fBwaits-for\fR. If the "to" service is not otherwise active it may be stopped
 126 as a result of removing the dependency.
 127 .\"
 128 .SH SERVICE OPERATION
 129 .\"
 130 Normally, services are only started if they have been explicitly activated (\fBstart\fR command) or if
 131 a started service depends on them. Therefore, starting a service also starts all services that the first
 132 depends on; stopping the same service then also stops the dependency services, unless they are also
 133 required by another explicitly activated service.
 134 .LP
 135 A service can be pinned in either the started or stopped state. This is mainly intended to be used to
 136 prevent automated stop or start of a service, including via a dependency or dependent service, during
 137 a manual administrative procedure.
 138 .LP
 139 Stopping a service does not in general prevent it from restarting. A service configured to restart
 140 automatically, or with a dependent service configured to do so, will restart immediately after stopping
 141 unless pinned.
 142 .\"
 143 .SH SEE ALSO
 144 \fBdinit\fR(8).
 145 .\"
 146 .SH AUTHOR
 147 Dinit, and this manual, were written by Davin McCall.