It is common in larger installations (e.g. large domestic networks or commercial installations) for a WiFi network to be configured with many different access points all advertising the same SSID (wifi network name) with the same authentication method and credentials.

The intention is that a WiFi client will choose “the best” access point (or rather “BSS”) to connect to. If network conditions change, or a client is physically moved to a different location, then “the best” BSS may change.

Even if there is a only a single access point present, then a client may prefer to disconnect from the access point on one radio frequency band and reconnect on another band (e.g. switch from using 5 GHz to 2.4 GHz). i.e. A single physical access point might have two or three different BSSs, one on each frequency band which it supports, and “roaming” between them looks a lot like the transition which occurs between access points.

The WiFi standards define:

A single network name as an SSID (Service Set ID).

A single access point advertising a single SSID as a BSS (Basic Service Set).

A configuration where the same SSID is available from multiple access points as an Extended Service Set (ESS).

Each BSS is identified with a 48bit number called a BSSID, this is usually written in the “EUI48” form used for Ethernet MAC addresses e.g. `52:54:00:d2:f3:89`.

n.b. A single physical access point with two radios (e.g. a 2.4 GHz radio and a 5 GHz radio) which advertise the same SSID on each frequency is also an ESS, the standards would refer to this as an ESS with two colocated BSS.

Over time, a number of optional features have been added to the WiFi standards to try to increase roaming performance within an ESS. These include:

• “Neighbor Reports” allow each BSS to provide its wifi clients with a list of alternative BSSIDs and frequencies within the same ESS. This reduces the time that each client needs to spend looking for an alternative “better” SSID because it no longer needs to scan all frequencies.
• “Network assisted Roaming” allows a BSS to recommend alternative BSSs that the client could roam to.
• “Fast Transition” reduces the time taken for a client to establish a secure connection when roaming to a different BSS.

Beware that an incorrectly configured or otherwise non-functional implementation of many roaming technologies can result in a poorer roaming experience than

“Neighbor reports” were originally standardised as part of 802.11k but later absorbed into the main 802.11 standard.

“Network assisted roaming” was originally standardised as part of 802.11v but later absorbed into the main 802.11 standard.

“Fast Transition” was originally standardised as part of 802.11r but later absorbed into the main 802.11 standard.

The latest version of the standard which covers all of these roaming technologies at the moment is 802.11-2024.

You will often see the old standard names (802.11k, 802.11v) used to refer to individual roaming related features, even though they are now officially superseded and the roaming features only made up a small part of some of those standards (e.g. there were many unrelated features included in 802.11v e.g. the ability for the access point to notify the client about its time zone).

The decision to roam to a different access point or “stick” with the existing association lies either wholly or partly with the client. Different clients behave differently. The roam decisions and interactions with the access point (OpenWrt or otherwise) can be complex, hard to debug, and vary greatly between different wifi clients. Client roaming behaviour is often poorly documented or not documented at all.

In general:

• Enabling Neighbor Reports (AKA 802.11k) results in the greatest improvements in roaming, and are especially useful for discovery of 5GHz access points which use channels that have a regulatory requirement for coexistence with radar.
• Enabling certain 802.11v features can enhance the roaming behaviour of a smaller subset of clients further by giving them additional information.
• Enabling 802.11r usually has a limited impact except on networks which use 802.1X authentication with high latency authentication servers (e.g. Eduroam), although in certain circumstances it can also benefit highly time sensitive realtime network applications like VOIP.

The “hostap” management software forms a key part of OpenWrt in that it manages advertising WiFi networks and authenticating WiFi clients. hostapd includes support for 802.11k and 802.11v, but relies on external software to make roaming recommendations and provide it with lists of alternative BSSIDs etc. OpenWrt packages software which can perform these functions and are intended to manage both 802.11k and 802.11v. Only one should be active at a time:

• dawn
• usteer

Alternatives which only implement 802.11k include:

• static-neighbor-reports
• nrsyncd
• rmm-nr-distributor

Double check that your wpad supports 802.11k - usually the “full” versions of wpad are needed (wpad-basic-mbedtls does not, e.g., in 24.10, whereas the corresponding wpad-mbedtls does support all three relevant standards 802.11k/r/v).

If you attempt to enable k/v with wpad-basic-mbedtls instead of wpad-mbedtls, the wireless interface will become disabled.

You can check that 802.11k is enabled using tcpdump and wireshark e.g.

iw phy phy1 interface add phy1mon0 type monitor
ip link set phy1mon0 up
tcpdump -i phy1mon0 -s 0 -w /tmp/output.pcap type mgt

Alternatively instead of writing to a RAM-backed capture file, you can stream captured packets over ssh:

ssh root@openwrt-host 'tcpdump -U -i phy1mon0 -w - type mgt' > /tmp/openwrt-host.pcap

The resulting file can be loaded into wireshark. The presence of beacons with 802.11k neighbor reports enabled can be checked using the filter wlan.rmcap.b1 == True. Alternatively, manual 802.11k checks can be made by examining a beacon frame. Expand: IEEE 802.11 Wireless Management → Tagged parameters → Tag: RM Enabled Capabilities → RM Capabilities a value of 1 in the Neighbor Report bit indicates enabled.

