dracut.asc

   1 dracut
   2 ======
   3 Harald Hoyer <harald@redhat.com>
   4 v3.0, October 2013
   5
   6 :language: bash
   7
   8 = Introduction
   9 This section is a modified version of
  10 http://en.wikipedia.org/wiki/Initrd which is licensed under the
  11 Creative Commons Attribution/Share-Alike License.
  12
  13 == Definition
  14 An _initial ramdisk_ is a temporary file system used in the boot process of the
  15 Linux kernel. _initrd_ and _initramfs_ refer to slightly different schemes for
  16 loading this file system into memory. Both are commonly used to make
  17 preparations before the real root file system can be mounted.
  18
  19 == Rationale
  20 Many Linux distributions ship a single, generic kernel image that is intended to
  21 boot as wide a variety of hardware as possible. The device drivers for this
  22 generic kernel image are included as loadable modules, as it is not possible to
  23 statically compile them all into the one kernel without making it too large to
  24 boot from computers with limited memory or from lower-capacity media like floppy
  25 disks.
  26
  27 This then raises the problem of detecting and loading the modules necessary to
  28 mount the root file system at boot time (or, for that matter, deducing where or
  29 what the root file system is).
  30
  31 To further complicate matters, the root file system may be on a software RAID
  32 volume, LVM, NFS (on diskless workstations), or on an encrypted partition. All
  33 of these require special preparations to mount.
  34
  35 Another complication is kernel support for hibernation, which suspends the
  36 computer to disk by dumping an image of the entire system to a swap partition or
  37 a regular file, then powering off. On next boot, this image has to be made
  38 accessible before it can be loaded back into memory.
  39
  40 To avoid having to hardcode handling for so many special cases into the kernel,
  41 an initial boot stage with a temporary root file system
  42 —now dubbed early user space— is used.  This root file system would contain
  43 user-space helpers that would do the hardware detection, module loading and
  44 device discovery necessary to get the real root file system mounted.
  45
  46 == Implementation
  47 An image of this initial root file system (along with the kernel image) must be
  48 stored somewhere accessible by the Linux bootloader or the boot firmware of the
  49 computer. This can be:
  50
  51 * The root file system itself
  52 * A boot image on an optical disc
  53 * A small ext2/ext3 or FAT-formatted partition on a local disk
  54   (a _boot partition_)
  55 * A TFTP server (on systems that can boot from Ethernet)
  56
  57 The bootloader will load the kernel and initial root file system image into
  58 memory and then start the kernel, passing in the memory address of the image.
  59
  60 Depending on which algorithms were compiled statically into it, the kernel can
  61 currently unpack initrd/initramfs images compressed with gzip, bzip2 and LZMA.
  62
  63 == Mount preparations
  64 dracut can generate a customized initrams image which contains only whatever is
  65 necessary to boot some particular computer, such as ATA, SCSI and filesystem
  66 kernel modules (host-only mode).
  67
  68 dracut can also generate a more generic initramfs image (default mode).
  69
  70 dracut's initramfs starts only with the device name of the root file system (or
  71 its UUID) and must discover everything else at boot time. A complex cascade of
  72 tasks must be performed to get the root file system mounted:
  73
  74 * Any hardware drivers that the boot process depends on must be loaded. All
  75 kernel modules for common storage devices are packed onto the initramfs and then
  76 udev pulls in modules matching the computer's detected hardware.
  77
  78 * On systems which display a boot rd.splash screen, the video hardware must be
  79 initialized and a user-space helper started to paint animations onto the display
  80 in lockstep with the boot process.
  81
  82 * If the root file system is on NFS, dracut does then:
  83 ** Bring up the primary network interface.
  84 ** Invoke a DHCP client, with which it can obtain a DHCP lease.
  85 ** Extract the name of the NFS share and the address of the NFS server from the
  86 lease.
  87 ** Mount the NFS share.
  88
  89 * If the root file system appears to be on a software RAID device, there is no
  90 way of knowing which devices the RAID volume spans; the standard MD utilities
  91 must be invoked to scan all available block devices with a raid signature and
  92 bring the required ones online.
  93
  94 * If the root file system appears to be on a logical volume, the LVM utilities
  95 must be invoked to scan for and activate the volume group containing it.
  96
  97 * If the root file system is on an encrypted block device:
  98 ** Invoke a helper script to prompt the user to type in a passphrase and/or
  99 insert a hardware token (such as a smart card or a USB security dongle).
 100
 101 * Create a decryption target with the device mapper.
 102
 103 dracut uses udev, an event-driven hotplug agent, which invokes helper programs
 104 as hardware devices, disk partitions and storage volumes matching certain rules
 105 come online. This allows discovery to run in parallel, and to progressively
 106 cascade into arbitrary nestings of LVM, RAID or encryption to get at the root
 107 file system.
 108
 109 When the root file system finally becomes visible:
 110
 111 * Any maintenance tasks which cannot run on a mounted root file system
 112 are done.
 113 * The root file system is mounted read-only.
 114 * Any processes which must continue running (such as the rd.splash screen helper
 115 and its command FIFO) are hoisted into the newly-mounted root file system.
 116
 117 The final root file system cannot simply be mounted over /, since that would
 118 make the scripts and tools on the initial root file system inaccessible for any
 119 final cleanup tasks. On an initramfs, the initial root file system cannot be
 120 rotated away. Instead, it is simply emptied and the final root file system
 121 mounted over the top.
 122
 123 If the systemd module is used in the initramfs, the ordering of the services
 124 started looks like <<dracutbootup7>>.
 125
 126 == Dracut on shutdown
 127
 128 On a systemd driven system, the dracut initramfs is also used for the shutdown
 129 procedure.
 130
 131 The following steps are executed during a shutdown:
 132
 133 * systemd switches to the shutdown.target
 134 * systemd starts
 135   $prefix/lib/systemd/system/shutdown.target.wants/dracut-shutdown.service
 136 * dracut-shutdown.service executes /usr/lib/dracut/dracut-initramfs-restore
 137   which unpacks the initramfs to /run/initramfs
 138 * systemd finishes shutdown.target
 139 * systemd kills all processes
 140 * systemd tries to unmount everything and mounts the remaining read-only
 141 * systemd checks, if there is a /run/initramfs/shutdown executable
 142 * if yes, it does a pivot_root to /run/initramfs and executes ./shutdown.
 143   The old root is then mounted on /oldroot.
 144   /usr/lib/dracut/modules.d/99shutdown/shutdown.sh is the shutdown executable.
 145 * shutdown will try to umount every /oldroot mount and calls the various
 146   shutdown hooks from the dracut modules
 147
 148 This ensures, that all devices are disassembled and unmounted cleanly.
 149
 150 = User Manual
 151
 152 :leveloffset: 1
 153 include::dracut.8.asc[]
 154
 155 :leveloffset: 1
 156 [[dracutconf5]]
 157 include::dracut.conf.5.asc[]
 158
 159 [[dracutcmdline7]]
 160 include::dracut.cmdline.7.asc[]
 161
 162 [[lsinitrd1]]
 163 include::lsinitrd.1.asc[]
 164
 165 [[mkinitrd8]]
 166 include::mkinitrd.8.asc[]
 167
 168 = Developer Manual
 169
 170 :leveloffset: 1
 171 [[dracutmodules7]]
 172 include::dracut.modules.7.asc[]
 173
 174 [[dracutbootup7]]
 175 include::dracut.bootup.7.asc[]
 176
 177 :leveloffset: 0
 178 [appendix]
 179 License
 180 -------
 181 This work is licensed under the Creative Commons Attribution/Share-Alike
 182 License. To view a copy of this license, visit
 183 http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
 184 Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
 185