Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 479 insertions, 0 deletions

diff --git a/man/man4/initrd.4 b/man/man4/initrd.4
new file mode 100644
index 0000000..099aeb3
--- /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 2024-05-02 "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