man4/initrd.4

   1 .\" This man-page is Copyright (C) 1997 John S. Kallal
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" If the you wish to distribute versions of this work under other
   6 .\" conditions than the above, please contact the author(s) at the following
   7 .\" for permission:
   8 .\"
   9 .\"  John S. Kallal -
  10 .\"     email: <kallal@voicenet.com>
  11 .\"     mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA
  12 .\"     phone: (302)654-5478
  13 .\"
  14 .\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $
  15 .TH INITRD 4 2021-03-22 "Linux man-pages (unreleased)"
  16 .SH NAME
  17 initrd \- boot loader initialized RAM disk
  18 .SH CONFIGURATION
  19 .I /dev/initrd
  20 is a read-only block device assigned
  21 major number 1 and minor number 250.
  22 Typically
  23 .I /dev/initrd
  24 is owned by
  25 root:disk
  26 with mode 0400 (read access by root only).
  27 If the Linux system does not have
  28 .I /dev/initrd
  29 already created, it can be created with the following commands:
  30 .PP
  31 .in +4n
  32 .EX
  33 mknod \-m 400 /dev/initrd b 1 250
  34 chown root:disk /dev/initrd
  35 .EE
  36 .in
  37 .PP
  38 Also, support for both "RAM disk" and "Initial RAM disk"
  39 (e.g.,
  40 .B CONFIG_BLK_DEV_RAM=y
  41 and
  42 .BR CONFIG_BLK_DEV_INITRD=y )
  43 must be compiled directly into the Linux kernel to use
  44 .IR /dev/initrd .
  45 When using
  46 .IR /dev/initrd ,
  47 the RAM disk driver cannot be loaded as a module.
  48 .\"
  49 .\"
  50 .\"
  51 .SH DESCRIPTION
  52 The special file
  53 .I /dev/initrd
  54 is a read-only block device.
  55 This device is a RAM disk that is initialized (e.g., loaded)
  56 by the boot loader before the kernel is started.
  57 The kernel then can use
  58 .IR /dev/initrd "'s"
  59 contents for a two-phase system boot-up.
  60 .PP
  61 In the first boot-up phase, the kernel starts up
  62 and mounts an initial root filesystem from the contents of
  63 .I /dev/initrd
  64 (e.g., RAM disk initialized by the boot loader).
  65 In the second phase, additional drivers or other modules
  66 are loaded from the initial root device's contents.
  67 After loading the additional modules, a new root filesystem
  68 (i.e., the normal root filesystem) is mounted from a
  69 different device.
  70 .\"
  71 .\"
  72 .\"
  73 .SS Boot-up operation
  74 When booting up with
  75 .BR initrd ,
  76 the system boots as follows:
  77 .IP 1. 3
  78 The boot loader loads the kernel program and
  79 .IR /dev/initrd 's
  80 contents into memory.
  81 .IP 2.
  82 On kernel startup,
  83 the kernel uncompresses and copies the contents of the device
  84 .I /dev/initrd
  85 onto device
  86 .I /dev/ram0
  87 and then frees the memory used by
  88 .IR /dev/initrd .
  89 .IP 3.
  90 The kernel then read-write mounts the device
  91 .I /dev/ram0
  92 as the initial root filesystem.
  93 .IP 4.
  94 If the indicated normal root filesystem is also the initial
  95 root filesystem (e.g.,
  96 .IR /dev/ram0 )
  97 then the kernel skips to the last step for the usual boot sequence.
  98 .IP 5.
  99 If the executable file
 100 .I /linuxrc
 101 is present in the initial root filesystem,
 102 .I /linuxrc
 103 is executed with UID 0.
 104 (The file
 105 .I /linuxrc
 106 must have executable permission.
 107 The file
 108 .I /linuxrc
 109 can be any valid executable, including a shell script.)
 110 .IP 6.
 111 If
 112 .I /linuxrc
 113 is not executed or when
 114 .I /linuxrc
 115 terminates, the normal root filesystem is mounted.
 116 (If
 117 .I /linuxrc
 118 exits with any filesystems mounted on the initial root
 119 filesystem, then the behavior of the kernel is
 120 .BR UNSPECIFIED .
 121 See the NOTES section for the current kernel behavior.)
 122 .IP 7.
 123 If the normal root filesystem has a directory
 124 .IR /initrd ,
 125 the device
 126 .I /dev/ram0
 127 is moved from
 128 .I /
 129 to
 130 .IR /initrd .
 131 Otherwise, if the directory
 132 .I /initrd
 133 does not exist, the device
 134 .I /dev/ram0
 135 is unmounted.
 136 (When moved from
 137 .I /
 138 to
 139 .IR /initrd ,
 140 .I /dev/ram0
 141 is not unmounted and therefore processes can remain running from
 142 .IR /dev/ram0 .
 143 If directory
 144 .I /initrd
 145 does not exist on the normal root filesystem
 146 and any processes remain running from
 147 .I /dev/ram0
 148 when
 149 .I /linuxrc
 150 exits, the behavior of the kernel is
 151 .BR UNSPECIFIED .
 152 See the NOTES section for the current kernel behavior.)
 153 .IP 8.
 154 The usual boot sequence (e.g., invocation of
 155 .IR /sbin/init )
 156 is performed on the normal root filesystem.
 157 .\"
 158 .\"
 159 .\"
 160 .SS Options
 161 The following boot loader options, when used with
 162 .BR initrd ,
 163 affect the kernel's boot-up operation:
 164 .TP
 165 .BI initrd= "filename"
 166 Specifies the file to load as the contents of
 167 .IR /dev/initrd .
 168 For
 169 .B LOADLIN
 170 this is a command-line option.
 171 For
 172 .B LILO
 173 you have to use this command in the
 174 .B LILO
 175 configuration file
 176 .IR /etc/lilo.config .
 177 The filename specified with this
 178 option will typically be a gzipped filesystem image.
 179 .TP
 180 .B noinitrd
 181 This boot option disables the two-phase boot-up operation.
 182 The kernel performs the usual boot sequence as if
 183 .I /dev/initrd
 184 was not initialized.
 185 With this option, any contents of
 186 .I /dev/initrd
 187 loaded into memory by the boot loader contents are preserved.
 188 This option permits the contents of
 189 .I /dev/initrd
 190 to be any data and need not be limited to a filesystem image.
 191 However, device
 192 .I /dev/initrd
 193 is read-only and can be read only one time after system startup.
 194 .TP
 195 .BI root= "device-name"
 196 Specifies the device to be used as the normal root filesystem.
 197 For
 198 .B LOADLIN
 199 this is a command-line option.
 200 For
 201 .B LILO
 202 this is a boot time option or
 203 can be used as an option line in the
 204 .B LILO
 205 configuration file
 206 .IR /etc/lilo.config .
 207 The device specified by this option must be a mountable
 208 device having a suitable root filesystem.
 209 .\"
 210 .\"
 211 .\"
 212 .SS Changing the normal root filesystem
 213 By default,
 214 the kernel's settings
 215 (e.g., set in the kernel file with
 216 .BR rdev (8)
 217 or compiled into the kernel file),
 218 or the boot loader option setting
 219 is used for the normal root filesystems.
 220 For an NFS-mounted normal root filesystem, one has to use the
 221 .B nfs_root_name
 222 and
 223 .B nfs_root_addrs
 224 boot options to give the NFS settings.
 225 For more information on NFS-mounted root see the kernel documentation file
 226 .I Documentation/filesystems/nfs/nfsroot.txt
 227 .\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32
 228 (or
 229 .I Documentation/filesystems/nfsroot.txt
 230 before Linux 2.6.33).
 231 For more information on setting the root filesystem see also the
 232 .B LILO
 233 and
 234 .B LOADLIN
 235 documentation.
 236 .PP
 237 It is also possible for the
 238 .I /linuxrc
 239 executable to change the normal root device.
 240 For
 241 .I /linuxrc
 242 to change the normal root device,
 243 .I /proc
 244 must be mounted.
 245 After mounting
 246 .IR /proc ,
 247 .I /linuxrc
 248 changes the normal root device by writing into the proc files
 249 .IR /proc/sys/kernel/real\-root\-dev ,
 250 .IR /proc/sys/kernel/nfs\-root\-name ,
 251 and
 252 .IR /proc/sys/kernel/nfs\-root\-addrs .
 253 For a physical root device, the root device is changed by having
 254 .I /linuxrc
 255 write the new root filesystem device number into
 256 .IR /proc/sys/kernel/real\-root\-dev .
 257 For an NFS root filesystem, the root device is changed by having
 258 .I /linuxrc
 259 write the NFS setting into files
 260 .I /proc/sys/kernel/nfs\-root\-name
 261 and
 262 .I /proc/sys/kernel/nfs\-root\-addrs
 263 and then writing 0xff (e.g., the pseudo-NFS-device number) into file
 264 .IR /proc/sys/kernel/real\-root\-dev .
 265 For example, the following shell command line would change
 266 the normal root device to
 267 .IR /dev/hdb1 :
 268 .PP
 269 .in +4n
 270 .EX
 271 echo 0x365 >/proc/sys/kernel/real\-root\-dev
 272 .EE
 273 .in
 274 .PP
 275 For an NFS example, the following shell command lines would change the
 276 normal root device to the NFS directory
 277 .I /var/nfsroot
 278 on a local networked NFS server with IP number 193.8.232.7 for a system with
 279 IP number 193.8.232.2 and named "idefix":
 280 .PP
 281 .in +4n
 282 .EX
 283 echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name
 284 echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e
 285     >/proc/sys/kernel/nfs\-root\-addrs
 286 echo 255 >/proc/sys/kernel/real\-root\-dev
 287 .EE
 288 .in
 289 .PP
 290 .BR Note :
 291 The use of
 292 .I /proc/sys/kernel/real\-root\-dev
 293 to change the root filesystem is obsolete.
 294 See the Linux kernel source file
 295 .I Documentation/admin\-guide/initrd.rst
 296 .\" commit 9d85025b0418163fae079c9ba8f8445212de8568
 297 (or
 298 .I Documentation/initrd.txt
 299 before Linux 4.10)
 300 as well as
 301 .BR pivot_root (2)
 302 and
 303 .BR pivot_root (8)
 304 for information on the modern method of changing the root filesystem.
 305 .\" FIXME . Should this manual page  describe the pivot_root mechanism?
 306 .\"
 307 .\"
 308 .\"
 309 .SS Usage
 310 The main motivation for implementing
 311 .B initrd
 312 was to allow for modular kernel configuration at system installation.
 313 .PP
 314 A possible system installation scenario is as follows:
 315 .IP 1. 3
 316 The loader program boots from floppy or other media with a minimal kernel
 317 (e.g., support for
 318 .IR /dev/ram ,
 319 .IR /dev/initrd ,
 320 and the ext2 filesystem) and loads
 321 .I /dev/initrd
 322 with a gzipped version of the initial filesystem.
 323 .IP 2.
 324 The executable
 325 .I /linuxrc
 326 determines what is needed to (1) mount the normal root filesystem
 327 (i.e., device type, device drivers, filesystem) and (2) the
 328 distribution media (e.g., CD-ROM, network, tape, ...).
 329 This can be done by asking the user, by auto-probing,
 330 or by using a hybrid approach.
 331 .IP 3.
 332 The executable
 333 .I /linuxrc
 334 loads the necessary modules from the initial root filesystem.
 335 .IP 4.
 336 The executable
 337 .I /linuxrc
 338 creates and populates the root filesystem.
 339 (At this stage the normal root filesystem does not have to be a
 340 completed system yet.)
 341 .IP 5.
 342 The executable
 343 .I /linuxrc
 344 sets
 345 .IR /proc/sys/kernel/real\-root\-dev ,
 346 unmounts
 347 .IR /proc ,
 348 the normal root filesystem and any other filesystems
 349 it has mounted, and then terminates.
 350 .IP 6.
 351 The kernel then mounts the normal root filesystem.
 352 .IP 7.
 353 Now that the filesystem is accessible and intact,
 354 the boot loader can be installed.
 355 .IP 8.
 356 The boot loader is configured to load into
 357 .I /dev/initrd
 358 a filesystem with the set of modules that was used to bring up the system.
 359 (e.g., device
 360 .I /dev/ram0
 361 can be modified, then unmounted, and finally, the image is written from
 362 .I /dev/ram0
 363 to a file.)
 364 .IP 9.
 365 The system is now bootable and additional installation tasks can be
 366 performed.
 367 .PP
 368 The key role of
 369 .I /dev/initrd
 370 in the above is to reuse the configuration data during normal system operation
 371 without requiring initial kernel selection, a large generic kernel or,
 372 recompiling the kernel.
 373 .PP
 374 A second scenario is for installations where Linux runs on systems with
 375 different hardware configurations in a single administrative network.
 376 In such cases, it may be desirable to use only a small set of kernels
 377 (ideally only one) and to keep the system-specific part of configuration
 378 information as small as possible.
 379 In this case, create a common file
 380 with all needed modules.
 381 Then, only the
 382 .I /linuxrc
 383 file or a file executed by
 384 .I /linuxrc
 385 would be different.
 386 .PP
 387 A third scenario is more convenient recovery disks.
 388 Because information like the location of the root filesystem
 389 partition is not needed at boot time, the system loaded from
 390 .I /dev/initrd
 391 can use a dialog and/or auto-detection followed by a
 392 possible sanity check.
 393 .PP
 394 Last but not least, Linux distributions on CD-ROM may use
 395 .B initrd
 396 for easy installation from the CD-ROM.
 397 The distribution can use
 398 .B LOADLIN
 399 to directly load
 400 .I /dev/initrd
 401 from CD-ROM without the need of any floppies.
 402 The distribution could also use a
 403 .B LILO
 404 boot floppy and then bootstrap a bigger RAM disk via
 405 .I /dev/initrd
 406 from the CD-ROM.
 407 .\"
 408 .\"
 409 .\"
 410 .SH FILES
 411 .I /dev/initrd
 412 .br
 413 .I /dev/ram0
 414 .br
 415 .I /linuxrc
 416 .br
 417 .I /initrd
 418 .\"
 419 .\"
 420 .\"
 421 .SH NOTES
 422 .IP 1. 3
 423 With the current kernel, any filesystems that remain mounted when
 424 .I /dev/ram0
 425 is moved from
 426 .I /
 427 to
 428 .I /initrd
 429 continue to be accessible.
 430 However, the
 431 .I /proc/mounts
 432 entries are not updated.
 433 .IP 2.
 434 With the current kernel, if directory
 435 .I /initrd
 436 does not exist, then
 437 .I /dev/ram0
 438 will
 439 .B not
 440 be fully unmounted if
 441 .I /dev/ram0
 442 is used by any process or has any filesystem mounted on it.
 443 If
 444 .I /dev/ram0
 445 is
 446 .B not
 447 fully unmounted, then
 448 .I /dev/ram0
 449 will remain in memory.
 450 .IP 3.
 451 Users of
 452 .I /dev/initrd
 453 should not depend on the behavior given in the above notes.
 454 The behavior may change in future versions of the Linux kernel.
 455 .\"
 456 .\"
 457 .\"
 458 .\" .SH AUTHORS
 459 .\" The kernel code for device
 460 .\" .BR initrd
 461 .\" was written by Werner Almesberger <almesber@lrc.epfl.ch> and
 462 .\" Hans Lermen <lermen@elserv.ffm.fgan.de>.
 463 .\" The code for
 464 .\" .BR initrd
 465 .\" was added to the baseline Linux kernel in development version 1.3.73.
 466 .SH SEE ALSO
 467 .BR chown (1),
 468 .BR mknod (1),
 469 .BR ram (4),
 470 .BR freeramdisk (8),
 471 .BR rdev (8)
 472 .PP
 473 .I Documentation/admin\-guide/initrd.rst
 474 .\" commit 9d85025b0418163fae079c9ba8f8445212de8568
 475 (or
 476 .I Documentation/initrd.txt
 477 before Linux 4.10)
 478 in the Linux kernel source tree, the LILO documentation,
 479 the LOADLIN documentation, the SYSLINUX documentation