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 \-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 constituted by the default daemon (system
background process) and its dependencies.
.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.
.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
.\" TODO: Clarify this under the new daemon model.
The
.Sy chain
target mounts the root filesystem as in
.Pa /etc/fstab
(see
.Xr fstab 5 )
and runs the next
.Nm
program.
This configuration file is a copy of the real file made by
.Xr update-initrd 8
when it makes a bootstrap
.Xr initrd 7 .
.Pp
Every block device and partition is scanned to determine if it is the root
filesystem.
It is checked for consistency if necessary.
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.
.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 Mountpoints
.Nm
mounts all the filesystems according to
.Xr fstab 5 .
.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 Merge
.\" TODO: Clarify this under the new daemon model.
The
.Sy merge
target completes a delayed system upgrade by invoking the
.Xr sysmerge 8
at
.Pa /sysmerge/sbin/sysmerge
with the
.Ar --booting
option.
If the upgrade succeeds, the temporary
.Nm
deinitializes the system and invokes the real (now upgraded)
.Nm
which will restart system initialization in the normal fashion.
.Ss Daemons
TODO: This section.
.Pp
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.
.Pp
Finally
.Nm
will start the target program according to its initialization target.
This will be a login screen, a root shell, or something else.
If the process exits abnormally
.Nm
will automatically restart it.
.Nm
will exit with the same exit status as the process if it exits normally.
The kernel decides whether to power off, reboot or halt based on this exit
status.
.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 .
.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 kblayout 5 ,
.Xr videomode 5 ,
.Xr initrd 7 ,
.Xr kernel 7 ,
.Xr login 8 ,
.Xr sysmerge 8 ,
.Xr halt 8 ,
.Xr poweroff 8 ,
.Xr reboot 8 ,
.Xr update-initrd 8