LICENSE: This gist is covered by the GNU GPL v.2 or more recent license. For further information, refer to https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
It's quite common to set up a GNU/Linux distribution on a computer only to find out wi-fi doesn't work, or to perform a software upgrade and find out the computer is no longer able to locate any wi-fi network. In this gist, I want to give some guidelines about how to troubleshoot wi-fi issues on GNU/Linux. Just a short legalese disclaimer: this piece of advice is offered with absolutely NO warranties whatsoever, and from this point on you are following my advice at your owk risk and danger. That being said, I am not liable for any damage or loss that might happen as a result of following this guide. You take full responsibility for the consequences of following this troubleshooting guide.
Troubleshooting any kind of hardware-related issue without knowing what kind of hardware you're working with is, for lack of a better term, a shot in the dark. It is imperative to know right from the start what kind of wi-fi board is installed on one's computer.
The first step to doing so is making sure the lshw package is installed in your system.
Once that's done, everything you need to know about your network-related hardware is included in the output of sudo lshw -C network. Once that information is acquired, it will be significantly easier to find relevant information through a search engine.
This is the truncated sample output of the command on my machine:
*-network
description: Wireless interface
product: Wireless 3165
vendor: Intel Corporation
physical id: 0
bus info: pci@0000:01:00.0
logical name: wlp1s0
version: 79
serial: 7c:67:a2:f1:fb:9e
width: 64 bits
clock: 33MHz
capabilities: pm msi pciexpress bus_master cap_list ethernet physical wireless
configuration: broadcast=yes driver=iwlwifi driverversion=5.1.12-300.fc30.x86_64 firmware=29.1044073957.0 ip=192.168.1.101 latency=0 link=yes multicast=yes wireless=IEEE 802.11
resources: irq:130 memory:df100000-df101fff
Take note of the name that appears after "logical name.", as it's the name of your wireless network interface and it will come in handy. Take note of the name that appears after "driver=", as it's the name of your network interface's driver. If you cannot spot the driver name immediately, other ways to find it are:
sudo lshw -C network | grep "driver="(same output, but it will only show the lines where the string "driver=" appears)ethtool -i $devicename(replacing$devicenamewith its "logical name").
Another way to figure out what kernel module (a.k.a. driver) your network interface uses is through the output of lspci -k.
rfkill is a tool for enabling and disabling wireless interfaces on Linux. It is a good idea to check whether your wireless network interface is enabled or disabled in rfkill, or to check whether the tool even detects it.
The first step that needs to be completed is to list all the network interfaces the program detects using rfkill list all.
Below is an example output of this command:
1: phy0: Wireless LAN
Soft blocked: no
Hard blocked: no
5: hci0: Bluetooth
Soft blocked: yes
Hard blocked: no
This output contains all the network interfaces detected by rfkill. In this example output, everything is fine and working as intended - namely, both my wifi wireless network interface and my Bluetooth adapter are detected, wi-fi is enabled, while the bluetooth radios are turned off. For each device, the output is structured this way:
- Network interface name and type. This is the part of the output that marks what interface does what. Take note of the number at the beginning on this line because you might need it later.
- Soft blocked: This line states whether that particular radio is disabled via a software switch or not.
- Hard blocked: This line states whether that particular radio is disabled via a hardware switch or not.
If your wi-fi interface is soft-blocked, the first thing you should do is try enabling it in your desktop environment's settings provider (if applicable). If that fails or you are not using a desktop environment, the command to unblock it is rfkill unblock $NUMBER, replacing $NUMBER with the number stated at the beginning of the line where rfkill states the network interface type. If that still does not work, the device driver might be compromised - keep on reading.
If your wi-fi interface is hard-blocked, it is likely controlled by a physical switch which you need to toggle. If you are using a laptop, accurately inspect its sides, as some laptops place their physical wireless switches there.
If your wi-fi interface is not listed at all, keep on reading this guide. While it could be due to a moltitude of variables, most commonly, this is a good indicator that your wireless interface's device driver (kernel module) was not loaded successfully at boot.
In this step, you'll verify whether the correct device driver is loaded at boot. To do this, run dmesg | grep $drivername, replacing $drivername with the driver name found in Step 1.
If the output suggests in any way that "no suitable kernel module was found", it means you are missing it. It will also state exactly what module it is failing to load, in the .ucode extension. In my case, the module name was iwlwifi-7265D-29.ucode.
The last line of the output should state:
[ 5.055786] iwlwifi 0000:01:00.0: check git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
The linked git repository contains all of the firmware modules officially supported by the Linux kernel. Open that page in a web browser, and try to locate the exact module name (for example, iwlwifi-7265D-29.ucode) in the list to figure out whether it's present or not. If the module you're looking for is not present on the page, then the Linux kernel simply doesn't support it yet and you'll have to wait until it does. Meanwhile, you should check its manufacturer's website; odds are it will offer a way to install the device driver on Linux. At this stage, you're mostly on your own and you'll have to resort to looking things up online.
However, if it is present, keep on reading.
New device drivers get included in the kernel as it updates. Look up what the latest stable Linux kernel is online and find out what version of the Linux kernel you are currently running using the command uname -r. If your kernel is older than the latest stable, it's worth a shot to upgrade to the latest stable kernel available. Just a word of advice: do this at your own risk and danger. Also, note that your Linux distribution may or may not support upgrading the kernel officially. A common example is Ubuntu LTS: it ships an older kernel for the sake of stability, but frequently newer hardware will not work on it. If you prefer trying another Linux distro altogether, Fedora Workstation, Arch Linux and openSUSE Tumbleweed are three Linux distros that always ship a very updated kernel.
It might be helpful to install or reinstall the Linux firmware package on your distro. This changes from distro to distro, but the command to do this on Fedora is sudo dnf reinstall linux-firmware. This, by the way, might not be enough: search your distro's repos for your specific driver by looking up your interface's driver name, as well as the module name that turned out in the dmesg output. If after a few searches nothing turns up, don't be afraid to ask around in your distro's community, as someone who has more experience with it might help you locate the correct package for your interface. In the off chance your distro does not package the needed blobs, look around online for a Linux distribution that does and use it instead. In my specific case (Dell Inspiron 5567, Kaby Lake i5 edition), Fedora packaged the iwlwifi-7265D-29.ucode module in the iwl7260-firmware package.
The absolute last resort would be cloning git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git and copying the your_module.ucode file in your /lib/firmware and /usr/lib/firwmare folders, but, while this will work, it is a dirty way of solving the problem, it has to be considered as your absolute last resort and it's very likely that at least one Linux distribution packages the needed blobs in their repositories.
Wi-fi issues on Linux are quite complex and it is therefore impossible that this guide will solve every single wi-fi related issue that turns out. However, I hope I have successfully covered the most common reasons why wi-fi does not work on GNU/Linux and ways to solve them, as well as introducing some tools and techniques that should be useful regardless.