Dinit
-----
-v0.02 (pre-release)
+v0.08 (pre-release)
What is it?
service's operation depends on another, the latter service will be started
first).
-For "process" services dinit can monitor the process corresponding to the
+For "process" services Dinit can monitor the process corresponding to the
service, and re-start it if it dies. It does this in an intelligent way,
-first "rolling back" all dependent services (which it will later re-start,
-if configured to do so).
+first "rolling back" all dependent services, and restarting them when their
+dependencies are satisfied.
+
+Dinit includes a tool ("dinitctl") to issue commands to the main Dinit
+process, and a "shutdown" program (with scripts "halt" and "reboot") to
+manage shutting down and restarting the system.
Dinit is designed to work on POSIXy operating systems such as Linux and
OpenBSD. It is written in C++ and uses the "Dasynq" event handling library,
A _bgprocess_ service is a mix between a process service and a scripted
service. A command is used to start the service, and once started, the
process ID is expected to be available in a file which Dinit can then
-read. Many existing daemons can operate in this way. Dinit can only
-supervise the process if it runs as the system "init" (PID 1),
+read. Many existing daemons can operate in this way. The process can only be
+supervised if Dinit runs as the system "init" (PID 1) - otherwise Dinit can
+not reliably know when the process has terminated.
+
+(Note, use of bgprocess services type requires care. The file from which the
+PID is read is trusted; Dinit may send signals to the specified PID. It
+should not be possible for unauthorised users to modify the file contents!)
An _internal_ service is just a placeholder service that can be used to
describe a set of dependencies. An internal service has no corresponding
A service description file consists of a number of parameter settings.
Settings in the SDF are denoted as a parameter name followed by either an
equal sign or colon and then the parameter value (all on the same line).
-Comments begin with a hash mark (#) and extend to the end of the line.
+Comments begin with a hash mark (#) and extend to the end of the line (they
+must be separated from setting values by at least one whitespace character).
Parameter values are interpreted literally, except that:
- whitespace is collapsed to a single space
non-collapsing whitespace, double-quote marks, and backslashes in the
parameter value.
-Parameters are:
+Some available parameters are:
type = process | bgprocess | scripted | internal
command = ...
+stop-command = ...
+run-as = (user-id)
+restart = (boolean)
+smooth-recovery = (boolean)
logfile = ...
-onstart = ...
+pid-file = ...
+options = ...
depends-on = (service name)
+depends-ms = (service name)
waits-for = (service name)
command = (external script or executable, and arguments)
stop-command = (external script or executable, and arguments)
For a 'scripted' service, this command is run to stop the service.
+run-as = (user-id)
+ Specifies which user to run the process(es) for this service as. The group
+ id for the process will also be set to the primary group of the specified
+ user.
+
restart = yes | true | no | false
Specifies whether the service should automatically restart if it becomes
stopped (for any reason, including being explicitly requested to stop).
the service does not reach the stopped state when the process terminates
unexpectedly).
-onstart = (internal commands)
- rw_ready - try again to open any logs, control socket etc that could not
- be opened previously due to a read-only filesystem.
+logfile = (log file path)
+ Specifies the log file for the service. Output from the service process
+ will go this file.
+
+pid-file = (path to file)
+ For "bgprocess" type services only; specifies the path of the file where
+ daemon will write its process ID before detaching.
depends-on = (service name)
This service depends on the named service. Starting this service will
executed until the named service has started. If the named service is
stopped then this service will also be stopped.
+depends-ms = (service name)
+ Indicates a "milestone dependency" on the named service. This service
+ requires the named service to start before it starts itself. Once the
+ named service has started, it remains active due to the dependency, but if
+ it stops for any reason then the dependency link is broken until the next
+ time this service is started.
+
waits-for = (service name)
When this service is started, wait for the named service to finish
starting (or to fail starting) before commencing the start procedure
for this service. Starting this service will automatically start
the named service.
-socket-listen = (socket path)
- Pre-open a socket for the service and pass it to the service using the
- Systemd activation protocol. This by itself does not give so called
- "socket activation", but does allow that any process trying to connect
- to the specified socket will be able to do so, even before the service
- is properly prepared to accept connections.
-
-socket-permissions = (octal permissions mask)
- Gives the permissions for the socket specified using socket-listen.
- Normally this will be 600 (user access only), 660 (user and group
- access), or 666 (all users).
-
-socket-uid = (numeric user id or username)
- Specifies the user that should own the activation socket. If socket-uid
- is specified without also specifying socket-gid, then the socket group
- is the primary group of the specified user (as found in the system user
- database, normally /etc/passwd). If the socket owner is not specified,
- the socket will be owned by the user id of the Dinit process.
-
-socket-gid = (numeric group id or group name)
- Specifies the group of the activation socket. See discussion of
- socket-uid.
-
-termsignal = HUP | INT | QUIT | USR1 | USR2
- Specifies an additional signal to send to the process when requesting it
- to terminate (applies to 'process' services only). SIGTERM is always
- sent along with the specified signal, unless the 'nosigterm' setting is
- set true.
-
-nosigterm = yes | true | no | false
- If true, the TERM signal will not be sent to the process to kill it. (If
- an alternate signal is specified using the "termsignal" setting, that
- signal will be sent instead; otherwise, no signal will be sent, and the
- process must be killed by external means).
-
-runs-on-console = yes | no | true | false
- If true, the service runs on the console; its input and output are
- directed to the console (actually, to the terminal on which Dinit is
- running) and Dinit's own output will be suppressed during this time.
- Control signals (^C) may be used to control a service running on the
- console.
-
- This is useful to allow a "login" master service to prevent Dinit output
- once terminal sessions are spawned, or to make fsck display its progress
- on the terminal (and be interruptible).
-
- Only one service can run on the console at a time (services will queue
- in order to gain access to the console).
-
- For scripted services, only the start command runs on the console.
- Process services and internal services take the console for the entire
- time that they are active (and cannot release it).
+options = ( runs-on-console | nosigterm | starts-rwfs | starts-log ) ...
+ Specifies various options for this service:
+
+ no-sigterm : specifies that the TERM signal should not be send to the
+ process to terminate it. (Another signal can be specified using
+ the "termsignal" setting; if no other signal is specified, NO
+ signal will be sent).
+
+ runs-on-console : specifies that this service uses the console; its input
+ and output should be directed to the console. A service running
+ on the console prevents other services from running on the
+ console (they will queue for the console).
+
+ The "interrupt" key (normally control-C) will be active for
+ process / scripted services that run on the console. Handling
+ of an interrupt is determined by the service process, but
+ typically will cause it to terminate.
+
+ starts-on-console : specifies that this service uses the console during
+ service startup. This is implied by runs-on-console, but can
+ be specified separately for services that need the console
+ while they start but not afterwards.
+
+ This setting is not applicable to regular "process" services,
+ but can be used for "scripted" and "bgprocess" services. It
+ allows for interrupting startup via the "interrupt" key
+ (normally control-C). This is useful to allow filesystem checks
+ to be interrupted/skipped.
+
+ starts-rwfs : this service mounts the root filesystem read/write (or at
+ least mounts the normal writable filesystems for the system).
+ This prompts Dinit to create its control socket, if it has not
+ already managed to do so.
+
+ starts-log : this service starts the system log daemon. Dinit will begin
+ logging via the /dev/log socket.
+
+ pass-cs-fd : pass an open Dinit control socket to the process when launching
+ it (the DINIT_CS_FD environment variable will be set to the file
+ descriptor of the socket). This allows the service to issue
+ commands to Dinit even if the regular control socket is not
+ available yet.
+
+ Using this option has security implications! The service which
+ receives the control socket must close it before launching any
+ untrusted processes. You should not use this option unless the
+ service is designed to receive a Dinit control socket.
+
+ start-interruptible : this service can have its startup interrupted
+ (cancelled) if it becomes inactive while still starting.
+ The SIGINT signal will be sent to the signal to cancel its
+ startup. This is meaningful only for scripted and bgprocess
+ services.
+
+Please see the manual page for a full list of service parameters and options.
+
+
+Controlling services
+=-=-=-=-=-=-=-=-=-=-
+
+You can use the "dinitctl" to start and stop services. Typical invocations
+are:
+
+ dinitctl start <service-name>
+ dinitctl stop <service-name>
+ dinitctl release <service-name>
+
+Note that a "start" markes the service active, as well as starting it if it is
+not already started; the opposite of this is actually "release", which clears
+the active mark and stops it if it has no active dependent services. The "stop"
+command by default acts as a "release" which also forces the service to stop
+(although it may then immediately restart, depending on how it and its
+dependents are configured).
+
+Use the "-s" switch to talk the "system" instance of dinit, rather than a
+personal instance, e.g:
+
+ dinitctl -s start mysql # start system mysql service
+
+For complete details on the command line, use:
+
+ dinitctl --help
+
+You can "pin" a service in either the stopped or started state, which prevents
+it from changing state either due to a dependency/dependent or a direct
+command:
+
+ dinitctl -s start --pin mysql # start mysql service, pin it as "started"
+ dinitctl -s stop mysql # issues stop, but doesn't take effect due to pin
+ dinitctl -s unpin mysql # release pin; service will now stop
+
+You can pin a service in the stopped state in order to make sure it doesn't
+get started accidentally (either via a dependency or directly). You can also
+use it to temporarily keep stopped a service that would otherwise restart
+immediately when you stopped it (because it, or a dependent, is configured
+to restart automatically).
+
+Finally, you can list the state of all loaded services:
+
+ dinitctl -s list
+
+This may result in something like the following:
+
+ [{+} ] boot
+ [{+} ] tty1
+ [{+} ] tty2
+ [{+} ] tty3
+ [{+} ] tty4
+ [{+} ] loginready
+ [{+} ] rcboot
+ [{+} ] filesystems
+ [{+} ] udevd
+ [ {-}] mysql
+
+The above represents a number of started services and one stopped service
+(mysql). Services transitioning state (starting or stopping) are displayed
+with an arrow indicating the transition direction:
+
+ [{ }<< ] mysql # starting
+ [ >>{ }] mysql # stopping
+
+The curly brackets indicate the desired state, which may not be the state to
+which the service is currently transitioning. For example:
+
+ [ <<{ }] mysql # starting, but will stop after starting
+ [{ }>> ] mysql # stopping, but will restart once stopped
+Remember that a "starting" service may be waiting for its dependencies to
+start, and a "stopping" service may be waiting for its dependencies to stop.
projects / oweals / dinit.git / blobdiff