inittab.man

.TH inittab 5
'''
.SH NAME
{/etc/inittab} - \fBinit\fR(8) configuration file.
'''
.SH DESCRIPTION
Inittab is a list of commands init should run.
.P
Each relevant line in inittab describes a single process (an entry)
to be run by init. Init records the ids of the processes it spawns
and tracks them until processes die.
.P
At any point, init is in one of runlevels 0, 1, ... 9, with zero or more
sublevels a, b, ..., f activated. Each entry has its own runlevel mask,
with zero or more runlevels and zero or more sublevels.
.P
Init decides whether an entry should be running or not using current
runlevel and entry's runlevel mask.  Subsequently the entry is either
spawned, killed or skipped. Entries are always started in top-to-bottom
order, and killed bottom-to-top.
.P
In case a tracked process dies, init attempts to respawn the relevant entry
unless the entry is explicitly marked as run-once. A typical configuration
would include run-once system initialization commands and respawn entries
for various system services (daemons).
.P
Along with the entries itself, inittab may also contain environment
variables to be passed to the spawned processes via \fBexecve\fR(2).
'''
.SH SYNTAX
Inittab is a text file parsed in line wise manner.
.IP "# \fIcomment\fR" 4
Lines starting with # are ignored by init
.IP "\fIvariable\fR=\fIvalue\fR" 4
Add \fIvariable\fR to the environment to be passed to processes started
by init.
.IP "\fIname\fR  \fImode\fR  \fIcommand\fR" 4
Define an entry. The fields (name, mode and command) may be separated
with spaces or tabs. See below for the meaning of each of the three fields.
.P
Init parses and later spawns the entries in top-to-bottom order.
Depending on flags and current runlevel, some entries may be skipped,
but not reordered.
.P
The relative order of environment and process lines is irrelevant.
All spawned processes will get exactly the same environment.
Comments and empty lines are ignored.
'''
.SS Naming entries
\fIname\fR is a string used to identify this entry, in particular when
stopping/starting processes with \fBtelinit\fR(8), as well as in syslog
messages. To make a unnamed entry, start a line with any whitespace character.
Non-empty names should be unique.
.P
During reconfiguration, init matches entries with the same name, and transfers
process ids from the old configuration. For un-named entries, and in case names
do not match, the old process gets killed and the new one started.
This is mostly relevant for respawning entries.
'''
.SS Entry mode
The second field, \fImode\fR, describes how the entry should be handled by init. 
Its format is \fIM\fB[\fI123\fB][\fI*\fB]\fR, with \fIM\fR (mode) determining
how the entry should be (re)started, and \fI123*\fR setting runlevel mask.
Possible modes are:
.IP "\fBS\fR" 4
Service (foreground daemon). The entry will be respawned, unless it respawns
too fast, in which case it will be disabled. Use for processes which are not
expected to exit during normal operation.
.IP "\fBF\fR" 4
Fast-respawning entry. Same as \fBS\fR, except the entry is allowed
to respawn fast as long as it keeps exiting with 0 exit code.
Use for processes that do respawn during normal operation (gettys and such).
.IP "\fBR\fR" 4
Run once. Do not respawn the process. Use this flag for independent system
initialization entries, like sysctl or non-root mounts or early network setup.
.IP "\fBW\fR" 4
Run once and wait for this process. Do not restart it, and do not proceed
further until it dies. Use this for critical initialization entries, like
mounting root. \fBW\fR-process will not be started until all preceding
\fBR\fR-entries have exited, and no subsequent entries will be started until
it exits.
.IP "\fBX\fR" 4
Run once when entering any runlevel not matching the mask.
Should be used for wakeup scripts.
.IP "\fBL\fR" 4
Like \fBS\fR, but wait for other processes die before stopping this one.
This may be useful for syslogd and klogd.
.IP "\fBT\fR" 4
Fast-respawning \fBgetty\fR(1)-like entry. SIGABRT is used to kill it,
as gettys tend to ignore SIGTERM, and abnormal exits are never logged.
.P
Runlevel mask is any subset of \fB0123456789\fR characters.
The entry will be started only if current runlevel is in entry's runlevel
mask (except for \fBX\fR-entries, which do the opposite). The \fB*\fR sign
extends the last runlevell all the way to \fB9\fR, so \fB3*\fR is the same
as \fB3456789\fR.
.P
Runlevel mask may also include a subset of secondary runlevels, \fBabcdef\fR.
If it does, it will only be started if current primary runlevel is in its
mask and all its secondary runlevels are active. Example: \fBS3ac\fR entry
will be started on runlevel \fB3\fR only if both \fBa\fR and \fBc\fR sublevels
are active. See \fBtelinit\fR(8) on how to activate or deactivate sublevels.
.P
Leaving out runlevels completely is the same as using \fB23456789\fR.
'''
.SS Commands
The last field, \fIcommand\fR, is the command to run. The field is parsed and
passed as the second argument to \fBexecve\fR(2) call.
.P
Wherever necessary, init calls /bin/sh -c to execute the command.
.P
.EX
    # Regular command, execve("/sbin/agetty", ...) will be used
    tty1   F    /sbin/agetty --noclear -8 -s 38400 tty1 linux
    # Shell command, execve("/bin/sh", "-c", "echo 1 > /proc/...")
           R    echo 1 > /proc/sys/net/ipv4/ip_forward
