1initrd(4)                  Kernel Interfaces Manual                  initrd(4)
2
3
4

NAME

6       initrd - boot loader initialized RAM disk
7

CONFIGURATION

9       /dev/initrd is a read-only block device assigned major number 1 and mi‐
10       nor number 250.  Typically /dev/initrd is owned by root:disk with  mode
11       0400  (read  access  by  root only).  If the Linux system does not have
12       /dev/initrd already created, it can be created with the following  com‐
13       mands:
14
15           mknod -m 400 /dev/initrd b 1 250
16           chown root:disk /dev/initrd
17
18       Also,  support  for  both "RAM disk" and "Initial RAM disk" (e.g., CON‐
19       FIG_BLK_DEV_RAM=y and CONFIG_BLK_DEV_INITRD=y)  must  be  compiled  di‐
20       rectly  into the Linux kernel to use /dev/initrd.  When using /dev/ini‐
21       trd, the RAM disk driver cannot be loaded as a module.
22

DESCRIPTION

24       The special file /dev/initrd is a read-only block device.  This  device
25       is a RAM disk that is initialized (e.g., loaded) by the boot loader be‐
26       fore the kernel is started.  The kernel then can use /dev/initrd's con‐
27       tents for a two-phase system boot-up.
28
29       In  the first boot-up phase, the kernel starts up and mounts an initial
30       root filesystem from the contents of /dev/initrd (e.g., RAM  disk  ini‐
31       tialized  by the boot loader).  In the second phase, additional drivers
32       or other modules are loaded from the initial  root  device's  contents.
33       After  loading the additional modules, a new root filesystem (i.e., the
34       normal root filesystem) is mounted from a different device.
35
36   Boot-up operation
37       When booting up with initrd, the system boots as follows:
38
39       (1)  The boot loader loads the kernel program  and  /dev/initrd's  con‐
40            tents into memory.
41
42       (2)  On kernel startup, the kernel uncompresses and copies the contents
43            of the device /dev/initrd onto device /dev/ram0 and then frees the
44            memory used by /dev/initrd.
45
46       (3)  The kernel then read-write mounts the device /dev/ram0 as the ini‐
47            tial root filesystem.
48
49       (4)  If the indicated normal root filesystem is also the  initial  root
50            filesystem  (e.g.,  /dev/ram0)  then  the kernel skips to the last
51            step for the usual boot sequence.
52
53       (5)  If the executable file /linuxrc is present  in  the  initial  root
54            filesystem,  /linuxrc  is executed with UID 0.  (The file /linuxrc
55            must have executable permission.  The file  /linuxrc  can  be  any
56            valid executable, including a shell script.)
57
58       (6)  If  /linuxrc is not executed or when /linuxrc terminates, the nor‐
59            mal root filesystem is  mounted.   (If  /linuxrc  exits  with  any
60            filesystems  mounted  on the initial root filesystem, then the be‐
61            havior of the kernel is UNSPECIFIED.  See the  NOTES  section  for
62            the current kernel behavior.)
63
64       (7)  If  the normal root filesystem has a directory /initrd, the device
65            /dev/ram0 is moved from / to /initrd.  Otherwise, if the directory
66            /initrd  does not exist, the device /dev/ram0 is unmounted.  (When
67            moved from / to /initrd, /dev/ram0 is not unmounted and  therefore
68            processes can remain running from /dev/ram0.  If directory /initrd
69            does not exist on the normal root filesystem and any processes re‐
70            main  running  from /dev/ram0 when /linuxrc exits, the behavior of
71            the kernel is UNSPECIFIED.  See the NOTES section for the  current
72            kernel behavior.)
73
74       (8)  The  usual  boot sequence (e.g., invocation of /sbin/init) is per‐
75            formed on the normal root filesystem.
76
77   Options
78       The following boot loader options, when used with  initrd,  affect  the
79       kernel's boot-up operation:
80
81       initrd=filename
82              Specifies  the file to load as the contents of /dev/initrd.  For
83              LOADLIN this is a command-line option.  For LILO you have to use
84              this  command  in  the LILO configuration file /etc/lilo.config.
85              The filename specified with this  option  will  typically  be  a
86              gzipped filesystem image.
87
88       noinitrd
89              This  boot option disables the two-phase boot-up operation.  The
90              kernel performs the usual boot sequence as  if  /dev/initrd  was
91              not  initialized.  With this option, any contents of /dev/initrd
92              loaded into memory by the boot loader  contents  are  preserved.
93              This  option  permits the contents of /dev/initrd to be any data
94              and need not be limited to a filesystem image.  However,  device
95              /dev/initrd  is  read-only  and  can be read only one time after
96              system startup.
97
98       root=device-name
99              Specifies the device to be used as the normal  root  filesystem.
100              For  LOADLIN  this is a command-line option.  For LILO this is a
101              boot time option or can be used as an option line  in  the  LILO
102              configuration  file  /etc/lilo.config.   The device specified by
103              this option must be a mountable device having  a  suitable  root
104              filesystem.
105
106   Changing the normal root filesystem
107       By  default,  the  kernel's settings (e.g., set in the kernel file with
108       rdev(8) or compiled into the kernel file), or the  boot  loader  option
109       setting  is  used  for the normal root filesystems.  For an NFS-mounted
110       normal  root  filesystem,  one  has  to  use  the   nfs_root_name   and
111       nfs_root_addrs  boot options to give the NFS settings.  For more infor‐
112       mation on NFS-mounted root see the kernel documentation file Documenta‐
113       tion/filesystems/nfs/nfsroot.txt   (or   Documentation/filesystems/nfs‐
114       root.txt before Linux 2.6.33).  For more  information  on  setting  the
115       root filesystem see also the LILO and LOADLIN documentation.
116
117       It  is  also  possible for the /linuxrc executable to change the normal
118       root device.  For /linuxrc to change the normal root device, /proc must
119       be mounted.  After mounting /proc, /linuxrc changes the normal root de‐
120       vice by writing into  the  proc  files  /proc/sys/kernel/real-root-dev,
121       /proc/sys/kernel/nfs-root-name,   and  /proc/sys/kernel/nfs-root-addrs.
122       For a physical root device, the root device is changed by having  /lin‐
123       uxrc  write  the  new root filesystem device number into /proc/sys/ker‐
124       nel/real-root-dev.  For an NFS root  filesystem,  the  root  device  is
125       changed   by   having   /linuxrc  write  the  NFS  setting  into  files
126       /proc/sys/kernel/nfs-root-name and /proc/sys/kernel/nfs-root-addrs  and
127       then  writing  0xff  (e.g.,  the  pseudo-NFS-device  number)  into file
128       /proc/sys/kernel/real-root-dev.  For example, the following shell  com‐
129       mand line would change the normal root device to /dev/hdb1:
130
131           echo 0x365 >/proc/sys/kernel/real-root-dev
132
133       For  an NFS example, the following shell command lines would change the
134       normal root device to the NFS directory /var/nfsroot on  a  local  net‐
135       worked  NFS server with IP number 193.8.232.7 for a system with IP num‐
136       ber 193.8.232.2 and named "idefix":
137
138           echo /var/nfsroot >/proc/sys/kernel/nfs-root-name
139           echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \
140               >/proc/sys/kernel/nfs-root-addrs
141           echo 255 >/proc/sys/kernel/real-root-dev
142
143       Note: The use of  /proc/sys/kernel/real-root-dev  to  change  the  root
144       filesystem  is  obsolete.   See the Linux kernel source file Documenta‐
145       tion/admin-guide/initrd.rst (or Documentation/initrd.txt  before  Linux
146       4.10) as well as pivot_root(2) and pivot_root(8) for information on the
147       modern method of changing the root filesystem.
148
149   Usage
150       The main motivation for implementing initrd was to  allow  for  modular
151       kernel configuration at system installation.
152
153       A possible system installation scenario is as follows:
154
155       (1)  The loader program boots from floppy or other media with a minimal
156            kernel (e.g., support for  /dev/ram,  /dev/initrd,  and  the  ext2
157            filesystem)  and  loads  /dev/initrd with a gzipped version of the
158            initial filesystem.
159
160       (2)  The executable /linuxrc determines what is needed to (1) mount the
161            normal   root  filesystem  (i.e.,  device  type,  device  drivers,
162            filesystem) and (2) the distribution media (e.g., CD-ROM, network,
163            tape, ...).  This can be done by asking the user, by auto-probing,
164            or by using a hybrid approach.
165
166       (3)  The executable /linuxrc loads the necessary modules from the  ini‐
167            tial root filesystem.
168
169       (4)  The executable /linuxrc creates and populates the root filesystem.
170            (At this stage the normal root filesystem does not have  to  be  a
171            completed system yet.)
172
173       (5)  The  executable  /linuxrc sets /proc/sys/kernel/real-root-dev, un‐
174            mounts /proc, the normal root filesystem and any other filesystems
175            it has mounted, and then terminates.
176
177       (6)  The kernel then mounts the normal root filesystem.
178
179       (7)  Now  that the filesystem is accessible and intact, the boot loader
180            can be installed.
181
182       (8)  The boot loader is configured to load into /dev/initrd a  filesys‐
183            tem  with the set of modules that was used to bring up the system.
184            (e.g., device /dev/ram0 can be modified, then unmounted,  and  fi‐
185            nally, the image is written from /dev/ram0 to a file.)
186
187       (9)  The  system  is now bootable and additional installation tasks can
188            be performed.
189
190       The key role of /dev/initrd in the above is to reuse the  configuration
191       data  during  normal  system operation without requiring initial kernel
192       selection, a large generic kernel or, recompiling the kernel.
193
194       A second scenario is for installations where Linux runs on systems with
195       different  hardware  configurations in a single administrative network.
196       In such cases, it may be desirable to use only a small set  of  kernels
197       (ideally  only  one) and to keep the system-specific part of configura‐
198       tion information as small as possible.  In this case, create  a  common
199       file  with  all needed modules.  Then, only the /linuxrc file or a file
200       executed by /linuxrc would be different.
201
202       A third scenario is more convenient recovery disks.   Because  informa‐
203       tion  like  the location of the root filesystem partition is not needed
204       at boot time, the system loaded  from  /dev/initrd  can  use  a  dialog
205       and/or auto-detection followed by a possible sanity check.
206
207       Last  but  not  least, Linux distributions on CD-ROM may use initrd for
208       easy installation from the CD-ROM.  The distribution can use LOADLIN to
209       directly load /dev/initrd from CD-ROM without the need of any floppies.
210       The distribution could also use a LILO boot floppy and then bootstrap a
211       bigger RAM disk via /dev/initrd from the CD-ROM.
212

FILES

214       /dev/initrd
215       /dev/ram0
216       /linuxrc
217       /initrd
218

NOTES

220       •  With  the  current  kernel, any filesystems that remain mounted when
221          /dev/ram0 is moved from / to  /initrd  continue  to  be  accessible.
222          However, the /proc/mounts entries are not updated.
223
224       •  With  the  current kernel, if directory /initrd does not exist, then
225          /dev/ram0 will not be fully unmounted if /dev/ram0 is  used  by  any
226          process  or  has  any filesystem mounted on it.  If /dev/ram0 is not
227          fully unmounted, then /dev/ram0 will remain in memory.
228
229       •  Users of /dev/initrd should not depend on the behavior given in  the
230          above  notes.   The  behavior  may  change in future versions of the
231          Linux kernel.
232

SEE ALSO

234       chown(1), mknod(1), ram(4), freeramdisk(8), rdev(8)
235
236       Documentation/admin-guide/initrd.rst (or  Documentation/initrd.txt  be‐
237       fore  Linux  4.10) in the Linux kernel source tree, the LILO documenta‐
238       tion, the LOADLIN documentation, the SYSLINUX documentation
239
240
241
242Linux man-pages 6.05              2023-02-05                         initrd(4)
Impressum