.Dd July 29, 2018
.Dt INIT 5
.Os
.Sh NAME
.Nm init
.Nd system initialization configuration
.Sh SYNOPSIS
.Nm /etc/init/
.Nm /share/init/
.Sh DESCRIPTION
.Xr init 8
starts each
.Xr daemon 7
(system background process) according to the daemon's
configuration file, which specifies the daemon's dependencies and how to run the
daemon.
.Pp
Configuration files are searched for in the
.Pa /etc/init/
directory (local initialization configuration owned by the system administrator,
which may be modified) and the
.Pa /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
.Sy exampled
might come with the default configuration file
.Pa /share/init/exampled
that the system administrator can override in
.Pa /etc/init/exampled .
.Pp
.Xr init 8
initially starts the
.Sy default
daemon which is configured in
.Pa /etc/init/default ,
which then depends on the daemons constituting the operating system (which in
turn depend on the
.Sy local
daemon).
The
.Pa /etc/init/default
file also defines default settings such as logging that are implicitly inherited
by all other deamons, as well as
.Xr init 8 Ns 's
own
.Pa /var/log/init.log
file.
.Pp
Local system daemons should be started by overriding the
.Sy local
daemon in
.Pa /etc/init/local ,
which then depends on the locally required daemons.
System provided daemons can be customized by making
.Pa /etc/init/exampled
which starts with the
.Sy furthermore
statement to include the default
.Pa /etc/share/exampled
configuration and then change the desired properties.
.Sh DAEMONS
The
.Sy default
daemon should
.Sy require
exactly one top level daemon with
.Sy exit-code
and nothing else.
.Pp
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:
.Bl -tag -width "12345678"
.It Sy multi-user
Starts the operating system in the multi-user mode.
It starts the
.Sy 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
.Sy base
and
.Sy local
daemons.
.It Sy 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
.Sy local
daemon.
It depends on the
.Sy base
and
.Sy local
daemons.
The dependency on
.Sy local
is marked
.Sy exit-code ,
letting the system administrator fully control the
.Sy default
daemon's exit code and when the system completes.
.It Sy single-user
Starts the operating system in the single user mode.
This foreground daemon starts the
.Sy 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
.Sy base
and
.Sy local
daemons.
.It Sy sysinstall
Starts the operating system installer.
This foreground daemon starts the
.Sy 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
.Sy base
and
.Sy local
daemons.
.It Sy sysupgrade
Starts the operating system upgrader.
This foreground daemon starts the
.Sy 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
.Sy base
and
.Sy local
daemons.
.El
.Pp
The following daemons are provided by the system:
.Bl -tag -width "12345678"
.It Sy base
Virtual daemon that depends on the core operating system daemons.
It depends on the
.Sy time
daemon.
.It Sy 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
.Pa /etc/init/local
by depending on daemons outside of the base system that should run on the local
system.
.It Sy 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
.Pa /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.
.El
.Sh 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.
.Bl -tag -width "12345678"
.It Sy cd Ar directory
The working directory to run the deamon inside.
(Default is
.Pa / )
.It Sy exec Ar command
The command line that starts the daemon.
The daemon becomes ready when it writes
a newline to the file descriptor mentioned in the
.Ev READYFD
environment variable as described in
.Xr daemon 7 .
.Pp
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).
.It Sy exit-code-meaning Oo Sy default "|" poweroff-reboot Oc
This property specifies how to interpret the exit code.
.Pp
The
.Sy default
meaning is that exiting 0 is successful.
Any other exit means the daemon failed.
.Pp
The
.Sy 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.
.Pp
Daemons are considered successful if they exit by
.Sy SIGTERM
if
.Xr init 8
stopped the daemon by sending
.Sy SIGTERM.
.It Sy 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
.Sy furthermore
statement, followed by additional configuration.
.Pp
This is not a property and cannot be
.Sy unset .
.It Sy log-control-messages Oo Sy false "|" true Oc
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
.Sy init .
.Pp
The default is
.Sy true
and is
inherited from the
.Sy default
deamon.
.It Sy log-file-mode Ar octal
Sets the log file permissions to the
.Ar octal
mode with
.Xr chmod 2 .
.Pp
The default value is
.Sy 644
and is inherited from the
.Sy default
deamon.
.It Sy log-format Ar format
Selects the
.Ar format
of the log:
.Bl -tag -width "nanoseconds"
.It Sy none
The log is exactly as written by the daemon with no additional formatting.
.It Sy seconds
"YYYY-dd-mm HH:MM:SS +0000: "
.Pp
Each line is prefixed with a timestamp with second precision and the timezone
offset.
.It Sy nanoseconds
"YYYY-dd-mm HH:MM:SS.nnnnnnnnn +0000: "
.Pp
Each line is prefixed with a timestamp with nanosecond precision and the
timezone offset.
.It Sy basic
"YYYY-dd-mm HH:MM:SS.nnnnnnnnn +0000 daemon: "
.Pp
Each line is prefixed with a timestamp with nanosecond precision and the
timezone offset followed by the name of the daemon.
.It Sy full
"YYYY-dd-mm HH:MM:SS.nnnnnnnnn +0000 hostname daemon: "
.Pp
Each line is prefixed with a timestamp with nanosecond precision and the
timezone offset followed
by the hostname and name of the daemon.
.It Sy syslog
"<ppp>1 YYYY-dd-mmTHH:MM:SS.uuuuuuZ hostname daemon pid - - "
.Pp
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.
.El
.Pp
The default format is
.Sy nanoseconds
and is inherited from the
.Sy default
deamon.
.It Sy log-line-size Ar line-size
When using the
.Sy rotate
log method, log files are cut at newlines if the lines don't exceed
.Ar line-size
bytes.
.Pp
The default value is 4096 bytes and is inherited from the
.Sy default
deamon.
.It Sy log-method Oo Sy none "|" append "|" rotate Oc
Selects the method for logging:
.Bl -tag -width "12345678"
.It Sy none
Disable logging.
.It Sy append
Always append the log data to the log file without any rotation.
For instance,
.Pa exampled.log
will contain all the log entries ever produced by the
.Sy exampled
daemon.
.Pp
This method does not lose log data but it will fail when filesystem space is
exhausted.
.It Sy rotate
Append lines to the log file until it becomes too large, in which case the
daemon's logs are rotated.
.Pp
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
.Sy log-line-size .
.Pp
For instance,
.Pa exampled.log.2
is deleted,
.Pa exampled.log.1
becomes
.Pa exampled.log.2 ,
.Pa exampled.log.1
becomes
.Pa exampled.log.2 ,
and a new
.Pa exampled.log
is begun.
.Pp
This method will lose old log data.
.El
.Pp
The default format is
.Sy rotate
and is inherited from the
.Sy default
deamon.
.It Sy log-rotate-on-start Oo Sy false "|" true Oc
When starting the daemon, rotate the logs (when using the
.Sy rotate
log method) or empty the log (when using the
.Sy append
log method), such that the daemon starts out with a new log.
.Pp
The default value is
.Sy false
and is inherited from the
.Sy default
deamon.
.It Sy log-size Ar size
When using the
.Sy rotate
log method, keep each log file below
.Ar size
bytes.
.Pp
The default value is 1048576 bytes and is inherited from the
.Sy default
deamon.
.It Sy need tty
Specifies that the daemon is not a background daemon, but instead is the
foreground daemon controlling the terminal in the
.Sy 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
.Sy 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
.Ev READYFD
daemon readiness protocol.
Upon exit, the original terminal settings are restored and
.Xr init 8
reclaims ownership of the terminal.
.It Sy require Ar dependency Oo Ar flag ... Oc
When the daemon is needed, start the
.Ar 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.
.Pp
The dependency can be customized with zero or more flags:
.Bl -tag -width "12345678"
.It Sy exit-code
If the daemon is a virtual daemon, then the daemon's exit code is that of the
specific
.Ar dependency
rather than whether all dependencies succeeded.
The daemon exits as soon as the
.Ar dependency
exits, rather than waiting for all dependencies to exit.
The
.Sy exit-code-meaning
field is set to that of the dependency.
.Sy exit-code
can at most be used on a single dependency for a daemon.
.It Sy no-await
Don't wait for the
.Ar 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 the dependency to come online,
as it is more efficient to only start the daemon once the dependency is ready.
.It Sy optional
Start the daemon even if the
.Ar dependency
fails.
The dependency is assumed to exist and a warning occurs if it doesn't exist.
.El
.Pp
Dependencies can be forgotten using
.Sy unset require Ar dependency .
Flags on a dependency can be be unset using
.Sy unset require Ar dependency flag ... .
.It Sy unset Ar property
Reset the given property to its default value.
.It Sy tty Ar device
If the daemon is a foreground daemon
.Sy ( need tty
is set), then connect the daemon to the terminal named
.Ar device .
.Pp
The default value is the terminal
.Xr init 8
is attached to, usually
.Pa tty1 .
.El
.Sh ENVIRONMENT
Daemons inherit their environment from
.Xr init 8
with this additional environment:
.Bl -tag -width "READYFD"
.It Ev READYFD
Daemons signal they are ready by writing a newline to the file descriptor
mentioned in the
.Ev READYFD
environment variable as described in
.Xr daemon 7 .
.El
.Sh FILES
.Bl -tag -width /share/init/default -compact
.It Pa /etc/init/
Daemon configuration for the local system (first in search path).
.It Pa /etc/init/default
The configuration file for the
.Sy default
daemon.
.It Pa /etc/init/local
The configuration file for the
.Sy local
daemon which depends on the installation's local daemons.
.It Pa /share/init/
Default daemon configuration provided by the operating system (second in search
path).
.It Pa /var/log/
Daemon log files.
.El
.Sh EXAMPLES
.Ss Configuring a daemon to start on boot
The local system can be configured to start the
.Sy exampled
daemon by creating
.Pa /etc/init/local
with the following contents:
.Bd -literal
require exampled optional
.Ed
.Pp
Additional lines can be included for any daemon you wish to start.
The
.Sy optional
flag means the
.Sy local
daemon doesn't fail if the daemon fails.
The top level daemons
.Sy ( multi-user , single-user , ... )
fails if the
.Sy local
daemon fails, which will shut down the operating system.
The
.Sy optional
flag should only be omitted if a local daemon is critical and the boot should
fail if the daemon fails.
.Ss Creating a new virtual daemon
The
.Sy exampled
daemon, which depends on the
.Sy food , bard ,
and
.Sy quxd
daemons and whose program file is called
.Pa exampled ,
can then be configured by creating
.Pa /etc/init/exampled
with the following contents:
.Bd -literal
require food
require bard
require quxd
exec exampled
.Ed
.Ss Changing the log format
The default log format of daemons and
.Xr init 8 Ns 's
own can be set by setting the properties in
.Pa /etc/init/default .
A few examples:
.Bd -literal
log-format full
log-method append
.Ed
.Pp
Uses the
.Sy full
log format and grows the log without limit, never losing data unless the
filesystem space is exhausted.
.Bd -literal
log-control-messages false
log-format none
log-method rotate
log-rotate-on-start true
.Ed
.Pp
Provides plain rotated log files, by disabling control messages from
.Xr init 8
about starting/stopping the daemon, turning off log metadata, and also rotates
the log when the deamon is started.
.Ss Configuring a multi-user system
The system can be configured to boot into multi-user mode by creating
.Pa /etc/init/default
with the following contents:
.Bd -literal
require multi-user exit-code
.Ed
.Ss Configuring an unattended system
A fully unattended system that only starts the base system and the
.Sy exampled
daemon, shutting down when the
.Sy exampled
daemon finishes, can be done by first creating
.Pa /etc/init/default
with the following contents:
.Bd -literal
require no-user exit-code
.Ed
.Pp
And then secondly creating
.Pa /etc/init/local
with the following contents:
.Bd -literal
require exampled exit-code
.Ed
.Sh SEE ALSO
.Xr daemon 7 ,
.Xr init 8
.Sh BUGS
The control messages mentioned in
.Sy log-control-messages
aren't implemented yet.
.Pp
The
.Sy tty
property isn't implemented yet and must be
.Pa tty1
if set.