Dinit
-----
-v0.03 (pre-release)
+v0.1.0 (pre-release)
What is it?
A _scripted_ service has separate commands for startup and (optional)
shutdown. Scripted services can be used for tasks such as mounting file
-systems that don't need a persisten process, and in some cases can be used
+systems that don't need a persistent process, and in some cases can be used
for daemon processes (although Dinit will not be able to supervise a
process that is registered as a scripted service).
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), or can otherwise mark
+itself as a subreaper (which is possible on Linux, FreeBSD and DragonFlyBSD) -
+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
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 = ...
+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).
+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.
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.
-
options = ( runs-on-console | nosigterm | starts-rwfs | starts-log ) ...
Specifies various options for this service:
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.
+
+ 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