The following wireshark filters may also be of use:

• Packets indicating Neighbor Reports enabled in Radio Measurement Capabilities: wlan.rmcap.b1 == True
• Packets containing neighbor reports: wlan.tag.number == 52
• Neighbor report request packets: wlan.fixed.action_code == 4
• Neighbor report reponse packets: wlan.fixed.action_code == 5

Note that neighbor report requests and responses are transferred in unicast management frames. In OpenWrt management frame protection is enabled by default so these frames are encrypted. Unless you take steps to decrypt these frames (see below), the filters above will not yield any results.

If for some reason you cannot successfully decrypt the management frames, then management frame protection can be disabled with option ieee80211w '0' , or via luci in the access point security settings. Also note that WPA3 requires management frame protection, so you can only disable management frame protection on WPA2 access points whilst monitoring for neighbor report responses. Management frame protection should be re-enabled once debugging is complete.

The Wireshark Wiki includes instructions on enabling wifi frame decryption: https://wiki.wireshark.org/HowToDecrypt802.11. See in particular the 'Gotchas' section - otherwise you may still not be able to decrypt the frames.

When joining (“associating with”) a wireless network with security enabled, a “4 way handshake” occurs between a wireless client and the BSS (usually a typical radio on an access point). In the case of “Enterprise” EAP / 802.1X type authentication (whereby each user has their own authentication credentials), this can be especially time consuming because the authentication step may involve a distant authentication server.

Without 802.11r, a roam (a transition to a different BSS) repeats the same authentication process. During this time, network traffic is interrupted. 802.11r aims to speed up the roam with a shorter packet exchange (e.g. 4 packets total vs 8) during the transition to the new BSS (n.b. the new BSS could also be on the same physical access point if the client switches between the 2.4GHz and 5GHz radios).

802.11r is particularly beneficial when “Enterprise” EAP / 802.1X type authentication is used because an additional (potentially high latency) round-trip to the authentication server is not required. See the linked WLPC presentation video in the “Additional Resources” section for some real world examples and timings.

The full set of 802.11r related options which OpenWrt supports can be found here in the documentation.

To configure using the Luci web interface, go to Network→Wireless, and on each SSID click Edit, scroll-down to the Interface Configuration tabs, select WLAN Roaming, check the 802.11r Fast Transition box, and put in a 4-digit Mobility Domain that matches the same SSID on your other 802.11r-enabled routers/AP's.

• If you do not see the WLAN Roaming tab, you need to update your OpenWrt or load a version of wpad that has the 802.11r features. All current versions of OpenWrt come with 802.11r support in the basic wpad drivers.

Clients without 802.11r support should connect to networks with 802.11r enabled, however some buggy clients are known to refuse to associate with networks which have 802.11r enabled, or have other problematic behaviour. A workaround for this is to create a separate “legacy” SSID which has 802.11r disabled, for those devices alone to connect to. In some cases upgrading the client firmware, drivers, or OS may fix issues.

• MacOS on Intel CPUs do not support 802.11r. Whilst most Intel Macs will join networks which have 802.11r enabled, some older Intel Macs will fail to associate with (join) SSIDs which have enabled 802.11r. For minimum versions for iOS devices Apple includes a table on this page.
• Windows 10 and Windows 11 (up to and including version 2024H2) only supports 802.11r on networks which use 802.1X authentication, so that fast transitions are not used on networks with PSK passphrases i.e. on the vast majority of OpenWrt setups, Windows will not use 801.11r).
• Some Intel Windows wifi6 client cards with driver versions 23.60.* would fail to re-associate to OpenWrt 23.x access points when 802.11r with PSK was enabled. Upgrading to Intel driver version 23.90.* fixed the problem.

To check if 802.11r is working properly, set log_level to 1 (cf. Common Options) and look for message “FT authentication already completed - do not start 4-way handshake” in your system log after roaming.

It's also possible to verify that clients are using 802.11r by inspecting the “Association Request” frames that they send. Verify the “Auth Key Management type” includes “FT” (Fast Transition).

In the packet capture screenshot below, Wireshark is used with the filter wlan.fc.type_subtype == 0. The client can be seen to request the use of 802.11r - the “Auth Key Management type” is set to “FT using SAE” (i.e. 802.11r fast transition, with WPA3 SAE pre-shared key).

When 802.11r is in use, this can be found in each Association Request frame, under IEEE 802.11 Wireless Management → Tagged parameters → RSN Information → Auth Key Management (AKM) List.

• A talk given at Wireless Lan Professionals Conference 2019 entitled "Effects of 802.11k/r/v"
• OneMarkFifty explaining how to set-up fast roaming OpenWrt Wi-Fi Access points (Youtube)
• OpenWrt Forum: Documentation on 802.11r
• OpenWrt Forum: 802.11r Fast Transition, another discussion