INIT(5)

NAME
init - system initialization configuration

SYNOPSIS
/etc/init/
/share/init/

DESCRIPTION
init(8) starts each daemon(7) (system background process) according to the daemon's configuration file, which specifies the daemon's dependencies and how to run the daemon.

Configuration files are searched for in the /etc/init/ directory (local initialization configuration owned by the system administrator, which may be modified) and the /share/init/ directory (default initialization configuration owned by the operating system, which should not be modified). The file name of each configuration file is that of the daemon without any file extension. For instance, the daemon exampled might come with the default configuration file /share/init/exampled that the system administrator can override in /etc/init/exampled.

init(8) initially starts the default daemon which is configured in /etc/init/default, which then depends on the daemons constituting the operating system (which in turn depend on the local daemon). The /etc/init/default file also defines default settings such as logging that are implicitly inherited by all other deamons, as well as init(8)'s own /var/log/init.log file.

Local system daemons should be started by overriding the local daemon in /etc/init/local, which then depends on the locally required daemons. System provided daemons can be customized by making /etc/init/exampled which starts with the furthermore statement to include the default /etc/share/exampled configuration and then change the desired properties.

DAEMONS
The default daemon should require exactly one top level daemon with exit-code and nothing else.

The following daemons are top level daemons that start the operating system. They are mutually exclusive and only a single one should be depended on:

multi-user
    Starts the operating system in the multi-user mode. It starts the login foreground daemon that provides a login screen and exits with login's exit code when login exits. This is a secure operating system mode where only authorized users have access. It depends on the base and local daemons.

no-user
    Starts the operating system in the no-user mode. This is a secure operating system mode where no user is granted access. Additional daemons can be started by configuring the local daemon. It depends on the base and local daemons. The dependency on local is marked exit-code, letting the system administrator fully control the default daemon's exit code and when the system completes.

single-user
    Starts the operating system in the single user mode. This foreground daemon starts the sh program that directly provides a root shell and exits with the shell's exit code when the shell exits. This operating system mode is insecure because it boots straight to root access without a password. It depends on the base and local daemons.

sysinstall
    Starts the operating system installer. This foreground daemon starts the sysinstall program that provides the operating system installer and exits with the installer's exit code when the installer exits. This operating system mode is insecure because it boots straight to root access without a password. It depends on the base and local daemons.

sysupgrade
    Starts the operating system upgrader. This foreground daemon starts the sysupgrade program that provides the operating system upgrader and exits with the upgrader's exit code when the upgrader exits. This operating system mode is insecure because it boots straight to root access without a password. It depends on the base and local daemons.

The following daemons are provided by the system:

base
    Virtual daemon that depends on the core operating system daemons. It depends on the network and time daemons.

dhclient
    Daemon that starts dhclient(8) on each network interface and becomes ready when each network interface has been attempted configured.

local
    Virtual daemon that starts daemons pertinent to the local system. The system provides a default implementation that does nothing. The system administrator is meant to override the daemon in /etc/init/local by depending on daemons outside of the base system that should run on the local system.

network
    Virtual daemon that becomes ready when an attempt has been made to establish network connectivity. It depends on the dhclient deamon. Daemons can depend on this daemon if they need the network to have been established before they start.

time
    Virtual daemon that becomes ready when the current date and time has been established. The system provides a default implementation that does nothing, as the base system does not contain a daemon that obtains the current date and time. The system administrator is meant to override the daemon in /etc/init/time by depending on a daemon that obtains the current date and time and sets the system time. Daemons can depend on this daemon if they need the current date and time to have been established before they start.

