DINITCTL(8) man page

dinitctl(8) - control services supervised by Dinit

Dinit 0.16.0pre, June 2022

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] 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] setenv [name[=value] ...]

Description

dinitctl is a utility to control services being managed by the dinit daemon. It allows starting and stopping services, and listing service status, amongst other actions. It functions by issuing commands to the daemon via a control socket.

General Options

• --help
  Display brief help text and then exit.
• --version
  Display version and then exit.
• -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 (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 (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 not specified, the DINIT_SOCKET_PATH environment variable is read, otherwise Dinit's default values are used.
• --quiet
  Suppress status output, except for errors.

Command Options

• --no-wait
  Do not wait for issued command to complete; exit immediately.
• --pin
  Pin the service in the requested state. The service will not leave the 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.

Note that a pin takes effect while the service is starting/stopping, before it reaches the target state. For example, issuing a stop command to a service which is starting and which is pinned started will have no effect other than removing explicit activation.

• --force
  Stop the service even if it will require stopping other services which depend on the specified service.
• --ignore-unstarted
  If the service is not started or doesn't exist, ignore the command and return an exit code indicating success.
• service-name
  Specifies the name of the service to which the command applies.
• 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.
• stop
  Stop the specified service, and remove explicit activation. If the service has (non-soft) dependents, an error will be displayed unless the --force option is used.

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

• 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).
• restart
  Restart the specified service. The service will be stopped and then restarted, without affecting explicit activation status or dependency links from dependents.
• wake
  Start the specified service after reattaching dependency links from all active dependents of the specified service. The service will not be marked explicitly activated, and so will stop if all the dependents stop.
• release
  Clear the explicit activation mark from a service (the service will then stop if it has no active dependents).
• 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.
• 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).
• 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.

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.

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

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.

• shutdown
  Stop all services (without restart) and terminate Dinit. If issued to the system instance of Dinit, this will also shut down the system.
• add-dep
  Add a dependency between two services. The dependency-type must be one of regular, milestone or waits-for. Note that adding a regular 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.
• rm-dep
  Remove a dependency between two services. The dependency-type must be one of regular, milestone or waits-for. If the "to" service is not otherwise active it may be stopped as a result of removing the dependency.
• 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.

If the --from option is not used to specify the dependent, the dependency is created from the boot service by default.

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

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.

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

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.

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.

Stopping a service manually will prevent it (and its dependents) from automatically restarting.

See Also

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

Author

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