Adding upstream version 060+5.upstream/060+5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 182 insertions, 0 deletions

diff --git a/man/dracut.asc b/man/dracut.asc
new file mode 100644
index 0000000..c806ab2
--- /dev/null
+++ b/man/dracut.asc
@@ -0,0 +1,182 @@
+dracut {mainversion}
+====================
+:author: Harald Hoyer
+:email: harald@profian.com
+:revnumber: {version}
+: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/ext4 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 initramfs 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 unmount 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[]
+
+= 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.
+