DebuggingKernelBoot

Differences between revisions 1 and 29 (spanning 28 versions)
Revision 1 as of 2008-06-06 00:30:31
Size: 2572
Editor: c-24-21-206-172
Comment: Draft some notes when running into failure to boot issues
Revision 29 as of 2019-11-02 17:01:33
Size: 4156
Editor: penalvch
Comment: Add link to debugging a system crash as highly relevant to bad boots.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Unfortunately it is sometimes the case that your system will fail to boot due to changes within the kernel. It is important that when submitting bug reports about these types of failures that you include the appropriate debugging information that can help the kernel team resolve the issue. The following wiki will document some useful tips to capture any relevant information. ||<tablestyle="float:right; font-size: 0.9em; background:#F1F1ED;margin: 0 0 1em 1em;" style="padding:2.0em;"><<TableOfContents>>||
Line 3: Line 3:
== Boot Options ==
When trying to capture relevant error messages that appear at boot it is often useful to boot with the '''quiet''' and '''splash''' options removed. This will hopefully allow you to see any messages that come across your screen. To edit boot option parameters, do the following:
= Introduction =
Line 6: Line 5:
 1. Press 'Escape' key at the 3 second pause by Grub bootloader.
 1. Then press 'e' (edit) on the buggy kernel entry, followed by 'e' again on the kernel line.
 1. Then remove the '''splash''' and '''quiet''' keywords and press 'b' to boot.
