Identify the problematic subsystem¶

Identifying which part of the Linux kernel might be causing your issueincreases your chances of getting your bug fixed. Simply posting to thegeneric linux-kernel mailing list (LKML) may cause your bug report to belost 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,and email that subsystem’s maintainer and mailing list. If the subsystemmaintainer doesn’t answer, then expand your scope to mailing lists likeLKML.

Identify who to notify¶

Once you know the subsystem that is causing the issue, you should send abug report. Some maintainers prefer bugs to be reported via bugzilla(https://bugzilla.kernel.org), while others prefer that bugs be reportedvia the subsystem mailing list.

To find out where to send an emailed bug report, find your subsystem ordevice driver in the MAINTAINERS file. Search in the file for relevantentries, 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. When themaintainer replies to you, make sure to ‘Reply-all’ in order to keep thepublic mailing list(s) in the email thread.

If you know which driver is causing issues, you can pass one of the driverfiles to the get_maintainer.pl script:

perl scripts/get_maintainer.pl -f <filename>

If it is a security bug, please copy the Security Contact listed in theMAINTAINERS file. They can help coordinate bugfix and disclosure. SeeDocumentation/admin-guide/security-bugs.rst for more information.

If you can’t figure out which subsystem caused the issue, you should filea bug in kernel.org bugzilla and send email tolinux-kernel@vger.kernel.org, referencing the bugzilla URL. (For moreinformation on the linux-kernel mailing list seehttp://vger.kernel.org/lkml/).

Tips for reporting bugs¶

If you haven’t reported a bug before, please read:

https://www.chiark.greenend.org.uk/~sgtatham/bugs.html

http://www.catb.org/esr/faqs/smart-questions.html

It’s REALLY important to report bugs that seem unrelated as separate emailthreads or separate bugzilla entries. If you report several unrelatedbugs at once, it’s difficult for maintainers to tease apart the relevantdata.

Gather information¶

The most important information in a bug report is how to reproduce thebug. This includes system information, and (most importantly)step-by-step instructions for how a user can trigger the bug.

If the failure includes an “OOPS:”, take a picture of the screen, capturea netconsole trace, or type the message from your screen into the bugreport. Please read “Documentation/admin-guide/bug-hunting.rst” before posting yourbug report. This explains what you should do with the “Oops” informationto make it useful to the recipient.

This is a suggested format for a bug report sent via email or bugzilla.Having a standardized bug report form makes it easier for you not tooverlook things, and easier for the developers to find the pieces ofinformation they’re really interested in. If some information is notrelevant to your bug, feel free to exclude it.

First run the ver_linux script included as scripts/ver_linux, whichreports the version of some important subsystems. Run this script withthe commandawk-fscripts/ver_linux.

Use that information to fill in all fields of the bug report form, andpost it to the mailing list with a subject of “PROBLEM: <one linesummary from [1.]>” for easy identification by the developers:

[1.] One line summary of the problem:[2.] Full description of the problem/report:[3.] Keywords (i.e., modules, networking, kernel):[4.] Kernel information[4.1.] Kernel version (from /proc/version):[4.2.] Kernel .config file:[5.] Most recent kernel version which did not have the bug:[6.] Output of Oops.. message (if applicable) with symbolic information     resolved (see Documentation/admin-guide/bug-hunting.rst)[7.] A small shell script or example program which triggers the     problem (if possible)[8.] Environment[8.1.] Software (add the output of the ver_linux script here)[8.2.] Processor information (from /proc/cpuinfo):[8.3.] Module information (from /proc/modules):[8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)[8.5.] PCI information ('lspci -vvv' as root)[8.6.] SCSI information (from /proc/scsi/scsi)[8.7.] Other information that might be relevant to the problem       (please look in /proc and include all information that you       think to be relevant):[X.] Other notes, patches, fixes, workarounds:

Expectations for bug reporters¶

Linux kernel maintainers expect bug reporters to be able to follow up onbug reports. That may include running new tests, applying patches,recompiling your kernel, and/or re-triggering your bug. The mostfrustrating thing for maintainers is for someone to report a bug, and thennever follow up on a request to try out a fix.

That said, it’s still useful for a kernel maintainer to know a bug existson a supported kernel, even if you can’t follow up with retests. Followup reports, such as replying to the email thread with “I tried the latestkernel and I can’t reproduce my bug anymore” are also helpful, becausemaintainers have to assume silence means things are still broken.

Expectations for kernel maintainers¶

Linux kernel maintainers are busy, overworked human beings. Some timesthey may not be able to address your bug in a day, a week, or two weeks.If they don’t answer your email, they may be on vacation, or at a Linuxconference. Check the conference schedule athttps://LWN.net for more info:

https://lwn.net/Calendar/

In general, kernel maintainers take 1 to 5 business days to respond tobugs. The majority of kernel maintainers are employed to work on thekernel, and they may not work on the weekends. Maintainers are scatteredaround the world, and they may not work in your time zone. Unless youhave a high priority bug, please wait at least a week after the first bugreport before sending the maintainer a reminder email.

The exceptions to this rule are regressions, kernel crashes, security holes,or userspace breakage caused by new kernel behavior. Those bugs should beaddressed by the maintainers ASAP. If you suspect a maintainer is notresponding to these types of bugs in a timely manner (especially during amerge window), escalate the bug to LKML and Linus Torvalds.

Thank you!

[Some of this is taken from Frohwalt Egerer’s original linux-kernel FAQ]