507 lines
16 KiB
Groff
507 lines
16 KiB
Groff
.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 daemon (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).
|
|
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.
|
|
.\" TODO: Daemon model.
|
|
.\" TODO: Log files.
|
|
.\" TODO: Readyness.
|
|
.\" TODO: chroot /var/empty
|
|
.\" TODO: Environment variables.
|
|
.\" TODO: No restart. exit 0 means finished. One stops.share/man/man5/init.5
|
|
.\" TODO: Run daemon as specific user.
|
|
.\" TODO: /etc/environment or /etc/environ.
|
|
.\" TODO: Environment variables.
|
|
.\" TODO: Method for including/extending files in /share/init
|
|
.\" TODO: Reference counting. No cycles.
|
|
.\" TODO: Init reload support?
|
|
.Sh DAEMONS
|
|
The
|
|
.Sy default
|
|
daemon should depend on exactly one top level daemon 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.
|
|
It starts the
|
|
.Sy sh
|
|
foreground daemon 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.
|
|
It starts the
|
|
.Sy sysinstall
|
|
foreground daemon 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.
|
|
It starts the
|
|
.Sy sysupgrade
|
|
foreground daemon 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.
|
|
The # character starts a comment and the rest of the line is ignored.
|
|
Each line specifies a property of the daemon.
|
|
.\" TODO: White space, tokenization.
|
|
.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.
|
|
.Pp
|
|
If this property isn't specified, then the daemon is a virtual daemon.
|
|
Virtual deamons become ready well 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 2 (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, and any other exit means the daemon failed (exit 2 should
|
|
preferably be used if the system should panic).
|
|
.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 .
|
|
.\" TODO: How are the default log options set?
|
|
.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 to include control messages.
|
|
.It Sy log-exec Ar program Oo Ar argument ... Oc
|
|
When using the
|
|
.Sy pipe
|
|
log method, start the log process using this program and arguments.
|
|
.\" TODO: The name of the daemon should be inserted as an argument?
|
|
.It Sy log-format
|
|
Selects the 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 - - - "
|
|
.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,
|
|
and the daemon name.
|
|
.El
|
|
.Pp
|
|
The default format is
|
|
.Sy nanoseconds .
|
|
.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.
|
|
.It Sy log-method Oo Sy append "|" rotate "|" pipe Oc
|
|
Selects the method for logging (the default is
|
|
.Sy rotate ) :
|
|
.Bl -tag -width "12345678"
|
|
.It Sy append
|
|
Always append the log data to the log file without any rotation.
|
|
.Pp
|
|
This method does not lose log data but it will fail when disk 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 example.log.2
|
|
is deleted,
|
|
.Pa example.log.1
|
|
becomes
|
|
.Pa example.log.2 ,
|
|
.Pa example.log.1
|
|
becomes
|
|
.Pa example.log.2 ,
|
|
and a new
|
|
.Pa example.log
|
|
is begun.
|
|
.Pp
|
|
This is the default log method.
|
|
This method will lose old log data.
|
|
.It Sy pipe
|
|
The daemon's logs are piped to the standard input of its own log process running
|
|
the
|
|
.Sy log-exec
|
|
program.
|
|
.Pp
|
|
After the daemon has stopped, the log daemon receives an end of file condition
|
|
on its input.
|
|
If the log daemon fails to exit after a timeout, it is sent
|
|
.Sy SIGTERM.
|
|
If it still hasn't exited after another timeout, it is killed with
|
|
.Sy SIGKILL.
|
|
.Pp
|
|
The daemon will not start if the log process could not be started, and the
|
|
daemon will stop with a failure if the log process fails.
|
|
.\" TODO: This is harsh, a single log failure can bring down the system. The
|
|
.\" log program needs to be written especially failsafe too. Maybe have a
|
|
.\" mode that just loses log messages and tries again?
|
|
.\" TODO: Have some sort of readiness signal in case the the process wants to
|
|
.\" initialize buffers (e.g. connect) and not lose any messages if the log
|
|
.\" fails?
|
|
.Pp
|
|
This method does not lose log data, always forwarding it to the spawned process,
|
|
but the spawned process might of course lose it.
|
|
.El
|
|
.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.
|
|
.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.
|
|
.It Sy need tty
|
|
.\" TODO: Only a single daemon can be this.
|
|
Specifies that the daemon is not a background daemon, but instead a foreground
|
|
daemon that requires a terminal.
|
|
.\" TODO: Make session leader.
|
|
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.
|
|
.\" TODO: Automatically being ready could be another independent property.
|
|
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
|
|
regains ownership of the terminal.
|
|
.It Sy require Ar dependency Oo Ar flag ... Oc
|
|
.\" TODO: 'suggest dependency' which doesn't fail if it can't be provided,
|
|
.\" and is just best-effort.
|
|
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.
|
|
.\" TODO: Whether all dependencies are waited for in the eror case.
|
|
If the daemon hasn't started yet, and any dependency finishes unsuccessfully,
|
|
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
|
|
.\" TODO: What about a dependency that succeeds if the dependency isn't
|
|
.\" installed?
|
|
Start the daemon even if the
|
|
.Ar dependency
|
|
fails.
|
|
.\" TODO: Warning or error?
|
|
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
|
|
.\" TODO: Do something with this property.
|
|
If the daemon is a foreground daemon
|
|
.Sy ( need tty
|
|
is set), then connect the daemon to the terminal named
|
|
.Ar device .
|
|
This property is currently ignored and the daemon is always connected to
|
|
.Pa tty1 .
|
|
.El
|
|
.Sh FILES
|
|
.\" TODO: Interesting daemons: default, local, base, time, single-user, etc.
|
|
.Bl -tag -width /share/init/ -compact
|
|
.It Pa /etc/init/
|
|
Daemon configuration for the local system (first in search path).
|
|
.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.
|
|
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 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 init 8
|