FORMAT
Daemon configuration files are processed line by line. Each line specifies a property of the daemon. Lines are tokenized like shell commands on white space with support for single qoutes, double quotes, and backslash escape sequences (\\, \', \", \a, \b, \e, \f, \n, \r, \t, \v). The # character starts a comment and the rest of the line is ignored.

cd directory
    The working directory to run the deamon inside. (Default is /)

exec command
    The command line that starts the daemon. The daemon becomes ready when it writes a newline to the file descriptor mentioned in the READYFD environment variable as described in daemon(7).

    If this property isn't specified, then the daemon is a virtual daemon. Virtual deamons become ready when all their dependencies are ready and finish when all their dependencies are finished. Virtual daemons exit 0 (success) if every dependency finished successfully, otherwise they exit 3 (failed).

exit-code-meaning [default | poweroff-reboot]
    This property specifies how to interpret the exit code.

    The default meaning is that exiting 0 is successful. Any other exit means the daemon failed.

    The poweroff-reboot meaning is that exiting 0 means the system should power off, exiting 1 means the system should reboot, exiting 2 means the system should halt, and any other exit means the daemon failed.

    Daemons are considered successful if they exit by SIGTERM if init(8) stopped the daemon by sending SIGTERM.

furthermore
    The current daemon configuration file extends an existing daemon that is defined in a configuration file by the same name later in the search path. The later configuration file is included into the current configuration file. This statement can only be used once per configuration file, any subsequent uses are silently ignored, but it can be used recursively. Customizing an existing daemon should be done by adding a new daemon file earlier in the search path that starts with the furthermore statement, followed by additional configuration.

    This is not a property and cannot be unset.

log-control-messages [false | true]
    Includes control messages such as the start and stop of the daemon and loss of log data. Control messages are inserted as entries from the daemon init.

    The default is true and is inherited from the default deamon.

log-file-mode octal
    Sets the log file permissions to the octal mode with chmod(2).

    The default value is 644 and is inherited from the default deamon.

log-format format
    Selects the format of the log:

    none
        The log is exactly as written by the daemon with no additional formatting.

    seconds
        "YYYY-dd-mm HH:MM:SS +0000: "

        Each line is prefixed with a timestamp with second precision and the timezone offset.

    nanoseconds
        "YYYY-dd-mm HH:MM:SS.nnnnnnnnn +0000: "

        Each line is prefixed with a timestamp with nanosecond precision and the timezone offset.

    basic
        "YYYY-dd-mm HH:MM:SS.nnnnnnnnn +0000 daemon: "

        Each line is prefixed with a timestamp with nanosecond precision and the timezone offset followed by the name of the daemon.

    full
        "YYYY-dd-mm HH:MM:SS.nnnnnnnnn +0000 hostname daemon: "

        Each line is prefixed with a timestamp with nanosecond precision and the timezone offset followed by the hostname and name of the daemon.

    syslog
        "<ppp>1 YYYY-dd-mmTHH:MM:SS.uuuuuuZ hostname daemon pid - - "

        Each line is prefixed in the RFC 5424 syslog version 1 format with the priority, the timestamp with microsecond precision and the timezone offset, the hostname, the daemon name, and the process id.

    The default format is nanoseconds and is inherited from the default deamon.

log-line-size line-size
    When using the rotate log method, log files are cut at newlines if the lines don't exceed line-size bytes.

    The default value is 4096 bytes and is inherited from the default deamon.

log-method [none | append | rotate]
    Selects the method for logging:

    none
        Disable logging.

    append
        Always append the log data to the log file without any rotation. For instance, exampled.log will contain all the log entries ever produced by the exampled daemon.

        This method does not lose log data but it will fail when filesystem space is exhausted.

    rotate
        Append lines to the log file until it becomes too large, in which case the daemon's logs are rotated.

        Rotation is done by deleting the oldest log (if there are too many), each of the remaining log files are renamed with the subsequent number, and a new log file is begun. The logs are cut on a newline boundary if the lines doesn't exceed log-line-size.

        For instance, exampled.log.2 is deleted, exampled.log.1 becomes exampled.log.2, exampled.log.1 becomes exampled.log.2, and a new exampled.log is begun.

        This method will lose old log data.

    The default format is rotate and is inherited from the default deamon.

log-rotate-on-start [false | true]
    When starting the daemon, rotate the logs (when using the rotate log method) or empty the log (when using the append log method), such that the daemon starts out with a new log.

    The default value is false and is inherited from the default deamon.

log-size size
    When using the rotate log method, keep each log file below size bytes.

    The default value is 1048576 bytes and is inherited from the default deamon.

need tty
    Specifies that the daemon is not a background daemon, but instead is the foreground daemon controlling the terminal in the tty property. The daemon is made a process group leader. The terminal's foreground process group is set to that of the daemon. The terminal is enabled by setting CREAD. The daemon is not logged, and the standard input, output, and error are instead connected to the terminal Foreground daemons are automatically considered ready and don't participate in the READYFD daemon readiness protocol. Upon exit, the original terminal settings are restored and init(8) reclaims ownership of the terminal.

per if
    Specifies that an instance of the daemon should run for each network interface. The daemon becomes a virtual daemon that depends on on the instantiated daemons for each network interface. The name of each instantiated daemon is the name of the virtual daemon plus ‘.’ plus the name of the network interface (e.g. exampled running on the loopback interface lo0 would be example.lo0). The name of the network interface is appended as a command line argument on the command line of each instantiated daemon. It is not possible to depend on the instantiated daemons.

require dependency [flag ...]
    When the daemon is needed, start the dependency first. The daemon starts when all its dependencies have become ready or have finished. Dependencies are started in parallel whenever possible. If the daemon hasn't started yet, and any non-optional dependency finishes unsuccessfully, then the daemon doesn't start and instead directly finishes unsuccessfully. If the daemon has started, it is the daemon's responsibility to detect failures in its dependencies.

    The dependency can be customized with zero or more flags:

    exit-code
        If the daemon is a virtual daemon, then the daemon's exit code is that of the specific dependency rather than whether all dependencies succeeded. The daemon exits as soon as the dependency exits, rather than waiting for all dependencies to exit. The exit-code-meaning field is set to that of the dependency. exit-code can at most be used on a single dependency for a daemon.

    no-await
        Don't wait for the dependency to become ready before starting this daemon. This flag is meant for dependencies that the daemon can make use of, but isn't essential to the daemon itself becoming ready. It shouldn't be used if the daemon polls for the dependency to come online, as it is more efficient to only start the daemon once the dependency is ready.

    optional
        Start the daemon even if the dependency fails. The dependency is assumed to exist and a warning occurs if it doesn't exist.

    Dependencies can be forgotten using unset require dependency. Flags on a dependency can be be unset using unset require dependency flag ....

unset property
    Reset the given property to its default value.

tty device
    If the daemon is a foreground daemon (need tty is set), then connect the daemon to the terminal named device.

    The default value is the terminal init(8) is attached to, usually tty1.

ENVIRONMENT
Daemons inherit their environment from init(8) with this additional environment:

READYFD
    Daemons signal they are ready by writing a newline to the file descriptor mentioned in the READYFD environment variable as described in daemon(7).

FILES
/etc/init/
    Daemon configuration for the local system (first in search path).
/etc/init/default
    The configuration file for the default daemon.
/etc/init/local
    The configuration file for the local daemon which depends on the installation's local daemons.
/share/init/
    Default daemon configuration provided by the operating system (second in search path).
/var/log/
    Daemon log files.

EXAMPLES

  Configuring a daemon to start on boot
The local system can be configured to start the exampled daemon by creating /etc/init/local with the following contents:

    require exampled optional

Additional lines can be included for any daemon you wish to start. The optional flag means the local daemon doesn't fail if the daemon fails. The top level daemons (multi-user, single-user, ...) fails if the local daemon fails, which will shut down the operating system. The optional flag should only be omitted if a local daemon is critical and the boot should fail if the daemon fails.

  Disable network auto-configuration (DHCP)
The network daemon depends by default on dhclient, which does DHCP configuration of the network. This dependency can be removed by creating /etc/init/network with the following contents:

    furthermore
    unset require dhclient

This example extends the existing configuration in /share/init/network by removing a dependency.

  Creating a new daemon
The exampled daemon, which depends on the food, bard, and quxd daemons and whose program file is called exampled, can then be configured by creating /etc/init/exampled with the following contents:

    require food
    require bard
    require quxd
    exec exampled

  Changing the log format
The default log format of daemons and init(8)'s own can be set by setting the properties in /etc/init/default. A few examples:

    log-format full
    log-method append

Uses the full log format and grows the log without limit, never losing data unless the filesystem space is exhausted.

    log-control-messages false
    log-format none
    log-method rotate
    log-rotate-on-start true

Provides plain rotated log files, by disabling control messages from init(8) about starting/stopping the daemon, turning off log metadata, and also rotates the log when the deamon is started.

  Configuring a multi-user system
The system can be configured to boot into multi-user mode by creating /etc/init/default with the following contents:

    require multi-user exit-code

  Configuring an unattended system
A fully unattended system that only starts the base system and the exampled daemon, shutting down when the exampled daemon finishes, can be done by first creating /etc/init/default with the following contents:

    require no-user exit-code

And then secondly creating /etc/init/local with the following contents:

    require exampled exit-code

SEE ALSO
daemon(7), init(8)

BUGS
The control messages mentioned in log-control-messages aren't implemented yet.

The tty property isn't implemented yet and must be tty1 if set.