sortix-mirror/init/init.8

.Dd October 5, 2015
.Dt INIT 8
.Os
.Sh NAME
.Nm init
.Nd system initialization
.Sh SYNOPSIS
.Nm init
.Op Fl qsv
.Op Fl \-target Ns "=" Ns Ar default-daemon
.Op Fl \-
.Op Ar chain-init ...
.Sh DESCRIPTION
.Nm
is the first program run after system startup and is responsible for
initializing the operating system.
.Pp
Each
.Xr daemon 7
is started in order as its dependencies become ready per its
.Xr init 5
configuration.
The
.Sy default
daemon is automatically started and its recursive dependencies constitute the
operating system.
The
.Sy default
daemon's single dependency is referred to as the target.
.Pp
The
.Xr kernel 7
starts the system in a temporary environment with a root filesystem
backed by system memory and extracts the
.Xr initrd 7
into it.
The kernel runs the
.Pa /sbin/init
program of the system memory root filesystem as the first process.
If the system is on bootable cdrom, then the initrd will be a fully functional
system and
.Nm
will start a live environment or an operating system installer.
If the system is installed on a harddisk, then the initrd is a minimal system
made with
.Xr update-initrd 8
that will search for the actual root filesystem and chain init it.
The next stage init will recognize itself as the intended system and complete
the system startup.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl q , \-quiet
Write status updates to the terminal only about failed daemons.
This behavior is the default.
.It Fl s , \-silent
Never write status updates about daemons to the terminal.
.It Fl t , \-target Ns "=" Ns Ar default-daemon
Boot
.Ar default-daemon
as the target.
The
.Sy default
daemon configuration is changed to only require the
.Ar default-daemon
dependency with the
.Sy exit-only
flag.
.It Fl v , \-verbose
Write all status updates about daemons starting and stopping to the terminal
.El
.Ss Cleanup of /tmp and /var/run
.Nm
deletes everything inside of
.Pa /tmp
if it exists, otherwise it is created with mode 1777.
.Pp
.Nm
creates
.Pa /var
with mode 755 if it doesn't exist.
.Nm
deletes everything inside of
.Pa /var/run
if it exists, otherwise it is created with mode 755.
.Ss Partition Creation
.Nm
will scan every block device for valid partition tables and create the
corresponding partition devices in
.Pa /dev .
.Ss Chain Initialization
If the target is
.Sy chain
or
.Sy chain-merge ,
then the real operating system is chain initialized.
.Pp
The root filesystem is mounted per
.Pa /etc/fstab
(see
.Xr fstab 5 ) .
This configuration file is a copy of the real file made by
.Xr update-initrd 8
when it makes the bootstrap
.Xr initrd 7 .
.Pp
The root filesystem is found by searching each block device and partition.
It is checked for consistency if necessary and mounted read-only if the check
fails.
It is mounted at
.Pa /tmp/fs.XXXXXX
and the
.Pa /dev
filesystem directory is bound at
.Pa /tmp/fs.XXXXXX/dev .
.Pp
Finally the
.Pa /sbin/init
program (or
.Ar chain-init
if specified) of the target root filesystem is run inside a chroot.
If the target is
.Sy chain-merge ,
then the
.Fl \-target=merge
option is passed to the next
.Nm .
.Ss Mountpoints
.Nm
mounts all the filesystems according to
.Xr fstab 5 .
The filesystems are checked for consistency if necessary and mounted read-only
if the check fails.
.Ss Logging
Logging to
.Pa /var/log
begins once the filesystems are mounted and
.Nm
writes the log entries from early boot to its
.Pa /var/log/init.log .
.Ss Random Seed
.Nm
will write 256 bytes of randomness to
.Pa /boot/random.seed ,
which serves as the initial entropy for the
.Xr kernel 7
on the next boot.
The file is also written on system shutdown where the system has the most
entropy.
.Ss Configuration
Once the
.Nm
of the real root filesystem runs, it will process basic configuration files and
apply them:
.Pp
.Bl -tag -width "/etc/videomode" -compact -offset indent
.It Pa /etc/hostname
set hostname (see
.Xr hostname 5 )
.It Pa /etc/kblayout
set keyboard layout (see
.Xr kblayout 5 )
.It Pa /etc/videomode
set graphics resolution (see
.Xr videomode 5 )
.El
.Ss Merge
If the target is
.Sy merge ,
then a delayed system upgrade is completed by invoking
.Xr sysmerge 8
at
.Pa /sysmerge/sbin/sysmerge
with the
.Ar --booting
option.
.Pp
If the upgrade succeeds, the temporary
.Pa /sysmerge/sbin/init
deinitializes the system and invokes the real (now upgraded)
.Pa /sbin/init ,
which will restart system initialization in the normal fashion.
.Ss Daemons
The
.Sy default
.Xr daemon 7
is started per its
.Pa /etc/init/default
.Xr init 5
configuration file, which constitutes the operating system, and once it exits
then
.Nm
exits with the same error code and the kernel shuts down the machine.
The
.Sy default
daemon is meant to be a virtual daemon depending on a single top level daemon
(the target), which provide the desired operating system functionality
(e.g. booting to a single user shell or a multi user login screen).
.Pp
The daemons are configured per
.Xr init 5
where
.Pa /etc/init
contains the installation's local configuration, which overrides the operating
system's default configuration in
.Pa /share/init .
The daemons are started in order as their dependencies become ready and are
stopped in order when they are no longer required.
.Pp
The
.Sy local
daemon is meant to start the installation's local daemon requirements.
.Sh ENVIRONMENT
.Nm
sets the following environment variables.
.Bl -tag -width "INIT_PID"
.It Ev HOME
root's home directory
.It Ev INIT_PID
.Nm Ns 's
process id
.It Ev LOGNAME
root
.It Ev PATH
.Pa /bin:/sbin
.It Ev SHELL
root's shell
.It Ev TERM
sortix
.It Ev USER
root
.El
.Sh FILES
.Bl -tag -width "/boot/random.seed" -compact
.It Pa /boot/random.seed
Initial kernel entropy
.It Pa /etc/init/
Daemon configuration for the local system (first in search path) (see
.Xr init 5 )
.It Pa /etc/init/default
Configuration for the default daemon (see
.Xr init 5 )
.It Pa /etc/fstab
Filesystem table (see
.Xr fstab 5 )
.It Pa /etc/hostname
Hostname (see
.Xr hostname 5 )
.It Pa /etc/kblayout
Keyboard layout (see
.Xr kblayout 5 )
.It Pa /etc/videomode
Graphics resolution (see
.Xr videomode 5 )
.It Pa /share/init/
Default daemon configuration provided by the operating system (second in
search path) (see
.Xr init 5 )
.It Pa /var/log/
Daemon log files (see
.Xr init 5 )
.It Pa /var/log/init.log
.Nm Ns 's
own log.
.El
.Sh ASYNCHRONOUS EVENTS
.Bl -tag -width "SIGUSR1"
.It Dv SIGTERM
Request system poweroff, normally sent by
.Xr poweroff 8 .
.It Dv SIGINT
Request system reboot, normally sent by
.Xr reboot 8 .
.It Dv SIGQUIT
Request system halt, normally sent by
.Xr halt 8 .
.It Dv SIGHUP
Request system reinitialization.
.El
.Sh EXIT STATUS
.Nm
exits 0 if the kernel should power off, exits 1 if the kernel should reboot, or
exits 2 if the boot failed and the kernel should halt with a complaint about an
.Nm
fatality.
Any other exit by the initial
.Nm
will cause the kernel to halt with a complaint about an unexpected exit code.
.Nm
exits with the same exit status as its target session if it terminates normally.
.Sh SEE ALSO
.Xr fstab 5 ,
.Xr hostname 5 ,
.Xr init 5 ,
.Xr kblayout 5 ,
.Xr videomode 5 ,
.Xr daemon 7 ,
.Xr initrd 7 ,
.Xr kernel 7 ,
.Xr halt 8 ,
.Xr login 8 ,
.Xr poweroff 8 ,
.Xr reboot 8 ,
.Xr sysmerge 8 ,
.Xr update-initrd 8
.Sh SECURITY CONSIDERATIONS
It is a full system compromise if unauthenticated users are able to boot the
wrong target.
The kernel command line can specify the path to
.Nm
and its arguments.
Unprivileged users can change the kernel command line from the bootloader
command line if it hasn't been password protected.
Likewise unprivileged users can use their own replacement bootloader by booting
a portable device under their control if the firmware configuration has not been
password protected.