doc/manpages/dinit.8

   1 .TH DINIT "8" "May 2019" "Dinit 0.5.1" "Dinit \- service management system"
   2 .SH NAME
   3 dinit \- supervise processes and manage services
   4 .\"
   5 .SH SYNOPSIS
   6 .\"
   7 .HP \w'\ 'u
   8 .B dinit
   9 [\fB\-s\fR|\fB\-\-system\fR|\fB\-u\fR|\fB\-\-user\fR] [\fB\-d\fR|\fB\-\-services\-dir\fR \fIdir\fR]
  10 [\fB\-p\fR|\fB\-\-socket\-path\fR \fIpath\fR] [\fB\-e\fR|\fB\-\-env\-file\fR \fIpath\fR]
  11 [\fB\-l\fR|\fB\-\-log\-file\fR \fIpath\fR]
  12 [\fIservice-name\fR...]
  13 .\"
  14 .SH DESCRIPTION
  15 .\"
  16 \fBDinit\fR is a process supervisor and service manager which can also
  17 function as a system \fBinit\fR process. It has a small but functional
  18 feature set, offering service dependency handling, parallel startup,
  19 automatic rate-limited restart of failing processes, and service control
  20 functions.
  21
  22 Dinit can be run as a system instance (when run as the root user or when
  23 specified via command line parameter) or as a user instance. This affects
  24 the default paths used to locate certain files.
  25
  26 When run as PID 1, the first process, Dinit acts as a system manager and
  27 shuts down or reboots the system on request (including on receipt of
  28 certain signals). This is currently fully supported only on Linux. See
  29 \fBRUNNING AS SYSTEM MANAGER / PRIMARY INIT\fR.
  30
  31 Dinit reads service descriptions from files located in a service
  32 description directory, normally one of \fI/etc/dinit.d\fR,
  33 \fI/usr/local/lib/dinit.d\fR or \fI/lib/dinit.d\fR for the system instance
  34 or just \fI$HOME/dinit.d\fR when run as a user process. See \fBSERVICE
  35 DESCRIPTION FILES\fR for details of the service description format.
  36 .\"
  37 .SH OPTIONS
  38 .TP
  39 \fB\-d\fR \fIdir\fP, \fB\-\-services\-dir\fR \fIdir\fP
  40 Specifies \fIdir\fP as the directory containing service definition files.
  41 The directory specified will be the only directory searched for service
  42 definitions.
  43
  44 If not specified, the default is \fI$HOME/dinit.d\fR or, for the
  45 system service manager, each of \fI/etc/dinit.d/fR, \fI/usr/local/lib/dinit.d\fR,
  46 and \fI/lib/dinit.d\fR (searched in that order).
  47 .TP
  48 \fB\-e\fR \fIfile\fP, \fB\-\-env\-file\fR \fIfile\fP
  49 Read initial environment from \fIfile\fP. For the system init process, the
  50 default is \fI/etc/dinit/environment\fR; see \fBFILES\fR.
  51 .TP
  52 \fB\-p\fR \fIpath\fP, \fB\-\-socket\-path\fR \fIpath\fP
  53 Specifies \fIpath\fP as the path to the control socket used to listen for
  54 commands from the \fBdinitctl\fR program. The default for the system service
  55 manager is usually \fI/dev/dinitctl\fR (but can be configured at build time).
  56 For a user service manager the default is \fI$HOME/.dinitctl\fR.
  57 .TP
  58 \fB\-l\fR \fIpath\fP, \fB\-\-log\-file\fR \fIpath\fP
  59 Species \fIpath\fP as the path to the log file, to which Dinit will log status
  60 and error messages. Note that when running as the system service manager, Dinit
  61 does not begin logging until the log service has started. Using this option
  62 inhibits logging via the syslog facility, however, all logging messages are
  63 duplicated as usual to the console (so long as no service owns the console).
  64 .TP
  65 \fB\-s\fR, \fB\-\-system\fR
  66 Run as the system service manager. This is the default if invoked as the root
  67 user. This option affects the default service definition directory and control
  68 socket path.
  69 .TP
  70 \fB\-u\fR, \fB\-\-user\fR
  71 Run as a user. This is the opposite of \fB\-\-system\fR, and is the default if
  72 not invoked as the root user.
  73 .TP
  74 \fB\-\-help\fR
  75 display this help and exit
  76 .TP
  77 \fIservice-name\fR
  78 Specifies the name of a service that should be started (along with its
  79 dependencies). If none are specified, defaults to \fIboot\fR (which requires
  80 that a suitable service description for the \fIboot\fR service exists).
  81 .\"
  82 .SH SERVICE DESCRIPTION FILES
  83 .\"
  84 Service description files specify the parameters of each service. They are
  85 named for the service they describe, and are found in \fI/etc/dinit.d\fR
  86 for a system instance or \fI$HOME/dinit.d\fR for a user instance.
  87
  88 Service description files are read by Dinit on an "as needed" basis. Once a
  89 service description has been read the configuration can be altered in limited
  90 ways via the \fBdinitctl\fR(8) program.
  91
  92 See \fBdinit-service\fR(5) for details of the format and available parameters.
  93 .\"
  94 .SH SPECIAL SERVICE NAMES
  95 .\"
  96 There are two service names that are "special" to Dinit.
  97
  98 The \fIboot\fR service is the service that Dinit starts by default, if no
  99 other service names are provided when it is started.
 100
 101 The \fIrecovery\fR service is a service that Dinit will offer to start if
 102 boot appears to fail (that is, if all services stop without a shutdown command
 103 having been issued), when Dinit is running as system manager.
 104 .\"
 105 .SH OPERATION
 106 .\"
 107 On starting, Dinit starts the initial service(s) as specified on the command
 108 line. Starting a service also causes the dependencies of that service to
 109 start, and any service processes will not be launched until the dependencies
 110 are satisfied. Similarly, stopping a service first stops any dependent
 111 services.
 112
 113 During execution, Dinit accepts commands via a control socket which is created
 114 by Dinit when it starts. This can be used to order that a service be started
 115 or stopped, to determine service status, or to make certain configuration
 116 changes. See \fBdinitctl\fR(8) for details.
 117
 118 Process-based services are monitored and, if the process terminates, the
 119 service may be stopped or the process may be re-started, according to the
 120 configuration in the service description.
 121
 122 Once all services stop, the \fBdinit\fR daemon will itself terminate (or, if
 123 running as PID 1, will perform the appropriate type of system shutdown).
 124 .\"
 125 .SS CHARACTER SET HANDLING
 126 .\"
 127 Dinit does no character set translation. Dinit's own output is in the execution
 128 character set as determined at compilation, as is the interpretation of input.
 129 Service names (and other user-defined inputs) are interpreted as byte sequences
 130 and are output as they were read. In general, modern systems use the UTF-8
 131 character set universally and no problems will arise; however, systems configured
 132 to use other character sets may see odd behaviour if the input character set does
 133 not match the output character set, or if either input or output character sets
 134 are not a superset of the execution character set.
 135 .\"
 136 .SS RUNNING AS SYSTEM MANAGER / PRIMARY INIT
 137 .\"
 138 Running as the system manager (primary \fBinit\fR) is currently supported only on
 139 Linux. When run as process ID 1, the \fBdinit\fR daemon assumes responsibility for
 140 system shutdown and restart (partially relying on external utilities which are
 141 part of the Dinit distribution).
 142
 143 When not running as process ID 1, \fBdinit\fR assumes responsibility only for
 144 service management. System shutdown or restart need to be handled by the primary
 145 \fBinit\fR, which should start \fBdinit\fR on normal startup, and terminate
 146 \fBdinit\fR before shutdown, by signalling it and waiting for it to terminate
 147 after stopping services (possibly by invoking \fBdinitctl shutdown\fR).
 148 .\"
 149 .SH FILES
 150 .\"
 151 .TP
 152 \fI/etc/dinit/environment\fR
 153 Default location of the environment file for Dinit when run as a system
 154 instance (for user instances there is no default). Values are specified as
 155 \fINAME\fR=\fIVALUE\fR, one per line, and add to and replace variables present
 156 in the environment when Dinit started. Lines beginning with a hash character
 157 (#) are ignored.
 158 .\"
 159 .SH SIGNALS
 160 .LP
 161 When run as a system manager, SIGINT stops all services and performs a reboot (on Linux, this signal can be
 162 generated using the control-alt-delete key combination); SIGTERM stops services and halts the system; and
 163 SIGQUIT performs an immediate shutdown with no service rollback.
 164 .LP
 165 When run as a user process or system service manager only, SIGINT and SIGTERM both stop services
 166 and exit Dinit; SIGQUIT exits Dinit immediately.
 167 .\"
 168 .SH SEE ALSO
 169 .\"
 170 \fBdinitctl\fR(8), \fBdinit-service\fR(5).
 171 .\"
 172 .SH AUTHOR
 173 Dinit, and this manual, were written by Davin McCall.