Dinit
-----
-v0.05 (pre-release)
+v0.1.1 (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).
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. 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.
+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
=-=-=-=-=-=-=-=-=-=-=-=-=
Dinit discovers services by reading _service description files_. These files
-reside in a directory (/etc/dinit.d is the default "system" location) and
-their name matches the name of the service. Service descriptions are loaded
-lazily, as needed by Dinit.
+reside in a directory (/etc/dinit.d is the default "system" location, with
+"/usr/local/lib/dinit.d" and "/lib/dinit.d" also searched) and their name
+matches the name of the service. Service descriptions are loaded lazily, as
+needed by Dinit.
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
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)
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).
-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.
+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
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:
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.
-logfile = (log file path)
- Specifies the log file for the service. Output from the service process
- will go this file.
+Please see the manual page for a full list of service parameters and options.
Controlling services
(mysql). Services transitioning state (starting or stopping) are displayed
with an arrow indicating the transition direction:
- [ <<{-}] mysql # starting
- [{+}>> ] mysql # stopping
+ [{ }<< ] 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.