Fixing FreeBSD Wi-Fi: Drivers, wpa_supplicant, and the Gotchas Nobody Documents

Nothing sours a first FreeBSD install faster than a laptop that boots cleanly, drops you at a login prompt, and then refuses to see a single wireless network. The installer's networking screen either shows no wireless device at all, or it shows one that never associates. This is the single most common source of "did anyone else have trouble installing FreeBSD" threads, and the frustration is real: the wired path is trivial and the wireless path is a small stack of separate steps that all have to be right at once.

The good news is that FreeBSD's wireless model is logical once you understand it. The bad news is that almost nobody documents the whole chain in one place. This guide walks it end to end on FreeBSD 14.x and 15.x: identifying your chipset, understanding the current driver landscape, the wlan cloning model that trips up everyone coming from Linux, wpa_supplicant, and the gotchas that eat an afternoon.

Step 1: Identify your Wi-Fi chipset

Before anything else, find out what hardware you actually have. Do not guess from the marketing name on the box. Run pciconf and look for the network device.

# pciconf -lv | grep -A4 -i network
none4@pci0:0:20:3:  class=0x028000 card=0x00708086 chip=0x51f08086 rev=0x01
    vendor     = 'Intel Corporation'
    device     = 'Alder Lake-P PCH CNVi WiFi'
    class      = network

Two things matter here. The vendor and device strings tell you who makes the chip, and the leading none4 tells you no driver has attached to it yet. If a driver had claimed the device you would see something like iwlwifi0@pci0... instead of none4. That none is your first diagnostic: the kernel sees the hardware but has not bound a driver to it.

Step 2: Understand the driver landscape

FreeBSD's wireless drivers fall into two camps, and knowing which one you are dealing with changes how you troubleshoot.

The native drivers are the old, stable, fully-in-tree ones: ath for many Atheros cards, iwm for older Intel (7260/7265/8260/9260-era) parts, run and rtwn for various USB adapters. These attach directly and behave predictably. If your card uses one of these, you are on the easy path.

The LinuxKPI-backed drivers are the newer story. To support modern chips, FreeBSD ships iwlwifi (Intel AX200/AX201/AX210 and newer) and rtw88/rtw89 (recent Realtek) as ports of the Linux drivers running on top of the LinuxKPI compatibility layer. These are what make current laptops work at all, but they are newer code and carry caveats: as of the 14.x/15.x line they generally negotiate 802.11a/b/g/n and often ac, while full 802.11ax (Wi-Fi 6) rates and some power-management paths are still maturing. Do not be surprised if a Wi-Fi 6 card links at ac rates. It is connected; it is just not showing you its top speed yet.

The practical mapping: the none4 Alder Lake CNVi device above is served by iwlwifi. Older Intel would be iwm. When in doubt, check the driver's manual page (man iwlwifi, man iwm, man ath) for the exact supported chip list on your release.

Step 3: Load the driver and its firmware

The LinuxKPI drivers do not load automatically, and they need firmware. On a running system, load the module by hand to test:

# kldload if_iwlwifi
# dmesg | tail
iwlwifi0: <iwlwifi> on pci0
iwlwifi0: successfully loaded firmware image 'iwlwifi-so-a0-gf-a0-83.ucode'
iwlwifi0: Detected crf-id 0x...
iwlwifi0: base HW address: xx:xx:xx:xx:xx:xx

Watch that dmesg output carefully. The line that matters is successfully loaded firmware image. If instead you see a complaint about a missing .ucode file, the firmware package is not installed. FreeBSD ships wireless firmware as a package rather than baking it into the kernel. Install it:

# pkg install wifi-firmware-iwlwifi-kmod
# or for Realtek:
# pkg install wifi-firmware-rtw88-kmod

Once the driver attaches and firmware loads, make it persistent across reboots in /boot/loader.conf:

# sysrc -f /boot/loader.conf if_iwlwifi_load="YES"

Native drivers like iwm and ath generally load on their own when the hardware is present, so this manual step is mostly a LinuxKPI concern.

Step 4: The wlan cloning model (the part nobody explains)