Unfortunately it is sometimes the case that your system will fail to boot due to changes within the kernel. It is important that when submitting bug reports about these types of failures that you include the debugging information from a failed boot (not a working boot). This article will help gather this information to provide in your report.
Line 10: Line 7:
It's best if you can attach a log file which may have captured any messages you see. If you are unable to capture a log file, a digital photo will work just as well. As a last resort you can even copy messages down by hand. = Capture information from a bad boot and post to your bug report =
Line 12: Line 9:
Depending on the type of error messages you encounter, there are other boot options you could try. For example, if you notice ACPI errors, try booting with the '''acpi=off''' boot option. For a detailed summary of these options, refer to the [http://www.kernel.org/doc/Documentation/kernel-parameters.txt kernel parameters] document. When trying to capture relevant error messages that appear at boot, one may edit boot option parameters via:
Line 14: Line 11:
== Initramfs ==
Sometimes you may even be dropped into an initramfs shell. Obviously this indicates errors in the boot sequence, for ex failing to find your root partition/filesystem. You are dropped into the initramfs shell in an effort to allow you to recover the system. Hopefully if you boot with the '''quiet''' and '''splash''' options removed you will notice error messages before being dropped into the shell which will help debug and direct you to a solution.
 1. Boot the machine.
 1. During the BIOS screen, press the shift key and hold it down. You should see the GRUB menu after the BIOS loads.
 1. Navigate to the kernel entry you want to boot, and press 'e'.
 1. In the line starting with linux, remove the following keywords: {{{
quiet
splash
vt.handoff=7}}}
 1.
  a. If using Ubuntu 18.04, on the line that contains: {{{
gfxmode $linux_gfx_mode
}}}modify it to: {{{
gfxmode text}}}
  a. If using an older version of Ubuntu, on the line that contains: {{{
gfxpayload=$linux_gfx_mode}}}modify it to: {{{
gfxpayload=text}}}
 1. Press 'Ctrl+x' to boot.
 1. Capture messages from the bad boot and attach to your report. In order of preference:
  * The appropriate log(s) in their entirety from /var/log uncompressed.
  * An unedited video of the entire bad boot from start to finish via cellphone or camera recording.
  * A picture of the bad boot via cellphone or camera.
  * Writing it down by hand.
Line 17: Line 33:
If you are dropped into an initramfs shell you may want to also try booting with the '''debug''' boot option. It should write a log to /tmp/initramfs.debug. You could also specify some arbitrary arguement (for example '''debug=vc''') to have the output written to the console. /!\ Please note, stating the boot didn't work or providing logs from a good boot is not enough for a developer to review the problem. You must provide evidence from a bad boot as noted above.
Line 19: Line 35:
There is another initramfs boot parameter which can purposely drop you into the initramfs shell during different stages of the initial boot sequence. The parameter is '''break=[option]''' where option can be: top, modules, premount, mount, bottom, or init. The default is premount if no options are specified. = Further diagnosing =

After the evidence above has been attached to your report, depending on the type of error messages you encounter, there are other boot options you could try to help a developer further diagnose.

For example, if you notice ACPI errors, try booting with the '''acpi=off''' boot option. For a full description of these options, refer to the [[https://www.kernel.org/doc/html/v4.14/admin-guide/kernel-parameters.html|kernel parameters]] document.

== Boot looping or boot halts ==

If your boot immediately restarts, or halts, please utilize the boot debugging options to capture the bad boot.

== Dropped into a initramfs shell ==

If your boot is dropped into an initramfs shell, this indicates errors in the boot sequence, for example failing to find your root partition/filesystem. You are put into the initramfs shell in an effort to allow you to recover the system. Hopefully, if you boot with the '''quiet''' and '''splash''' options removed you will notice error messages before being dropped into the shell which will help debug and direct you to a solution.

If you are dropped into an initramfs shell you may want to also try booting with the '''debug''' boot option. It should write a log to /tmp/initramfs.debug. You could also specify some arbitrary argument (for example '''debug=vc''') to have the output written to the console.

Additionally, being able to extract log files from the system would be helpful. Once dropped into an initramfs shell, you can type '''httpd'''. You should then be able to point a web browser to the IP address of the system and view the contents of the /var/log folder.

There is another initramfs boot parameter which can purposely drop you into the initramfs shell during different stages of the initial boot sequence. The parameter is '''break=[option]''' where option can be: top, modules, premount, mount, bottom, or init. The default is premount if no options are specified. More information about the break= parameters can be found in "/usr/share/initramfs-tools/init" on your Ubuntu system.

= Links =

 * [[https://help.ubuntu.com/community/DebuggingSystemCrash|Debugging a System Crash]]
 * [[https://help.ubuntu.com/community/vt.handoff|vt.handoff]] explained

----
CategoryBugSquad CategoryDebugging

Introduction

Unfortunately it is sometimes the case that your system will fail to boot due to changes within the kernel. It is important that when submitting bug reports about these types of failures that you include the debugging information from a failed boot (not a working boot). This article will help gather this information to provide in your report.

Capture information from a bad boot and post to your bug report

When trying to capture relevant error messages that appear at boot, one may edit boot option parameters via:

  1. Boot the machine.
  2. During the BIOS screen, press the shift key and hold it down. You should see the GRUB menu after the BIOS loads.
  3. Navigate to the kernel entry you want to boot, and press 'e'.
  4. In the line starting with linux, remove the following keywords:

    quiet
    splash
    vt.handoff=7
    1. If using Ubuntu 18.04, on the line that contains:

      gfxmode $linux_gfx_mode

      modify it to:

      gfxmode text
    2. If using an older version of Ubuntu, on the line that contains:

      gfxpayload=$linux_gfx_mode

      modify it to:

      gfxpayload=text
  5. Press 'Ctrl+x' to boot.
  6. Capture messages from the bad boot and attach to your report. In order of preference:
    • The appropriate log(s) in their entirety from /var/log uncompressed.
    • An unedited video of the entire bad boot from start to finish via cellphone or camera recording.
    • A picture of the bad boot via cellphone or camera.
    • Writing it down by hand.

Warning /!\ Please note, stating the boot didn't work or providing logs from a good boot is not enough for a developer to review the problem. You must provide evidence from a bad boot as noted above.

Further diagnosing

After the evidence above has been attached to your report, depending on the type of error messages you encounter, there are other boot options you could try to help a developer further diagnose.

For example, if you notice ACPI errors, try booting with the acpi=off boot option. For a full description of these options, refer to the kernel parameters document.

Boot looping or boot halts

If your boot immediately restarts, or halts, please utilize the boot debugging options to capture the bad boot.

Dropped into a initramfs shell

If your boot is dropped into an initramfs shell, this indicates errors in the boot sequence, for example failing to find your root partition/filesystem. You are put into the initramfs shell in an effort to allow you to recover the system. Hopefully, if you boot with the quiet and splash options removed you will notice error messages before being dropped into the shell which will help debug and direct you to a solution.

If you are dropped into an initramfs shell you may want to also try booting with the debug boot option. It should write a log to /tmp/initramfs.debug. You could also specify some arbitrary argument (for example debug=vc) to have the output written to the console.

Additionally, being able to extract log files from the system would be helpful. Once dropped into an initramfs shell, you can type httpd. You should then be able to point a web browser to the IP address of the system and view the contents of the /var/log folder.

There is another initramfs boot parameter which can purposely drop you into the initramfs shell during different stages of the initial boot sequence. The parameter is break=[option] where option can be: top, modules, premount, mount, bottom, or init. The default is premount if no options are specified. More information about the break= parameters can be found in "/usr/share/initramfs-tools/init" on your Ubuntu system.

Links


CategoryBugSquad CategoryDebugging

DebuggingKernelBoot (last edited 2019-11-02 17:01:33 by penalvch)