Add simulated band steering post

Author: a-gavin

content/blog/2025-11-simulated-band-steering.md

@@ -0,0 +1,245 @@
++++
+title = "Simulated WiFi Band Steering"
+date = "2025-11-01"
+description = ""
+path = "blog/simulated-band-steering"
+
+#[taxonomies]
+#tags = ["linux", "wifi"]
++++
+
+## Overview
+
+In this post, I'll provide some background on and demonstrate how to simulate WiFi band steering. We'll use open source
+Linux tools that are used in commercial WiFi products. _No physical WiFi radios are required!_
+
+If you'd like to replicate this yourself, you'll need a Linux system with `sudo` access, kernel support for the `mac80211_hwsim` driver
+(which is generally the case for most Linux distributions), and `hostapd` and `wpa_supplicant` installed. These tools will permit
+complete WiFi simulation in software. However, the same setup will also work with real WiFi radios. This can also be run within
+a container or virtual machine.
+
+This setup will require some experience using Linux, Wireshark, and WiFi. There are plenty of great resources out there.
+I maintain a reference of Linux commands I use often [here](@/blog/2023-12-linux-cmds.md). Additionally, if you'd like to (responsibly) do real
+WiFi packet capture with Wireshark, I wrote a guide which is available [here](@/blog/2023-10-wifi-packet-capture.md).
+
+## Background
+
+Before we dive in, I'd like to first cover some background WiFi information, especially as it relates to band steering. If you're familiar already, skip to the next section.
+
+In WiFi, clients select and connect to the WiFi access point (AP) BSSID they want. Each client operates slightly differently, but metrics like channel utilization and estimated throughput strongly influence this decision. As a client operates and possibly moves around in its environment, conditions will change. The client may decide to shift to another channel on the same AP (different BSSID), it may roam to another AP, or it may do something else entirely! These decisions are ultimately left up to the client, not the AP.
+
+Given this, an AP is left with limited options to influence the client decisions. An AP can reject the client's authentication/association request or send a deauthentication/disassociation. However, these methods are heavy handed and may result in poor user experience.
+
+Several amendments to the WiFi 802.11 standard serve to address this and to improve user experience generally. Amendments 802.11k (neighbor reports), 802.11r (fast transition), and 802.11v (BSS transition management) are a couple widely known examples. For the purposes of this post, we'll focus on 802.11k and 802.11v, which introduce neighbor reports and BSS transition management (BTM), respectively. Both are essential for band steering, whether it be simulated or real-world.
+
+If you'd like to brush up on band steering or the amendments I mentioned, check out my colleague Isaac Konikoff's talk on band steering fails [here](https://www.youtube.com/watch?v=X5ffNbd5Duw) and this Cisco 802.11v explainer available [here](https://web.archive.org/web/20230815035221/https://www.cisco.com/c/en/us/td/docs/wireless/controller/9800/config-guide/b_wl_16_10_cg/802-11v.pdf). For more in-depth coverage, check out my colleague Sitarama Penumetsa's lecture [here](https://youtu.be/BiktVCtMGnk?si=c6LDYNyg1qJ_DqQ8&t=2002) from his WiFi fundamentals course.
+
+With this all in mind, we're ready to setup for testing!
+
+## Test Setup
+
+In order to simulate band steering, we must first configure our test environment. While this same configuration is possible with
+real radios, we'll instead use the `mac80211_hwsim` Linux driver to simulate this testing entirely in software.
+
+### Recommendations
+
+To make your life easier, I recommend the following:
+
+- **Use three terminals**
+
+  - One terminal each for AP, client, and configuration CLI
+
+  - This will permit reading logs while we setup and run the test
+
+  - Now may be a good time to learn how to use `tmux` or `screen`
+
+  - It's possible to setup this test with `wpa_supplicant` and `hostapd` daemonized (`-B` argument), but I would only recommend it for advanced users
+
+- **Disconnect from your WiFi (if present) while running this**
+
+  - When running with verbose logging, `wpa_supplicant` and `hostapd` will output information on any changes to any interface
+    on the system. Verbose logs can especially become busy on a normal system, as they will log periodic scans run by
+    your networking daemon for any existing WiFi interface.
+
+  - Make sure **not** to run `nmcli radio wifi off`, as this will enable rfkill which soft blocks WiFi on all interfaces
+    (including the `mac80211_hwsim` ones)
+
+### Instructions
+
+**NOTE:** Many commands in this post will require root permissions (e.g. run with `sudo`), including `hostapd`, `wpa_supplicant`, `modprobe`.
+
+1. **Load the `mac80211_hwsim` kernel module (driver)**
+
+   ```Bash
+   # Three simulated radios are needed
+   #  1. Client (STA)
+   #  2. AP 2.4 GHz BSSID
+   #  3. AP 5 GHz BSSID
+   modprobe mac80211_hwsim radios=3 support_p2p_device=0
+   ```
+
+2. **Identify simulated WiFi interfaces and their MAC addresses**
+
+   **Most likely the `mac80211_hwsim` interfaces will be named `wlan0`, `wlan1`, and `wlan2`**. The driver will additionally
+   create another interface named `hwsim0`, which permits packet capture of simulated WiFi traffic.
+
+   To identify the interfaces and corresponding MAC addresses, use the `ip -br addr show` and `ip -br link show` commands.
+   First check the MAC address. The driver creates the interfaces using the format `02:00:00:00:XX:00`, where the `XX`
+   matches the simulated radio number, which is easy to identify.
+
+   If you're encountering issues or want to know more, check out [this section](#identifying-interfaces-and-macs-cont).
+
+3. **Configure your network daemon to ignore the interfaces**
+
+   Practically all modern workstation Linux distributions ship with NetworkManager. If you're using something else, I assume you know
+   what you're doing or can figure it out...
+
+   When using NetworkManager, we must configure it to ignore the new `mac80211_hwsim` interfaces, which you can do with the
+   following command. We don't need any IP configuration for this testing anyway.
+
+   When complete, the interfaces should show as `unmanaged` in the output of `nmcli device status` (or `nmcli device` for short),
+   as shown below.
+
+   ```Bash
+   # Run this for each simulated WiFi interface, substituting in
+   # your system's interface names for this and subsequent commands
+   nmcli device set wlan0 managed false
+   ```
+
+4. **Download example `hostapd` and `wpa_supplicant` configs from [here](https://codeberg.org/a-gavin/hostap-confs)**
+
+   I recommend using the open (no security) configuration, as this will make packet capture much more simple.
+   With configurations supporting encryption, packet decryption is possible, but security improvements like 802.11w
+   and WPA3 make this increasingly difficult (which is good for security!).
+
+   ```Bash
+   git clone https://codeberg.org/a-gavin/hostap-confs.git
+   ```
+
+5. **Start the AP interfaces**
+
+   ```Bash
+   # Options used are:
+   #  -t:  Print timestamps
+   #  -i:  Specify interface to run AP with. Can be specified multiple times.
+   #
+   # For verbose or very verbose logging, add the '-d' or '-dd' options
+   hostapd -t -i wlan0 -i wlan1 hostapd_2.4GHz-open.conf hostapd_5GHz-open.conf
+   ```
+
+   Assuming no errors appear in the logs, you can verify the AP interface channel/frequency, SSID, and MAC
+   with the `iw wlan0 info` command.
+
+6. **Enable `mac80211_hwsim` packet capture interface**
+
+   This interface is likely named `hwsim0`.
+
+   ```Bash
+   ip link set up dev hwsim0
+   ```
+
+7. **Run Wireshark using the `mac80211_hwsim` packet capture interface**
+
+   Packet capture requires root permissions. See the Wireshark documentation [here](https://wiki.wireshark.org/capturesetup/captureprivileges#gnulinux-distributions-wireshark-is-installed-using-a-package-manager) for more information on how to enable
+   this.
+
+8. **Start the client interface**
+
+   ```Bash
+   # Similar options and requirements as 'hostapd'
+   # The '-c' option required to specify the config file
+   wpa_supplicant -t -i wlan2 -c supplicant_open.conf
+   ```
+
+9. **Wait for client to connect**
+
+   As the client connects, you should see start to see the simulated WiFi traffic in Wireshark. The simulated client will
+   connect through the normal WiFi client connection process (use the `wlan.fc.type_subtype != 8` filter to filter out beacons).
+   Connection is complete once the AP responds with a successful association response frame.
+
+   Once the client connects, you should see the message `CTRL-EVENT-CONNECTED` in the station logs and `AP-STA-CONNECTED` in
+   the AP logs. Take note of the AP interface that the client connected to. As with the AP interfaces, you can run the
+   `iw wlan2 info` command to verify connection, channel, SSID, BSSID, etc.
+
+With the simulated client connected and Wireshark running, we're ready to run some tests!
+
+## Simulated Band Steering
+
+To start, we'll first attempt to steer the client from its currently associated AP BSSID to the other AP BSSID.
+This aims to simulate a real AP requesting a client transition.
+
+This type of interaction is often seen as client signal reduces. The AP monitors this and suggests the client transition to
+a higher signal BSSID (e.g. from 6 GHz to 5 GHz). Metrics like signal to noise ratio (SNR) are often used for this.
+
+1. **Connect to the `hostapd` CLI interface**
+
+   In another terminal, run the following command. This will enter a the `hostapd` CLI interface which may
+   or may not permit line editing and/or command history, depending on your system.
+
+   ```Bash
+   # The '-p' option isn't necessary if using the example configs, as they use
+   # the default control interface path
+   hostapd_cli -p /var/run/hostapd/
+   ```
+
+2. **Select the AP interface to which the client connected**
+
+   Using the `interface` command, select the desired interface. Then, check the list of connected clients
+   with the `list_sta` command, as shown below.
+
+   ```Bash
+   $ hostapd_cli -p /var/run/hostapd/
+   ...
+   > interface wlan0
+   > list_sta           <---- No clients associated, check the other AP interface
+   > interface wlan1
+   > list_sta
+   02:00:00:00:02:00
+   ```
+
+3. **Send a BSS Transition Management (BTM) request to the client**
+
+   With the interface still selected in the `hostapd` CLI interface, run the following command to send a BTM request
+   to the client. This will generate a BTM request frame, to which the client should respond.
+
+   If a client does not support BTM, then the client should not respond. You can simulate this by adding `disable_btm=1`
+   to the client's `wpa_supplicant` config outside of the network block and then resetting the client to make this active.
+
+   ```Bash
+   # From 5 GHz to 2.4 GHz
+   # First MAC is client MAC. Second MAC (neighbor) is 2.4 GHz BSSID.
+   bss_tm_req 02:00:00:00:02:00 pref=1 neighbor=02:00:00:00:00:00,0x0000008f,81,1,14
+
+   # From 2.4 GHz to 5 GHz
+   # First MAC is client MAC. Second MAC (neighbor) is 5 GHz BSSID.
+   bss_tm_req 02:00:00:00:02:00 pref=1 neighbor=02:00:00:00:01:00,0x0000008f,81,36,14
+   ```
+
+   Assuming this ran okay, you should see a successful BTM request and response exchange in Wireshark as shown below.
+
+   {{ image(src="/blog/2025-11-simulated-band-steering/btm_request_success_5ghz_to_2.4ghz.png", caption="BTM Request to downsteer from 5 GHz to 2.4 GHz BSSID", alt="BTM Request to downsteer from 5 GHz to 2.4 GHz BSSID") }}
+
+   Here's another BTM request exchange, this time where the client rejects the AP's request with status code 7, no suitable candidates.
+
+   {{ image(src="/blog/2025-11-simulated-band-steering/btm_request_reject_no_suitable_candidates.png", caption="BTM Request rejected, no suitable candidates", alt="BTM Request rejected, no suitable candidates") }}
+
+## Identifying Interfaces and MACs Cont
+
+In the case that interface names and MAC addresses are non-default or difficult to identify, there may be several
+things getting in the way. This section covers a couple reasons why this may be.
+
+When any WiFi kernel module loads, the driver creates a virtual interface (vif) per radio. A vif is a general term which refers
+to a WiFi interface, be it a station, AP, monitor, or others and applies regardless of WiFi driver (simulated or not).
+It's possible to load the `mac80211_hwsim` kernel module without creating a vif for each radio, but that's beyond the
+scope of this post (see `modinfo mac80211_hwsim`).
+
+When created, virtual interfaces will generally use a unique name on most modern Linux distributions, thanks to systemd's
+predictable network interface naming (see [here](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) for more info). The
+`mac80211_hwsim` interfaces generally dodge this and are reliably named `wlanX` (unsure if they skip udev), assuming the
+configured name doesn't already exist.
+
+If the `mac80211_hwsim` interfaces are difficult to identify by name, check the MAC address which is configured to something matching
+the format `02:00:00:00:XX:00` (output by `ip -br link show`), assuming your network daemon doesn't get in the way (NetworkManager
+may randomize the MACs, have fun).
+
+<!-- TODO: How to disable MAC changing on NetworkManager -->