Dinit
-----
-v0.03 (pre-release)
+v0.05 (pre-release)
What is it?
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) - otherwise Dinit will
-not know when the process has terminated.
+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
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
the service does not reach the stopped state when the process terminates
unexpectedly).
+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.
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). For scripted services
- "runs-on-console" applies only during execution of the start
- script.
+ 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. This is
- useful to allow filesystem checks to be interrupted/skipped.
+ 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).
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.