Import 2.2.8pre2

[davej-history.git] / Documentation / initrd.txt

Using the initial RAM disk (initrd)
===================================

Written 1996 by Werner Almesberger <almesber@lrc.epfl.ch> and
                Hans Lermen <lermen@elserv.ffm.fgan.de>


initrd adds the capability to load a RAM disk by the boot loader. This
RAM disk can then be mounted as the root file system and programs can be
run from it. Afterwards, a new root file system can be mounted from a
different device. The previous root (from initrd) is then either moved
to the directory /initrd or it is unmounted.

initrd is mainly designed to allow system startup to occur in two phases,
where the kernel comes up with a minimum set of compiled-in drivers, and
where additional modules are loaded from initrd.


Operation
---------

When using initrd, the system boots as follows:

  1) the boot loader loads the kernel and the initial RAM disk
  2) the kernel converts initrd into a "normal" RAM disk and
     frees the memory used by initrd
  3) initrd is mounted read-write as root
  4) /linuxrc is executed (this can be any valid executable, including
     shell scripts; it is run with uid 0 and can do basically everything
     init can do)
  5) when linuxrc terminates, the "real" root file system is mounted
  6) if a directory /initrd exists, the initrd is moved there
     otherwise, initrd is unmounted
  7) the usual boot sequence (e.g. invocation of /sbin/init) is performed
     on the root file system

Note that moving initrd from / to /initrd does not involve unmounting it.
It is therefore possible to leave processes running on initrd (or leave
file systems mounted, but see below) during that procedure. However, if
/initrd doesn't exist, initrd can only be unmounted if it is not used by
anything. If it can't be unmounted, it will stay in memory.

Also note that file systems mounted under initrd continue to be accessible,
but their /proc/mounts entries are not updated. Also, if /initrd doesn't
exist, initrd can't be unmounted and will "disappear" and take those file
systems with it, thereby preventing them from being re-mounted. It is
therefore strongly suggested to generally unmount all file systems (except
of course for the root file system, but including /proc) before switching
from initrd to the "normal" root file system.

In order to deallocate the memory used for the initial RAM disk, you have
to execute freeramdisk (see 'Resources' below) after unmounting /initrd.


Boot command-line options
-------------------------

initrd adds the following new options:

  initrd=<path>    (LOADLIN only)

    Loads the specified file as the initial RAM disk. When using LILO, you
    have to specify the RAM disk image file in /etc/lilo.conf, using the
    INITRD configuration variable.

  noinitrd

    initrd data is preserved but it is not converted to a RAM disk and
    the "normal" root file system is mounted. initrd data can be read
    from /dev/initrd. Note that the data in initrd can have any structure
    in this case and doesn't necessarily have to be a file system image.
    This option is used mainly for debugging.

    Note that /dev/initrd is read-only and that it can only be used once.
    As soon as the last process has closed it, all data is freed and
    /dev/initrd can't be opened any longer.

  root=/dev/ram

    initrd is mounted as root, and /linuxrc is started. If no /linuxrc
    exists, the normal boot procedure is followed, with the RAM disk
    still mounted as root. This option is mainly useful when booting from
    a floppy disk. Compared to directly mounting an on-disk file system,
    the intermediate step of going via initrd adds a little speed
    advantage and it allows the use of a compressed file system.
    Also, together with LOADLIN you may load the RAM disk directly from
    CDROM or disk, hence having a floppyless boot from CD,
    e.g.: E:\loadlin E:\bzImage root=/dev/ram initrd=E:\rdimage


Installation
------------

First, the "normal" root file system has to be prepared as follows:

# mknod /dev/initrd b 1 250 
# chmod 400 /dev/initrd
# mkdir /initrd

If the root file system is created during the boot procedure (i.e. if
you're creating an install floppy), the root file system creation
procedure should perform these operations.

Note that neither /dev/initrd nor /initrd are strictly required for
correct operation of initrd, but it is a lot easier to experiment with
initrd if you have them, and you may also want to use /initrd to pass
data to the "real" system.

Second, the kernel has to be compiled with RAM disk support and with
support for the initial RAM disk enabled. Also, at least all components
needed to execute programs from initrd (e.g. executable format and file
system) must be compiled into the kernel.

Third, you have to create the RAM disk image. This is done by creating a
file system on a block device and then by copying files to it as needed.
With recent kernels, at least three types of devices are suitable for
that:

 - a floppy disk (works everywhere but it's painfully slow)
 - a RAM disk (fast, but allocates physical memory)
 - a loopback device (the most elegant solution, but currently requires a
   modified mount)

We'll describe the RAM disk method:

 1) make sure you have a RAM disk device /dev/ram (block, major 1, minor 0)
 2) create an empty file system of the appropriate size, e.g.
    # mke2fs -m0 /dev/ram 300   
    (if space is critical, you may want to use the Minix FS instead of Ext2)
 3) mount the file system on an appropriate directory, e.g.
    # mount -t ext2 /dev/ram /mnt
 4) create the console device:
    # mkdir /mnt/dev
    # mknod /mnt/dev/tty1 c 4 1
 5) copy all the files that are needed to properly use the initrd
    environment. Don't forget the most important file, /linuxrc
    Note that /linuxrc's permissions must include "x" (execute).
 6) unmount the RAM disk
    # umount /dev/ram
 7) copy the image to a file
    # dd if=/dev/ram bs=1k count=300 of=/boot/initrd
 8) deallocate the RAM disk
    # freeramdisk /dev/ram