Here is the conceptual leap that catches every Linux refugee. On FreeBSD you do not configure iwlwifi0 or iwm0 directly. The raw device is a physical parent. You create a logical wlan interface cloned onto it, and everything you configure happens on the wlan interface. This separation exists so a single radio can host multiple virtual interfaces (station plus access point, for example) with distinct configurations.

To test it live:

# ifconfig wlan0 create wlandev iwlwifi0
# ifconfig wlan0 up scan
SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
homenet         xx:xx:xx:xx:xx:xx    36   54M -52:-96  100 EPS  RSN HTCAP WME
neighbor-5g     yy:yy:yy:yy:yy:yy   149   54M -71:-96  100 EPS  RSN HTCAP WME

If scan returns access points, your hardware, driver, and firmware are all working. That is the milestone. If the scan is empty in an area you know has networks, the problem is almost always firmware or regulatory domain, not the association step you have not reached yet.

The permanent version of this lives in /etc/rc.conf. Note the device name in the variable is the raw parent, and it tells rc which wlan interfaces to clone at boot:

# sysrc wlans_iwlwifi0="wlan0"
# sysrc ifconfig_wlan0="WPA SYNCDHCP"

The WPA keyword tells the system to run wpa_supplicant against this interface. SYNCDHCP runs the DHCP client synchronously so the network is up before dependent services start; plain DHCP works too if you prefer it backgrounded.

Step 5: wpa_supplicant.conf

Authentication credentials live in /etc/wpa_supplicant.conf. For a standard WPA2/WPA3-PSK home network, the minimal file is short:

ctrl_interface=/var/run/wpa_supplicant
eapol_version=1
ap_scan=1
fast_reauth=1

network={
    ssid="homenet"
    psk="your-passphrase-here"
}

A cleaner habit than putting the plaintext passphrase in the file is to generate the hashed PSK with wpa_passphrase, which keeps the raw password out of the config:

# wpa_passphrase homenet 'your-passphrase-here' >> /etc/wpa_supplicant.conf

That appends a network={} block containing both a commented plaintext line and the hashed psk= value. Delete the commented plaintext line and you are left with only the hash. Lock the file down with chmod 600 /etc/wpa_supplicant.conf since it holds credentials. If you connect to multiple networks, add more network={} blocks; wpa_supplicant picks the best available match.

Step 6: Bring it up and the regulatory-domain gotcha

With rc.conf and wpa_supplicant.conf in place, restart networking:

# service netif restart
# service routing restart
# ifconfig wlan0

You want to see status: associated and an assigned IPv4 address. If you associate but see no 5 GHz networks, or you get lower rates than expected, the culprit is very often the regulatory domain. FreeBSD defaults conservatively, and until it knows your country it will not enable channels or transmit power that are only legal in specific regions. Set your country in /etc/rc.conf so it applies to every wlan interface at creation:

# sysrc create_args_wlan0="country US regdomain FCC"

Replace US/FCC with your actual location (DE/ETSI, JP/MKK, and so on). This single line is behind a surprising share of "I can see 2.4 GHz but never the 5 GHz SSID" reports. It also affects whether higher-bandwidth channels are usable at all.

A quick troubleshooting checklist

• No device in pciconf -lv at all: the chip may be too new, or it is a CNVi part whose companion is disabled in BIOS. Check firmware/BIOS wireless settings.
• Device shows as none: driver not loaded. kldload the right module and confirm in dmesg.
• Driver loads but complains about .ucode: install the matching wifi-firmware-*-kmod package.
• Scan returns nothing: regulatory domain, or firmware not actually loaded. Re-read dmesg.
• Associates but no IP: DHCP issue, not a wireless issue. Check dhclient and your ifconfig_wlan0 line.
• Links but slow: expected on Wi-Fi 6 hardware under current LinuxKPI drivers; ac-class rates are normal for now.

Takeaway

FreeBSD wireless is not fragile, it is layered: identify the chip, load driver plus firmware, clone a wlan interface onto the raw device, feed wpa_supplicant your credentials, and set the regulatory domain. Get those five things right and modern Intel and Realtek laptops connect reliably. The mechanics here were verified against the current FreeBSD Handbook for the 14.x/15.x line; because the LinuxKPI drivers are actively evolving, always cross-check man iwlwifi, man rtw88, or your driver's page on the exact release you are running before assuming a limitation is permanent.