.EE
'''
.SH USAGE
The primary role of inittab is listing commands needed to bring the system up
after booting the kernel. Typically this involves run-once entries performing
runtime kernel configuration (file systems, network) and respawning entries
for system daemons and user interface.
.P
Transition to other system states (reboot, shutdown, sleep) may be described
if appropriate, using run-once entries to alter kernel state and runlevel
masks to start or stop certain system services.
'''
.SS Runlevel designation
Certain runlevels have particular meaning assigned to them:
.IP "\fB0\fR" 4
System shutdown (reset, halt or poweroff).
.IP "\fB1\fR" 4
Single-user mode, or recovery mode.
.IP "\fB3\fR" 4
Default runlevel, common or multi-user mode
.IP "\fB7\fR, \fB8\fR, \fB9\fR" 4
Slippery runlevels intended for sleep modes.
.P
Runlevels other than \fB0\fR and \fB789\fR are general-purpose.
Runlevel \fB0\fR is hard-coded to initiate \fBreboot\fR(2) call
and may not be used for anything else.
'''
.SS System startup and shutdown
Commands to run during system startup should be placed at the start
of inittab either \fBW\fR-entries or \fBR\fR-entries; \fBW\fR should
be used commands that affect common environment like mount root while
\fBR\fR is enough for independent commands.
.P
Most startup commands should have empty runlevel mask, which translates
to \fB23456789\fR. Commands common for normal and recovery startup, if any,
need single \fB*\fR. Recovery-only commands should be \fBR1\fR or \fBW1\fR.
.P
Shutdown commands should be \fBR0\fR or \fBW0\fR.
.P
.EX
    # System initialization
    mount       W     /sbin/mount -o remount,rw /
    hwclock     R     /sbin/hwclock -s
    umount      X     /sbin/umount -a
.EE
'''
.SS Foreground daemons
Any process doing \fBdaemon\fR(3) style startup will confuse init if configured
as an \fBS\fR-type entry, since init has no way to track the daemonized child
process and will attemp to take action immediately after the parent exits.
.P
Whenever possible, processes must be instructed to run in foreground mode.
Most daemons allow this; check relevant man pages.
.P
.EX
    # Start some foreground services
    syslogd     L     /usr/sbin/syslogd -n
    ntpd        S     /usr/sbin/ntpd -g -n
    vsftpd      S     /usr/bin/vsftpd /etc/vsftpd.conf -obackground=NO
.EE
.P
In case \fBinitdir\fR(5) is used, most \fBS\fR-type entries should
go there and not to inittab. Any ordered entries, including \fBL\fR-type
services, must remain in inittab.
'''
.SS Slippery runlevels
Reaching any of runlevels \fB7\fR, \fB8\fR, \fB9\fR initiates immediate
switch back to the original non-slippery runlevel.
For instance, running \fBtelinit 8\fR while on runlevel \fB3\fR makes
init switch \fB3\fR to \fB8\fR and back to \fB3\fR.
.P
To implement a sleep state using a slippery runlevel, make all pre-sleep
preparation \fBR\fR-entries, put the sleep command itself as a \fBW\fR-entry,
and make post-sleep recovery \fBX\fR-entries:
.P
.EX
    # Suspend-to-ram implemented as runlevel 7:
            R7   /sbin/network down
    sleep   W7   /bin/echo mem > /sys/power/state
            X7   /sbin/network up
.EE
.P
In case respawning processes that should be stopped when entering sleep mode,
remove relevant runlevels from their respective masks (\fBS3456\fR instead
of \fBS3*\fR).
'''
.SH COMPATIBILITY
This page describes inittab format for \fB{INIT}\fR package.
It is not compatible with the traditional System V init format.
.P
Most features of System V style inittab features translate easily into those
understood by sninit. However, SysV-compatible implementations tend
to use initscripts system instead of \fBinitdir\fR(5), making automated
translation between two formats pointless.
Shutdown/reboot handling differs as well, and sleep modes are not typically
supported.
.P
Because of this, translating traditional inittab for use with {INIT}
rarely makes sense.
'''
.SH SEE ALSO
\fBinit\fR(8), \fBtelinit\fR(8)