doc/manpages/dinit.8

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