| blob | 20d5618294bef2c76b70f743b9ff1e37f34becff |
1 .\" This man-page is Copyright (C) 1997 John S. Kallal
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" If the you wish to distribute versions of this work under other
6 .\" conditions than the above, please contact the author(s) at the following
7 .\" for permission:
8 .\"
9 .\" John S. Kallal -
10 .\" email: <kallal@voicenet.com>
11 .\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA
12 .\" phone: (302)654-5478
13 .\"
14 .\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $
15 .TH initrd 4 (date) "Linux man-pages (unreleased)"
16 .SH NAME
17 initrd \- boot loader initialized RAM disk
18 .SH CONFIGURATION
19 .I /dev/initrd
20 is a read-only block device assigned
21 major number 1 and minor number 250.
22 Typically
23 .I /dev/initrd
24 is owned by
25 root:disk
26 with mode 0400 (read access by root only).
27 If the Linux system does not have
28 .I /dev/initrd
29 already created, it can be created with the following commands:
30 .PP
31 .in +4n
32 .EX
33 mknod \-m 400 /dev/initrd b 1 250
34 chown root:disk /dev/initrd
35 .EE
36 .in
37 .PP
38 Also, support for both "RAM disk" and "Initial RAM disk"
39 (e.g.,
40 .B CONFIG_BLK_DEV_RAM=y
41 and
42 .BR CONFIG_BLK_DEV_INITRD=y )
43 must be compiled directly into the Linux kernel to use
44 .IR /dev/initrd .
45 When using
46 .IR /dev/initrd ,
47 the RAM disk driver cannot be loaded as a module.
48 .\"
49 .\"
50 .\"
51 .SH DESCRIPTION
52 The special file
53 .I /dev/initrd
54 is a read-only block device.
55 This device is a RAM disk that is initialized (e.g., loaded)
56 by the boot loader before the kernel is started.
57 The kernel then can use
58 .IR /dev/initrd "'s"
59 contents for a two-phase system boot-up.
60 .PP
61 In the first boot-up phase, the kernel starts up
62 and mounts an initial root filesystem from the contents of
63 .I /dev/initrd
64 (e.g., RAM disk initialized by the boot loader).
65 In the second phase, additional drivers or other modules
66 are loaded from the initial root device's contents.
67 After loading the additional modules, a new root filesystem
68 (i.e., the normal root filesystem) is mounted from a
69 different device.
70 .\"
71 .\"
72 .\"
73 .SS Boot-up operation
74 When booting up with
75 .BR initrd ,
76 the system boots as follows:
77 .IP (1) 5
78 The boot loader loads the kernel program and
79 .IR /dev/initrd 's
80 contents into memory.
81 .IP (2)
82 On kernel startup,
83 the kernel uncompresses and copies the contents of the device
84 .I /dev/initrd
85 onto device
86 .I /dev/ram0
87 and then frees the memory used by
88 .IR /dev/initrd .
89 .IP (3)
90 The kernel then read-write mounts the device
91 .I /dev/ram0
92 as the initial root filesystem.
93 .IP (4)
94 If the indicated normal root filesystem is also the initial
95 root filesystem (e.g.,
96 .IR /dev/ram0 )
97 then the kernel skips to the last step for the usual boot sequence.
98 .IP (5)
99 If the executable file
100 .I /linuxrc
101 is present in the initial root filesystem,
102 .I /linuxrc
103 is executed with UID 0.
104 (The file
105 .I /linuxrc
106 must have executable permission.
107 The file
108 .I /linuxrc
109 can be any valid executable, including a shell script.)
110 .IP (6)
111 If
112 .I /linuxrc
113 is not executed or when
114 .I /linuxrc
115 terminates, the normal root filesystem is mounted.
116 (If
117 .I /linuxrc
118 exits with any filesystems mounted on the initial root
119 filesystem, then the behavior of the kernel is
120 .BR UNSPECIFIED .
121 See the NOTES section for the current kernel behavior.)
122 .IP (7)
123 If the normal root filesystem has a directory
124 .IR /initrd ,
125 the device
126 .I /dev/ram0
127 is moved from
128 .I /
129 to
130 .IR /initrd .
131 Otherwise, if the directory
132 .I /initrd
133 does not exist, the device
134 .I /dev/ram0
135 is unmounted.
136 (When moved from
137 .I /
138 to
139 .IR /initrd ,
140 .I /dev/ram0
141 is not unmounted and therefore processes can remain running from
142 .IR /dev/ram0 .
143 If directory
144 .I /initrd
145 does not exist on the normal root filesystem
146 and any processes remain running from
147 .I /dev/ram0
148 when
149 .I /linuxrc
150 exits, the behavior of the kernel is
151 .BR UNSPECIFIED .
152 See the NOTES section for the current kernel behavior.)
153 .IP (8)
154 The usual boot sequence (e.g., invocation of
155 .IR /sbin/init )
156 is performed on the normal root filesystem.
157 .\"
158 .\"
159 .\"
160 .SS Options
161 The following boot loader options, when used with
162 .BR initrd ,
163 affect the kernel's boot-up operation:
164 .TP
165 .BI initrd= "filename"
166 Specifies the file to load as the contents of
167 .IR /dev/initrd .
168 For
169 .B LOADLIN
170 this is a command-line option.
171 For
172 .B LILO
173 you have to use this command in the
174 .B LILO
175 configuration file
176 .IR /etc/lilo.config .
177 The filename specified with this
178 option will typically be a gzipped filesystem image.
179 .TP
180 .B noinitrd
181 This boot option disables the two-phase boot-up operation.
182 The kernel performs the usual boot sequence as if
183 .I /dev/initrd
184 was not initialized.
185 With this option, any contents of
186 .I /dev/initrd
187 loaded into memory by the boot loader contents are preserved.
188 This option permits the contents of
189 .I /dev/initrd
190 to be any data and need not be limited to a filesystem image.
191 However, device
192 .I /dev/initrd
193 is read-only and can be read only one time after system startup.
194 .TP
195 .BI root= "device-name"
196 Specifies the device to be used as the normal root filesystem.
197 For
198 .B LOADLIN
199 this is a command-line option.
200 For
201 .B LILO
202 this is a boot time option or
203 can be used as an option line in the
204 .B LILO
205 configuration file
206 .IR /etc/lilo.config .
207 The device specified by this option must be a mountable
208 device having a suitable root filesystem.
209 .\"
210 .\"
211 .\"
212 .SS Changing the normal root filesystem
213 By default,
214 the kernel's settings
215 (e.g., set in the kernel file with
216 .BR rdev (8)
217 or compiled into the kernel file),
218 or the boot loader option setting
219 is used for the normal root filesystems.
220 For an NFS-mounted normal root filesystem, one has to use the
221 .B nfs_root_name
222 and
223 .B nfs_root_addrs
224 boot options to give the NFS settings.
225 For more information on NFS-mounted root see the kernel documentation file
226 .I Documentation/filesystems/nfs/nfsroot.txt
227 .\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32
228 (or
229 .I Documentation/filesystems/nfsroot.txt
230 before Linux 2.6.33).
231 For more information on setting the root filesystem see also the
232 .B LILO
233 and
234 .B LOADLIN
235 documentation.
236 .PP
237 It is also possible for the
238 .I /linuxrc
239 executable to change the normal root device.
240 For
241 .I /linuxrc
242 to change the normal root device,
243 .I /proc
244 must be mounted.
245 After mounting
246 .IR /proc ,
247 .I /linuxrc
248 changes the normal root device by writing into the proc files
249 .IR /proc/sys/kernel/real\-root\-dev ,
250 .IR /proc/sys/kernel/nfs\-root\-name ,
251 and
252 .IR /proc/sys/kernel/nfs\-root\-addrs .
253 For a physical root device, the root device is changed by having
254 .I /linuxrc
255 write the new root filesystem device number into
256 .IR /proc/sys/kernel/real\-root\-dev .
257 For an NFS root filesystem, the root device is changed by having
258 .I /linuxrc
259 write the NFS setting into files
260 .I /proc/sys/kernel/nfs\-root\-name
261 and
262 .I /proc/sys/kernel/nfs\-root\-addrs
263 and then writing 0xff (e.g., the pseudo-NFS-device number) into file
264 .IR /proc/sys/kernel/real\-root\-dev .
265 For example, the following shell command line would change
266 the normal root device to
267 .IR /dev/hdb1 :
268 .PP
269 .in +4n
270 .EX
271 echo 0x365 >/proc/sys/kernel/real\-root\-dev
272 .EE
273 .in
274 .PP
275 For an NFS example, the following shell command lines would change the
276 normal root device to the NFS directory
277 .I /var/nfsroot
278 on a local networked NFS server with IP number 193.8.232.7 for a system with
279 IP number 193.8.232.2 and named "idefix":
280 .PP
281 .in +4n
282 .EX
283 echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name
284 echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e
285 >/proc/sys/kernel/nfs\-root\-addrs
286 echo 255 >/proc/sys/kernel/real\-root\-dev
287 .EE
288 .in
289 .PP
290 .BR Note :
291 The use of
292 .I /proc/sys/kernel/real\-root\-dev
293 to change the root filesystem is obsolete.
294 See the Linux kernel source file
295 .I Documentation/admin\-guide/initrd.rst
296 .\" commit 9d85025b0418163fae079c9ba8f8445212de8568
297 (or
298 .I Documentation/initrd.txt
299 before Linux 4.10)
300 as well as
301 .BR pivot_root (2)
302 and
303 .BR pivot_root (8)
304 for information on the modern method of changing the root filesystem.
305 .\" FIXME . Should this manual page describe the pivot_root mechanism?
306 .\"
307 .\"
308 .\"
309 .SS Usage
310 The main motivation for implementing
311 .B initrd
312 was to allow for modular kernel configuration at system installation.
313 .PP
314 A possible system installation scenario is as follows:
315 .IP (1) 5
316 The loader program boots from floppy or other media with a minimal kernel
317 (e.g., support for
318 .IR /dev/ram ,
319 .IR /dev/initrd ,
320 and the ext2 filesystem) and loads
321 .I /dev/initrd
322 with a gzipped version of the initial filesystem.
323 .IP (2)
324 The executable
325 .I /linuxrc
326 determines what is needed to (1) mount the normal root filesystem
327 (i.e., device type, device drivers, filesystem) and (2) the
328 distribution media (e.g., CD-ROM, network, tape, ...).
329 This can be done by asking the user, by auto-probing,
330 or by using a hybrid approach.
331 .IP (3)
332 The executable
333 .I /linuxrc
334 loads the necessary modules from the initial root filesystem.
335 .IP (4)
336 The executable
337 .I /linuxrc
338 creates and populates the root filesystem.
339 (At this stage the normal root filesystem does not have to be a
340 completed system yet.)
341 .IP (5)
342 The executable
343 .I /linuxrc
344 sets
345 .IR /proc/sys/kernel/real\-root\-dev ,
346 unmounts
347 .IR /proc ,
348 the normal root filesystem and any other filesystems
349 it has mounted, and then terminates.
350 .IP (6)
351 The kernel then mounts the normal root filesystem.
352 .IP (7)
353 Now that the filesystem is accessible and intact,
354 the boot loader can be installed.
355 .IP (8)
356 The boot loader is configured to load into
357 .I /dev/initrd
358 a filesystem with the set of modules that was used to bring up the system.
359 (e.g., device
360 .I /dev/ram0
361 can be modified, then unmounted, and finally, the image is written from
362 .I /dev/ram0
363 to a file.)
364 .IP (9)
365 The system is now bootable and additional installation tasks can be
366 performed.
367 .PP
368 The key role of
369 .I /dev/initrd
370 in the above is to reuse the configuration data during normal system operation
371 without requiring initial kernel selection, a large generic kernel or,
372 recompiling the kernel.
373 .PP
374 A second scenario is for installations where Linux runs on systems with
375 different hardware configurations in a single administrative network.
376 In such cases, it may be desirable to use only a small set of kernels
377 (ideally only one) and to keep the system-specific part of configuration
378 information as small as possible.
379 In this case, create a common file
380 with all needed modules.
381 Then, only the
382 .I /linuxrc
383 file or a file executed by
384 .I /linuxrc
385 would be different.
386 .PP
387 A third scenario is more convenient recovery disks.
388 Because information like the location of the root filesystem
389 partition is not needed at boot time, the system loaded from
390 .I /dev/initrd
391 can use a dialog and/or auto-detection followed by a
392 possible sanity check.
393 .PP
394 Last but not least, Linux distributions on CD-ROM may use
395 .B initrd
396 for easy installation from the CD-ROM.
397 The distribution can use
398 .B LOADLIN
399 to directly load
400 .I /dev/initrd
401 from CD-ROM without the need of any floppies.
402 The distribution could also use a
403 .B LILO
404 boot floppy and then bootstrap a bigger RAM disk via
405 .I /dev/initrd
406 from the CD-ROM.
407 .\"
408 .\"
409 .\"
410 .SH FILES
411 .I /dev/initrd
412 .br
413 .I /dev/ram0
414 .br
415 .I /linuxrc
416 .br
417 .I /initrd
418 .\"
419 .\"
420 .\"
421 .SH NOTES
422 .IP \(bu 3
423 With the current kernel, any filesystems that remain mounted when
424 .I /dev/ram0
425 is moved from
426 .I /
427 to
428 .I /initrd
429 continue to be accessible.
430 However, the
431 .I /proc/mounts
432 entries are not updated.
433 .IP \(bu
434 With the current kernel, if directory
435 .I /initrd
436 does not exist, then
437 .I /dev/ram0
438 will
439 .B not
440 be fully unmounted if
441 .I /dev/ram0
442 is used by any process or has any filesystem mounted on it.
443 If
444 .I /dev/ram0
445 is
446 .B not
447 fully unmounted, then
448 .I /dev/ram0
449 will remain in memory.
450 .IP \(bu
451 Users of
452 .I /dev/initrd
453 should not depend on the behavior given in the above notes.
454 The behavior may change in future versions of the Linux kernel.
455 .\"
456 .\"
457 .\"
458 .\" .SH AUTHORS
459 .\" The kernel code for device
460 .\" .BR initrd
461 .\" was written by Werner Almesberger <almesber@lrc.epfl.ch> and
462 .\" Hans Lermen <lermen@elserv.ffm.fgan.de>.
463 .\" The code for
464 .\" .BR initrd
465 .\" was added to the baseline Linux kernel in development version 1.3.73.
466 .SH SEE ALSO
467 .BR chown (1),
468 .BR mknod (1),
469 .BR ram (4),
470 .BR freeramdisk (8),
471 .BR rdev (8)
472 .PP
473 .I Documentation/admin\-guide/initrd.rst
474 .\" commit 9d85025b0418163fae079c9ba8f8445212de8568
475 (or
476 .I Documentation/initrd.txt
477 before Linux 4.10)
478 in the Linux kernel source tree, the LILO documentation,
479 the LOADLIN documentation, the SYSLINUX documentation