FreeBSD Wi-Fi Client Operations: Driver, WPA, and DHCP

FreeBSD Wi-Fi connectivity is a sequence of separate operations: the hardware must attach to a driver, the wlan(4) layer must expose a station interface, the client must scan and associate, wpa_supplicant(8) must complete the network’s authentication, and the interface must obtain a usable address and route. “The card appears in pciconf” proves only hardware discovery. “The SSID is visible” does not prove authentication, DHCP, DNS, or application traffic works.

This guide focuses on a FreeBSD station joining an existing network. It does not configure FreeBSD as an access point or assume every adapter supports the same channels, roaming behavior, or 802.11 mode. The actual driver and firmware manuals for the installed release define what a particular device can do; a protocol-layer feature does not guarantee chipset-level support.

Identify the radio before creating a station interface

Begin with the installed release, PCI/USB devices, kernel messages, and wireless devices exported by the system:

freebsd-version -kru
pciconf -lv
dmesg | grep -i -E 'wlan|wifi|wireless|firmware|iwm|iwx'
sysctl net.wlan.devices
ifconfig -a

The exact driver name depends on the chipset and release. net.wlan.devices lists devices that FreeBSD exposes to the 802.11 stack. If it is empty, do not try to create wlan0 blindly. Verify that the device is supported, the driver attached, required firmware is available, and the radio is not disabled by a hardware switch or platform setting. A working wired connection can keep management access available while investigating firmware or driver changes.

The generic wlan(4) module supplies shared 802.11 link-layer support for native wireless drivers. It does not mean all listed modes or features work on every radio. For example, a driver’s manual can document firmware requirements, unsupported operation modes, or limitations that the generic wlan page does not describe. Check the manual page matching the actual interface driver, such as iwm(4), iwx(4), or another device-specific page, before treating an advertised access-point mode or feature as available.

Create the wlan station interface persistently

For an adapter exposed as iwm0, a station interface named wlan0 can be created at runtime with:

ifconfig wlan0 create wlandev iwm0
ifconfig wlan0 up

The persistent rc configuration uses the parent radio’s wlans_ variable. The following is an example only; replace iwm0 with the device in net.wlan.devices and choose interface names that do not collide with existing interfaces:

sysrc wlans_iwm0="wlan0"

If the radio already has a station interface, do not create a duplicate. Inspect ifconfig -a and rc configuration first. A cloned interface is distinct from the physical parent, and the parent’s driver-specific controls remain relevant to the child station.

Regulatory domain and country settings determine which channels are permitted and how the radio operates. Read /etc/regdomain.xml and the installed ifconfig(8) manual for valid values in the host’s actual location. Do not copy a country/regdomain pair from a sample for another region. If the interface needs a persistent override, use the documented create_args_<interface> rc setting and verify the selected channels after reboot.

Configure a network profile and association

For a WPA personal network, FreeBSD’s Handbook uses /etc/wpa_supplicant.conf with a network block. This illustrative profile uses placeholders, not a real network credential:

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

network={
    ssid="Example network"
    psk="REPLACE_WITH_APPROVED_NETWORK_KEY"
}

The SSID and pre-shared key must match the network’s configured values. Add scan_ssid=1 only for a hidden SSID; it is not needed for an ordinarily advertised network. For enterprise authentication, consult the installed wpa_supplicant.conf(5) manual and the network administrator’s profile instead of converting a personal-key example by guesswork. A syntactically valid network block does not prove that the access point and client agree on authentication parameters.

To configure a DHCP-managed station through rc, the Handbook documents:

sysrc ifconfig_wlan0="WPA DHCP"

This combines WPA supplicant association with DHCP client configuration for the interface. If the network uses a static address, configure the addressing policy explicitly instead of leaving DHCP enabled. Avoid restarting all interfaces remotely: service netif restart can interrupt wired management, jails, bridges, VLANs, or storage traffic. Apply Wi-Fi changes from console or a planned maintenance session, then verify both the station and any required wired failover behavior.

The Handbook also shows the required clone mapping when the adapter is iwm0:

