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
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 ) ...
- This is a newer way of specifying some of the above options
- (runs-on-console, nosigterm, onstart = rw_ready) and an additional option
- for specifying that this service is the system logging service, which
- Dinit can log to once the service has started.
+ 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