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