DINIT(8) man page

DINIT(8)

Dinit - service management system

DINIT(8)

NAME

dinit - supervise processes and manage services

SYNOPSIS

dinit [OPTION]... [service-name]...

DESCRIPTION

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, /run/dinit.d, /usr/local/lib/dinit.d and /lib/dinit.d for the system instance or $XDG_CONFIG_HOME/dinit.d, $HOME/.config/dinit.d, /etc/dinit.d/user, /usr/lib/dinit.d/user and /usr/local/lib/dinit.d/user when run as a user process. See SERVICE DESCRIPTION FILES for details of the service description format.

OPTIONS

-d dir, --services-dir dir

Specifies dir as the directory containing service definition files. This can be specified multiple times for multiple service directories.

The default service directories are listed in the FILES section. Note that the default directories will not be searched when the -d/--services-dir option is specified.

-e file, --env-file file

Read initial environment from file. For the system init process, the default is /etc/dinit/environment; see FILES.

-p path, --socket-path path

Specifies path as the path to the control socket used to listen for commands from the dinitctl program. The default for the system service manager is usually /dev/dinitctl (but can be configured at build time). For a user service manager the default is either $XDG_RUNTIME_DIR/dinitctl or $HOME/.dinitctl, depending on whether $XDG_RUNTIME_DIR is set.

-F fd, --ready-fd fd

Specifies fd as the file descriptor number to report readiness to. Readiness means that the control socket is open and the service manager is ready to accept commands (e.g. via dinitctl). It does not mean that services are finished starting yet. The path to the currently open control socket is written on the file descriptor.

-l path, --log-file path

Species path as the path to the log file, to which Dinit will log status and error messages. Using this option inhibits logging via the syslog facility, however, all logging messages are duplicated as usual to the console (as long as --quiet has not also been specified). Note that when running as the system init, Dinit will continue if it cannot open the specified file, and will attempt to open it again once the root file system is writable. If not running as the system init and the file cannot be opened, Dinit will immediately exit with an error.

-s, --system

Run as the system service manager. This is the default if invoked as the root user. This option affects the default service definition directory and control socket path.

-m, --system-mgr

Run as the system manager (perform operations directly related to machine startup and shutdown). This is the default when running as process ID 1. The main user-visible effect of this option is to invoke the shutdown program when a shutdown is requested (and after all services have stopped), and to provide some basic support for system recovery in case the boot service (or other specified service) cannot be started.

-u, --user

Run as a user service manager. This is the opposite of --system, and is the default if not invoked as the root user.

-o, --container

Run in "container mode", i.e. do not perform system management functions (such as shutdown/reboot). The dinit daemon will simply exit rather than executing the shutdown program.

-q, --quiet

Run with no output to the terminal/console. This disables service status messages and sets the log level for the console log to none. To re-enable (some) output, use the --console-level option after this option.

-b path, --cgroup-path path

Specify the path to resolve relative cgroup paths against. If service description settings contain relative cgroup paths, they will be resolved relative to this path. This option is only available if dinit is built with cgroups support.

--help

Display brief help text and then exit.

--version

Display version number and then exit.

[-t] service-name, [--service] service-name

Specifies the name of a service that should be started (along with its dependencies). If none are specified, defaults to boot (which requires that a suitable service description for the boot service exists). Multiple services can be specified in which case they will each be started.

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.

--console-level level

Specify the minimum log level of messages that should be logged to the console. From highest to lowest, the levels are error, warn, info and debug. Use a level of none to suppress all messages. Note that unless --quiet (-q) is also specified, service state change messages (service started, stopped etc) are always output.

--log-level level

Specify the minimum log level of messages that should be sent to the primary log (syslog facility or file). From highest to lowest, the levels are error, warn, info and debug. Use a level of none to suppress all messages.

SERVICE DESCRIPTION FILES

Service description files specify the parameters of each service. They are named for the service they describe, and are found in one of several directories (including /etc/dinit.d) for a system instance or $XDG_CONFIG_HOME/dinit.d and $HOME/.config/dinit.d for a user instance (see also --services-dir option).

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.

SPECIAL SERVICE NAMES

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.

OPERATION

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).

SERVICE ACTIVATION MODEL

