diff options
Diffstat (limited to 'man/man4/initrd.4')
| -rw-r--r-- | man/man4/initrd.4 | 479 |
1 files changed, 479 insertions, 0 deletions
diff --git a/man/man4/initrd.4 b/man/man4/initrd.4 new file mode 100644 index 000000000..6c63d6b13 --- /dev/null +++ b/man/man4/initrd.4 @@ -0,0 +1,479 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" If the you wish to distribute versions of this work under other +.\" conditions than the above, please contact the author(s) at the following +.\" for permission: +.\" +.\" John S. Kallal - +.\" email: <kallal@voicenet.com> +.\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA +.\" phone: (302)654-5478 +.\" +.\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ +.TH initrd 4 (date) "Linux man-pages (unreleased)" +.SH NAME +initrd \- boot loader initialized RAM disk +.SH CONFIGURATION +.I /dev/initrd +is a read-only block device assigned +major number 1 and minor number 250. +Typically +.I /dev/initrd +is owned by +root:disk +with mode 0400 (read access by root only). +If the Linux system does not have +.I /dev/initrd +already created, it can be created with the following commands: +.P +.in +4n +.EX +mknod \-m 400 /dev/initrd b 1 250 +chown root:disk /dev/initrd +.EE +.in +.P +Also, support for both "RAM disk" and "Initial RAM disk" +(e.g., +.B CONFIG_BLK_DEV_RAM=y +and +.BR CONFIG_BLK_DEV_INITRD=y ) +must be compiled directly into the Linux kernel to use +.IR /dev/initrd . +When using +.IR /dev/initrd , +the RAM disk driver cannot be loaded as a module. +.\" +.\" +.\" +.SH DESCRIPTION +The special file +.I /dev/initrd +is a read-only block device. +This device is a RAM disk that is initialized (e.g., loaded) +by the boot loader before the kernel is started. +The kernel then can use +.IR /dev/initrd "'s" +contents for a two-phase system boot-up. +.P +In the first boot-up phase, the kernel starts up +and mounts an initial root filesystem from the contents of +.I /dev/initrd +(e.g., RAM disk initialized by the boot loader). +In the second phase, additional drivers or other modules +are loaded from the initial root device's contents. +After loading the additional modules, a new root filesystem +(i.e., the normal root filesystem) is mounted from a +different device. +.\" +.\" +.\" +.SS Boot-up operation +When booting up with +.BR initrd , +the system boots as follows: +.IP (1) 5 +The boot loader loads the kernel program and +.IR /dev/initrd 's +contents into memory. +.IP (2) +On kernel startup, +the kernel uncompresses and copies the contents of the device +.I /dev/initrd +onto device +.I /dev/ram0 +and then frees the memory used by +.IR /dev/initrd . +.IP (3) +The kernel then read-write mounts the device +.I /dev/ram0 +as the initial root filesystem. +.IP (4) +If the indicated normal root filesystem is also the initial +root filesystem (e.g., +.IR /dev/ram0 ) +then the kernel skips to the last step for the usual boot sequence. +.IP (5) +If the executable file +.I /linuxrc +is present in the initial root filesystem, +.I /linuxrc +is executed with UID 0. +(The file +.I /linuxrc +must have executable permission. +The file +.I /linuxrc +can be any valid executable, including a shell script.) +.IP (6) +If +.I /linuxrc +is not executed or when +.I /linuxrc +terminates, the normal root filesystem is mounted. +(If +.I /linuxrc +exits with any filesystems mounted on the initial root +filesystem, then the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP (7) +If the normal root filesystem has a directory +.IR /initrd , +the device +.I /dev/ram0 +is moved from +.I / +to +.IR /initrd . +Otherwise, if the directory +.I /initrd +does not exist, the device +.I /dev/ram0 +is unmounted. +(When moved from +.I / +to +.IR /initrd , +.I /dev/ram0 +is not unmounted and therefore processes can remain running from +.IR /dev/ram0 . +If directory +.I /initrd +does not exist on the normal root filesystem +and any processes remain running from +.I /dev/ram0 +when +.I /linuxrc +exits, the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP (8) +The usual boot sequence (e.g., invocation of +.IR /sbin/init ) +is performed on the normal root filesystem. +.\" +.\" +.\" +.SS Options +The following boot loader options, when used with +.BR initrd , +affect the kernel's boot-up operation: +.TP +.BI initrd= "filename" +Specifies the file to load as the contents of +.IR /dev/initrd . +For +.B LOADLIN +this is a command-line option. +For +.B LILO +you have to use this command in the +.B LILO +configuration file +.IR /etc/lilo.config . +The filename specified with this +option will typically be a gzipped filesystem image. +.TP +.B noinitrd +This boot option disables the two-phase boot-up operation. +The kernel performs the usual boot sequence as if +.I /dev/initrd +was not initialized. +With this option, any contents of +.I /dev/initrd +loaded into memory by the boot loader contents are preserved. +This option permits the contents of +.I /dev/initrd +to be any data and need not be limited to a filesystem image. +However, device +.I /dev/initrd +is read-only and can be read only one time after system startup. +.TP +.BI root= "device-name" +Specifies the device to be used as the normal root filesystem. +For +.B LOADLIN +this is a command-line option. +For +.B LILO +this is a boot time option or +can be used as an option line in the +.B LILO +configuration file +.IR /etc/lilo.config . +The device specified by this option must be a mountable +device having a suitable root filesystem. +.\" +.\" +.\" +.SS Changing the normal root filesystem +By default, +the kernel's settings +(e.g., set in the kernel file with +.BR rdev (8) +or compiled into the kernel file), +or the boot loader option setting +is used for the normal root filesystems. +For an NFS-mounted normal root filesystem, one has to use the +.B nfs_root_name +and +.B nfs_root_addrs +boot options to give the NFS settings. +For more information on NFS-mounted root see the kernel documentation file +.I Documentation/filesystems/nfs/nfsroot.txt +.\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32 +(or +.I Documentation/filesystems/nfsroot.txt +before Linux 2.6.33). +For more information on setting the root filesystem see also the +.B LILO +and +.B LOADLIN +documentation. +.P +It is also possible for the +.I /linuxrc +executable to change the normal root device. +For +.I /linuxrc +to change the normal root device, +.I /proc +must be mounted. +After mounting +.IR /proc , +.I /linuxrc +changes the normal root device by writing into the proc files +.IR /proc/sys/kernel/real\-root\-dev , +.IR /proc/sys/kernel/nfs\-root\-name , +and +.IR /proc/sys/kernel/nfs\-root\-addrs . +For a physical root device, the root device is changed by having +.I /linuxrc +write the new root filesystem device number into +.IR /proc/sys/kernel/real\-root\-dev . +For an NFS root filesystem, the root device is changed by having +.I /linuxrc +write the NFS setting into files +.I /proc/sys/kernel/nfs\-root\-name +and +.I /proc/sys/kernel/nfs\-root\-addrs +and then writing 0xff (e.g., the pseudo-NFS-device number) into file +.IR /proc/sys/kernel/real\-root\-dev . +For example, the following shell command line would change +the normal root device to +.IR /dev/hdb1 : +.P +.in +4n +.EX +echo 0x365 >/proc/sys/kernel/real\-root\-dev +.EE +.in +.P +For an NFS example, the following shell command lines would change the +normal root device to the NFS directory +.I /var/nfsroot +on a local networked NFS server with IP number 193.8.232.7 for a system with +IP number 193.8.232.2 and named "idefix": +.P +.in +4n +.EX +echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name +echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e + >/proc/sys/kernel/nfs\-root\-addrs +echo 255 >/proc/sys/kernel/real\-root\-dev +.EE +.in +.P +.BR Note : +The use of +.I /proc/sys/kernel/real\-root\-dev +to change the root filesystem is obsolete. +See the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +as well as +.BR pivot_root (2) +and +.BR pivot_root (8) +for information on the modern method of changing the root filesystem. +.\" FIXME . Should this manual page describe the pivot_root mechanism? +.\" +.\" +.\" +.SS Usage +The main motivation for implementing +.B initrd +was to allow for modular kernel configuration at system installation. +.P +A possible system installation scenario is as follows: +.IP (1) 5 +The loader program boots from floppy or other media with a minimal kernel +(e.g., support for +.IR /dev/ram , +.IR /dev/initrd , +and the ext2 filesystem) and loads +.I /dev/initrd +with a gzipped version of the initial filesystem. +.IP (2) +The executable +.I /linuxrc +determines what is needed to (1) mount the normal root filesystem +(i.e., device type, device drivers, filesystem) and (2) the +distribution media (e.g., CD-ROM, network, tape, ...). +This can be done by asking the user, by auto-probing, +or by using a hybrid approach. +.IP (3) +The executable +.I /linuxrc +loads the necessary modules from the initial root filesystem. +.IP (4) +The executable +.I /linuxrc +creates and populates the root filesystem. +(At this stage the normal root filesystem does not have to be a +completed system yet.) +.IP (5) +The executable +.I /linuxrc +sets +.IR /proc/sys/kernel/real\-root\-dev , +unmounts +.IR /proc , +the normal root filesystem and any other filesystems +it has mounted, and then terminates. +.IP (6) +The kernel then mounts the normal root filesystem. +.IP (7) +Now that the filesystem is accessible and intact, +the boot loader can be installed. +.IP (8) +The boot loader is configured to load into +.I /dev/initrd +a filesystem with the set of modules that was used to bring up the system. +(e.g., device +.I /dev/ram0 +can be modified, then unmounted, and finally, the image is written from +.I /dev/ram0 +to a file.) +.IP (9) +The system is now bootable and additional installation tasks can be +performed. +.P +The key role of +.I /dev/initrd +in the above is to reuse the configuration data during normal system operation +without requiring initial kernel selection, a large generic kernel or, +recompiling the kernel. +.P +A second scenario is for installations where Linux runs on systems with +different hardware configurations in a single administrative network. +In such cases, it may be desirable to use only a small set of kernels +(ideally only one) and to keep the system-specific part of configuration +information as small as possible. +In this case, create a common file +with all needed modules. +Then, only the +.I /linuxrc +file or a file executed by +.I /linuxrc +would be different. +.P +A third scenario is more convenient recovery disks. +Because information like the location of the root filesystem +partition is not needed at boot time, the system loaded from +.I /dev/initrd +can use a dialog and/or auto-detection followed by a +possible sanity check. +.P +Last but not least, Linux distributions on CD-ROM may use +.B initrd +for easy installation from the CD-ROM. +The distribution can use +.B LOADLIN +to directly load +.I /dev/initrd +from CD-ROM without the need of any floppies. +The distribution could also use a +.B LILO +boot floppy and then bootstrap a bigger RAM disk via +.I /dev/initrd +from the CD-ROM. +.\" +.\" +.\" +.SH FILES +.I /dev/initrd +.br +.I /dev/ram0 +.br +.I /linuxrc +.br +.I /initrd +.\" +.\" +.\" +.SH NOTES +.IP \[bu] 3 +With the current kernel, any filesystems that remain mounted when +.I /dev/ram0 +is moved from +.I / +to +.I /initrd +continue to be accessible. +However, the +.I /proc/mounts +entries are not updated. +.IP \[bu] +With the current kernel, if directory +.I /initrd +does not exist, then +.I /dev/ram0 +will +.B not +be fully unmounted if +.I /dev/ram0 +is used by any process or has any filesystem mounted on it. +If +.I /dev/ram0 +is +.B not +fully unmounted, then +.I /dev/ram0 +will remain in memory. +.IP \[bu] +Users of +.I /dev/initrd +should not depend on the behavior given in the above notes. +The behavior may change in future versions of the Linux kernel. +.\" +.\" +.\" +.\" .SH AUTHORS +.\" The kernel code for device +.\" .BR initrd +.\" was written by Werner Almesberger <almesber@lrc.epfl.ch> and +.\" Hans Lermen <lermen@elserv.ffm.fgan.de>. +.\" The code for +.\" .BR initrd +.\" was added to the baseline Linux kernel in development version 1.3.73. +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ram (4), +.BR freeramdisk (8), +.BR rdev (8) +.P +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +in the Linux kernel source tree, the LILO documentation, +the LOADLIN documentation, the SYSLINUX documentation |