917722cf70
This change adds the display(1) graphical user interface and desktop environment with basic windowing support and the graphical terminal(1) emulator along with integrations in chkblayout(1), chvideomode(1), sysinstall(8), sysupgrade(8), as well as the games and ports. Adopt the Aurora procedural wallpaper in display(1) and login(8). Remove the obsolete dispd. Juhani contributed keyboard and video mode APIs to the display protocol and other miscellaneous changes. dzwdz contributed the initial functioning window buttons, improved title bar, window tiling, and minor bug fixes Co-authored-by: Juhani Krekelä <juhani@krekelä.fi> Co-authored-by: dzwdz <kg67199@gmail.com>
667 lines
18 KiB
Groff
667 lines
18 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
|
|
.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 single-user-gui
|
|
Like
|
|
.Sy single-user ,
|
|
but runs the root shell in
|
|
.Xr terminal 1
|
|
inside the
|
|
.Xr display 1
|
|
graphical user interface environment.
|
|
This operating system mode is insecure because it boots straight to root access
|
|
without a password.
|
|
.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 sysinstall-gui
|
|
Like
|
|
.Sy sysinstall ,
|
|
but runs it in
|
|
.Xr terminal 1
|
|
inside the
|
|
.Xr display 1
|
|
graphical user interface environment.
|
|
This operating system mode is insecure because it boots straight to root access
|
|
without a password.
|
|
.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.
|
|
.It Sy sysupgrade-gui
|
|
Like
|
|
.Sy sysupgrade ,
|
|
but runs it in
|
|
.Xr terminal 1
|
|
inside the
|
|
.Xr display 8
|
|
graphical user interface environment.
|
|
This operating system mode is insecure because it boots straight to root access
|
|
without a password.
|
|
.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 network
|
|
and
|
|
.Sy time
|
|
daemons.
|
|
.It Sy dhclient
|
|
Daemon that starts
|
|
.Xr dhclient 8
|
|
on each network interface and becomes ready when each network interface has
|
|
been attempted configured.
|
|
.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 network
|
|
Virtual daemon that becomes ready when an attempt has been made to establish
|
|
network connectivity.
|
|
It depends on the
|
|
.Sy dhclient
|
|
deamon.
|
|
Daemons can depend on this daemon if they need the network to have been
|
|
established before they start.
|
|
.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 such as
|
|
.Xr ntpd 8
|
|
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, exit means system
|
|
should reload its configuration and reinitialize, 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 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
|
|
.Sq "."
|
|
plus the name of the network interface (e.g.
|
|
.Sy exampled
|
|
running on the loopback interface
|
|
.Sy lo0
|
|
would be
|
|
.Sy 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.
|
|
.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 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 Disable network auto-configuration (DHCP)
|
|
The
|
|
.Sy network
|
|
daemon depends by default on
|
|
.Sy dhclient ,
|
|
which does DHCP configuration of the network.
|
|
This dependency can be removed by creating
|
|
.Pa /etc/init/network
|
|
with the following contents:
|
|
.Bd -literal
|
|
furthermore
|
|
unset require dhclient
|
|
.Ed
|
|
.Pp
|
|
This example extends the existing configuration in
|
|
.Pa /share/init/network
|
|
by removing a dependency.
|
|
.Ss Creating a new 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.
|