DINIT(8)

📦
version 0.21.0 · 3 versions
, in alpine 3.24

💖 NAME 💖

dinit — supervise processes and manage services. Welcome to the dinit(8) page, bestie — this is the manual for the service manager/supervisor that keeps your processes behaving.

🌈 SYNOPSIS 🌈

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

✨ DESCRIPTION ✨

dinit is a process supervisor and service manager that can also function as a system init process. It has a small but functional feature set, and it offers service dependency handling, parallel startup, automatic rate-limited restart of failing processes, and service control functions. Lowkey iconic.

Dinit can run as a system instance (when it's run as the root user or when that's specified via a command line parameter) or as a user instance. This affects the default paths used to locate certain files.

When it's 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 that's one of these for the system instance:

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

And when it's run as a user process, it's normally one of these:

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

See SERVICE DESCRIPTION FILES for the details of the service description format.

💅 OPTIONS 💅

  • -d dir, --services-dir dir — specifies dir as the directory containing service description files. You can specify this 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 the 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 it 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 — specifies 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 description 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 dinit-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 dinit-shutdown program.
  • -r, --auto-recovery — automatically run the recovery service on apparent boot failures (if all services stop without a shutdown command having been issued) without prompting the user when Dinit is running as system manager.
  • -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, it 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. An argument to the service may be included here.
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 the --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 🦋

ok so when Dinit boots up, it starts the initial service(s) exactly like you told it to on the command line — no cap. And here's the tea: starting a service also drags its whole dependency tree into existence, but no service process gets launched until all its dependencies are satisfied. Same energy in reverse: stopping a service first stops everything that depends on it. Respect the hierarchy, bestie.

While it's running, Dinit takes commands over a control socket that it creates for itself at startup. Through that you can order services to start or stop, peek at service status, or tweak certain config bits. The details live in dinitctl(8) — go read it, iykyk. One thing though: Dinit tries to check whether an already-active socket exists first, and it will refuse to start if one does. But 😭 that check cannot be done atomically, so please don't rely on it as your general strategy for avoiding two dinit instances. It's giving "best effort," not "guarantee."

Process-based services get monitored 👀 — if the process terminates, the service may be stopped, or the process may be restarted, all according to whatever the service description says.

And when all services stop, the dinit daemon itself terminates too. (Unless it's running as system manager, in which case it performs the appropriate type of system shutdown instead. Different hat, different vibe.)

🌸 SERVICE ACTIVATION MODEL 🌸

Dinit keeps a whole set of running services. Some of them you explicitly activated, and some are only alive because they're a dependency of another active service. At the very start, only the boot service is explicitly activated — or whatever other service(s) you specified on the command line. There are "hard" dependencies and (various types of) "soft" dependencies between services; dinit-service(5) has the full lore.

For a service to start, all its hard dependencies must first start successfully. If any of them fail, the dependent just won't start. That's it, that's the rule. 💅

For services tied to an external process, the process won't be started until every hard dependency has already started. And if a service fails to start because a dependency failed? The service command never runs at all. Never ever.

If a process associated with a running service terminates, the service stops automatically — though service settings can affect this, and the service might restart automatically too. If it's not going to auto-restart, then any explicit activation gets removed. And when you stop a service that has a running process, that process will not be signalled for termination (and its termination command won't be executed) until all dependent services have been stopped. Order matters, periodt.

If a service stops and it's a hard dependency of another service, that other service must stop too — it'll be stopped automatically, though it may restart automatically if configured that way, which might in turn cause the dependency to restart. Cute little cascade. 💫 A service won't be stopped by dinit until its dependents have completely stopped.

You can explicitly activate services with the dinitctl(8) subcommand, start (activating a service also causes it to start, if it isn't already started). You can remove explicit activation with the release subcommand — which stops the service only if it isn't also a dependency of another active service. And heads up: the stop subcommand also removes explicit activation, but it can fail with no effect if the service won't be stopped (because it's a dependency of another active service). 🙈

If a running service is not explicitly activated and has no running dependents, it will be stopped. Which means a service stopping can cause some or all of its dependencies to stop too. The general rule: starting a service by explicitly activating it also starts any of its dependencies that aren't currently started, and then stopping that same service results in the same set of dependencies stopping as well.

⚠️ But there are exceptions! Specifically: a stopped service that is a soft dependency of an otherwise unrelated active service may get started as a result of starting a third service, of which it is also a dependency. And in that case, the third service stopping again will not cause the first to stop, since the second service remains an active dependent. The manpage literally says it's not likely this quirk will ever be problematic or even noticed — it's described here for completeness. So like, don't stress, but now you know. 💀

🎀 CHARACTER SET HANDLING 🎀

Dinit does no character set translation. None. Zero. Dinit's own output is in the execution character set as determined at compilation, and the interpretation of input works the same way. Service names (and other user-defined inputs) are interpreted as byte sequences and output exactly as they were read.

In general, modern systems use UTF-8 universally and no problems will arise ✨ — but systems configured for other character sets may see odd behaviour if the input character set doesn't match the output character set, or if either the input or output character sets aren't a superset of the execution character set. Weird vibes only in that case, bestie.

👑 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 that are part of the Dinit distribution.

When it's not running as a system manager, dinit only takes responsibility for service management. System shutdown or restart needs 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). Cooperation nation. 🫶

✨ LOGGING ✨

Dinit "logs" through two mechanisms simultaneously:

  • the "console" — that's standard output, which isn't necessarily associated with an actual console if dinit was started with output directed elsewhere
  • the "main log facility" — the syslog facility by default, but it may be directed to a file instead

Various options control the types and "levels" of messages sent to each facility, plus the destination of the main facility. The levels, from low to high, are:

  1. debug
  2. notice
  3. warn
  4. error

Picking a particular log level for a facility means that facility receives messages of that level and higher. And the special level none inhibits a facility from receiving any messages. Silence. 🤫

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

💡 Debugging boot issues? Try -q (which also sets the level to none) and then reset the level via the --console-level option to either warn or error. That reduces noise from successful service startup so the actual problems can shine. Iconic troubleshooting behaviour, honestly.

🌈 COMMAND LINE FROM KERNEL 🌈

When running as PID 1, dinit may process the command line differently, to compensate for kernel behaviour. (The kernel is the main character here and we just live in its world. 😭)

On Linux, kernel command line options that the kernel doesn't recognise get passed on to dinit. But! Bugs in some kernel versions may cause some options that are recognised to also be passed to dinit. And boot managers may insert command-line options such as auto (which indicates an "unattended" boot).

So 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 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.
  • 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 they add to and replace variables present in the environment when Dinit started (the "original environment"). Lines beginning with a hash character (#) are ignored.

These 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.
  • SIGQUIT performs an immediate shutdown with no service rollback. Like, no cleanup, just yeet. 💀

When run as a user instance or system service manager (but not system manager):

  • SIGINT and SIGTERM both stop services and exit Dinit.
  • SIGQUIT exits Dinit immediately.

Regardless of operation mode, SIGUSR1 will open the control socket, if it isn't open yet, or if it has been deleted from the file system. Little signal that could. 🧚

💖 SEE ALSO 💖

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

🌟 AUTHOR 🌟

Dinit, and this manual, were written by Davin McCall. Thank you for your service, king. 👑

And that's the whole page, bestie — Dinit 0.21.0, dated March 2026, page DINIT(8) in the manuals. Go forth and manage your services, you absolute icon. 🎀✨

📦 where this page comes from