For experimenting with initrd, you may want to take a rescue floppy (e.g.
rescue.gz from Slackware) and only add a symbolic link from /linuxrc to
/bin/sh, e.g.

 # gunzip <rescue.gz >/dev/ram
 # mount -t minix /dev/ram /mnt
 # ln -s /bin/sh /mnt/linuxrc
 # umount /dev/ram
 # dd if=/dev/ram bs=1k count=1440 of=/boot/initrd
 # freeramdisk /dev/ram

Finally, you have to boot the kernel and load initrd. Currently,
preliminary versions of LOADLIN 1.6 and LILO 18 support initrd (see
below for where to get them). With LOADLIN, you simply execute

     LOADLIN <kernel> initrd=<disk_image>
e.g. LOADLIN C:\LINUX\VMLINUZ initrd=C:\LINUX\INITRD

With LILO, you add the option INITRD=<path> to either the global section
or to the section of the respective kernel in /etc/lilo.conf, e.g.

  image = /vmlinuz
    initrd = /boot/initrd

and run /sbin/lilo

Now you can boot and enjoy using initrd.


Setting the root device
-----------------------

By default, the standard settings in the kernel are used for the root
device, i.e. the default compiled in or set with rdev, or what was passed
with root=xxx on the command line, or, with LILO, what was specified in
/etc/lilo.conf It is also possible to use initrd with an NFS-mounted
root; you have to use the nfs_root_name and nfs_root_addrs boot options
for this.

It is also possible to change the root device from within the initrd
environment. In order to do so, /proc has to be mounted. Then, the
following files are available:

  /proc/sys/kernel/real-root-dev
  /proc/sys/kernel/nfs-root-name
  /proc/sys/kernel/nfs-root-addrs

real-root-dev can be changed by writing the number of the new root FS
device to it, e.g.

  # echo 0x301 >/proc/sys/kernel/real-root-dev

for /dev/hda1. When using an NFS-mounted root, nfs-root-name and
nfs-root-addrs have to be set accordingly and then real-root-dev has to
be set to 0xff, e.g.

  # echo /var/nfsroot >/proc/sys/kernel/nfs-root-name
  # echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \
    >/proc/sys/kernel/nfs-root-addrs
  # echo 255 >/proc/sys/kernel/real-root-dev

If the root device is set to the RAM disk, the root file system is not
moved to /initrd, but the boot procedure is simply continued by starting
init on the initial RAM disk.


Usage scenarios
---------------

The main motivation for implementing initrd was to allow for modular
kernel configuration at system installation. The procedure would work
as follows:

  1) systems boots from floppy or other media with a minimal kernel
     (e.g. support for RAM disks, initrd, a.out, and the ext2 FS) and
     loads initrd
  2) /linuxrc determines what is needed to (1) mount the "real" root FS
     (i.e. device type, device drivers, file system) and (2) the
     distribution media (e.g. CD-ROM, network, tape, ...). This can be
     done by asking the user, by auto-probing, or by using a hybrid
     approach.
  3) /linuxrc loads the necessary modules
  4) /linuxrc creates and populates the root file system (this doesn't
     have to be a very usable system yet)
  5) /linuxrc unmounts the root file system and possibly any other file
     systems it has mounted, sets /proc/sys/kernel/..., and terminates
  6) the root file system is mounted
  7) now that we're sure that the file system is accessible and intact,
     the boot loader can be installed
  8) the boot loader is configured to load an initrd with the set of
     modules that was used to bring up the system (e.g. /initrd can be
     modified, then unmounted, and finally, the image is written from
     /dev/ram to a file)
  9) now the system is bootable and additional installation tasks can be
     performed

The key role of initrd here is to re-use the configuration data during
normal system operation without requiring the use of a bloated "generic"
kernel or re-compilation or re-linking of the kernel.

A second scenario is for installations where Linux runs on systems with
different hardware configurations in a single administrative domain. In
such cases, it is desirable to generate only a small set of kernels
(ideally only one) and to keep the system-specific part of configuration
information as small as possible. In this case, a common initrd could be
generated with all the necessary modules. Then, only /linuxrc or a file
read by it would have to be different.

A third scenario are more convenient recovery disks, because information
like the location of the root FS partition doesn't have to be provided at
boot time, but the system loaded from initrd can use a user-friendly
dialog and it can also perform some sanity checks (or even some form of
auto-detection).

Last not least, CDROM distributors may use it for better installation from CD,
either using a LILO boot floppy and bootstrapping a bigger RAM disk via
initrd from CD, or using LOADLIN to directly load the RAM disk from CD
without need of floppies.

Since initrd is a fairly generic mechanism, it is likely that additional
uses will be found.


Resources
---------

The bzImage+initrd patch (bzImage is an extension to load kernels directly
above 1 MB, which allows kernels sizes of up to approximately 2 MB) can be
found at
ftp://lrcftp.epfl.ch/pub/people/almesber/lilo/bzImage+initrd-1.3.71.patch.gz
and
ftp://elserv.ffm.fgan.de/pub/linux/loadlin-1.6/bzImage+initrd-1.3.71.patch.gz

A preliminary version of LOADLIN 1.6 is available on
ftp://elserv.ffm.fgan.de/pub/linux/loadlin-1.6/loadlin-1.6-pre8-bin.tgz

A preliminary version of LILO 18 is available on
ftp://lrcftp.epfl.ch/pub/people/almesber/lilo/lilo.18dev3.tar.gz

A very simple example for building an image for initrd, also including
the program 'freeramdisk', can be found on
ftp://elserv.ffm.fgan.de/pub/linux/loadlin-1.6/initrd-example.tgz