| .\" -*- nroff -*- |
| .\" This man-page is Copyright (C) 1997 John S. Kallal |
| .\" |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and author(s) of this work. |
| .\" |
| .\" 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 2010-09-04 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| initrd \- boot loader initialized RAM disk |
| .SH CONFIGURATION |
| The |
| .I /dev/initrd |
| is a read-only block device assigned |
| major number 1 and minor number 250. |
| Typically |
| .I /dev/initrd |
| is owned by |
| .I 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: |
| .nf |
| \fB |
| mknod \-m 400 /dev/initrd b 1 250 |
| chown root:disk /dev/initrd |
| \fP |
| .fi |
| .PP |
| Also, support for both "RAM disk" and "Initial RAM disk" |
| (e.g., |
| .BR 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. |
| .PP |
| In the first boot-up phase, the kernel starts up |
| and mounts an initial root file-system 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 file system |
| (i.e., the normal root file system) is mounted from a |
| different device. |
| .\" |
| .\" |
| .\" |
| .SS "Boot-up Operation" |
| When booting up with |
| .BR initrd , |
| the system boots as follows: |
| .IP 1. 3 |
| 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 file system. |
| .IP 4. |
| If the indicated normal root file system is also the initial |
| root file-system (e.g., |
| .IR /dev/ram0 ) |
| then the kernel skips to the last step for the usual boot sequence. |
| .IP 5. |
| If the executable file |
| .IR /linuxrc |
| is present in the initial root file-system, |
| .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 file system is mounted. |
| (If |
| .I /linuxrc |
| exits with any file-systems mounted on the initial root |
| file-system, then the behavior of the kernel is |
| .BR UNSPECIFIED . |
| See the NOTES section for the current kernel behavior.) |
| .IP 7. |
| If the normal root file system has a directory |
| .IR /initrd , |
| the device |
| .I /dev/ram0 |
| is moved from |
| .IR / |
| to |
| .IR /initrd . |
| Otherwise if the directory |
| .IR /initrd |
| does not exist, the device |
| .I /dev/ram0 |
| is unmounted. |
| (When moved from |
| .IR / |
| 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 file system |
| and any processes remain running from |
| .IR /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 file system. |
| .\" |
| .\" |
| .\" |
| .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 file-system image. |
| .TP |
| .I 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 file system 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 file system. |
| 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 the this option must be a mountable |
| device having a suitable root file-system. |
| .\" |
| .\" |
| .\" |
| .SS "Changing the Normal Root File System" |
| 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 file systems. |
| For an NFS-mounted normal root file system, 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 |
| .BR Documentation/filesystems/nfsroot.txt . |
| For more information on setting the root file system see also the |
| .BR LILO |
| and |
| .BR LOADLIN |
| documentation. |
| .PP |
| It is also possible for the |
| .I /linuxrc |
| executable to change the normal root device. |
| For |
| .I /linuxrc |
| to change the normal root device, |
| .IR /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 file system device number into |
| .IR /proc/sys/kernel/real-root-dev . |
| For an NFS root file system, the root device is changed by having |
| .I /linuxrc |
| write the NFS setting into files |
| .IR /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 : |
| .nf |
| |
| echo 0x365 >/proc/sys/kernel/real-root-dev |
| |
| .fi |
| 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": |
| .nf |
| |
| echo /var/nfsroot >/proc/sys/kernel/nfs-root-name |
| echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \\ |
| >/proc/sys/kernel/nfs-root-addrs |
| echo 255 >/proc/sys/kernel/real-root-dev |
| .fi |
| |
| .BR Note : |
| The use of |
| .I /proc/sys/kernel/real-root-dev |
| to change the root file system is obsolete. |
| See the Linux kernel source file |
| .I Documentation/initrd.txt |
| as well as |
| .BR pivot_root (2) |
| and |
| .BR pivot_root (8) |
| for information on the modern method of changing the root file system. |
| .\" FIXME the manual page should describe the pivot_root mechanism. |
| .\" |
| .\" |
| .\" |
| .SS Usage |
| The main motivation for implementing |
| .B initrd |
| was to allow for modular kernel configuration at system installation. |
| .PP |
| A possible system installation scenario is as follows: |
| .IP 1. 3 |
| 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 file-system) and loads |
| .IR /dev/initrd |
| with a gzipped version of the initial file-system. |
| .IP 2. |
| The executable |
| .I /linuxrc |
| determines what is needed to (1) mount the normal root file-system |
| (i.e., device type, device drivers, file system) 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 file-system. |
| .IP 4. |
| The executable |
| .I /linuxrc |
| creates and populates the root file system. |
| (At this stage the normal root file system does not have to be a |
| completed system yet.) |
| .IP 5. |
| The executable |
| .IR /linuxrc |
| sets |
| .IR /proc/sys/kernel/real-root-dev , |
| unmount |
| .IR /proc , |
| the normal root file system and any other file |
| systems it has mounted, and then terminates. |
| .IP 6. |
| The kernel then mounts the normal root file system. |
| .IP 7. |
| Now that the file system is accessible and intact, |
| the boot loader can be installed. |
| .IP 8. |
| The boot loader is configured to load into |
| .I /dev/initrd |
| a file system 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. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| A third scenario is more convenient recovery disks. |
| Because information like the location of the root file-system |
| 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. |
| .PP |
| 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 |
| .IR /dev/initrd |
| from the CD-ROM. |
| .\" |
| .\" |
| .\" |
| .SH FILES |
| .I /dev/initrd |
| .br |
| .I /dev/ram0 |
| .br |
| .I /linuxrc |
| .br |
| .I /initrd |
| .\" |
| .\" |
| .\" |
| .SH NOTES |
| .IP 1. 3 |
| With the current kernel, any file systems 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 2. |
| 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 file-system mounted on it. |
| If |
| .IR /dev/ram0 |
| is |
| .B not |
| fully unmounted, then |
| .I /dev/ram0 |
| will remain in memory. |
| .IP 3. |
| Users of |
| .I /dev/initrd |
| should not depend on the behavior give 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) |
| |
| .I Documentation/initrd.txt |
| in the Linux kernel source tree, the LILO documentation, |
| the LOADLIN documentation, the SYSLINUX documentation |