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:
https://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html
Identifying your problem area
1. Remove 'rhgb' and 'quiet' from the kernel command line
2. Add 'rd.shell' to the kernel command line. This will present
a shell should dracut be unable to locate your root device
3. 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
4. The file /run/initramfs/rdsosreport.txt is generated, which
contains all the logs and the output of all significant
tools, which are mentioned later.
If you want to save that output, simply mount /boot by hand or
insert an USB stick and mount that. Then you can store the output
for later inspection.
Information to include in your report
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.
/boot/grub2/grub.cfg) 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.
• Turn on dracut debugging (see the debugging dracut
section), and attach the file
/run/initramfs/rdsosreport.txt.
• If you use a dracut configuration file, please include
/etc/dracut.conf and all files in
/etc/dracut.conf.d/*.conf
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 the section called 'All bug reports',
include the following information:
• Please include the output of
# /sbin/ifup <interfacename>
# ip addr show
Debugging dracut
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.
1. First, enable serial console output for both the kernel
and the bootloader.
2. Open the file /boot/grub2/grub.cfg for editing. Below the
line 'timeout=5', add the following:
serial --unit=0 --speed=9600
terminal --timeout=5 serial console
3. Also in /boot/grub2/grub.cfg, add the following boot
arguments to the 'kernel' line:
console=tty0 console=ttyS0,9600
4. When finished, the /boot/grub2/grub.cfg 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
5. 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
6. 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
dracut offers a shell for interactive debugging in the event
dracut fails to locate your root filesystem. To enable the
shell:
1. Add the boot parameter 'rd.shell' to your bootloader
configuration file (e.g. /boot/grub2/grub.cfg)
2. Remove the boot arguments 'rhgb' and 'quiet'
A sample /boot/grub2/grub.cfg 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
3. 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.
#
4. Use this shell prompt to gather the information requested
above (see the section called 'All bug reports').
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.example: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.
1. 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
2. You recall that your root volume was a LVM logical
volume. Scan and activate any logical volumes.
# lvm vgscan
# lvm vgchange -ay
3. 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"
4. 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.
5. Next, make a symbolic link to the unlocked root volume
# ln -s /dev/mapper/luks-$UUID /dev/root
6. With the root volume available, you may continue booting
the system by exiting the dracut shell
# exit
Additional dracut boot parameters
For more debugging options, see dracut.cmdline(7).
Debugging dracut on shutdown
To debug the shutdown sequence on systemd systems, you can
rd.break on pre-shutdown or shutdown.
To do this from an already booted system:
# mkdir -p /run/initramfs/etc/cmdline.d
# echo "rd.debug rd.break=pre-shutdown rd.break=shutdown" > /run/initramfs/etc/cmdline.d/debug.conf
# touch /run/initramfs/.need_shutdown
This will give you a dracut shell after the system pivot'ed
back in the initramfs.
