original/man4/initrd.4

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