You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1034 lines
32 KiB
1034 lines
32 KiB
dracut |
|
====== |
|
Harald Hoyer <harald@redhat.com> |
|
v2.0, March 2011 |
|
|
|
: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. |
|
|
|
= User Manual |
|
|
|
== Creating an initramfs Image |
|
To create a initramfs image, the most simple command is: |
|
---- |
|
# dracut |
|
---- |
|
|
|
This will generate a general purpose initramfs image, with all possible |
|
functionality resulting of the combination of the installed dracut modules and |
|
system tools. The image is /boot/initramfs-_++<kernel version>++_.img and |
|
contains the kernel modules of the currently active kernel with version |
|
_++<kernel version>++_. |
|
|
|
If the initramfs image already exists, dracut will display an error message, and |
|
to overwrite the existing image, you have to use the --force option. |
|
---- |
|
# dracut --force |
|
---- |
|
|
|
If you want to specify another filename for the resulting image you would issue |
|
a command like: |
|
---- |
|
# dracut foobar.img |
|
---- |
|
|
|
To generate an image for a specific kernel version, the command would be: |
|
---- |
|
# dracut foobar.img 2.6.40-1.rc5.f20 |
|
---- |
|
|
|
A shortcut to generate the image at the default location for a specific kernel |
|
version is: |
|
---- |
|
# dracut '' 2.6.40-1.rc5.f20 |
|
---- |
|
|
|
If you want to create lighter, smaller initramfs images, you may want to specify |
|
the --host-only or -H option. Using this option, the resulting image will |
|
contain only those dracut modules, kernel modules and filesystems, which are |
|
needed to boot this specific machine. This has the drawback, that you can't put |
|
the disk on another controller or machine, and that you can't switch to another |
|
root filesystem, without recreating the initramfs image. The usage of the |
|
--host-only option is only for experts and you will have to keep the broken |
|
pieces. At least keep a copy of a general purpose image (and corresponding |
|
kernel) as a fallback to rescue your system. |
|
|
|
=== Inspecting the Contents |
|
To see the contents of the image created by dracut, you can use the lsinitrd tool. |
|
---- |
|
# lsinitrd /boot/initramfs-$(uname -r).img | less |
|
---- |
|
|
|
To display the contents of a file in the initramfs also use the lsinitrd tool: |
|
---- |
|
# lsinitrd /boot/initramfs-$(uname -r).img /etc/ld.so.conf |
|
include ld.so.conf.d/*.conf |
|
---- |
|
|
|
=== Adding dracut Modules |
|
Some dracut modules are turned off by default and have to be activated manually. |
|
You can do this by adding the dracut modules to the configuration file |
|
_/etc/dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_. See <<dracutconf5>>. |
|
You can also add dracut modules on the command line |
|
by using the -a or --add option: |
|
---- |
|
# dracut --add bootchart initramfs-bootchart.img |
|
---- |
|
|
|
To see a list of available dracut modules, use the --list-modules option: |
|
---- |
|
# dracut --list-modules |
|
---- |
|
|
|
or, if you have a dracut version earlier than +008+, issue the command: |
|
---- |
|
# for mod in /usr/lib/dracut/modules.d/*; do echo ${mod##*/??}; done |
|
---- |
|
|
|
=== Omitting dracut Modules |
|
Sometimes you don't want a dracut module to be included for reasons of speed, |
|
size or functionality. To do this, either specify the omit_dracutmodules |
|
variable in the _dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_ configuration |
|
file (see <<dracutconf5>>), or use the -o or --omit option |
|
on the command line: |
|
---- |
|
# dracut -o "multipath lvm" no-multipath-lvm.img |
|
---- |
|
|
|
=== Adding Kernel Modules |
|
If you need a special kernel module in the initramfs, which is not |
|
automatically picked up by dracut, you have the use the --add-drivers option |
|
on the command line or the drivers vaiable in the _/etc/dracut.conf_ |
|
or _/etc/dracut.conf.d/myconf.conf_ configuration file (see <<dracutconf5>>): |
|
---- |
|
# dracut --add-drivers mymod initramfs-with-mymod.img |
|
---- |
|
|
|
== Boot parameters |
|
The generated initramfs.img file normally does not contain any system |
|
configuration files (except for some special exceptions), so the configuration |
|
has to be done on the kernel command line. With this flexibility, you can easily |
|
boot from a changed root partition, without the need to recompile the initramfs |
|
image. So, you could completly change your root partition (move it inside a md |
|
raid with encryption and LVM on top), as long as you specify the correct |
|
filesystem LABEL or UUID on the kernel command line for your root device, dracut |
|
will find it and boot from it. |
|
|
|
The kernel command line usually can be configured in _/boot/grub/grub.conf_, if |
|
grub is your bootloader and it also can be edited in the real boot process in |
|
the grub menu. |
|
|
|
The kernel command line can also be provided by the dhcp server with the |
|
root-path option. See <<NetworkBoot>>. |
|
|
|
For a full reference of all kernel command line parameters, see <<dracut8>>. |
|
|
|
=== Specifying the root Device |
|
This is the only option dracut really needs to boot from your root partition. |
|
Because your root partition can live in various environments, there are a lot of |
|
formats for the root= option. The most basic one is root=_++<path to device |
|
node>++_: |
|
---- |
|
root=/dev/sda2 |
|
---- |
|
|
|
Because device node names can change, dependent on the drive ordering, you are |
|
encouraged to use the filesystem identifier (UUID) or filesystem label (LABEL) |
|
to specify your root partition: |
|
---- |
|
root=UUID=19e9dda3-5a38-484d-a9b0-fa6b067d0331 |
|
---- |
|
|
|
or |
|
|
|
---- |
|
root=LABEL=myrootpartitionlabel |
|
---- |
|
|
|
To see all UUIDs or LABELs on your system, do: |
|
---- |
|
# ls -l /dev/disk/by-uuid |
|
---- |
|
|
|
or |
|
|
|
---- |
|
# ls -l /dev/disk/by-label |
|
---- |
|
|
|
If your root partition is on the network see <<NetworkBoot>>. |
|
|
|
=== Keyboard Settings |
|
If you have to input passwords for encrypted disk volumes, you might want to set |
|
the keyboard layout and specify a display font. |
|
|
|
A typical german kernel command would contain: |
|
---- |
|
vconsole.font=latarcyrheb-sun16 vconsole.keymap=de-latin1-nodeadkeys locale.LANG=de_DE.UTF-8 |
|
---- |
|
|
|
Setting these options can override the setting stored on your system, if you use |
|
a modern init system, like systemd. |
|
|
|
For dracut versions prior to version +008+ the line would look like: |
|
---- |
|
LANG=de_DE.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc KEYTABLE=de-latin1-nodeadkeys |
|
---- |
|
|
|
=== Blacklisting Kernel Modules |
|
Sometimes it is required to prevent the automatic kernel module loading of a |
|
specific kernel module. To do this, just add rd.blacklist=_++<kernel module |
|
name>++_, with _++<kernel module name>++_ not containing the _.ko_ |
|
suffix, to the kernel command line. For example: |
|
---- |
|
rd.driver.blacklist=mptsas rd.driver.blacklist=nouveau |
|
---- |
|
|
|
The option can be specified multiple times on the kernel command line. |
|
|
|
=== Speeding up the Boot Process |
|
If you want to speed up the boot process, you can specify as much information |
|
for dracut on the kernel command as possible. For example, you can tell dracut, |
|
that you root partition is not on a LVM volume or not on a raid partition, or |
|
that it lives inside a specific crypto LUKS encrypted volume. By default, dracut |
|
searches everywhere. A typical dracut kernel command line for a plain primary or |
|
logical partition would contain: |
|
---- |
|
rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 |
|
---- |
|
|
|
On systems with dracut version prior to +008+ the line would look like: |
|
---- |
|
rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM |
|
---- |
|
|
|
This turns off every automatic assembly of LVM, MD raids, DM raids and crypto LUKS. |
|
|
|
Of course, you could also omit the dracut modules in the initramfs creation |
|
process, but then you would lose the posibility to turn it on on demand. |
|
|
|
|
|
[[Injecting]] |
|
=== Injecting custom Files |
|
To add your own files to the initramfs image, you have several possibilities. |
|
|
|
The --include option let you specify a source path and a target path. For example |
|
---- |
|
# dracut --include cmdline-preset /etc/cmdline initramfs-cmdline-pre.img |
|
---- |
|
will create an initramfs image, where the file cmdline-preset will be copied |
|
inside the initramfs to _/etc/cmdline_. --include can only be specified once. |
|
|
|
|
|
---- |
|
# mkdir rd.live.overlay |
|
# mkdir rd.live.overlay/etc |
|
# mkdir rd.live.overlay/etc/conf.d |
|
# echo "ip=auto" >> rd.live.overlay/etc/cmdline |
|
# echo export TESTVAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf |
|
# echo export TESTVAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf |
|
# tree rd.live.overlay/ |
|
rd.live.overlay/ |
|
└── etc |
|
├── cmdline |
|
└── conf.d |
|
└── testvar.conf |
|
# dracut --include rd.live.overlay / initramfs-rd.live.overlay.img |
|
---- |
|
|
|
This will put the contents of the rd.live.overlay directory into the root of the |
|
initramfs image. |
|
|
|
The --install option let you specify several files, which will get installed in |
|
the initramfs image at the same location, as they are present on initramfs |
|
creation time. |
|
|
|
|
|
---- |
|
# dracut --install 'strace fsck.ext3 ssh' initramfs-dbg.img |
|
---- |
|
|
|
This will create an initramfs with the strace, fsck.ext3 and ssh executables, |
|
together with the libraries needed to start those. The --install option can be |
|
specified multiple times. |
|
|
|
|
|
[[NetworkBoot]] |
|
== Network Boot |
|
|
|
If your root partition is on a network drive, you have to have the network |
|
dracut modules installed to create a network aware initramfs image. |
|
|
|
On a Red Hat Enterprise Linux or Fedora system, this means, you have to install |
|
the _dracut-network_ rpm package: |
|
|
|
|
|
---- |
|
# yum install dracut-network |
|
---- |
|
|
|
The resulting initramfs image can be served by a boot manager residing on your |
|
local hard drive or it can be served by a PXE/TFTP server. |
|
|
|
How to setup your PXE/TFTP server can be found in the |
|
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/[Red |
|
Hat Enterprise Linux Storage Administration Guide]. |
|
|
|
If you specify rd.ip=auto on the kernel command line, then dracut asks a dhcp |
|
server about the ip adress for the machine. The dhcp server can also serve an |
|
additional root-path, which will set the root device for dracut. With this |
|
mechanism, you have static configuration on your client machine and a |
|
centralized boot configuration on your TFTP/DHCP server. If you can't pass a |
|
kernel command line, then you can inject _/etc/cmdline_, with a method described |
|
in <<Injecting>>. |
|
|
|
|
|
|
|
|
|
=== Reducing the Image Size |
|
|
|
To reduce the size of the initramfs, you should create it with by ommitting all |
|
dracut modules, which you know, you don't need to boot the machine. |
|
|
|
You can also specify the exact dracut and kernel modules to produce a very tiny |
|
initramfs image. |
|
|
|
For example for a NFS image, you would do: |
|
|
|
|
|
---- |
|
# dracut -m "nfs network base" initramfs-nfs-only.img |
|
---- |
|
|
|
Then you would boot from this image with your target machine and reduce the size |
|
once more by creating it on the target machine with the --host-only option: |
|
|
|
|
|
---- |
|
# dracut -m "nfs network base" --host-only initramfs-nfs-host-only.img |
|
---- |
|
|
|
This will reduce the size of the initramfs image significantly. |
|
|
|
|
|
|
|
=== NFS Root Device |
|
|
|
FIXME |
|
|
|
=== iSCSI Root Device |
|
|
|
FIXME |
|
|
|
=== FCoE Root Device |
|
|
|
FIXME |
|
|
|
== Troubleshooting |
|
|
|
If the boot process does not succeed, you have several options to debug the |
|
situation. Some of the basic operations are covered here. For more information |
|
you should also visit: |
|
http://fedoraproject.org/wiki/How_to_debug_Dracut_problems |
|
|
|
|
|
[[identifying-your-problem-area]] |
|
=== Identifying your problem area |
|
. Remove ''rhgb'' and ''quiet'' from the kernel command line |
|
. Add ''rd.shell'' to the kernel command line. This will present a shell should |
|
dracut be unable to locate your root device |
|
. Add ''rd.shell rd.debug log_buf_len=1M'' to the kernel command line so that |
|
dracut shell commands are printed as they are executed |
|
. With dracut >= 002-11, you can inspect the rd.debug output with: |
|
+ |
|
---- |
|
# less /run/initramfs/init.log |
|
# dmesg | less |
|
---- |
|
|
|
[[information-to-include-in-your-report]] |
|
=== Information to include in your report |
|
|
|
[[all-bug-reports]] |
|
==== All bug reports |
|
In all cases, the following should be mentioned and attached to your bug report: |
|
|
|
* The exact kernel command-line used. Typically from the bootloader |
|
configuration file (e.g. _/etc/grub.conf_) or from _/proc/cmdline_. |
|
* A copy of your disk partition information from _/etc/fstab_, which might be |
|
obtained booting an old working initramfs or a rescue medium. |
|
* A device listing from device-mapper. This can be obtained by running the |
|
command |
|
+ |
|
---- |
|
# dmsetup ls --tree |
|
---- |
|
+ |
|
* A list of block device attributes including vol_id compatible mode. This can |
|
be obtained by running the commands: |
|
+ |
|
---- |
|
# blkid -p |
|
# blkid -p -o udev |
|
---- |
|
* Turn on dracut debugging (see _the 'debugging dracut' section_), and attach |
|
all relevant information from the boot log. This can be obtained by running the |
|
command |
|
+ |
|
---- |
|
# dmesg|grep dracut |
|
---- |
|
+ |
|
* If you use a dracut configuration file, please include _/etc/dracut.conf_ and |
|
all files in _/etc/dracut.conf.d/*.conf_ |
|
|
|
[[logical-volume-management-related-problems]] |
|
==== Logical Volume Management related problems |
|
As well as the information from <<all-bug-reports>> include the following |
|
information: |
|
|
|
* Include physical volume information by running the command: |
|
+ |
|
---- |
|
# lvm pvdisplay |
|
---- |
|
+ |
|
* Include volume group information by running the command: |
|
+ |
|
---- |
|
# lvm vgdisplay |
|
---- |
|
+ |
|
* Include logical volume information by running the command: |
|
+ |
|
---- |
|
# lvm lvdisplay |
|
---- |
|
|
|
[[software-raid-related-problems]] |
|
==== Software RAID related problems |
|
As well as the information from <<all-bug-reports>>, include the following |
|
information: |
|
|
|
* If using software RAID disk partitions, please include the output of |
|
+ |
|
---- |
|
# cat /proc/mdstat |
|
---- |
|
|
|
[[network-root-device-related-problems]] |
|
==== Network root device related problems |
|
This section details information to include when experiencing problems on a |
|
system whose root device is located on a network attached volume (e.g. iSCSI, |
|
NFS or NBD). As well as the information from <<all-bug-reports>>, include the |
|
following information: |
|
|
|
|
|
* Please include the output of |
|
+ |
|
---- |
|
# /sbin/ifup <interfacename> |
|
# ip addr show |
|
---- |
|
|
|
[[debugging-dracut]] |
|
=== Debugging dracut |
|
|
|
|
|
[[configure-a-serial-console]] |
|
==== Configure a serial console |
|
|
|
Successfully debugging dracut will require some form of console |
|
logging during the system boot. This section documents configuring a |
|
serial console connection to record boot messages. |
|
|
|
. First, enable serial console output for both the kernel and the bootloader. |
|
. Open the file _/etc/grub.conf_ for editing. Below the line ''timeout=5'', add |
|
the following: |
|
+ |
|
---- |
|
serial --unit=0 --speed=9600 |
|
terminal --timeout=5 serial console |
|
---- |
|
+ |
|
. Also in _/etc/grub.conf_, add the following boot arguemnts to the ''kernel'' |
|
line: |
|
+ |
|
---- |
|
console=tty0 console=ttyS0,9600 |
|
---- |
|
+ |
|
. When finished, the _/etc/grub.conf_ file should look similar to the example |
|
below. |
|
+ |
|
---- |
|
default=0 |
|
timeout=5 |
|
serial --unit=0 --speed=9600 |
|
terminal --timeout=5 serial console |
|
title Fedora (2.6.29.5-191.fc11.x86_64) |
|
root (hd0,0) |
|
kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 console=ttyS0,9600 |
|
initrd /dracut-2.6.29.5-191.fc11.x86_64.img |
|
---- |
|
+ |
|
. More detailed information on how to configure the kernel for console output |
|
can be found at |
|
http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL. |
|
. Redirecting non-interactive output |
|
+ |
|
-- |
|
NOTE: You can redirect all non-interactive output to _/dev/kmsg_ and the kernel |
|
will put it out on the console when it reaches the kernel buffer by doing |
|
|
|
---- |
|
# exec >/dev/kmsg 2>&1 </dev/console |
|
---- |
|
-- |
|
|
|
[[using-the-dracut-shell]] |
|
==== Using the dracut shell |
|
|
|
Dracut offers a shell for interactive debugging in the event dracut fails to |
|
locate your root filesystem. To enable the shell: |
|
|
|
. Add the boot parameter ''rd.shell'' to your bootloader configuration file |
|
(e.g. _/etc/grub.conf_) |
|
. Remove the boot arguments ''rhgb'' and ''quiet'' |
|
+ |
|
A sample _/etc/grub.conf_ bootloader configuration file is listed below. |
|
+ |
|
---- |
|
default=0 |
|
timeout=5 |
|
serial --unit=0 --speed=9600 |
|
terminal --timeout=5 serial console |
|
title Fedora (2.6.29.5-191.fc11.x86_64) |
|
root (hd0,0) |
|
kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 rd.shell |
|
initrd /dracut-2.6.29.5-191.fc11.x86_64.img |
|
---- |
|
+ |
|
. If system boot fails, you will be dropped into a shell as seen in the example below. |
|
+ |
|
---- |
|
No root device found |
|
Dropping to debug shell. |
|
|
|
# |
|
---- |
|
+ |
|
. Use this shell prompt to gather the information requested above (see <<all-bug-reports>>). |
|
|
|
[[accessing-the-root-volume-from-the-dracut-shell]] |
|
==== Accessing the root volume from the dracut shell |
|
From the dracut debug shell, you can manually perform the task of locating and |
|
preparing your root volume for boot. The required steps will depend on how your |
|
root volume is configured. Common scenarios include: |
|
|
|
* A block device (e.g. _/dev/sda7_) |
|
* A LVM logical volume (e.g. _/dev/VolGroup00/LogVol00_) |
|
* An encrypted device (e.g. _/dev/mapper/luks-4d5972ea-901c-4584-bd75-1da802417d83_) |
|
* A network attached device (e.g. netroot=iscsi:@192.168.0.4::3260::iqn.2009-02.org.fedoraproject:for.all) |
|
|
|
The exact method for locating and preparing will vary. However, to continue with |
|
a successful boot, the objective is to locate your root volume and create a |
|
symlink _/dev/root_ which points to the file system. For example, the following |
|
example demonstrates accessing and booting a root volume that is an encrypted |
|
LVM Logical volume. |
|
|
|
. Inspect your partitions using parted |
|
+ |
|
---- |
|
# parted /dev/sda -s p |
|
Model: ATA HTS541060G9AT00 (scsi) |
|
Disk /dev/sda: 60.0GB |
|
Sector size (logical/physical): 512B/512B |
|
Partition Table: msdos |
|
Number Start End Size Type File system Flags |
|
1 32.3kB 10.8GB 107MB primary ext4 boot |
|
2 10.8GB 55.6GB 44.7GB logical lvm |
|
---- |
|
+ |
|
. You recall that your root volume was a LVM logical volume. Scan and activate |
|
any logical volumes. |
|
+ |
|
---- |
|
# lvm vgscan |
|
# lvm vgchange -ay |
|
---- |
|
+ |
|
. You should see any logical volumes now using the command blkid: |
|
+ |
|
---- |
|
# blkid |
|
/dev/sda1: UUID="3de247f3-5de4-4a44-afc5-1fe179750cf7" TYPE="ext4" |
|
/dev/sda2: UUID="Ek4dQw-cOtq-5MJu-OGRF-xz5k-O2l8-wdDj0I" TYPE="LVM2_member" |
|
/dev/mapper/linux-root: UUID="def0269e-424b-4752-acf3-1077bf96ad2c" TYPE="crypto_LUKS" |
|
/dev/mapper/linux-home: UUID="c69127c1-f153-4ea2-b58e-4cbfa9257c5e" TYPE="ext3" |
|
/dev/mapper/linux-swap: UUID="47b4d329-975c-4c08-b218-f9c9bf3635f1" TYPE="swap" |
|
---- |
|
+ |
|
. From the output above, you recall that your root volume exists on an encrypted |
|
block device. Following the guidance disk encryption guidance from the |
|
Installation Guide, you unlock your encrypted root volume. |
|
+ |
|
---- |
|
# UUID=$(cryptsetup luksUUID /dev/mapper/linux-root) |
|
# cryptsetup luksOpen /dev/mapper/linux-root luks-$UUID |
|
Enter passphrase for /dev/mapper/linux-root: |
|
Key slot 0 unlocked. |
|
---- |
|
+ |
|
. Next, make a symbolic link to the unlocked root volume |
|
+ |
|
---- |
|
# ln -s /dev/mapper/luks-$UUID /dev/root |
|
---- |
|
+ |
|
. With the root volume available, you may continue booting the system by exiting |
|
the dracut shell |
|
+ |
|
---- |
|
# exit |
|
---- |
|
|
|
[[additional-dracut-boot-parameters]] |
|
==== Additional dracut boot parameters |
|
For more debugging options, see <<dracutkerneldebug>> in <<dracutcmdline7>>. |
|
|
|
= Developer Manual |
|
|
|
== dracut Components |
|
|
|
dracut uses a modular system to build and extend the initramfs image. All |
|
modules are located in _/usr/lib/dracut/modules.d_ or in _<git-src>/modules.d_. |
|
The most basic dracut module is _99base_. In _99base_ the initial shell script |
|
init is defined, which gets run by the kernel after initramfs loading. Although |
|
you can replace init with your own version of _99base_, this is not encouraged. |
|
Instead you should use, if possible, the hooks of dracut. All hooks, and the |
|
point of time in which they are executed, are described in <<stages>>. |
|
|
|
The main script, which creates the initramfs is dracut itsself. It parses all |
|
arguments and sets up the directory, in which everything is installed. It then |
|
executes all check, install, installkernel scripts found in the modules, which |
|
are to be processed. After everything is installed, the install directory is |
|
archived and compressed to the final initramfs image. All helper functions used |
|
by check, install and installkernel are found in in the file _dracut-functions_. |
|
These shell functions are available to all module installer (install, |
|
installkernel) scripts, without the need to source _dracut-functions_. |
|
|
|
A module can check the preconditions for install and installkernel with the |
|
check script. Also dependencies can be expressed with check. If a module passed |
|
check, install and installkernel will be called to install all of the necessary |
|
files for the module. To split between kernel and non-kernel parts of the |
|
installation, all kernel module related parts have to be in installkernel. All |
|
other files found in a module directory are module specific and mostly are hook |
|
scripts and udev rules. |
|
|
|
|
|
[[stages]] |
|
== Boot Process Stages |
|
|
|
The init script in _99base_ is the main script, which prepares the root file |
|
system for usage, runs udev, mounts the real root device, kills the remaining |
|
processes, and switches to the real root device for further booting. dracut |
|
modules can insert custom script at various points, to control the boot process. |
|
These hooks are plain directories containing shell scripts ending with ".sh", |
|
which are sourced by init. |
|
Common used functions are in _dracut-lib.sh_, which can be sourced by any script. |
|
|
|
|
|
|
|
=== Basic Setup |
|
|
|
The first thing init does, is to mount _/proc_ and _/sys_ and manually create |
|
the basic device nodes and symbolic links in _/dev_ needed to execute basic |
|
commands. Then logging is setup according to kernel command line arguments. |
|
_/dev/pts_ and _/dev/shm_ are mounted and the first hook is sourced. |
|
|
|
|
|
|
|
=== Hook: cmdline |
|
|
|
The _cmdline_ hook is a place to insert scripts to parse the kernel command line |
|
and prepare the later actions, like setting up udev rules and configuration |
|
files. |
|
|
|
In this hook the most important environment variable is defined: root. The |
|
second one is rootok, which indicates, that a module claimed to be able to parse |
|
the root defined. So for example, **root=**__iscsi:....__ will be claimed by the |
|
iscsi dracut module, which then sets rootok. |
|
|
|
=== Hook: pre-udev |
|
|
|
This hook is executed right after the cmdline hook and a check if root and |
|
rootok were set. Here modules can take action with the final root, and before |
|
udev has been run. |
|
|
|
|
|
|
|
=== Start Udev |
|
|
|
Now udev is started and the logging for udev is setup. |
|
|
|
|
|
|
|
=== Hook: pre-trigger |
|
|
|
In this hook, you can set udev environment variables with **udevadm control |
|
--property=KEY=_value_** or control the further execution of udev with |
|
udevadm. |
|
|
|
|
|
|
|
=== Trigger Udev |
|
|
|
udev is triggered by calling udevadm trigger, which sends add events for all |
|
devices and subsystems. |
|
|
|
|
|
|
|
=== Main Loop |
|
|
|
Now the main loop of 99base/init begins. Here we loop until udev has settled and |
|
all scripts in _initqueue/finished_ returned true. In this loop there are three |
|
hooks, where scripts can be inserted by calling /sbin/initqueue. |
|
|
|
|
|
|
|
==== Initqueue |
|
|
|
This hook gets executed every time a script is inserted here, regardless of the |
|
udev state. |
|
|
|
|
|
|
|
==== Initqueue settled |
|
|
|
This hooks gets executed every time udev has settled. |
|
|
|
|
|
|
|
==== Initqueue timeout |
|
|
|
This hooks gets executed, when the main loop counter becomes half of the |
|
rd.retry counter. |
|
|
|
|
|
|
|
==== Initqueue finished |
|
|
|
This hook is called after udev has settled and if all scripts herein return 0 |
|
the main loop will be ended. |
|
|
|
|
|
|
|
=== Hook: pre-mount |
|
|
|
Before the root device is mounted all scripts in the hook pre-mount are |
|
executed. In some cases (e.g. NFS) the real root device is already mounted, |
|
though. |
|
|
|
|
|
|
|
=== Hook: mount |
|
|
|
This hook is mainly to mount the real root device. |
|
|
|
|
|
|
|
=== Hook: pre-pivot |
|
|
|
This hook is called before cleanup hook, This is a good place for |
|
actions other than cleanups which need to be called before pivot. |
|
|
|
|
|
=== Hook: cleanup |
|
|
|
This hook is the last hook and is called before init finally switches root to |
|
the real root device. This is a good place to clean up and kill processes not |
|
needed anymore. |
|
|
|
|
|
=== Cleanup and switch_root |
|
|
|
Init kills all udev processes, cleans up the environment, sets up the arguments |
|
for the real init process and finally calls switch_root. switch_root removes the |
|
whole filesystem hierarchy of the initramfs, chroot()s to the real root device |
|
and calls /sbin/init with the specified arguments. |
|
|
|
To ensure all files in the initramfs hierarchy can be removed, all processes |
|
still running from the initramfs should not have any open file descriptors left. |
|
|
|
|
|
|
|
== Network Infrastructure |
|
|
|
|
|
FIXME |
|
|
|
|
|
== Writing a Module |
|
|
|
A simple example module is _96insmodpost_, which modprobes a kernel module after |
|
udev has settled and the basic device drivers have been loaded. |
|
|
|
All module installation information is in the file module-setup.sh. |
|
|
|
First we create a check() function, which just exits with 0 indicating that this |
|
module should be included by default. |
|
|
|
check(): |
|
|
|
|
|
---- |
|
return 0 |
|
---- |
|
|
|
The we create the install() function, which installs a cmdline hook with |
|
priority number 20 called _parse-insmodpost.sh_. It also installs the |
|
_insmodpost.sh_ script in _/sbin_. |
|
|
|
install(): |
|
|
|
|
|
---- |
|
inst_hook cmdline 20 "$moddir/parse-insmodpost.sh" |
|
inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh |
|
---- |
|
|
|
The _pase-instmodpost.sh_ parses the kernel command line for a argument |
|
rd.driver.post, blacklists the module from being autoloaded and installs the |
|
hook _insmodpost.sh_ in the _initqueue/settled_. |
|
|
|
_parse-insmodpost.sh_: |
|
|
|
|
|
---- |
|
for p in $(getargs rd.driver.post=); do |
|
echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf |
|
_do_insmodpost=1 |
|
done |
|
|
|
[ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh |
|
unset _do_insmodpost |
|
|
|
---- |
|
|
|
_insmodpost.sh_, which is called in the _initqueue/settled_ hook will just |
|
modprobe the kernel modules specified in all rd.driver.post kernel command line |
|
parameters. It runs after udev has settled and is only called once (--onetime). |
|
|
|
_insmodpost.sh_: |
|
|
|
|
|
---- |
|
. /lib/dracut-lib.sh |
|
|
|
for p in $(getargs rd.driver.post=); do |
|
modprobe $p |
|
done |
|
|
|
---- |
|
|
|
|
|
|
|
=== check() |
|
|
|
_check()_ is called by dracut to evaluate the inclusion of a dracut module in |
|
the initramfs. |
|
|
|
$hostonly:: If the $hostonly variable is set, then the module check() function |
|
should be in "hostonly" mode, which means, that the check() should only return |
|
0, if the module is really needed to boot this specific host. |
|
|
|
check() should return with: |
|
|
|
0:: Include the dracut module in the initramfs. |
|
|
|
1:: Do not include the dracut module. The requirements are not fullfilled |
|
(missing tools, etc.) |
|
|
|
255:: Only include the dracut module, if another module requires it or if |
|
explicitly specified in the config file or on the argument list. |
|
|
|
|
|
|
|
=== depends() |
|
|
|
The function depends() should echo all other dracut module names the module |
|
depends on. |
|
|
|
|
|
|
|
=== install() |
|
|
|
dracut_install |
|
|
|
inst |
|
|
|
inst_hook |
|
|
|
inst_rules |
|
|
|
|
|
|
|
|
|
|
|
=== installkernel() |
|
|
|
instmods |
|
|
|
|
|
|
|
=== Creation Functions |
|
|
|
|
|
FIXME |
|
|
|
|
|
=== Initramfs Functions |
|
|
|
|
|
FIXME |
|
|
|
|
|
=== Network Modules |
|
|
|
FIXME |
|
|
|
|
|
:leveloffset: 1 |
|
[[dracut8]] |
|
include::dracut.8.asc[] |
|
|
|
[[dracutconf5]] |
|
include::dracut.conf.5.asc[] |
|
|
|
[[dracutcmdline7]] |
|
include::dracut.cmdline.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. |
|
|
|
|