sysrc wlans_iwm0="wlan0"
sysrc ifconfig_wlan0="WPA DHCP"

Review existing values with sysrc wlans_iwm0 ifconfig_wlan0 before setting them. Check the installed rc behavior for the release and driver; a working manual ifconfig session is not proof that boot will recreate the same interface and start the same supplicant.

Scan and prove the connection in stages

Bring the interface up and request a scan:

ifconfig wlan0 up list scan
ifconfig wlan0

The scan reports properties such as SSID, BSSID, channel, signal-to-noise indication, and advertised capabilities. Choose the intended access point using its BSSID and channel, not SSID text alone, because several access points may advertise the same network name. A scan result is time-sensitive and does not establish that association will succeed.

Validate each stage with a separate observation:

Radio and clone: sysctl net.wlan.devices lists the parent, and ifconfig wlan0 shows the expected child interface and regulatory state.
Scan: the intended BSSID appears under the supported channel set with a plausible signal reading.
Association: interface state and logs show the station joined the intended BSS; do not infer this solely from the AP appearing in a scan.
Authentication: the WPA supplicant completes the configured method without repeated failure.
Addressing: the station has the expected IPv4 or IPv6 address, route, and resolver configuration.
Application: a bounded request to the actual service succeeds over the intended address family.

For DHCP, inspect the active interface configuration, lease record, default route, and resolver state independently. The DHCP client can hold a valid lease while an application still uses the wrong resolver or route. A connected Wi-Fi state and a valid IPv4 address also do not prove that IPv6 policy is correct.

Diagnose common failure boundaries

No wireless device is listed. Check device support for the exact hardware revision, attach messages, firmware availability, module state, and radio switch. Do not debug WPA before a driver has created a parent radio.

The parent exists but wlan0 does not. Confirm the wlans_<parent> mapping and look for a naming collision or rc error. Create one temporary child with the documented ifconfig syntax and verify its wlandev before changing persistent startup configuration.

The SSID is not in the scan. Check interface state, antenna connection, signal, regulatory domain, channel selection, and driver diagnostics. Hidden-network scan behavior is distinct from normal scanning; do not enable scan_ssid=1 as a generic remedy.

The access point appears but association fails. Compare the configured authentication method and network profile with the AP. Reduce variables in a controlled test and inspect the station authentication/association trace. wlandebug supports scan, authentication, association, and roam message groups, but different drivers emit different detail. Enable only the necessary debug categories for a bounded interval because logs can become noisy.

Association succeeds but there is no usable network. Move to the IP layer: check DHCP exchange, address, prefix, default route, DNS, and firewall policy. Do not change the SSID or WPA settings to repair an exhausted DHCP pool or incorrect VLAN upstream.

The station disconnects or roams unexpectedly. Record BSSID, channel, signal, timestamps, driver messages, power state, and whether the same issue occurs near a different access point. Reproduce with a fixed location and one network profile. A signal reading alone does not establish interference or driver fault; compare controlled runs and check the device-specific limitations.

Operational acceptance and version discipline

An accepted deployment has a documented radio driver and firmware source, one intended wlan clone, a reviewed regulatory configuration, a matching supplicant profile, the correct address policy, and a boot-tested rc configuration. Test link bounce, reboot, DHCP renewal, AP restart, and any supported roaming path. Verify wired management remains available when changing a laptop or server’s only wireless route.

Record the FreeBSD kernel and userland versions, adapter model, driver, firmware version, regulatory domain, AP model and configuration, channel, BSSID, authentication mode, DHCP result, and application test. Feature availability is a property of the complete adapter-driver-firmware-AP combination, not simply of a standard’s name or the FreeBSD release number. When one device fails, compare a known-supported adapter or a different AP before changing unrelated global network settings.

FreeBSD’s wireless stack is most manageable when each transition is evidenced separately. First prove the radio exists, then prove scanning, association, authentication, addressing, routing, and application access. That order avoids treating every failure as “bad Wi-Fi” and keeps network changes limited to the layer that actually failed.

Related:

Sources: