linux/Documentation/initrd.txt
<<
>>
Prefs
   1Using the initial RAM disk (initrd)
   2===================================
   3
   4Written 1996,2000 by Werner Almesberger <werner.almesberger@epfl.ch> and
   5                     Hans Lermen <lermen@fgan.de>
   6
   7
   8initrd provides the capability to load a RAM disk by the boot loader.
   9This RAM disk can then be mounted as the root file system and programs
  10can be run from it. Afterwards, a new root file system can be mounted
  11from a different device. The previous root (from initrd) is then moved
  12to a directory and can be subsequently unmounted.
  13
  14initrd is mainly designed to allow system startup to occur in two phases,
  15where the kernel comes up with a minimum set of compiled-in drivers, and
  16where additional modules are loaded from initrd.
  17
  18This document gives a brief overview of the use of initrd. A more detailed
  19discussion of the boot process can be found in [1].
  20
  21
  22Operation
  23---------
  24
  25When using initrd, the system typically boots as follows:
  26
  27  1) the boot loader loads the kernel and the initial RAM disk
  28  2) the kernel converts initrd into a "normal" RAM disk and
  29     frees the memory used by initrd
  30  3) if the root device is not /dev/ram0, the old (deprecated)
  31     change_root procedure is followed. see the "Obsolete root change
  32     mechanism" section below.
  33  4) root device is mounted. if it is /dev/ram0, the initrd image is
  34     then mounted as root
  35  5) /sbin/init is executed (this can be any valid executable, including
  36     shell scripts; it is run with uid 0 and can do basically everything
  37     init can do).
  38  6) init mounts the "real" root file system
  39  7) init places the root file system at the root directory using the
  40     pivot_root system call
  41  8) init execs the /sbin/init on the new root filesystem, performing
  42     the usual boot sequence
  43  9) the initrd file system is removed
  44
  45Note that changing the root directory does not involve unmounting it.
  46It is therefore possible to leave processes running on initrd during that
  47procedure. Also note that file systems mounted under initrd continue to
  48be accessible.
  49
  50
  51Boot command-line options
  52-------------------------
  53
  54initrd adds the following new options:
  55
  56  initrd=<path>    (e.g. LOADLIN)
  57
  58    Loads the specified file as the initial RAM disk. When using LILO, you
  59    have to specify the RAM disk image file in /etc/lilo.conf, using the
  60    INITRD configuration variable.
  61
  62  noinitrd
  63
  64    initrd data is preserved but it is not converted to a RAM disk and
  65    the "normal" root file system is mounted. initrd data can be read
  66    from /dev/initrd. Note that the data in initrd can have any structure
  67    in this case and doesn't necessarily have to be a file system image.
  68    This option is used mainly for debugging.
  69
  70    Note: /dev/initrd is read-only and it can only be used once. As soon
  71    as the last process has closed it, all data is freed and /dev/initrd
  72    can't be opened anymore.
  73
  74  root=/dev/ram0
  75
  76    initrd is mounted as root, and the normal boot procedure is followed,
  77    with the RAM disk mounted as root.
  78
  79Compressed cpio images
  80----------------------
  81
  82Recent kernels have support for populating a ramdisk from a compressed cpio
  83archive. On such systems, the creation of a ramdisk image doesn't need to
  84involve special block devices or loopbacks; you merely create a directory on
  85disk with the desired initrd content, cd to that directory, and run (as an
  86example):
  87
  88find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img
  89
  90Examining the contents of an existing image file is just as simple:
  91
  92mkdir /tmp/imagefile
  93cd /tmp/imagefile
  94gzip -cd /boot/imagefile.img | cpio -imd --quiet
  95
  96Installation
  97------------
  98
  99First, a directory for the initrd file system has to be created on the
 100"normal" root file system, e.g.
 101
 102# mkdir /initrd
 103
 104The name is not relevant. More details can be found on the pivot_root(2)
 105man page.
 106
 107If the root file system is created during the boot procedure (i.e. if
 108you're building an install floppy), the root file system creation
 109procedure should create the /initrd directory.
 110
 111If initrd will not be mounted in some cases, its content is still
 112accessible if the following device has been created:
 113
 114# mknod /dev/initrd b 1 250 
 115# chmod 400 /dev/initrd
 116
 117Second, the kernel has to be compiled with RAM disk support and with
 118support for the initial RAM disk enabled. Also, at least all components
 119needed to execute programs from initrd (e.g. executable format and file
 120system) must be compiled into the kernel.
 121
 122Third, you have to create the RAM disk image. This is done by creating a
 123file system on a block device, copying files to it as needed, and then
 124copying the content of the block device to the initrd file. With recent
 125kernels, at least three types of devices are suitable for that:
 126
 127 - a floppy disk (works everywhere but it's painfully slow)
 128 - a RAM disk (fast, but allocates physical memory)
 129 - a loopback device (the most elegant solution)
 130
 131We'll describe the loopback device method:
 132
 133 1) make sure loopback block devices are configured into the kernel
 134 2) create an empty file system of the appropriate size, e.g.
 135    # dd if=/dev/zero of=initrd bs=300k count=1
 136    # mke2fs -F -m0 initrd
 137    (if space is critical, you may want to use the Minix FS instead of Ext2)
 138 3) mount the file system, e.g.
 139    # mount -t ext2 -o loop initrd /mnt
 140 4) create the console device:
 141    # mkdir /mnt/dev
 142    # mknod /mnt/dev/console c 5 1
 143 5) copy all the files that are needed to properly use the initrd
 144    environment. Don't forget the most important file, /sbin/init
 145    Note that /sbin/init's permissions must include "x" (execute).
 146 6) correct operation the initrd environment can frequently be tested
 147    even without rebooting with the command
 148    # chroot /mnt /sbin/init
 149    This is of course limited to initrds that do not interfere with the
 150    general system state (e.g. by reconfiguring network interfaces,
 151    overwriting mounted devices, trying to start already running demons,
 152    etc. Note however that it is usually possible to use pivot_root in
 153    such a chroot'ed initrd environment.)
 154 7) unmount the file system
 155    # umount /mnt
 156 8) the initrd is now in the file "initrd". Optionally, it can now be
 157    compressed
 158    # gzip -9 initrd
 159
 160For experimenting with initrd, you may want to take a rescue floppy and
 161only add a symbolic link from /sbin/init to /bin/sh. Alternatively, you
 162can try the experimental newlib environment [2] to create a small
 163initrd.
 164
 165Finally, you have to boot the kernel and load initrd. Almost all Linux
 166boot loaders support initrd. Since the boot process is still compatible
 167with an older mechanism, the following boot command line parameters
 168have to be given:
 169
 170  root=/dev/ram0 rw
 171
 172(rw is only necessary if writing to the initrd file system.)
 173
 174With LOADLIN, you simply execute
 175
 176     LOADLIN <kernel> initrd=<disk_image>
 177e.g. LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw
 178
 179With LILO, you add the option INITRD=<path> to either the global section
 180or to the section of the respective kernel in /etc/lilo.conf, and pass
 181the options using APPEND, e.g.
 182
 183  image = /bzImage
 184    initrd = /boot/initrd.gz
 185    append = "root=/dev/ram0 rw"
 186
 187and run /sbin/lilo
 188
 189For other boot loaders, please refer to the respective documentation.
 190
 191Now you can boot and enjoy using initrd.
 192
 193
 194Changing the root device
 195------------------------
 196
 197When finished with its duties, init typically changes the root device
 198and proceeds with starting the Linux system on the "real" root device.
 199
 200The procedure involves the following steps:
 201 - mounting the new root file system
 202 - turning it into the root file system
 203 - removing all accesses to the old (initrd) root file system
 204 - unmounting the initrd file system and de-allocating the RAM disk
 205
 206Mounting the new root file system is easy: it just needs to be mounted on
 207a directory under the current root. Example:
 208
 209# mkdir /new-root
 210# mount -o ro /dev/hda1 /new-root
 211
 212The root change is accomplished with the pivot_root system call, which
 213is also available via the pivot_root utility (see pivot_root(8) man
 214page; pivot_root is distributed with util-linux version 2.10h or higher
 215[3]). pivot_root moves the current root to a directory under the new
 216root, and puts the new root at its place. The directory for the old root
 217must exist before calling pivot_root. Example:
 218
 219# cd /new-root
 220# mkdir initrd
 221# pivot_root . initrd
 222
 223Now, the init process may still access the old root via its
 224executable, shared libraries, standard input/output/error, and its
 225current root directory. All these references are dropped by the
 226following command:
 227
 228# exec chroot . what-follows <dev/console >dev/console 2>&1
 229
 230Where what-follows is a program under the new root, e.g. /sbin/init
 231If the new root file system will be used with udev and has no valid
 232/dev directory, udev must be initialized before invoking chroot in order
 233to provide /dev/console.
 234
 235Note: implementation details of pivot_root may change with time. In order
 236to ensure compatibility, the following points should be observed:
 237
 238 - before calling pivot_root, the current directory of the invoking
 239   process should point to the new root directory
 240 - use . as the first argument, and the _relative_ path of the directory
 241   for the old root as the second argument
 242 - a chroot program must be available under the old and the new root
 243 - chroot to the new root afterwards
 244 - use relative paths for dev/console in the exec command
 245
 246Now, the initrd can be unmounted and the memory allocated by the RAM
 247disk can be freed:
 248
 249# umount /initrd
 250# blockdev --flushbufs /dev/ram0
 251
 252It is also possible to use initrd with an NFS-mounted root, see the
 253pivot_root(8) man page for details.
 254
 255
 256Usage scenarios
 257---------------
 258
 259The main motivation for implementing initrd was to allow for modular
 260kernel configuration at system installation. The procedure would work
 261as follows:
 262
 263  1) system boots from floppy or other media with a minimal kernel
 264     (e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and
 265     loads initrd
 266  2) /sbin/init determines what is needed to (1) mount the "real" root FS
 267     (i.e. device type, device drivers, file system) and (2) the
 268     distribution media (e.g. CD-ROM, network, tape, ...). This can be
 269     done by asking the user, by auto-probing, or by using a hybrid
 270     approach.
 271  3) /sbin/init loads the necessary kernel modules
 272  4) /sbin/init creates and populates the root file system (this doesn't
 273     have to be a very usable system yet)
 274  5) /sbin/init invokes pivot_root to change the root file system and
 275     execs - via chroot - a program that continues the installation
 276  6) the boot loader is installed
 277  7) the boot loader is configured to load an initrd with the set of
 278     modules that was used to bring up the system (e.g. /initrd can be
 279     modified, then unmounted, and finally, the image is written from
 280     /dev/ram0 or /dev/rd/0 to a file)
 281  8) now the system is bootable and additional installation tasks can be
 282     performed
 283
 284The key role of initrd here is to re-use the configuration data during
 285normal system operation without requiring the use of a bloated "generic"
 286kernel or re-compiling or re-linking the kernel.
 287
 288A second scenario is for installations where Linux runs on systems with
 289different hardware configurations in a single administrative domain. In
 290such cases, it is desirable to generate only a small set of kernels
 291(ideally only one) and to keep the system-specific part of configuration
 292information as small as possible. In this case, a common initrd could be
 293generated with all the necessary modules. Then, only /sbin/init or a file
 294read by it would have to be different.
 295
 296A third scenario is more convenient recovery disks, because information
 297like the location of the root FS partition doesn't have to be provided at
 298boot time, but the system loaded from initrd can invoke a user-friendly
 299dialog and it can also perform some sanity checks (or even some form of
 300auto-detection).
 301
 302Last not least, CD-ROM distributors may use it for better installation
 303from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk
 304via initrd from CD; or by booting via a loader like LOADLIN or directly
 305from the CD-ROM, and loading the RAM disk from CD without need of
 306floppies. 
 307
 308
 309Obsolete root change mechanism
 310------------------------------
 311
 312The following mechanism was used before the introduction of pivot_root.
 313Current kernels still support it, but you should _not_ rely on its
 314continued availability.
 315
 316It works by mounting the "real" root device (i.e. the one set with rdev
 317in the kernel image or with root=... at the boot command line) as the
 318root file system when linuxrc exits. The initrd file system is then
 319unmounted, or, if it is still busy, moved to a directory /initrd, if
 320such a directory exists on the new root file system.
 321
 322In order to use this mechanism, you do not have to specify the boot
 323command options root, init, or rw. (If specified, they will affect
 324the real root file system, not the initrd environment.)
 325  
 326If /proc is mounted, the "real" root device can be changed from within
 327linuxrc by writing the number of the new root FS device to the special
 328file /proc/sys/kernel/real-root-dev, e.g.
 329
 330  # echo 0x301 >/proc/sys/kernel/real-root-dev
 331
 332Note that the mechanism is incompatible with NFS and similar file
 333systems.
 334
 335This old, deprecated mechanism is commonly called "change_root", while
 336the new, supported mechanism is called "pivot_root".
 337
 338
 339Mixed change_root and pivot_root mechanism
 340------------------------------------------
 341
 342In case you did not want to use root=/dev/ram0 to trigger the pivot_root
 343mechanism, you may create both /linuxrc and /sbin/init in your initrd image.
 344
 345/linuxrc would contain only the following:
 346
 347#! /bin/sh
 348mount -n -t proc proc /proc
 349echo 0x0100 >/proc/sys/kernel/real-root-dev
 350umount -n /proc
 351
 352Once linuxrc exited, the kernel would mount again your initrd as root,
 353this time executing /sbin/init. Again, it would be the duty of this init
 354to build the right environment (maybe using the root= device passed on
 355the cmdline) before the final execution of the real /sbin/init.
 356
 357
 358Resources
 359---------
 360
 361[1] Almesberger, Werner; "Booting Linux: The History and the Future"
 362    http://www.almesberger.net/cv/papers/ols2k-9.ps.gz
 363[2] newlib package (experimental), with initrd example
 364    http://sources.redhat.com/newlib/
 365[3] Brouwer, Andries; "util-linux: Miscellaneous utilities for Linux"
 366    ftp://ftp.win.tue.nl/pub/linux-local/utils/util-linux/
 367