Drop hurd specific dependency on libc0.3 (>= 2.3.2.ds1-12). It is
[sysvinit.git] / man / init.8
1 '\" -*- coding: UTF-8 -*-
2 .\" Copyright (C) 1998-2004 Miquel van Smoorenburg.
3 .\"
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
8 .\"
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
13 .\"
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with this program; if not, write to the Free Software
16 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 .\"
18 .\"{{{}}}
19 .\"{{{ Title
20 .TH INIT 8 "29 Jul 2004" "" "Linux System Administrator's Manual"
21 .\"}}}
22 .\"{{{ Name
23 .SH NAME
24 init, telinit \- process control initialization
25 .\"}}}
26 .\"{{{ Synopsis
27 .SH SYNOPSIS
28 .B /sbin/init
29 .RB [ " -a " ]
30 .RB [ " -s " ]
31 .RB [ " -b " ]
32 [ \fB\-z\fP \fIxxx\fP ]
33 .RB [ " 0123456Ss " ]
34 .br
35 .B /sbin/telinit
36 [ \fB\-t\fP \fISECONDS\fP ]
37 .RB [ " 0123456sSQqabcUu " ]
38 .br
39 .B /sbin/telinit
40 [ \fB\-e\fP \fIVAR\fP[\fB=\fP\fIVAL\fP] ]
41 .\"}}}
42 .\"{{{ Description
43 .SH DESCRIPTION
44 .\"{{{ init
45 .SS Init
46 .B Init
47 is the parent of all processes. Its primary role is to create processes
48 from a script stored in the file \fB/etc/inittab\fP (see
49 \fIinittab\fP(5)). This file usually has entries which cause \fBinit\fP
50 to spawn \fBgetty\fPs on each line that users can log in. It also
51 controls autonomous processes required by any particular system.
52 .PP
53 .\"{{{ Runlevels
54 .SH RUNLEVELS
55 A \fIrunlevel\fP is a software configuration of the system which allows
56 only a selected group of processes to exist. The processes spawned by
57 \fBinit\fP for each of these runlevels are defined in the
58 \fB/etc/inittab\fP file. \fBInit\fP can be in one of eight runlevels:
59 \fB0\(en6\fP and \fBS\fP or \fBs\fP. The runlevel is
60 changed by having a privileged user run \fBtelinit\fP, which sends
61 appropriate signals to \fBinit\fP, telling it which runlevel to change
62 to.
63 .PP
64 Runlevels \fB0\fP, \fB1\fP, and \fB6\fP are reserved. Runlevel 0 is used to
65 halt the system, runlevel 6 is used to reboot the system, and runlevel
66 1 is used to get the system down into single user mode. Runlevel \fBS\fP
67 is not really meant to be used directly, but more for the scripts that are
68 executed when entering runlevel 1. For more information on this,
69 see the manpages for \fBshutdown\fP(8) and \fBinittab\fP(5).
70 .PP
71 Runlevels 7-9 are also valid, though not really documented. This is
72 because "traditional" Unix variants don't use them.
73 In case you're curious, runlevels \fIS\fP and \fIs\fP are in fact the same.
74 Internally they are aliases for the same runlevel.
75 .\"}}}
76 .PP
77 .SH BOOTING
78 After \fBinit\fP is invoked as the last step of the kernel boot sequence,
79 it looks for the file \fB/etc/inittab\fP to see if there is an entry of the
80 type \fBinitdefault\fP (see \fIinittab\fP(5)). The \fBinitdefault\fP entry
81 determines the initial runlevel of the system. If there is no such
82 entry (or no \fB/etc/inittab\fP at all), a runlevel must be
83 entered at the system console.
84 .PP
85 Runlevel \fBS\fP or \fBs\fP bring the system to single user mode
86 and do not require an \fB/etc/inittab\fP file. In single user mode,
87 \fB/sbin/sulogin\fP is invoked on \fB/dev/console\fP.
88 .PP
89 When entering single user mode, \fBinit\fP initializes the consoles
90 \fBstty\fP settings to sane values. Clocal mode is set. Hardware
91 speed and handshaking are not changed.
92 .PP
93 When entering a multi-user mode for the first time, \fBinit\fP performs the
94 \fBboot\fP and \fBbootwait\fP entries to allow file systems to be
95 mounted before users can log in. Then all entries matching the runlevel
96 are processed.
97 .PP
98 When starting a new process, \fBinit\fP first checks whether the file
99 \fI/etc/initscript\fP exists. If it does, it uses this script to
100 start the process.
101 .PP
102 Each time a child terminates, \fBinit\fP records the fact and the reason
103 it died in \fB/var/run/utmp\fP and \fB/var/log/wtmp\fP,
104 provided that these files exist.
105 .SH CHANGING RUNLEVELS
106 After it has spawned all of the processes specified, \fBinit\fP waits
107 for one of its descendant processes to die, a powerfail signal, or until
108 it is signaled by \fBtelinit\fP to change the system's runlevel.
109 When one of the above three conditions occurs, it re-examines
110 the \fB/etc/inittab\fP file. New entries can be added to this file at
111 any time. However, \fBinit\fP still waits for one of the above three
112 conditions to occur. To provide for an instantaneous response, the
113 \fBtelinit Q\fP or \fBq\fP command can wake up \fBinit\fP to re-examine the
114 \fB/etc/inittab\fP file.
115 .PP
116 If \fBinit\fP is not in single user mode and receives a powerfail
117 signal (SIGPWR), it reads the file \fB/etc/powerstatus\fP. It then starts
118 a command based on the contents of this file:
119 .IP F(AIL)
120 Power is failing, UPS is providing the power. Execute the \fBpowerwait\fP
121 and \fBpowerfail\fP entries.
122 .IP O(K)
123 The power has been restored, execute the \fBpowerokwait\fP entries.
124 .IP L(OW)
125 The power is failing and the UPS has a low battery. Execute the
126 \fBpowerfailnow\fP entries.
127 .PP
128 If /etc/powerstatus doesn't exist or contains anything else then the
129 letters \fBF\fP, \fBO\fP or \fBL\fP, init will behave as if it has read
130 the letter \fBF\fP.
131 .PP
132 Usage of \fBSIGPWR\fP and \fB/etc/powerstatus\fP is discouraged. Someone
133 wanting to interact with \fBinit\fP should use the \fB/dev/initctl\fP
134 control channel - see the source code of the \fBsysvinit\fP package
135 for more documentation about this.
136 .PP
137 When \fBinit\fP is requested to change the runlevel, it sends the
138 warning signal \s-1\fBSIGTERM\fP\s0 to all processes that are undefined
139 in the new runlevel. It then waits 5 seconds before forcibly
140 terminating these processes via the \s-1\fBSIGKILL\fP\s0 signal.
141 Note that \fBinit\fP assumes that all these processes (and their
142 descendants) remain in the same process group which \fBinit\fP
143 originally created for them. If any process changes its process group
144 affiliation it will not receive these signals. Such processes need to
145 be terminated separately.
146 .\"}}}
147 .\"{{{ telinit
148 .SH TELINIT
149 \fB/sbin/telinit\fP is linked to \fB/sbin/init\fP. It takes a
150 one-character argument and signals \fBinit\fP to perform the appropriate
151 action. The following arguments serve as directives to
152 \fBtelinit\fP:
153 .IP "\fB0\fP,\fB1\fP,\fB2\fP,\fB3\fP,\fB4\fP,\fB5\fP or \fB6\fP"
154 tell \fBinit\fP to switch to the specified run level.
155 .IP \fBa\fP,\fBb\fP,\fBc\fP
156 tell \fBinit\fP to process only those \fB/etc/inittab\fP file
157 entries having runlevel \fBa\fP,\fBb\fP or \fBc\fP.
158 .IP "\fBQ\fP or \fBq\fP"
159 tell \fBinit\fP to re-examine the \fB/etc/inittab\fP file.
160 .IP "\fBS\fP or \fBs\fP"
161 tell \fBinit\fP to switch to single user mode.
162 .IP "\fBU\fP or \fBu\fP"
163 tell \fBinit\fP to re-execute itself (preserving the state). No re-examining of
164 \fB/etc/inittab\fP file happens. Run level should be one of
165 \fBSs0123456\fP
166 otherwise request would be silently ignored.
167 .PP
168 \fBtelinit\fP can tell \fBinit\fP how long it should wait
169 between sending processes the SIGTERM and SIGKILL signals. The default
170 is 5 seconds, but this can be changed with the \fB-t\fP option.
171 .PP
172 \fBtelinit -e\fP tells \fBinit\fP to change the environment
173 for processes it spawns.
174 The argument of \fB-e\fP is either of the form \fIVAR\fP=\fIVAL\fP
175 which sets variable \fIVAR\fP to value \fIVAL\fP,
176 or of the form \fIVAR\fP
177 (without an equality sign)
178 which unsets variable \fIVAR\fP.
179 .PP
180 \fBtelinit\fP can be invoked only by users with appropriate
181 privileges.
182 .PP
183 The \fBinit\fP binary checks if it is \fBinit\fP or \fBtelinit\fP by looking
184 at its \fIprocess id\fP; the real \fBinit\fP's process id is always \fB1\fP.
185 From this it follows that instead of calling \fBtelinit\fP one can also
186 just use \fBinit\fP instead as a shortcut.
187 .\"}}}
188 .\"}}}
189 .SH ENVIRONMENT
190 \fBInit\fP sets the following environment variables for all its children:
191 .IP \fBPATH\fP
192 \fI/bin:/usr/bin:/sbin:/usr/sbin\fP
193 .IP \fBINIT_VERSION\fP
194 As the name says. Useful to determine if a script runs directly from \fBinit\fP.
195 .IP \fBRUNLEVEL\fP
196 The current system runlevel.
197 .IP \fBPREVLEVEL\fP
198 The previous runlevel (useful after a runlevel switch).
199 .IP \fBCONSOLE\fP
200 The system console. This is really inherited from the kernel; however
201 if it is not set \fBinit\fP will set it to \fB/dev/console\fP by default.
202 .SH BOOTFLAGS
203 It is possible to pass a number of flags to \fBinit\fP from the
204 boot monitor (eg. LILO). \fBInit\fP accepts the following flags:
205 .TP 0.5i
206 .B -s, S, single
207 Single user mode boot. In this mode \fI/etc/inittab\fP is
208 examined and the bootup rc scripts are usually run before
209 the single user mode shell is started.
210 .PP
211 .TP 0.5i
212 .B 1-5
213 Runlevel to boot into.
214 .PP
215 .TP 0.5i
216 .B -b, emergency
217 Boot directly into a single user shell without running any
218 other startup scripts.
219 .PP
220 .TP 0.5i
221 .B -a, auto
222 The LILO boot loader adds the word "auto" to the command line if it
223 booted the kernel with the default command line (without user intervention).
224 If this is found \fBinit\fP sets the "AUTOBOOT" environment
225 variable to "yes". Note that you cannot use this for any security
226 measures - of course the user could specify "auto" or \-a on the
227 command line manually.
228 .PP
229 .TP 0.5i
230 .BI "-z " xxx
231 The argument to \fB-z\fP is ignored. You can use this to expand the command
232 line a bit, so that it takes some more space on the stack. \fBInit\fP
233 can then manipulate the command line so that \fBps\fP(1) shows
234 the current runlevel.
235 .PP
236 .SH INTERFACE
237 Init listens on a \fIfifo\fP in /dev, \fI/dev/initctl\fP, for messages.
238 \fBTelinit\fP uses this to communicate with init. The interface is not
239 very well documented or finished. Those interested should study the
240 \fIinitreq.h\fP file in the \fIsrc/\fP subdirectory of the \fBinit\fP
241 source code tar archive.
242 .SH SIGNALS
243 Init reacts to several signals:
244 .TP 0.5i
245 .B SIGHUP
246 Has the same effect as \fBtelinit q\fP.
247 .PP
248 .TP 0.5i
249 .B SIGUSR1
250 On receipt of this signals, init closes and re-opens its control fifo,
251 \fB/dev/initctl\fP. Useful for bootscripts when /dev is remounted.
252 .TP 0.5i
253 .B SIGINT
254 Normally the kernel sends this signal to init when CTRL-ALT-DEL is
255 pressed. It activates the \fIctrlaltdel\fP action.
256 .TP 0.5i
257 .B SIGWINCH
258 The kernel sends this signal when the \fIKeyboardSignal\fP key is hit.
259 It activates the \fIkbrequest\fP action.
260 \"{{{ Conforming to
261 .SH CONFORMING TO
262 \fBInit\fP is compatible with the System V init. It works closely
263 together with the scripts in the directories
264 \fI/etc/init.d\fP and \fI/etc/rc{runlevel}.d\fP.
265 If your system uses this convention, there should be a \fIREADME\fP
266 file in the directory \fI/etc/init.d\fP explaining how these scripts work.
267 .\"}}}
268 .\"{{{ Files
269 .SH FILES
270 .nf
271 /etc/inittab
272 /etc/initscript
273 /dev/console
274 /var/run/utmp
275 /var/log/wtmp
276 /dev/initctl
277 .fi
278 .\"}}}
279 .\"{{{ Warnings
280 .SH WARNINGS
281 \fBInit\fP assumes that processes and descendants of processes
282 remain in the same process group which was originally created
283 for them. If the processes change their group, \fBinit\fP can't
284 kill them and you may end up with two processes reading from one
285 terminal line.
286 .\"}}}
287 .\"{{{ Diagnostics
288 .SH DIAGNOSTICS
289 If \fBinit\fP finds that it is continuously respawning an entry
290 more than 10 times in 2 minutes, it will assume that there is an error
291 in the command string, generate an error message on the system console,
292 and refuse to respawn this entry until either 5 minutes has elapsed or
293 it receives a signal. This prevents it from eating up system resources
294 when someone makes a typographical error in the \fB/etc/inittab\fP file
295 or the program for the entry is removed.
296 .\"}}}
297 .\"{{{ Author
298 .SH AUTHOR
299 Miquel van Smoorenburg (miquels@cistron.nl), initial manual
300 page by Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.de).
301 .\"}}}
302 .\"{{{ See also
303 .SH "SEE ALSO"
304 .BR getty (1),
305 .BR login (1),
306 .BR sh (1),
307 .BR runlevel (8),
308 .BR shutdown(8),
309 .BR kill (1),
310 .BR inittab (5),
311 .BR initscript (5),
312 .BR utmp (5)
313 .\"}}}