dinitctl - control services supervised by Dinit
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] catlog [--clear]
service-name
dinitctl [options] signal {
signal-id service-name | --list | -l }
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.
- --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 value from the
DINIT_SOCKET_PATH environment variable is used, with the default
path (as documented for dinit(8)) used if the variable is
unset.
- --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 with the
connection is identified by the contents of the DINIT_CS_FD environment
variable.
- --quiet
- Suppress status output, except for errors.
- --offline,
-o
- Work "offline", without communicating with the dinit
daemon. This is applicable only for the enable and disable
subcommands.
- --services-dir
dir, -d dir
- Specifies dir as the directory containing service description files
(can be given multiple times to specify multiple service directories).
Default directories are not searched for services when this option is
provided. This option is ignored when --offline (-o) is not
also specified (otherwise, dinitctl can query the dinit
daemon for the service description directories).
- --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. 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.
- --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.
- --ignore-unstarted
- If the service is not started or doesn't exist, ignore the command and
return an exit code indicating success.
- --clear
- Clear the log buffer for the service after displaying it.
- 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 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.
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).
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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 (i.e. it will override the restart
setting in the service configuration).
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.
dinit(8), dinit-service(5), shutdown(8).
Dinit, and this manual, were written by Davin McCall.