diff --git a/doc_site/modules/ROOT/pages/index.adoc b/doc_site/modules/ROOT/pages/index.adoc index 6465d8169..7dc2322e0 100644 --- a/doc_site/modules/ROOT/pages/index.adoc +++ b/doc_site/modules/ROOT/pages/index.adoc @@ -4,88 +4,79 @@ :revnumber: {version} :language: bash -dracut is a tool to create an initial image used by the kernel for loading -necessary drivers and performing other configuration required to enabling -booting of the main system. +dracut is a modular tool which generates an initial image capable of loading +necessary drivers and performing other configuration during early Linux boot. -dracut creates an initrd image by copying tools and files from an installed -system and combining it with dracut modules, usually found in -/usr/lib/dracut/modules.d. - -Unlike other implementations, dracut hard-codes as little -as possible into the initramfs. The initramfs has -(basically) one purpose in life -- getting the rootfs mounted so that -we can transition to the real rootfs. This is all driven off of -device availability. Therefore, instead of scripts hard-coded to do -various things, we depend on udev to create device nodes for us and -then when we have the rootfs's device node, we mount and carry on. -This helps to keep the time required in the initramfs as little as -possible so that things like a 5 second boot aren't made impossible as -a result of the very existence of an initramfs. - -Most of the initramfs generation functionality in dracut is provided by a bunch -of generator modules that are sourced by the main dracut script to install -specific functionality into the initramfs. They live in the modules.d -subdirectory, and use functionality provided by dracut-functions to do their - -== initrd and initramfs - -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. +== The early boot environment -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). +Most Linux distributions ship a single, generic kernel image that is intended +to boot a wide variety of hardware. The device drivers for this generic kernel +image are included as loadable modules, as it is not practical to statically +compile them all into the one kernel without making it excessively large. +However, this then raises the problem of detecting and loading the device +driver 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. +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 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 contains user-space helpers that do the hardware +detection, module loading and device discovery necessary to get the "real" root +file system mounted, which the kernel then "pivots" onto to continue the boot +process. -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) - +computer. This is usally partition on a local disk (a _boot partition_) or +perhaps remotely via 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. +== initrd and initramfs -== 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). +_initrd_ and _initramfs_ are two related but different methods of creating the +early user space environment. Both achieve similar goals of allowing the +kernel to find the main root device, but operate differently. -dracut can also generate a more generic initramfs image (default mode). +In short, _initrd_ is a block device image, while an _initramfs_ is a +link:https://en.wikipedia.org/wiki/Cpio[cpio] archive that the kernel extracts +to a link:https://www.kernel.org/doc/html/v6.6/filesystems/tmpfs.html[temporary +file system] created at boot. The difference is subtle but important to many +of the internal operations of kernel initalization; for more details see +link:https://kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt[kernel +rootfs documentation]. + +While the _initrd_ approach is essentially obsolete, you may still see +references to it; confusingly the terms are sometimes used interchangeably. + +dracut creates _initramfs_ archives. + +== dracut's approach + +dracut creates an initrd image by copying tools and files from an installed +system and combining it with dracut modules, usually found on an installed +system in `/usr/lib/dracut/modules.d`. + +Unlike other implementations, dracut hard-codes as little as possible into the +initramfs. To keep the time required in the initramfs as little as possible, +instead of scripts hard-coded to do various things, dracut depends on on `udev` +to create device nodes. When the rootfs's device node is available, we mount +and carry on. + +Most of the initramfs generation functionality in dracut is provided by +generator modules that are sourced by the main dracut script to install +specific functionality into the initramfs. They live in the `modules.d` +subdirectory, and use functionality provided by dracut-functions to do their +work. + +== Mount preparations 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 @@ -95,9 +86,9 @@ tasks must be performed to get the root file system mounted: 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. +* 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. @@ -120,18 +111,18 @@ 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. +dracut uses link:https://en.wikipedia.org/wiki/Udev[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 +* 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 @@ -143,6 +134,18 @@ mounted over the top. If the systemd module is used in the initramfs, the ordering of the services started looks like xref:man/dracut.bootup.7.adoc[]. +== Host v Default mode + +Dracut can operate in two modes + +host-only mode:: dracut will generate a smaller customized initramfs image +which contains only whatever is necessary to boot based on examining the +running system. + +default mode:: dracut will generate a larger, but more generic, initramfs +image. This is important for generic kernels, or if you are switching hardware +for an installed system. + == Dracut on shutdown On a systemd driven system, the dracut initramfs is also used for the shutdown