doc/manpages/dinit.8.m4

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