Dinit maintains a set of running services, some of which have been explicitly activated and some of which are active only because they are a dependency of another active service. Initially, only the boot service (or another service or services as specified via the command line) will be explicitly activated. There are both "hard" dependencies between services, and (various types of) "soft" dependencies; see dinit-service(5) for details.

For a service to start, all its hard dependencies must first start successfully; if any of them fail, the dependent will not be started.

In the case of services which are associated with an external process, the process will not be started until all hard dependencies have already started; in the case of a service which fails to start due to a dependency failing, the service command will never be run.

If a process associated with a running service terminates, the service will stop automatically (this can be affected by service settings, and the service may also restart automatically). If the service will not be automatically restarted, any explicit activation will be removed. When stopping a service with an associated running process, the process will not be signalled for termination (or have its termination command executed) until all dependent services have been stopped.

If a service stops, and is a hard dependency of another service, the other service must also stop (and will be stopped automatically, though may restart automatically if configured to do so, which may in turn also cause the dependency to restart).

Services can be explicitly activated using the dinitctl(8) subcommand, start (activating a service will also cause it to start, if it is not already started). Explicit activation can be removed using the release subcommand (which will stop the service only if it is not also a dependency of another active service). Note that the stop subcommand also removes explicit activation, but can fail with no effect if the service will not be stopped (due to being a dependency of another active service).

If a running service is not explicitly activated and has no running dependents, it will be stopped. As a consequence, a service stopping may result in some or all of its dependencies also stopping. A general rule is that starting a service by explicitly activating it will also start any of its dependencies which are not currently started, and that then stopping the same service will result in the same set of dependencies also stopping; there are exceptions to this, however - in particular, a stopped service which is a soft dependency of an otherwise unrelated active service may be started as a result of the starting of a third service, of which it is also a dependency, and in this case the third service stopping again will not cause the first to stop, since the second service remains an active dependent (it is not likely that this particular quirk of behaviour will ever be problematic or even noticed, but it is described here for completeness).

CHARACTER SET HANDLING

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 SYSTEM MANAGER / PRIMARY INIT

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).

LOGGING

Dinit "logs" via two mechanisms simultaneously: the "console" (standard output, not necessarily associated with an actual console if dinit was started with output directed elsewhere) and the "main log facility" which is the syslog facility by default but which may be directed to a file.

Various options are available to control the types and "levels" of message that will be sent to each facility, and the destination of the main facility. The levels available (from low to high) are debug, notice, warn, and error. Selecting a particular log level for facility will cause the facility to receive messages of that level and higher. The special level none inhibits a facility from receiving any messages.

Service status messages (service started or stopped) have a nominal level of notice, except for failure which has a level of error or warn in case of transitive failure (due to a dependency). These messages are, by default, always issued to the console regardless of level, unless the --quiet (-q) option has been used.

To debug boot issues it may be useful to use -q (which also sets the level to none) and then also reset the level via the --console-level option to either warn or error. This will reduce noise in the output from successful service startup.

COMMAND LINE FROM KERNEL

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.

FILES

/etc/dinit/environment

Default location of the environment file for Dinit when run as a system instance (for user instances there is no default). Values are specified as NAME=VALUE, one per line, and add to and replace variables present in the environment when Dinit started (the "original environment"). Lines beginning with a hash character (#) are ignored.

The following special commands can be used (each on a single line):

!clear

Clears the environment completely (prevents inheritance of any variables from the original environment).

!unset var-name...

Unsets the specified variables. Any previously specified value for these variables is forgotten, and they will not inherit any value from the original environment.

!import var-name...

Imports the value of the named variables from the original environment, overriding the effect of any value set previously as well as the effect of previous !unset and !clear commands.

/etc/dinit.d, /run/dinit.d, /usr/local/lib/dinit.d, /lib/dinit.d

Default locations for service description files. The directories are searched in the order listed.

$XDG_CONFIG_HOME/dinit.d, $HOME/.config/dinit.d, /etc/dinit.d/user, /usr/lib/dinit.d/user, /usr/local/lib/dinit.d/user

Default location for service description files for user instances. The directories are searched in the order listed.

SIGNALS

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.

SEE ALSO

dinitctl(8), dinit-service(5), dinitcheck(8), shutdown(8).

AUTHOR

Dinit, and this manual, were written by Davin McCall.

September 2024

Dinit 0.19.0