Reporting bugs

This section helps users report bugs in the right place.

Relevant software

Wireless drivers are just one component of the software stack necessary for wireless devices to function. There are also userspace components, namely NetworkManager, wpa_supplicant, Dbus, wireless-tools, wireless-regdb, CRDA, and iw.

It is important for you to try to distinguish what these are when reporting issues. If unsure you can check out user support IRC channel and ask there.

Knowing what wireless driver you use

If you are unsure of which wireless card you have or which driver you are using, run the lspci -k command in a terminal (note that the -k option for lspci is available in version 3.0.0 or later). Some example output follows:

$ lspci -k | grep -A3 "Network controller"
0c:00.0 Network controller: Intel Corporation PRO/Wireless 3945ABG [Golan] Network Connection (rev 02)
        Kernel driver in use: iwl3945
        Kernel modules: iwl3945

Kernel panics / Kernel hangs

Kernel panics are kernel bugs, and should be reported immediately. Kernel hangs can be kernel bugs and should be reported as well. Keep in mind you must first ensure your distribution is running the latest stable kernel which matches upstream. You can check that by looking at the v2.6 kernel archives or if you are running the actual latest stable kernel simply by looking at http://kernel.org (another option is the Linux kernel.org finger banner). If you are say on 2.6.27.10 and see there is a 2.6.27.12 you should firs try out 2.6.27.12.

Other issues - Fixes for the stable kernel series requirements

Non-kernel panic or non-hang issues still need to be reported but to better assist Linux wireless developers you are encouraged to try the latest wireless drivers first so the issues can be fixed first upstream and then the respective backport fixes can be propagated down to the older kernel stable series. Reason for this is the stable kernel series has a requirement of having a respective fix in Linus' tree first before applying it to any old stable kernel release. If you are using your distribution's kernel chances are very high you are not using Linus' tree directly but an old stable kernel release.

If you are not sure if your issues is driver or userspace specific you can check asking on our user support IRC channel for help in trying to make that determination.

If you determine you have issues with your drivers you are encouraged to try the latest and greatest wireless drivers. You have a few options, these are covered below.

Getting the latest and greatest Linux wireless drivers

In summary:

• John's wireless-testing tree

• compat-wireless

• Stephen Rothwell's linux-next tree

• Why not Linus' tree? – because John pulls from him so you already get his stuff

We elaborate on these below.

Using John's wireless-testing git tree

John Linville is the Linux wireless maintainer and as such his tree is used to push patches upstream to be queued for the next kernel release. Patches pushed into his tree eventually make it to David Miller's tree for the next stable kernel. David then pushes his changes down to Linus and Linus blesses a new release. For more elaborate details you can refer the Linux wireless developer documentation. What you need to know John's tree is the point of entry for any wireless patch.

To use John's tree directly you are expected to know how to configure your kernel, compile it, and load it. If you're up for that you can use our git-guide for reference on how to use git and then clone this tree:

git://git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-testing.git

Use compat-wireless

You can use compat-wireless to get the latest and greatest drivers as well. This basically takes what John has and applies some compatibility patches and gets you going with the latest and greatest on older kernels. You are expected to be able to run 'make' and 'sudo make install' and 'sudo reboot'. For further details you should read the compat-wireless documentation.

Use Stephen Rothwell's linux-next git tree

This is similar to using John's tree but with the added benefit of getting not only the latest and greatest Linux wireless drivers but also the latest *everything* (technically all the -next git trees). You may want this if you have issues with other devices on your system. Read the git-guide and then check out his tree (gitweb):

git://git.kernel.org/pub/scm/linux/kernel/git/sfr/linux-next.git

Why are you not recommending Linus' tree?

John's tree is based on Linus' tree so by testing his tree you test Linus' tree already and you get the latest Linux wireless drivers as well. This is after all the Linux wireless page.

Distribution specific notes

Distributions may have a few notes which they can add here to help their users in the process of reporting bugs for Linux wireless.

• Ubuntu's Linux wireless guide

Identifying the bug

In order to help developers help you better you can do some work on your part to try to narrow bugs down better. If you are unsure about where the bug lies you can start by turning off NetworkManager and its attached wpa_supplicant and then try running wpa_supplicant yourself with your own configuration file. NetworkManager keeps its configuration internally and uses Dbus to relay to wpa_supplicant its configuration settings. To try to reproduce a configuration file similar to the one NetworkManager uses you can check the log file used by NetworkManager (/var/log/messages in most some systems) to review the settings used. If you can still reproduce the issue then try using wireless-tools or iw to connect manually. You will only be able to use wireless-tools or iw to connect manually if your wireless connection *does not require* WPA or WPA2. For connections with WPA or WPA2 you *need* to use wpa_supplicant.

To stop NetworkManager use:

# Red Hat based systems
sudo /sbin/service NetworkMananger stop
# Debian based systems (Ubuntu is one)
sudo /etc/init.d/NetworkManager stop
sudo killall -TERM wpa_supplicant

iw event log

Please install iw and provide the output of the iw event -t in your bug report. The -t is to add timing information.

increase debugging in the kernel log

We recommended these to be enabled:

CONFIG_MAC80211_HT_DEBUG=y
CONFIG_MAC80211_VERBOSE_PS_DEBUG=y
CONFIG_MAC80211_VERBOSE_DEBUG=y

If using compat-wireless you can edit config.mk and enable them there. Note that each driver may also have their own respective debug parameters so this could also help but usually it is best to first just use the iw event log and the kernel log to report an issue.

Reporting bugs in NetworkManager

If you have a bug in NetworkManager you can report it on GNOME's NetworkManager bugzilla product page.

Reporting bugs in wpa_supplicant

You can report bugs in the hostap mailing lists.

Reporting bugs in drivers or mac80211

You should report them on the Linux wireless mailing list.