dracut.asc - pub/scm/boot/dracut/dracut - Git at Google

 dracut
 ======
 Harald Hoyer <harald@redhat.com>
 v3.0, October 2013

 :language: bash

 = Introduction
 This section is a modified version of
 http://en.wikipedia.org/wiki/Initrd which is licensed under the
 Creative Commons Attribution/Share-Alike License.

 == Definition
 An _initial ramdisk_ is a temporary file system used in the boot process of the
 Linux kernel. _initrd_ and _initramfs_ refer to slightly different schemes for
 loading this file system into memory. Both are commonly used to make
 preparations before the real root file system can be mounted.

 == Rationale
 Many Linux distributions ship a single, generic kernel image that is intended to
 boot as wide a variety of hardware as possible. The device drivers for this
 generic kernel image are included as loadable modules, as it is not possible to
 statically compile them all into the one kernel without making it too large to
 boot from computers with limited memory or from lower-capacity media like floppy
 disks.

 This then raises the problem of detecting and loading the modules necessary to
 mount the root file system at boot time (or, for that matter, deducing where or
 what the root file system is).

 To further complicate matters, the root file system may be on a software RAID
 volume, LVM, NFS (on diskless workstations), or on an encrypted partition. All
 of these require special preparations to mount.

 Another complication is kernel support for hibernation, which suspends the
 computer to disk by dumping an image of the entire system to a swap partition or
 a regular file, then powering off. On next boot, this image has to be made
 accessible before it can be loaded back into memory.

 To avoid having to hardcode handling for so many special cases into the kernel,
 an initial boot stage with a temporary root file system
 —now dubbed early user space— is used.  This root file system would contain
 user-space helpers that would do the hardware detection, module loading and
 device discovery necessary to get the real root file system mounted.

 == Implementation
 An image of this initial root file system (along with the kernel image) must be
 stored somewhere accessible by the Linux bootloader or the boot firmware of the
 computer. This can be:

 * The root file system itself
 * A boot image on an optical disc
 * A small ext2/ext3 or FAT-formatted partition on a local disk
   (a _boot partition_)
 * A TFTP server (on systems that can boot from Ethernet)

 The bootloader will load the kernel and initial root file system image into
 memory and then start the kernel, passing in the memory address of the image.

 Depending on which algorithms were compiled statically into it, the kernel can
 currently unpack initrd/initramfs images compressed with gzip, bzip2 and LZMA.

 == Mount preparations
 dracut can generate a customized initrams image which contains only whatever is
 necessary to boot some particular computer, such as ATA, SCSI and filesystem
 kernel modules (host-only mode).

 dracut can also generate a more generic initramfs image (default mode).

 dracut's initramfs starts only with the device name of the root file system (or
 its UUID) and must discover everything else at boot time. A complex cascade of
 tasks must be performed to get the root file system mounted:

 * Any hardware drivers that the boot process depends on must be loaded. All
 kernel modules for common storage devices are packed onto the initramfs and then
 udev pulls in modules matching the computer's detected hardware.

 * On systems which display a boot rd.splash screen, the video hardware must be
 initialized and a user-space helper started to paint animations onto the display
 in lockstep with the boot process.

 * If the root file system is on NFS, dracut does then:
 ** Bring up the primary network interface.
 ** Invoke a DHCP client, with which it can obtain a DHCP lease.
 ** Extract the name of the NFS share and the address of the NFS server from the
 lease.
 ** Mount the NFS share.

 * If the root file system appears to be on a software RAID device, there is no
 way of knowing which devices the RAID volume spans; the standard MD utilities
 must be invoked to scan all available block devices with a raid signature and
 bring the required ones online.

 * If the root file system appears to be on a logical volume, the LVM utilities
 must be invoked to scan for and activate the volume group containing it.

 * If the root file system is on an encrypted block device:
 ** Invoke a helper script to prompt the user to type in a passphrase and/or
 insert a hardware token (such as a smart card or a USB security dongle).

 * Create a decryption target with the device mapper.

 dracut uses udev, an event-driven hotplug agent, which invokes helper programs
 as hardware devices, disk partitions and storage volumes matching certain rules
 come online. This allows discovery to run in parallel, and to progressively
 cascade into arbitrary nestings of LVM, RAID or encryption to get at the root
 file system.

 When the root file system finally becomes visible:

 * Any maintenance tasks which cannot run on a mounted root file system
 are done.
 * The root file system is mounted read-only.
 * Any processes which must continue running (such as the rd.splash screen helper
 and its command FIFO) are hoisted into the newly-mounted root file system.

 The final root file system cannot simply be mounted over /, since that would
 make the scripts and tools on the initial root file system inaccessible for any
 final cleanup tasks. On an initramfs, the initial root file system cannot be
 rotated away. Instead, it is simply emptied and the final root file system
 mounted over the top.

 If the systemd module is used in the initramfs, the ordering of the services
 started looks like <<dracutbootup7>>.

 == Dracut on shutdown

 On a systemd driven system, the dracut initramfs is also used for the shutdown
 procedure.

 The following steps are executed during a shutdown:

 * systemd switches to the shutdown.target
 * systemd starts
   $prefix/lib/systemd/system/shutdown.target.wants/dracut-shutdown.service
 * dracut-shutdown.service executes /usr/lib/dracut/dracut-initramfs-restore
   which unpacks the initramfs to /run/initramfs
 * systemd finishes shutdown.target
 * systemd kills all processes
 * systemd tries to unmount everything and mounts the remaining read-only
 * systemd checks, if there is a /run/initramfs/shutdown executable
 * if yes, it does a pivot_root to /run/initramfs and executes ./shutdown.
   The old root is then mounted on /oldroot.
   /usr/lib/dracut/modules.d/99shutdown/shutdown.sh is the shutdown executable.
 * shutdown will try to umount every /oldroot mount and calls the various
   shutdown hooks from the dracut modules

 This ensures, that all devices are disassembled and unmounted cleanly.

 = User Manual

 :leveloffset: 1
 include::dracut.8.asc[]

 :leveloffset: 1
 [[dracutconf5]]
 include::dracut.conf.5.asc[]

 [[dracutcmdline7]]
 include::dracut.cmdline.7.asc[]

 [[lsinitrd1]]
 include::lsinitrd.1.asc[]

 [[mkinitrd8]]
 include::mkinitrd.8.asc[]

 = Developer Manual

 :leveloffset: 1
 [[dracutmodules7]]
 include::dracut.modules.7.asc[]

 [[dracutbootup7]]
 include::dracut.bootup.7.asc[]

 :leveloffset: 0
 [appendix]
 License
 -------
 This work is licensed under the Creative Commons Attribution/Share-Alike
 License. To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
 Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
	dracut
	======
	Harald Hoyer <harald@redhat.com>
	v3.0, October 2013

	:language: bash

	= Introduction
	This section is a modified version of
	http://en.wikipedia.org/wiki/Initrd which is licensed under the
	Creative Commons Attribution/Share-Alike License.

	== Definition
	An _initial ramdisk_ is a temporary file system used in the boot process of the
	Linux kernel. _initrd_ and _initramfs_ refer to slightly different schemes for
	loading this file system into memory. Both are commonly used to make
	preparations before the real root file system can be mounted.

	== Rationale
	Many Linux distributions ship a single, generic kernel image that is intended to
	boot as wide a variety of hardware as possible. The device drivers for this
	generic kernel image are included as loadable modules, as it is not possible to
	statically compile them all into the one kernel without making it too large to
	boot from computers with limited memory or from lower-capacity media like floppy
	disks.

	This then raises the problem of detecting and loading the modules necessary to
	mount the root file system at boot time (or, for that matter, deducing where or
	what the root file system is).

	To further complicate matters, the root file system may be on a software RAID
	volume, LVM, NFS (on diskless workstations), or on an encrypted partition. All
	of these require special preparations to mount.

	Another complication is kernel support for hibernation, which suspends the
	computer to disk by dumping an image of the entire system to a swap partition or
	a regular file, then powering off. On next boot, this image has to be made
	accessible before it can be loaded back into memory.

	To avoid having to hardcode handling for so many special cases into the kernel,
	an initial boot stage with a temporary root file system
	—now dubbed early user space— is used. This root file system would contain
	user-space helpers that would do the hardware detection, module loading and
	device discovery necessary to get the real root file system mounted.

	== Implementation
	An image of this initial root file system (along with the kernel image) must be
	stored somewhere accessible by the Linux bootloader or the boot firmware of the
	computer. This can be:

	* The root file system itself
	* A boot image on an optical disc
	* A small ext2/ext3 or FAT-formatted partition on a local disk
	(a _boot partition_)
	* A TFTP server (on systems that can boot from Ethernet)

	The bootloader will load the kernel and initial root file system image into
	memory and then start the kernel, passing in the memory address of the image.

	Depending on which algorithms were compiled statically into it, the kernel can
	currently unpack initrd/initramfs images compressed with gzip, bzip2 and LZMA.

	== Mount preparations
	dracut can generate a customized initrams image which contains only whatever is
	necessary to boot some particular computer, such as ATA, SCSI and filesystem
	kernel modules (host-only mode).

	dracut can also generate a more generic initramfs image (default mode).

	dracut's initramfs starts only with the device name of the root file system (or
	its UUID) and must discover everything else at boot time. A complex cascade of
	tasks must be performed to get the root file system mounted:

	* Any hardware drivers that the boot process depends on must be loaded. All
	kernel modules for common storage devices are packed onto the initramfs and then
	udev pulls in modules matching the computer's detected hardware.

	* On systems which display a boot rd.splash screen, the video hardware must be
	initialized and a user-space helper started to paint animations onto the display
	in lockstep with the boot process.

	* If the root file system is on NFS, dracut does then:
	** Bring up the primary network interface.
	** Invoke a DHCP client, with which it can obtain a DHCP lease.
	** Extract the name of the NFS share and the address of the NFS server from the
	lease.
	** Mount the NFS share.

	* If the root file system appears to be on a software RAID device, there is no
	way of knowing which devices the RAID volume spans; the standard MD utilities
	must be invoked to scan all available block devices with a raid signature and
	bring the required ones online.

	* If the root file system appears to be on a logical volume, the LVM utilities
	must be invoked to scan for and activate the volume group containing it.

	* If the root file system is on an encrypted block device:
	** Invoke a helper script to prompt the user to type in a passphrase and/or
	insert a hardware token (such as a smart card or a USB security dongle).

	* Create a decryption target with the device mapper.

	dracut uses udev, an event-driven hotplug agent, which invokes helper programs
	as hardware devices, disk partitions and storage volumes matching certain rules
	come online. This allows discovery to run in parallel, and to progressively
	cascade into arbitrary nestings of LVM, RAID or encryption to get at the root
	file system.

	When the root file system finally becomes visible:

	* Any maintenance tasks which cannot run on a mounted root file system
	are done.
	* The root file system is mounted read-only.
	* Any processes which must continue running (such as the rd.splash screen helper
	and its command FIFO) are hoisted into the newly-mounted root file system.

	The final root file system cannot simply be mounted over /, since that would
	make the scripts and tools on the initial root file system inaccessible for any
	final cleanup tasks. On an initramfs, the initial root file system cannot be
	rotated away. Instead, it is simply emptied and the final root file system
	mounted over the top.

	If the systemd module is used in the initramfs, the ordering of the services
	started looks like <<dracutbootup7>>.

	== Dracut on shutdown

	On a systemd driven system, the dracut initramfs is also used for the shutdown
	procedure.

	The following steps are executed during a shutdown:

	* systemd switches to the shutdown.target
	* systemd starts
	$prefix/lib/systemd/system/shutdown.target.wants/dracut-shutdown.service
	* dracut-shutdown.service executes /usr/lib/dracut/dracut-initramfs-restore
	which unpacks the initramfs to /run/initramfs
	* systemd finishes shutdown.target
	* systemd kills all processes
	* systemd tries to unmount everything and mounts the remaining read-only
	* systemd checks, if there is a /run/initramfs/shutdown executable
	* if yes, it does a pivot_root to /run/initramfs and executes ./shutdown.
	The old root is then mounted on /oldroot.
	/usr/lib/dracut/modules.d/99shutdown/shutdown.sh is the shutdown executable.
	* shutdown will try to umount every /oldroot mount and calls the various
	shutdown hooks from the dracut modules

	This ensures, that all devices are disassembled and unmounted cleanly.

	= User Manual

	:leveloffset: 1
	include::dracut.8.asc[]

	:leveloffset: 1
	[[dracutconf5]]
	include::dracut.conf.5.asc[]

	[[dracutcmdline7]]
	include::dracut.cmdline.7.asc[]

	[[lsinitrd1]]
	include::lsinitrd.1.asc[]

	[[mkinitrd8]]
	include::mkinitrd.8.asc[]

	= Developer Manual

	:leveloffset: 1
	[[dracutmodules7]]
	include::dracut.modules.7.asc[]

	[[dracutbootup7]]
	include::dracut.bootup.7.asc[]

	:leveloffset: 0
	[appendix]
	License
	-------
	This work is licensed under the Creative Commons Attribution/Share-Alike
	License. To view a copy of this license, visit
	http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
	Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.