<para>If the boot process does not succeed, you have several options to debug the situation:</para>
<para>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: <ulink url="http://fedoraproject.org/wiki/How_to_debug_Dracut_problems">http://fedoraproject.org/wiki/How_to_debug_Dracut_problems</ulink></para>
<para>Follow the instructions on: <ulink url="http://fedoraproject.org/wiki/How_to_debug_Dracut_problems">http://fedoraproject.org/wiki/How_to_debug_Dracut_problems</ulink></para>
<section id="identifying-your-problem-area">
<para/>
<title>Identifying your problem area</title>
<para>
<orderedlist>
<section><title>Identifying your problem area</title>
<listitem>
<para>
<para>Remove ''rhgb'' and ''quiet'' from the kernel command line
# 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 [http://koji.fedoraproject.org/koji/buildinfo?buildID=134721], you can inspect the rdinitdebug output with:
#:<pre># less /init.log</pre>
#:<pre># dmesg | less</pre>
</para>
</para>
</section>
</listitem>
== Logical Volume Management related problems ==
<listitem>
<para>Add ''rdshell'' to the kernel command line. This will present a shell should dracut be unable to locate your root device
As well as the information from [[How_to_debug_Dracut_problems#AllInfo|the 'all bug reports' section]], include the following information:
</para>
</listitem>
* Include physical volume information by running the command: {{command|lvm pvdisplay}}
<listitem>
* Include volume group information by running the command: {{command|lvm vgdisplay}}
<para>Add ''rdshell rdinitdebug'' to the kernel command line so that dracut shell commands are printed as they are executed
* Include logical volume information by running the command: {{command|lvm lvdisplay}}
</para>
</listitem>
== Software RAID related problems ==
<listitem>
<para>With dracut >= 002-11, you can inspect the rdinitdebug output with:
As well as the information from [[How_to_debug_Dracut_problems#AllInfo|the 'all bug reports' section]], include the following information:
</para>
<screen># less /init.log
* If using software RAID disk partitions, please include the output of {{filename|/proc/mdstat}}
# dmesg | less</screen>
</listitem>
== Network root device related problems ==
</orderedlist>
</section>
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 [[How_to_debug_Dracut_problems#AllInfo|the 'all bug reports' section]], include the following information:
<para>In all cases, the following should be mentioned and attached to your bug report:
</para>
= Debugging dracut =
<itemizedlist>
<listitem>
== Configure a serial console ==
<para>The exact kernel command-line used. Typically from the bootloader configuration file (e.g. <filename>/etc/grub.conf</filename>) or from <filename>/proc/cmdline</filename>.</para>
</listitem>
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.
<listitem>
<para>A copy of your disk partition information from <filename>/etc/fstab</filename>, which might be obtained booting an old working initramfs or a rescue medium.</para>
# First, enable serial console output for both the kernel and the bootloader.
</listitem>
#* Open the file {{filename|/etc/grub.conf}} for editing. Below the line ''timeout=5'', add the following:
<listitem>
#*: <pre>
<para>A device listing from device-mapper. This can be obtained by running the command <screen># dmsetup ls --tree</screen></para>
#*:serial --unit=0 --speed=9600
</listitem>
#*:terminal --timeout=5 serial console
<listitem>
#*:</pre>
<para>A list of block device attributes including vol_id compatible mode. This can be obtained by running the commands: <screen># blkid -p
#* Also in {{filename|/etc/grub.conf}}, add the following boot arguemnts to the ''kernel'' line:
# blkid -p -o udev</screen></para>
#*: <pre>console=tty0 console=ttyS0,9600</pre>
</listitem>
#* When finished, the {{filename|/etc/grub.conf}} file should look similar to the example below.
<listitem>
#*:<pre>
<para>Turn on dracut debugging (see <filename>the 'debugging dracut' section</filename>), and attach all relevant information from the boot log. This can be obtained by running the command <screen># dmesg|grep dracut</screen></para>
#*:default=0
</listitem>
#*:timeout=5
<listitem>
#*:serial --unit=0 --speed=9600
<para>If you use a dracut configuration file, please include <filename>/etc/dracut.conf</filename>
#*:terminal --timeout=5 serial console
and all files in <filename>/etc/dracut.conf.d/*.conf</filename></para>
#* 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].
<title id="logical-volume-management-related-problems-title">Logical Volume Management related problems</title>
<para>As well as the information from <xref linkend="all-bug-reports"/> include the following information:
{{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
</para>
<pre>exec >/dev/kmsg 2>&1 </dev/console</pre>}}
<itemizedlist>
<listitem>
== Using the dracut shell ==
<para>Include physical volume information by running the command: <screen># lvm pvdisplay</screen></para>
</listitem>
Dracut offers a shell for interactive debugging in the event dracut fails to locate your root filesystem. To enable the shell:
<listitem>
# Add the boot parameter ''rdshell'' to your bootloader configuration file (e.g. {{filename|/etc/grub.conf}}
<para>Include volume group information by running the command: <screen># lvm vgdisplay</screen></para>
# Remove the boot arguments ''rhgb'' and ''quiet''
</listitem>
<listitem>
A sample {{filename|/etc/grub.conf}} bootloader configuration file is listed below.
<para>Include logical volume information by running the command: <screen># lvm lvdisplay</screen></para>
</listitem>
<pre>default=0
</itemizedlist>
</section>
<section id="software-raid-related-problems">
<title id="software-raid-related-problems-title">Software RAID related problems</title>
<para>As well as the information from <xref linkend="all-bug-reports"/>, include the following information:
</para>
<itemizedlist>
<listitem>
<para>If using software RAID disk partitions, please include the output of <screen># cat /proc/mdstat</screen></para>
<title id="network-root-device-related-problems-title">Network root device related problems</title>
<para>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 <xref linkend="all-bug-reports"/>, include the following information:
</para>
<itemizedlist>
<listitem>
<para>Please include the output of <screen># /sbin/ifup <replaceable><interfacename></replaceable>
<title id="configure-a-serial-console-title">Configure a serial console</title>
<para>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.
</para>
<orderedlist>
<listitem>
<para>First, enable serial console output for both the kernel and the bootloader.
</para>
</listitem>
<listitem>
<para>Open the file <filename>/etc/grub.conf</filename> for editing. Below the line ''timeout=5'', add the following:
<screen>serial --unit=0 --speed=9600
terminal --timeout=5 serial console</screen></para>
</listitem>
<listitem>
<para>Also in <filename>/etc/grub.conf</filename>, add the following boot arguemnts to the ''kernel'' line:
If system boot fails, you will be dropped into a shell as seen in the example below.
<listitem>
<pre>
<para>More detailed information on how to configure the kernel for console output can be found at <ulink url="http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL">http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL</ulink>.
No root device found
</para>
</listitem>
</orderedlist>
<note>
<title>Redirecting non-interactive output</title>
<para>You can redirect all non-interactive output to <filename>/dev/kmsg</filename> and the kernel will put it out on the console when it reaches the kernel buffer by doing<screen># exec >/dev/kmsg 2>&1 </dev/console</screen></para>
</note>
</section>
<section id="using-the-dracut-shell">
<title id="using-the-dracut-shell-title">Using the dracut shell</title>
<para>Dracut offers a shell for interactive debugging in the event dracut fails to locate your root filesystem. To enable the shell:
<orderedlist>
<listitem>
<para>Add the boot parameter ''rdshell'' to your bootloader configuration file (e.g. <filename>/etc/grub.conf</filename>)</para>
</listitem>
<listitem>
<para>Remove the boot arguments ''rhgb'' and ''quiet''
</para>
<para>
A sample <filename>/etc/grub.conf</filename> bootloader configuration file is listed below.
<para>If system boot fails, you will be dropped into a shell as seen in the example below.
<screen>No root device found
Dropping to debug shell.
Dropping to debug shell.
sh: can't access tty; job control turned off
sh: can't access tty; job control turned off
#
</pre>
Use this shell prompt to gather the information requested above (see [[How_to_debug_Dracut_problems#AllInfo|the 'all bug reports' section]]).
== Accessing the root volume from the dracut shell ==
# </screen></para>
</listitem>
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:
<listitem>
* A block device (e.g. {{filename|/dev/sda7}})
<para>Use this shell prompt to gather the information requested above (see <xref linkend="all-bug-reports"/>).
* A LVM logical volume (e.g. {{filename|/dev/VolGroup00/LogVol00}})
</para>
* An encrypted device (e.g. {{filename|/dev/mapper/luks-4d5972ea-901c-4584-bd75-1da802417d83}})
</listitem>
* A network attached device (e.g. {{filename|netroot{{=}}iscsi:@192.168.0.4::3260::iqn.2009-02.org.fedoraproject:for.all}})
</orderedlist></para>
</section>
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 {{filename|/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.
<title id="accessing-the-root-volume-from-the-dracut-shell-title">Accessing the root volume from the dracut shell</title>
# Inspect your partitions using {{command|parted}}
<para>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:
# From the output above, you recall that your root volume exists on an encrypted block device. Following the guidance disk encryption guidance from the [http://docs.fedoraproject.org/install-guide/f{{FedoraVersion}}/en-US/html/apcs04s04.html {{FedoraVersion|long}} Installation Guide], you unlock your encrypted root volume.
<para>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 <filename>/dev/root</filename> 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. </para>
<orderedlist>
<listitem>
<para>Inspect your partitions using <command>parted</command><screen># parted /dev/sda -s p
<para>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.
Harald Hoyer
15 years ago