Dinit ----- v0.03 (pre-release) What is it? =-=-=-=-=-= "Dinit" is a service supervisor with dependency support which can also act as the system "init" program. Specifically it can launch multiple services (generally, "daemon" processes, but see notes below) in parallel, with dependency management (i.e. if one service's operation depends on another, the latter service will be started first). For "process" services Dinit can monitor the process corresponding to the service, and re-start it if it dies. It does this in an intelligent way, first "rolling back" all dependent services, and restarting them when their dependencies are satisfied. Dinit includes a tool ("dinitctl") to issue commands to the main Dinit process, and a "shutdown" program (with scripts "halt" and "reboot") to manage shutting down and restarting the system. Dinit is designed to work on POSIXy operating systems such as Linux and OpenBSD. It is written in C++ and uses the "Dasynq" event handling library, which was written especially to support Dinit. Development goals include clean design, robustness, portability, and avoiding feature bloat (whilst still handling a variety of use cases). See doc/COMPARISON for a comparison of Dinit with similar software packages. Dinit is licensed under the Apache License, version 2.0. A copy of this license can be found in the LICENSE file. Dinit was written by Davin McCall . See BUILD for information on how to build Dinit. Introduction to services =-=-=-=-=-=-=-=-=-=-=-=- A "service" is nominally a persistent process or system state. The two main types of service are a _process_ service (represented by a an actual process) and a _scripted_ service (which is started and stopped by running a process - often a shell script - to completion). There are also _bgprocess_ services and _internal_services. Many programs that you might want to run under dinit's supervision can run either "in the foreground" or as a daemon ("in the background"), and the choice is dictated by a command line switch (for instance the -D and -F switches to Samba's "smbd"). Although it might seem counterintuitive, the "foreground" mode should be used for programs registered as process services in dinit; this allows dinit to monitor the process. Process services are attractive due to the ease of monitoring (and restarting) the service, however, they have one inherent problem, which is that dinit cannot tell when the service is truly started. Once the process has been launched, dinit assumes that the service has started, but in fact there will be a short delay before the process sets itself up, starts listening on sockets, etc; during this time any other process (including one from a service listed as dependent) which tries to contact it will not be able to do so. In practice, this is not usually a problem (and external solutions, like D-Bus, do exist). 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 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. (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 should not be possible for unauthorised users to modify the file contents!) An _internal_ service is just a placeholder service that can be used to describe a set of dependencies. An internal service has no corresponding process. Service Hiearchy and states =-=-=-=-=-=-=-=-=-=-=-=-=-= Services can depend on other services for operation, and so form a dependency hierarchy. Starting a service which depends on another causes that other service to start (and the first service waits until the latter has started before its process is launched and it is itself considered started). Services are considered _active_ when they are not stopped. Services can also be explicitly marked as active (this normally happens when you explicitly start a service). Finally, a service with an active dependent is also considered active. If a service stops and becomes inactive (i.e. it is not explicitly marked active and has no active dependents) then any services it depends on will also be marked inactive and stopped unless they have other active dependents, or were explicitly started and marked active. What this means is that, in general, starting an (inactive, stopped) service and then stopping it will return the system to its prior state - no dependencies which were started automatically will be left running. Service Description files =-=-=-=-=-=-=-=-=-=-=-=-= 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. 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. Parameter values are interpreted literally, except that: - whitespace is collapsed to a single space - double quotes can be used around all or part(s) of a parameter to prevent whitespace collapse and interpretation of special characters - backslash can be used to 'escape' the next character, preventing any special meaning from being associated with it. It can be used to include non-collapsing whitespace, double-quote marks, and backslashes in the parameter value. Parameters are: type = process | bgprocess | scripted | internal command = ... logfile = ... onstart = ... depends-on = (service name) waits-for = (service name) command = (external script or executable, and arguments) For a 'process' service, this is the process to run. For a 'scripted' service, this command is run to start the service. stop-command = (external script or executable, and arguments) For a 'scripted' service, this command is run to stop the service. 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). Only active services will restart automatically. smooth-recovery = yes | true | no | false For process services only. Specifies that, should the process die, it can be restarted without bringing the service itself down. This means that any dependent services do not need to be stopped/restarted. Such recovery happens regardless of the "restart" setting (if smooth-recovery is enabled, 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. depends-on = (service name) This service depends on the named service. Starting this service will start the named service; the command to start this service will not be executed until the named service has started. If the named service is stopped then this service will also be stopped. 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. 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.