diff --git a/doc/README.md b/doc/README.md index 7ac9c004..8b7b74d8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -21,6 +21,7 @@ regression test system solely relies on NETCONF and RESTCONF. - [Introduction](introduction.md) - [System Configuration](system.md) - [Network Configuration](networking.md) + - [Wi-Fi](wifi.md) - [DHCP Server](dhcp.md) - [Syslog Support](syslog.md) - **Infix In-Depth** diff --git a/doc/img/wifi-mesh-roaming.svg b/doc/img/wifi-mesh-roaming.svg new file mode 100644 index 00000000..fc5704d2 --- /dev/null +++ b/doc/img/wifi-mesh-roaming.svg @@ -0,0 +1,396 @@ + + + + + + + + + + + + + Internet + + + + 802.11s mesh + 802.11s mesh + + + + Node A + (mesh + AP) + + bridge br0 + + clients + + + + Node B + (mesh + AP) + + bridge br0 + + clients + + + + Node C + (mesh + AP) + + bridge br0 + + clients + + clients roam between nodes (802.11r/k/v) + diff --git a/doc/wifi.md b/doc/wifi.md index af3ca8fc..14b4e18d 100644 --- a/doc/wifi.md +++ b/doc/wifi.md @@ -517,13 +517,17 @@ the same mobility domain without manual configuration: admin@example:/config/interface/wifi0/> set wifi access-point roaming dot11r mobility-domain hash ``` -You can optionally set NAS identifier mode: +The NAS-Identifier (Network Access Server Identifier) is a string that +uniquely identifies each AP within the 802.11r mobility domain. APs +exchange this identifier during fast BSS transition so they can look up +the correct PMK-R1 key for the roaming client. It must be unique per AP +BSS and stable across reboots. ``` admin@example:/config/interface/wifi0/> set wifi access-point roaming dot11r nas-identifier auto ``` -`auto` derives: +`auto` derives the identifier as: `-.` @@ -554,6 +558,46 @@ admin@example:/config/interface/wifi0/> set wifi access-point roaming dot11v Allows APs to suggest better APs to clients, improving roaming decisions. +#### Band Steering (MBO) + +Enabling `dot11v` also turns on MBO (Multi-Band Operation), advertised in +beacons and association responses. MBO lets a dual-band client see that +the same SSID exists on another band and decide for itself when to move, +while 802.11v BSS Transition Management lets the AP suggest a better +target. + +On top of the client-cooperative hints, the AP applies active steering: +on a 2.4 GHz access-point it suppresses probe responses to clients that +were recently seen on the same SSID on the 5/6 GHz band, nudging +dual-band clients onto the higher band. MBO is **enabled by default** +whenever `dot11v` is enabled: + +``` +admin@example:/config/interface/wifi0/> set wifi access-point roaming dot11v +``` + +To turn it off while keeping BSS Transition Management: + +``` +admin@example:/config/interface/wifi0/> set wifi access-point roaming dot11v band-steering false +``` + +> [!NOTE] +> Band steering only matters when the same SSID is offered on two or more +> bands (one access-point per radio). On a single-band network there is +> no other band to move to, so it has no effect. + +### Opportunistic Key Caching (OKC) + +OKC reduces re-authentication time for roaming clients that do not +support 802.11r. The AP caches the PMK from previous associations and +shares it with other APs in the same mobility group. It is **enabled by +default** and only activates when both AP and client support it: + +``` +admin@example:/config/interface/wifi0/> set wifi access-point roaming okc false +``` + ### Recommended Configuration For optimal roaming experience, enable all three features: @@ -581,20 +625,114 @@ Repeat for all APs that should participate in the roaming group. > support 802.11k/r/v, but older devices may only support basic roaming without > fast transition. -### AP as Bridge Port +## 802.11s Mesh Point Mode -WiFi AP interfaces can be added to bridges to integrate wireless devices -into your LAN: +IEEE 802.11s is a wireless mesh networking standard operating at Layer 2. +Mesh nodes form peer links directly with each other and route traffic +using HWMP (Hybrid Wireless Mesh Protocol), which is built into the +Linux mac80211 subsystem. There is no central controller; nodes +discover peers and find paths on their own. + +The standard defines two node roles: + +- **Mesh Point (MP)** - a basic mesh node that forwards traffic within + the mesh +- **Mesh Portal (MPP)** - a mesh node that bridges traffic between the + mesh and an external network (e.g., a wired LAN) + +In practice, a node bridging the mesh interface to a LAN acts as a mesh +portal. + +> [!NOTE] +> Not all WiFi hardware supports 802.11s mesh. The driver must implement +> mesh point mode in mac80211. Check your adapter's capabilities with +> `iw phy info` and look for "mesh point" under "Supported interface +> modes". + +### 802.11s vs EasyMesh + +| | **802.11s** | **EasyMesh** | +|-----------------------------|--------------------------|--------------------------------| +| **Standard** | IEEE (open, ratified) | Wi-Fi Alliance (certification) | +| **Topology** | Peer-to-peer, any-to-any | Controller-based tree | +| **Single point of failure** | None | Controller | +| **Multi-hop** | True N-hop | Limited (1-2 hops) | +| **Vendor lock-in** | None | Common | +| **Linux support** | Kernel-native (mac80211) | Requires proprietary firmware | + +Infix uses 802.11s because it runs entirely in the kernel with no +proprietary components. + +### Mesh configuration + +A mesh point requires the radio to have `band`, `channel`, and a valid +`country-code` configured. Mesh and AP modes cannot coexist on the same +radio. + +**Step 1: Configure the radio** 
admin@example:/> configure
-admin@example:/config/> edit interface br0
-admin@example:/config/interface/br0/> set type bridge
-
-admin@example:/config/> edit interface wifi0
-admin@example:/config/interface/wifi0/> set bridge-port bridge br0
-admin@example:/config/interface/wifi0/> leave
+admin@example:/config/> edit hardware component radio1 wifi-radio
+admin@example:/config/hardware/component/radio1/wifi-radio/> set country-code DE
+admin@example:/config/hardware/component/radio1/wifi-radio/> set band 5GHz
+admin@example:/config/hardware/component/radio1/wifi-radio/> set channel 36
+admin@example:/config/hardware/component/radio1/wifi-radio/> leave
+**Step 2: Create keystore entry for mesh security** + +All mesh links use WPA3-SAE encryption. All nodes in the same mesh +network must share the same passphrase: + +
admin@example:/> configure
+admin@example:/config/> edit keystore symmetric-key mesh-secret
+admin@example:/config/keystore/…/mesh-secret/> set key-format passphrase-key-format
+admin@example:/config/keystore/…/mesh-secret/> change cleartext-symmetric-key
+Passphrase: ************
+Retype passphrase: ************
+admin@example:/config/keystore/…/mesh-secret/> end
+
+ +**Step 3: Configure the mesh interface** + +
admin@example:/config/> edit interface wifi-mesh
+admin@example:/config/interface/wifi-mesh/> set type wifi
+admin@example:/config/interface/wifi-mesh/> set wifi radio radio1
+admin@example:/config/interface/wifi-mesh/> set wifi mesh-point mesh-id my-mesh
+admin@example:/config/interface/wifi-mesh/> set wifi mesh-point security secret mesh-secret
+admin@example:/config/interface/wifi-mesh/> leave
+
+ +**Mesh parameters:** + +- `mesh-id`: Network identifier, 1-32 characters. All nodes in the mesh + must use the same mesh ID +- `forwarding`: L2 mesh forwarding (default: true). When enabled, the + interface can be added to a bridge as a mesh portal +- `security secret`: Keystore reference for the WPA3-SAE passphrase + +### Mesh portal (bridge integration) + +To connect the wireless mesh to a wired LAN, add the mesh interface to +a bridge: + +
admin@example:/config/> edit interface wifi-mesh
+admin@example:/config/interface/wifi-mesh/> set bridge-port bridge br0
+admin@example:/config/interface/wifi-mesh/> leave
+
+ +### Mesh with roaming APs + +You can combine 802.11s mesh backhaul with roaming-enabled access +points. Each node has a mesh interface for backhaul on one radio and +AP interfaces for clients on another: + +![802.11s mesh backhaul with roaming-enabled access points](img/wifi-mesh-roaming.svg) + +With 802.11r/k/v roaming enabled on the APs (same SSID, same +passphrase, same mobility domain), clients hand off between nodes while +the mesh carries backhaul traffic. + ## Troubleshooting Use `show interface wifi0` to verify signal strength and connection status.