DINITCTL(8)

📦
version 0.21.0 · 3 versions
, in alpine 3.24

🎀 DINITCTL(8) 🎀

okay bestie, buckle up — this is dinitctl from the Dinit - service management system corner of the manual, and it's genuinely the remote control for your whole service situation. section 8, iykyk 💅

✨ NAME ✨

dinitctl — literally the tool that controls services supervised by Dinit. that's the whole vibe. 🫶

🌸 SYNOPSIS 🌸

dinitctl [options] start [--no-wait] [--pin] service-name
dinitctl [options] stop [--no-wait] [--pin] [--ignore-unstarted]
       service-name
dinitctl [options] status service-name
dinitctl [options] is-started service-name
dinitctl [options] is-failed service-name
dinitctl [options] restart [--no-wait] [--ignore-unstarted] service-name

dinitctl [options] wake [--no-wait] service-name
dinitctl [options] release [--ignore-unstarted] service-name
dinitctl [options] unpin service-name
dinitctl [options] unload service-name
dinitctl [options] reload service-name
dinitctl [options] list
dinitctl [options] shutdown
dinitctl [options] add-dep dependency-type from-service to-service
dinitctl [options] rm-dep dependency-type from-service to-service
dinitctl [options] enable [--from from-service] to-service
dinitctl [options] disable [--from from-service] to-service
dinitctl [options] trigger service-name
dinitctl [options] untrigger service-name
dinitctl [options] setenv [name[=value] ...]
dinitctl [options] unsetenv [name ...]
dinitctl [options] catlog [--clear] service-name
dinitctl [options] signal { signal-id service-name | --list | -l }

like, that's a lot of subcommands, and no, we are not skipping any of them. 🙈

🦋 DESCRIPTION 🦋

so dinitctl is the utility you use to control services that are being managed by the dinit daemon. it's giving "mission control but make it services" ✨ — you can start stuff, stop stuff, list out service status, and a whole bunch of other actions on top.

the way it works: it functions by issuing commands to the daemon via a control socket. that's the whole magic trick. 🪄

💜 GENERAL OPTIONS 💜

  • --help — display brief help text and then exit. cute, quick, done. 💅
  • --version — display version and then exit. hi, what version are we on, bestie.
  • -s, --system — control the system init process (this is the default when run as root). this option determines the default path to the control socket used to communicate with the dinit daemon process — and heads up, it does not override the -p option. 👑
  • -u, --user — control the user init process (this is the default when not run as root). this option determines the default path to the control socket used to communicate with the dinit daemon process — and again, it does not override the -p option. 🫶
  • --socket-path socket-path, -p socket-path — specify the path to the socket used for communicating with the service manager daemon. when it's not specified, the value from the DINIT_SOCKET_PATH environment variable is used, and if that variable is unset, the default path gets used (as documented for dinit(8)). 🔌
  • --use-passed-cfd — instead of attempting to open a socket connection to the service daemon, use a pre-opened connection that has been passed to the dinitctl process from its parent via an open file descriptor. the file descriptor holding that connection is identified by the contents of the DINIT_CS_FD environment variable. very "i already have the connection, thanks" energy. ✨
  • --quiet — suppress status output, except for errors. no chatter, just the important stuff. 🤫
  • --offline, -o — work "offline", without communicating with the dinit daemon. this is applicable only for the enable and disable subcommands, so don't try to make it a whole personality. 🙈
  • --services-dir dir, -d dir — specifies dir as the directory containing service description files (can be given multiple times to specify multiple service directories). when this option is provided, default directories are not searched for services. and this option is ignored when --offline (-o) is not also specified — because otherwise, dinitctl can just query the dinit daemon for the service description directories. 📁

🎀 COMMAND OPTIONS 🎀

  • --no-wait — do not wait for the issued command to complete; exit immediately. hit it and quit it. 💨
  • --pin — pin the service in the requested state. the service will not leave that state until it is unpinned. 📌

a service that is pinned stopped cannot be marked active — that is, start commands issued to the service have no effect. dependents (via hard dependency relationships) of the pinned service will be unable to start. 😭

a service that is pinned started cannot be stopped, however its explicit activation can be removed (eg via the stop or release commands). once unpinned, a service which is not explicitly activated, and which has no active dependents, will automatically stop. if a pinned-started service fails to start, the pin is removed. 🫠

ngl, pay attention here: a pin takes effect while the service is starting/stopping, before it reaches the target state. stopping or restarting a service that is pinned started and which is already starting or started is not possible. similarly, starting a service which is pinned stopped and which is stopping or stopped is not possible. that's not a bug, that's just the rules. 💀
  • --force — stop the service even if it will require stopping other services which depend on the specified service. when applied to the restart command, this will cause the dependent services to also be restarted. it's giving "take everyone down with you" 😤
  • --ignore-unstarted — if the service is not started or doesn't exist, ignore the command and return an exit code indicating success. fake it till you make it, exit-code-wise. ✨
  • --clear — clear the log buffer for the service after displaying it. 🧹
  • service-name — specifies the name of the service to which the command applies. it may have an argument that is passed to the service. 🏷️

⭐ more parts coming, bestie — don't go anywhere 💖

💅 COMMAND DESCRIPTIONS 💅

okay bestie, this is the part where we actually do things with dinitctl, and honestly it’s giving main character energy. Each command below is a whole little vibe, but the facts are all here — no cap. 🫶

start ✨

Start the specified service. The service is marked as explicitly activated and will not be stopped automatically if its dependents stop. If the service is currently stopping, it will generally continue to stop before it is then restarted. slay. 💅

stop 🛑

Stop the specified service, and remove explicit activation. If the service has (non-soft) dependents, an error will be displayed and no further action taken, unless the --force option is used. If the service is pinned started (and not already stopped or stopping), an error will be displayed and no further action taken. bestie, read that twice. 😭

The restart option (see dinit-service(5)) applied to the stopped service will not cause the service to restart when it is stopped via this command (that is, this command inhibits automatic restart). This also applies to any dependents that must also be stopped at the same time.

Any pending start orders (including for restarts) are cancelled, though a service which is starting will continue its startup before then stopping (unless the service is configured to have an interruptible startup or is otherwise at a stage of startup which can be safely interrupted). okay so it’s not a magic instant cancel, got it. ✨

status 👑

Give a status report on the specified service. This will show the current state (and target state, if different), and information such as process ID (pid) if applicable. If the service is stopped for any reason other than a normal stop, the reason for the service stopping will be displayed (along with any further relevant information, if available). it’s literally the service’s little check-in post. 💖

is-started 🌸

Check if the specified service is currently started. Any other state (including if the service is currently starting or stopping) will exit without returning success. Unless --quiet is specified, the current service status (STOPPED, STARTING, STARTED, STOPPING) will be printed to standard output. yes, it will absolutely tell you the state, bestie. 🦋

is-failed 💀

Check if the specified service is currently failed. The service counts as failed if it is known it is currently stopped either because of startup failure, timeout or dependency failure. Any other state, including protocol and parse errors, will exit without returning success. Unless --quiet is specified, the current service status (STOPPED, STARTING, STARTED, STOPPING) will be printed to standard output. not me checking if the service is okay 😭

restart 🔥

Restart the specified service. The service will be stopped and then restarted, without affecting explicit activation status. periodt. 💅

wake 🌈

Start the specified service. The service will not be marked explicitly activated, and so will stop if all the dependents stop. it’s a soft launch, not a permanent commitment. 🫶

release 🎀

Clear the explicit activation mark from a service (the service will then stop if it has no active dependents). so it can finally chill if nobody needs it. ✨

unpin 🧚

Remove start- and stop- pins from a service. If a started service is not explicitly activated and has no active dependents, it will stop. If a started service has a dependency service which is stopping, it will stop. If a stopped service has a dependent service which is starting, it will start. Otherwise, any pending start/stop commands will be carried out. the pins are gone, the drama continues. 💜

unload 🍓

Completely unload a service. This can only be done if the service is stopped and has no loaded dependents (i.e. dependents must be unloaded before their dependencies). sorry bestie, no abandoning your dependents — unload them first. 😭

reload 🌸

Attempt to reload a service description. This is intended as a convenience for making simple changes to a service, without having to stop, remove dependencies to and unload the service. However it is not completely equivalent to doing a proper unload/reload; some altered settings may not take effect until the service is restarted, and some cannot be changed at all while the service is running. it’s giving “quick refresh,” not “full factory reset.” 💅

In particular, the type of a running service cannot be changed; nor can the inittab-id, inittab-line, or pid-file settings, or the runs-on-console or shares-console flags. If any hard dependencies are added to a running service, the dependencies must already be started. no cap, those are the rules. 🫶

list 👑

List loaded services and their state. Before each service, one of the following state indicators is displayed:

  • [{+} ] — service has started.
  • [{ }<< ] — service is starting.
  • [ <<{ }] — service is starting, will stop once started.
  • [{ }>> ] — service is stopping, will start once stopped.
  • [ >>{ }] — service is stopping.
  • [ {-}] — service has stopped.

The << and >> symbols represent a transition state (starting and stopping respectively); curly braces indicate the target state (left: started, right: stopped); square brackets are used if the service is marked active (target state will always be started if this is the case). iykyk. 👑

An s in place of + means that the service startup was skipped (possible only if the service is configured as skippable). An X in place of - means that the service failed to start, or that the service process unexpectedly terminated with an error status or signal while running. 💀

Additional information, if available, will be printed after the service name: whether the service owns, or is waiting to acquire, the console; the process ID; the exit status or signal that caused termination. the tea is fully spilled. ☕✨

shutdown 🌙

