# Dinit
-v0.3.0 (pre-release)
+v0.5.2 (pre-release)
This is the README for Dinit, the service manager and init system. It is
intended to provide an overview; For full documentation please check the manual pages.
+The impatient may wish to check out the [getting started guide](doc/getting_started.md).
## Contents
2. [Configuring services](#configuring-services)
1. [Service types](#service-types)
2. [Service description files](#service-description-files)
-3. [Controlling services](#controlling-services)
+3. [Running Dinit](#running-dinit)
+4. [Controlling services](#controlling-services)
1. [Service hierarchy and states](#service-hierarchy-and-states)
2. [Using dinitctl](#using-dinitctl)
service, and re-start it if it dies, and it can do this in an intelligent way,
first "rolling back" all dependent services, and restarting them when their
dependencies are satisfied. However, the precise nature of dependency
-relations between services is highly configurable.
+relations between services is highly configurable. The "dinitctl" tool can
+be used to start or stop services and check their state (by issuing commands
+to the "dinit" daemon).
-Dinit includes "dinitctl", a tool to issue commands to the main Dinit
-process in order to start or stop services and check their state, as well as
-a "shutdown" program (with scripts "halt" and "reboot") to manage shutting
-down and restarting the system.
+Dinit is designed to run as either as a system service manager (runs as root,
+uses system paths for configuration etc) or a user process (runs as a user,
+uses paths in the user's home directory by default).
Dinit is designed to work on POSIXy operating systems such as Linux and
OpenBSD. It is written in C++ and uses the [Dasynq](http://davmac.org/projects/dasynq/)
-event handling library, which was written especially to support Dinit.
+event handling library, which was written especially to support Dinit. (Note
+that a copy of Dasynq is bundled with Dinit, so a separate copy is not
+required for compilation; however, the bundled copy does not include the
+documentation or test suite).
Development goals include clean design, robustness, portability, and
avoiding feature bloat (whilst still handling a variety of use cases).
Dinit was written by Davin McCall <davmac@davmac.org>.
-See BUILD for information on how to build Dinit.
+See BUILD.txt for information on how to build Dinit.
## Configuring services
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
+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.
+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
+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
Dinit discovers services by reading _service description files_. These files
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.
+"/usr/local/lib/dinit.d" and "/lib/dinit.d" also searched; the default user
+location is "$HOME/dinit.d") and the name of a service description file
+matches the name of the service they configure. Service descriptions are
+loaded lazily, as needed by Dinit.
+
+(An example of a complete set of system service descriptions can be found in
+the [doc/linux/services](doc/linux/services) directory).
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
Please see the manual page for a full list of service parameters and options.
+## Running Dinit
+
+Dinit can run as the system "init" - the first process started by the kernel
+on boot - which is normally done by linking or copying it to `/sbin/init`.
+This is currently supported only on Linux. It requires having suitable service
+descriptions in place and should be attempted only by those comfortable
+with low-level system administration and recovery. See doc/linux directory for
+more information.
+
+Dinit can also run as a normal process, and can be started in this case by a
+regular user.
+
+By default, regardless of whether it runs as a system or user process, Dinit
+will look for and start the service named "boot". This service should be
+configured with dependencies which will cause any other desired services to
+start. You can specify alternative services to start via the `dinit` command
+line (consult the man page for more information).
## Controlling services
### Using dinitctl
-You can use the "dinitctl" to start and stop services. Typical invocations
+You can use the "dinitctl" utility 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
+Note that a "start" marks 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
+command by default acts as a "release" that 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
+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
projects / oweals / dinit.git / blobdiff