doc/manpages/dinit.8

   1 .TH DINIT "8" "May 2019" "Dinit 0.5.0" "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 OPERATION
  95 .\"
  96 On starting, Dinit starts the initial service(s) as specified on the command
  97 line. Starting a service also causes the dependencies of that service to
  98 start, and any service processes will not be launched until the dependencies
  99 are satisfied. Similarly, stopping a service first stops any dependent
 100 services.
 101
 102 During execution, Dinit accepts commands via a control socket which is created
 103 by Dinit when it starts. This can be used to order that a service be started
 104 or stopped, to determine service status, or to make certain configuration
 105 changes. See \fBdinitctl\fR(8) for details.
 106
 107 Process-based services are monitored and, if the process terminates, the
 108 service may be stopped or the process may be re-started, according to the
 109 configuration in the service description.
 110
 111 Once all services stop, the \fBdinit\fR daemon will itself terminate (or, if
 112 running as PID 1, will perform the appropriate type of system shutdown).
 113 .\"
 114 .SS CHARACTER SET HANDLING
 115 .\"
 116 Dinit does no character set translation. Dinit's own output is in the execution
 117 character set as determined at compilation, as is the interpretation of input.
 118 Service names (and other user-defined inputs) are interpreted as byte sequences
 119 and are output as they were read. In general, modern systems use the UTF-8
 120 character set universally and no problems will arise; however, systems configured
 121 to use other character sets may see odd behaviour if the input character set does
 122 not match the output character set, or if either input or output character sets
 123 are not a superset of the execution character set.
 124 .\"
 125 .SS RUNNING AS SYSTEM MANAGER / PRIMARY INIT
 126 .\"
 127 Running as the system manager (primary \fBinit\fR) is currently supported only on
 128 Linux. When run as process ID 1, the \fBdinit\fR daemon assumes responsibility for
 129 system shutdown and restart (partially relying on external utilities which are
 130 part of the Dinit distribution).
 131
 132 When not running as process ID 1, \fBdinit\fR assumes responsibility only for
 133 service management. System shutdown or restart need to be handled by the primary
 134 \fBinit\fR, which should start \fBdinit\fR on normal startup, and terminate
 135 \fBdinit\fR before shutdown, by signalling it and waiting for it to terminate
 136 after stopping services.
 137 .\"
 138 .SH FILES
 139 .\"
 140 .TP
 141 \fI/etc/dinit/environment\fR
 142 Default location of the environment file for Dinit when run as a system
 143 instance (for user instances there is no default). Values are specified as
 144 \fINAME\fR=\fIVALUE\fR, one per line, and add to and replace variables present
 145 in the environment when Dinit started. Lines beginning with a hash character
 146 (#) are ignored.
 147 .\"
 148 .SH SIGNALS
 149 .LP
 150 When run as a system manager, SIGINT stops all services and performs a reboot (on Linux, this signal can be
 151 generated using the control-alt-delete key combination); SIGTERM stops services and halts the system; and
 152 SIGQUIT performs an immediate shutdown with no service rollback.
 153 .LP
 154 When run as a user process or system service manager only, SIGINT and SIGTERM both stop services
 155 and exit Dinit; SIGQUIT exits Dinit immediately.
 156 .\"
 157 .SH SEE ALSO
 158 .\"
 159 \fBdinitctl\fR(8), \fBdinit-service\fR(5).
 160 .\"
 161 .SH AUTHOR
 162 Dinit, and this manual, were written by Davin McCall.