This page describes how to debug Dracut. For general information on how to file a bug, should you need to do so, please see Bugs and feature requests.

Identifying your problem area

{{{problem_area}}}

Information to include in your report

{{{report_info}}}

Foreword

If you are experiencing a problem with system initialization due to Dracut, please see the common bugs document before filing a bug. Some easy configuration tweaks that fix a wide range of issues may be listed there. If the problem you are seeing is not listed there or none of the workarounds seem to help, please consider filing a bug to help us make Fedora run better on your hardware.

Be prepared to include some information (logs) about your system as well. These should be complete (no snippets please), not in an archive, uncompressed, with MIME type set as text/plain.

Identifying your problem area

Remove rhgb and quiet from the kernel command line
Add rdshell to the kernel command line. This will present a shell should dracut be unable to locate your root device
Add rdshell rdinitdebug to the kernel command line so that dracut shell commands are printed as they are executed
With dracut >= 002-11 [1], you can inspect the rdinitdebug output with:
```
# less /init.log
```
```
# dmesg | less
```

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. /etc/grub.conf) or from /proc/cmdline
A copy of your disk partition information from /etc/fstab
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 and blkid -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

Logical Volume Management related problems

As well as the information from the 'all bug reports' section, 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

As well as the information from the 'all bug reports' section, include the following information:

If using software RAID disk partitions, please include the output of /proc/mdstat

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 'all bug reports' section, include the following information:

Please include the output of 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 capture 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 [2].

Redirecting non-interactive output
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

Enable the dracut debug module

To turn on dracut debugging, you must rebuild the dracut initial ramdisk with the appropriate parameter. The following commands demonstrate rebuilding the ramdisk with the debug dracut module enabled.

Create a dracut ramdisk image with debugging enabled

dracut -a debug /boot/initrd-debug-$(uname -r).img $(uname -r)

Next, tell your bootloader to use the new dracut ramdisk
```
grubby --make-default --title "Debugging dracut" \
```
--add-kernel /boot/vmlinuz-$(uname -r) \

--initrd /boot/initrd-debug-$(uname -r).img \

--copy-default
When ready to debug dracut, reboot the system

Using the 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 rdshell 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 console=ttyS0,9600 rdshell 
        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.

sh: can't access tty; job control turned off
#

Use this shell prompt to gather the information requested above (see the 'all bug reports' section).

Additional dracut boot parameters

The following boot parameters are also available to further assist with debugging boot issues.

rdshell: Drop to a shell, if the initramfs fails.
rdinitdebug: set -x for the dracut shell.
rdbreak=[pre-udev|pre-mount|mount|pre-pivot|]: drop the shell on defined breakpoint
rdudevinfo: set udev to loglevel info
rdudevdebug: set udev to loglevel debug
rdnetdebug: debug network scripts in dracut. Output is written to /tmp

Search

How to debug Dracut problems2

Contents