|DINIT(8)||Dinit - service management system||DINIT(8)|
dinit - supervise processes and manage services
dinit [OPTION]... [service-name]...
Dinit is a process supervisor and service manager which can also function as a system init process. It has a small but functional feature set, offering service dependency handling, parallel startup, automatic rate-limited restart of failing processes, and service control functions.
Dinit can be run as a system instance (when run as the root user or when specified via command line parameter) or as a user instance. This affects the default paths used to locate certain files.
When run as PID 1, the first process, Dinit by default acts as a system manager and shuts down or reboots the system on request (including on receipt of certain signals). This is currently fully supported only on Linux. See RUNNING AS SYSTEM MANAGER / PRIMARY INIT.
Dinit reads service descriptions from files located in a service description directory, normally one of /etc/dinit.d, /usr/local/lib/dinit.d or /lib/dinit.d for the system instance or just $HOME/.config/dinit.d when run as a user process. See SERVICE DESCRIPTION FILES for details of the service description format.
If not specified, the default is $HOME/.config/dinit.d or, for the system service manager, each of /etc/dinit.d, /usr/local/lib/dinit.d, and /lib/dinit.d (searched in that order).
Note: on Linux, if dinit is running as PID 1 and with UID 0, it may ignore "naked" service names (without preceding --service/-t) provided on the command line. See the COMMAND LINE FROM KERNEL section.
Service description files specify the parameters of each service. They are named for the service they describe, and are found in /etc/dinit.d for a system instance or $HOME/.config/dinit.d for a user instance.
Service description files are read by Dinit on an "as needed" basis. Once loaded, a service description is never automatically unloaded (even if the service stops or fails). A service description can however be unloaded (if the service is stopped) or reloaded (with some limitations) via dinitctl(8) using the unload and reload subcommands respectively.
See dinit-service(5) for details of the format and available parameters.
There are two service names that are "special" to Dinit.
The boot service is the service that Dinit starts by default, if no other service names are provided when it is started.
The recovery service is a service that Dinit will offer to start if boot appears to fail (that is, if all services stop without a shutdown command having been issued), when Dinit is running as system manager.
On starting, Dinit starts the initial service(s) as specified on the command line. Starting a service also causes the dependencies of that service to start, and any service processes will not be launched until the dependencies are satisfied. Similarly, stopping a service first stops any dependent services.
During execution, Dinit accepts commands via a control socket which is created by Dinit when it starts. This can be used to order that a service be started or stopped, to determine service status, or to make certain configuration changes. See dinitctl(8) for details. Dinit attempts to check for the existence of an already-active socket first, and will refuse to start if one exists. Unfortunately, this check cannot be done atomically, and should not be relied upon generally as a means to avoid starting two instances of dinit.
Process-based services are monitored and, if the process terminates, the service may be stopped or the process may be re-started, according to the configuration in the service description.
Once all services stop, the dinit daemon will itself terminate (or, if running as system manager, will perform the appropriate type of system shutdown).
Dinit does no character set translation. Dinit's own output is in the execution character set as determined at compilation, as is the interpretation of input. Service names (and other user-defined inputs) are interpreted as byte sequences and are output as they were read. In general, modern systems use the UTF-8 character set universally and no problems will arise; however, systems configured to use other character sets may see odd behaviour if the input character set does not match the output character set, or if either input or output character sets are not a superset of the execution character set.
Running as the system manager (primary init) is currently supported only on Linux. When run as process ID 1, the dinit daemon by default assumes responsibility for system shutdown and restart (partially relying on external utilities which are part of the Dinit distribution).
When not running as a system manager, dinit assumes responsibility only for service management. System shutdown or restart need to be handled by the primary init, which should start dinit on normal startup, and terminate dinit before shutdown, by signalling it and waiting for it to terminate after stopping services (possibly by invoking dinitctl shutdown).
When running as PID 1, dinit may process the command line differently, to compensate for kernel behaviour.
On Linux, kernel command line options that are not recognised by the kernel will be passed on to dinit. However, bugs in some kernel versions may cause some options that are recognised to also be passed to dinit. Also, boot managers may insert command-line options such as "auto" (which indicates an "unattended" boot). Therefore, dinit ignores all "word like" options other than "single", which it treats as the name of the service to start (thus allowing "single user mode", assuming that a suitable service description exists). Options beginning with "--" will not be recognised by the kernel and will be passed to (and processed by) dinit; for example --quiet can be used to suppress console output. Options containing "=" that are unrecognised by the kernel (or some that are, due to bugs) are passed to init via the environment rather than via the command line.
There are several ways to work around this. Service names following the --container (-o) or --system-mgr (-m) options are not ignored. Also, the --service (-t) option can be used to force a service name to be recognised regardless of operating mode.
When run as a system manager, SIGINT stops all services and performs a reboot (on Linux, this signal can be generated using the control-alt-delete key combination); SIGTERM stops services and halts the system; and SIGQUIT performs an immediate shutdown with no service rollback.
When run as a user process or system service manager only, SIGINT and SIGTERM both stop services and exit Dinit; SIGQUIT exits Dinit immediately.
dinitctl(8), dinit-service(5), dinitcheck(8), shutdown(8).
Dinit, and this manual, were written by Davin McCall.
|October 2022||Dinit 0.17.0pre|