How to debug Dracut problems

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(All bug reports: add blkid output)
m (Some wiki updates and corrected template use)
Line 1: Line 1:
 
<!--{{header|dracut}}-->
 
<!--{{header|dracut}}-->
  
== All bug reports ==
+
'''Foreword'''
  
In all cases, the following should be mentioned and attached to your bug report:
+
If you are experiencing a problem with system initialization due to [[Dracut]], please see the [[Bugs/Common|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.
  
'''The exact kernel command line used!'''
+
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.
  
An copy of '''/etc/fstab'''
+
= Identifying your problem area =
  
<pre>cp /etc/fstab ~USER/Desktop/fstab.txt</pre>
+
{{admon/note|FIXME|provide guidance on what dracut bugs look like. How to tell if this is related to dracut, or just a kernel problem?}}
  
The output of '''dmsetup ls --tree'''.
+
= Information to include in your report =
<pre> dmsetup ls --tree > ~USER/Desktop/dmsetup.txt</pre>
+
  
The output of '''blkid; blkid -o udev'''.
+
{{Anchor|AllInfo}}
<pre> (blkid; blkid -o udev) > ~USER/Desktop/blkid.txt</pre>
+
  
If using an raid device the output of '''cat /proc/mdstat'''.
+
== All bug reports ==
  
<pre> cat /proc/mdstat > ~USER/Desktop/mdstat.txt</pre>
+
In all cases, the following should be mentioned and attached to your bug report:
  
A copy of '''/etc/dracut.conf''' if you have edited it.
+
* The exact kernel command-line used.  Typically from the bootloader configuration file (e.g. {{filename|/etc/grub.conf}}) or from {{filename|/proc/cmdline}}
 +
* A copy of your disk partition information from {{filename|/etc/fstab}}
 +
* A device listing from device-mapper. This can be obtained by running the command {{command|dmsetup ls --tree}}
 +
* A list of block device attributes including vol_id compatible mode.  This can be obtained by running the commands {{command|blkid}} and {{command|blkid -o udev}}
 +
* Turn on dracut debugging (see [[How_to_debug_Dracut_problems#Debugging|the 'debugging dracut' section]]), and attach all relevant information from the boot log.  This can be obtained by running the command {{command|dmesg{{!}}grep dracut}}. 
 +
* If you use a dracut configuration file, please include {{filename|/etc/dracut.conf}}
  
<pre> cp /etc/dracut.conf ~USER/home/Desktop/dracut.conf.txt</pre>
+
=== Software RAID related problems ===
  
The output of on an image with debugging enabled.
+
As well as the information from [[How_to_debug_Dracut_problems#AllInfo|the 'all bug reports' section]], include the following information:
  
<pre>dmesg|grep dracut </pre>
+
* If using software RAID disk partitions, please include the output of {{filename|/proc/mdstat}}
  
{{admon/note| You will need to have created an image with debug enabled and added the rdshell to the kernel command line see below for details on how to do that.}}
+
{{Anchor|Debugging}}
 +
= Debugging dracut =
  
== Preparing your system for debugging ==
+
== Configure a serial console ==
  
To be successful in debugging you will need setup and remotely connect to the 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.
  
Add the following lines to you '''/etc/grub.conf'''  
+
# First, enable serial console output for both the kernel and the bootloader.
 +
#* Open the file {{filename|/etc/grub.conf}} for editing.  Below the line ''timeout=5'', add the following:
 +
#*: <pre>serial --unit=0 --speed=9600
 +
#*: terminal --timeout=5 serial console</pre>
 +
#* Also in {{filename|/etc/grub.conf}}, add the following boot arguemnts to the ''kernel'' line:
 +
#*: <pre>console=tty0 console=ttyS0,9600</pre>
 +
#* When finished, the {{filename|/etc/grub.conf}} file should look similar to the example below.
 +
#*:<pre>
 +
#*: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</pre>
 +
#* 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].
  
{{admon/note|2='''This example uses the first serial port, giving <serial_port> the value 0, which in turn gives kernel parameter console=ttyS0'''}}
+
{{admon/tip|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
 +
<pre>exec >/dev/kmsg 2>&1 </dev/console</pre>}}
  
Beneath '''timeout=5''' put..
+
== Enable the dracut debug module ==
  
<pre>serial --unit=0 --speed=9600</pre>
+
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.
<pre>terminal --timeout=5 serial console</pre>
+
  
At the end of the '''kernel''' line put..
+
# Create a dracut ramdisk image with debugging enabled
 +
#: <pre>dracut -a debug /boot/initrd-debug-$(uname -r).img $(uname -r) </pre>
 +
# Next, tell your bootloader to use the new dracut ramdisk
 +
#: <pre>grubby --make-default --title "Debugging dracut" \
 +
#:  --add-kernel /boot/vmlinuz-$(uname -r) \
 +
#:  --initrd /boot/initrd-debug-$(uname -r).img \
 +
#:  --copy-default</pre>
 +
# When ready to debug dracut, reboot the system
  
<pre>console=tty0 console=ttyS0,9600</pre>
+
== Using the shell ==
  
So '''/etc/grub.conf''' should look something like this after you've made those changes..
+
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. {{filename|/etc/grub.conf}}
 +
# Remove the boot arguments ''rhgb'' and ''quiet''
  
<pre>default=0
+
A sample {{filename|/etc/grub.conf}} bootloader configuration file is listed below.
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</pre>
+
 
+
Further information on how to configure the kernel for console output can be found [http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL here].
+
 
+
{{admon/tip| 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
+
<pre>exec >/dev/kmsg 2>&1 </dev/console</pre> }}
+
 
+
Create the image with debug enabled.  
+
 
+
<pre>dracut -a debug /boot/debug-$(uname -r) $(uname -r) </pre>
+
 
+
{{admon/tip| You can overwrite an existing image by using the -f option.
+
<pre>dracut -f -a debug <imagename> <kernel version></pre>}}
+
 
+
Boot with debug enable.
+
 
+
<pre>rdinitdebug rdnetdebug</pre>
+
 
+
== Using the shell to debug ==
+
 
+
Add "rdshell" to the kernel command line and remove "rhgb" and "quiet" and boot the image.
+
This will drop you to the shell if the initramfs fails.
+
 
+
{{admon/note| Sample grub entry with serial enabled and rdshell kernel parameter added }}
+
  
 
<pre>default=0
 
<pre>default=0
Line 91: Line 90:
 
         initrd /dracut-2.6.29.5-191.fc11.x86_64.img</pre>
 
         initrd /dracut-2.6.29.5-191.fc11.x86_64.img</pre>
  
Need commands example #FIXME
+
{{admon/note|FIXME|Need sample shell commands.}}
  
== Dracut debugging kernel command parameters ==
+
== Additional dracut boot parameters ==
  
 
<pre>rdshell</pre>
 
<pre>rdshell</pre>
Line 118: Line 117:
 
{{admon/note|debug network scripts in dracut. Output is written to /tmp/}}
 
{{admon/note|debug network scripts in dracut. Output is written to /tmp/}}
  
 +
= Creating a dracut.conf =
 +
 +
{{admon/note|FIXME|more information on creating a a dracut.conf and when that might be needed}}
  
 
[[Category:Debugging]] [[Category:How to]]
 
[[Category:Debugging]] [[Category:How to]]

Revision as of 16:47, 26 August 2009


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.

Contents

Identifying your problem area

Note.png
FIXME
provide guidance on what dracut bugs look like. How to tell if this is related to dracut, or just a kernel problem?

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

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

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.

  1. 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 [1].
Idea.png
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.

  1. Create a dracut ramdisk image with debugging enabled
    dracut -a debug /boot/initrd-debug-$(uname -r).img $(uname -r) 
  2. 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
  3. 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:

  1. Add the boot parameter rdshell to your bootloader configuration file (e.g. /etc/grub.conf
  2. 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
Note.png
FIXME
Need sample shell commands.

Additional dracut boot parameters

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

Creating a dracut.conf

Note.png
FIXME
more information on creating a a dracut.conf and when that might be needed