Dinit
-----
-v0.1 (pre-release)
+v0.05 (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 "libev" event handling library.
+OpenBSD. It is written in C++ and uses the "Dasynq" event handling library,
+which was written especially to support Dinit.
+
Development goals include clean design, robustness, portability, and
avoiding feature bloat (whilst still handling a variety of use cases).
Dinit was written by Davin McCall <davmac@davmac.org>.
+See BUILD for information on how to build Dinit.
+
Introduction to services
=-=-=-=-=-=-=-=-=-=-=-=-
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
If a service stops and becomes inactive (i.e. it is not explicitly marked
active and has no active dependents) then any services it depends on will
also be marked inactive and stopped unless they have other active
-dependents (or are explicitly active).
+dependents, or were explicitly started and marked active.
What this means is that, in general, starting an (inactive, stopped)
service and then stopping it will return the system to its prior state -
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
type = process | bgprocess | scripted | internal
command = ...
logfile = ...
-onstart = ...
+options = ...
depends-on = (service name)
waits-for = (service name)
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.
+restart-delay = XXX.YYYY
+ Specifies the minimum time in seconds between automatic restarts. The
+ default is 0.2 (i.e. 200ms). This prevents Dinit from consuming processor
+ cycles when a process continuously fails immediately after it starts.
+
+restart-limit-interval = XXX.YYYY
+ Specifies the interval, in seconds, over which restarts are limited. If a
+ process automatically restarts more than a certain number of times (default
+ 3) in this time interval, it will not restart again. The default value is
+ 10 seconds. Use this to prevent broken services from continuously
+ restarting ad infinitum.
+
+restart-limit-count = NNN
+ Specifies the maximum number of times that a service can automatically
+ restart over the interval specified by restart-limit-interval (default of
+ 10 seconds). Specify a value of 0 to disable the restart limit.
+
+stop-timeout = XXX.YYYY
+ Specifies the time in seconds allowed for the service to stop. If the
+ service takes longer than this, its process group is sent a SIGKILL signal
+ which should cause it to terminate immediately. The timeout period begins
+ only when all dependent services have already stopped. The default stop
+ timeout is 10 seconds.
+
+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
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.
+
+logfile = (log file path)
+ Specifies the log file for the service. Output from the service process
+ will go this file.
+
+
+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
+
+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