1INITRD(4)                  Linux Programmer's 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  contents
40          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 step
51          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 valid
56          executable, including a shell script.)
57
58       6. If  /linuxrc is not executed or when /linuxrc terminates, the normal
59          root filesystem is mounted.  (If /linuxrc exits with any filesystems
60          mounted  on  the  initial  root filesystem, then the behavior of the
61          kernel is UNSPECIFIED.  See the NOTES section for the current kernel
62          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 the
71          kernel is UNSPECIFIED.  See the NOTES section for the current kernel
72          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 ini‐
158          tial 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, filesys‐
162          tem) and (2) the distribution media (e.g.,  CD-ROM,  network,  tape,
163          ...).   This  can be done by asking the user, by auto-probing, or by
164          using a hybrid approach.
165
166       3. The executable /linuxrc loads the necessary modules from the initial
167          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 com‐
171          pleted 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  filesystem
183          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 be
188          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       1. 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       2. 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       3. 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

COLOPHON

241       This page is part of release 5.12 of the Linux  man-pages  project.   A
242       description  of  the project, information about reporting bugs, and the
243       latest    version    of    this    page,    can     be     found     at
244       https://www.kernel.org/doc/man-pages/.
245
246
247
248Linux                             2021-03-22                         INITRD(4)
Impressum