Stop all services (without restart) and terminate Dinit. If issued to the system instance of Dinit, this will also shut down the system. okay so this is the big “everybody out” button. 🫶

add-dep 🔗

Add a dependency between two services. The dependency-type must be one of need, milestone or waits-for. Note that adding a need dependency requires that the service states are consistent with the dependency (i.e. if the "from" service is started, the "to" service must also be started). Circular dependency chains may not be created. bestie, do not make a dependency ouroboros. 😭

The dependency-type regular is also supported, as a deprecated alias of need. it’s giving legacy but still valid. 💅

rm-dep ✂️

Remove a dependency between two services. The dependency-type must be one of need, milestone or waits-for. If the "to" service is not otherwise active it may be stopped as a result of removing the dependency. so yeah, removing the link can absolutely change the vibe. 🦋

enable 🌟

Persistently enable a waits-for dependency between two services. This is much like add-dep but it also starts the dependency if the dependent is started (without explicit activation, so the dependency will stop if the dependent stops), and it creates a symbolic link in the directory specified via the waits-for.d directive in the service description (there must be only one such directive) so that the dependency will survive between sessions. it’s literally making the dependency official. 🎀

If the --from option is not used to specify the dependent, the dependency is created from the service specified by any @meta enable-via directive in the service description, or from the boot service by default. no --from? it’s got a fallback plan. 💖

disable 🚫

Permanently disable a waits-for dependency between two services. This is the complement of the enable command; see the description above for more information. the opposite of enable, obviously. 💅

Note that the disable command affects only the dependency specified (or implied). It has no other effect, and a service that is "disabled" may still be started if it is a dependency of another started service. so “disabled” is not the same as “cannot ever start,” bestie. 😭

trigger 🎯

Mark the specified service (which must be a triggered service) as having its external trigger set. This will allow the service to finish starting. go off, trigger. 🔥

untrigger 🙈

Clear the trigger for the specified service (which must be a triggered service). This will delay the service from starting, until the trigger is set. If the service has already started, this will have no immediate effect. so if it’s already up, this is just a vibe update, not an instant stop. ✨

setenv 🌈

Export one or more variables into the activation environment. The value can be provided on the command line or retrieved from the environment dinitctl is called in. Any subsequently started or restarted service will have these environment variables available. This is particularly useful for user services that need access to session information. literally handing the service the session tea. ☕💅

unsetenv 🧹

Unset one or more variables in the activation environment. Any subsequently started or restarted service will have these environment variables unset. clean sweep, no leftover env vibes. 🫶

catlog 📜

Show the contents of the log buffer for the named service. This is possible only if the log type of the service is set to buffer. If the log is truncated or appears incomplete, a warning message follows the output. If the --clear option is specified, the buffer is cleared after displaying its contents. it’s giving “show me the receipts, then delete them.” 😭✨

signal ⚡

Send a signal to the process associated with the specified service. The signal-id can either be specified as an integer or signal name (standard POSIX name minus the SIG- prefix; a limited selection of signal names are recognised, including TERM, HUP, and KILL). The --list (-l) option can be used (without signal-id and service-name) to list the full set of supported signal names. signal delivery, but make it fashion. 💅🔥

🧚 SERVICE OPERATION 🧚

Normally, services are only started if they have been explicitly activated (start command) or if a started service depends on them. Therefore, starting a service also starts all services that the first depends on; stopping the same service then also stops the dependency services, unless they are also required by another explicitly activated service or have been explicitly activated themselves. it’s a whole ecosystem, bestie. 🌸

A service can be pinned in either the started or stopped state. This is mainly intended to be used to prevent automated stop or start of a service, including via a dependency or dependent service, during a manual administrative procedure. think of pins as little “do not disturb” signs. 🎀

Stopping a service manually will prevent it (and its dependents) from automatically restarting (i.e. it will override the restart setting in the service configuration). so yeah, manual stop says “not today” to auto-restart. 💅

🌈 ENVIRONMENT VARIABLES 🌈

The following environment variables may control dinitctl's operation:

DINIT_SOCKET_PATH 💖

The path to the socket used to communicate with the dinit(8) daemon. May be overridden by certain command line options. If not set, and not overridden, the dinit defaults are used. that’s the socket tea, no cap. 🫶

🎀 SEE ALSO 🎀

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

✨ AUTHOR ✨

Okay so real talk: Dinit — the whole thing, the daemon, the vibe, all of it — and this very manual page too, were written by Davin McCall. 🫶

That's it. That's the whole credit. One person, one absolutely iconic contribution to the Unix ecosystem, no cap 👑✨

🎀 and that's a wrap bestie!! if you made it all the way here you're literally a dinitctl main character now 💅

This page is for Dinit version 0.21.0, dated March 2026 — so if you're reading this in some wildly different timeline, do a little vibe check on your version first 🙈🌸

Now go forth, manage your services, and slay 💖✨🦋

📦 where this page comes from