• Immutable Page
  • Info
  • Attachments

Diff for "BugReporting"

Differences between revisions 6 and 8

Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
So, you think you've found a Linux Kernel bug? Maybe your dmesg has an oops message in it, or your wireless doesn't work after an upgrade? Maybe your new whizbang USB device doesn't work on any kernel? This is the place to get directions on how to report bugs to kernel engineers.

= Identify the problematic subsystem =

Identifying which part of the Linux kernel might be causing your issue increases your chances of getting your bug fixed. Simply posting to the generic linux-kernel mailing list (LKML) may cause your bug report to be lost in the noise of a mailing list that gets 1000+ emails a day. Instead, try to figure out which kernel subsystem is causing the issue (like the USB or SCSI subsystem), and email that subsystem's maintainer and mailing list.

There are several tools you can use to figure out which subsystem is causing the problem. The simpliest is the command-line tool `dmesg`, which displays the Linux log file from the last time your computer booted. If you want to see messages prior to your last boot, you can look in the individual log files in /var/log. Some useful log files are /var/log/kern.log (the Linux kernel log file) and /var/log/Xorg.0.log (the Xserver log file). Things to look for are warnings, failures, or oops messages.

== Oops messages ==

An oops is a message that appears in dmesg when a bug is triggered. An oops message looks [http://marc.info/?l=linux-kernel&m=135048168712624&w=2 something like this]. If you want to learn how to decode an oops message, there's a good tutorial in the "Oops Messages" section of the Linux Device Drivers book, [http://lwn.net/Kernel/LDD3/ Chapter 4]. Basically, you want to look at the "Call Trace" portion of the oops message and see which subsystems were in the path of the oops. In the linked example, the oops might take place somewhere in the security apparmor layer.

= Identify who to notify =

Once you know the subsystem that is causing the issue, you should send a bug report. Some maintainers prefer bugs to be reported via the [https://bugzilla.kernel.org kernel.org Bugzilla], while others prefer that bugs be reported via the [http://vger.kernel.org/vger-lists.html subsystem mailing list].

To find out where to send an emailed bug report, find your subsystem or device driver in the [http://lxr.linux.no/source/MAINTAINERS MAINTAINERS] file. Skip down to the "Descriptions of section entries" part, since the beginning bit is about submitting patches, not reporting bugs. Search in the file for relevant entries (e.g. bluetooth), and send your bug report to the person(s) listed in the "M:" lines, making sure to Cc the mailing list(s) in the "L:" lines. It's fine to send email to multiple lists. For example, if you're having trouble with a USB bluetooth adapter, you could send email to both the bluetooth and USB mailing lists.

You can also use the directions on the KernelInstall page to download the Linux kernel source and use the [http://lxr.linux.no/source/scripts/get_maintainer.pl get_maintainer.pl] script to find the maintainer. This requires you know which file caused the issue, which may be possible if you use `git grep` to search for function names in your oops message.

If you can't figure out which subsystem caused the issue, you should file a bug in [https://bugzilla.kernel.org kernel.org bugzilla] and send email to [http://vger.kernel.org/vger-lists.html#linux-kernel LKML], referencing the bugzilla URL.

= Tips for Reporting Bugs =

Please read the CommunicationTips page for the best way to send email to kernel developers.

It's good to read the Linux kernel's [http://lxr.linux.no/source/REPORTING-BUGS REPORTING-BUGS file], but it's not necessary to include everything that file mentions in your bug report. You should send the minimum amount of information necessary in order for the maintainer to reproduce your bug, which is usually your current kernel version, a good description of how to trigger the bug, and whether any older kernel version worked. Your .config file, PCI, and SCSI information are optional.

If you haven't filed many bug reports and you have some time on your hands, [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively] is a good read.

= Has your bug been fixed? =

One of the most common questions you'll be asked when you report a bug is, "Can you reproduce your bug on the latest kernel?" The first step is to make sure your Linux distribution's kernel is up-to-date. You can find the Linux kernel package in your distro's software update tool or package manager. If this still doesn't fix your issue, kernel developers will usually ask you to install a newer kernel from source. This requires you to download, compile, and install a new Linux kernel. You can follow the instructions in the KernelInstall page.

= No one is paying attention to my bug!?! =

The Linux kernel developers are usually pretty busy people. They try to fix all bugs, but if they're overloaded, they get really annoyed when they are constantly reminded of unfixed bugs. It's sort of like when your parent tells you to clean up your room. Every. Single. Day.

If no one has replied to your message, wait at least five business days (Monday-Friday) before sending a reminder message. If no one answers in a week, check and see if a Linux conference is happening. If so, you've probably hit the maintainer when they're at the conference. If two weeks passes and you get no answer, re-send your bug report to a broader set of mailing lists, like [http://vger.kernel.org/vger-lists.html#linux-kernel LKML]. If a maintainer says they don't have time to fix your bug, respect that, and ping them a couple weeks later if it's still not fixed.
Tell others about this page: