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
logfile = ...
options = ...
depends-on = (service name)
+depends-ms = (service name)
waits-for = (service name)
command = (external script or executable, and arguments)
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.
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
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).
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