Document mesh and roaming

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**

doc/wifi.md

@@ -144,7 +144,7 @@ admin@example:/config/hardware/component/radio0/wifi-radio/> <b>leave</b>
 **Key radio parameters:**
 
 - `country-code`: Two-letter [ISO 3166-1 alpha-2][1] code, determines allowed
-  channels and maximum power. Examples: US, DE, GB, SE, FR, JP.  
+  channels and maximum power. Examples: US, DE, GB, SE, FR, JP.
   **⚠ Must match your physical location for legal compliance! ⚠**
 - `band`: 2.4GHz, 5GHz, or 6GHz (required for AP mode). Automatically enables
   appropriate WiFi standards:
@@ -265,7 +265,7 @@ hardware, your passphrase must meet the following criteria:
 > [!TIP] Why the limit?
 > Standard WiFi security (WPA2/WPA3) requires a minimum of 8 characters to
 > prevent "brute-force" hacking.  The character limit ensures your password
-> works on older routers and various operating systems.  
+> works on older routers and various operating systems.
 > Tips for password strength, see [XKCD #936](https://xkcd.com/936/).
 
 ## Station Mode (Client)
@@ -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:
 
 `<interface-name>-<hostname>.<mobility-domain>`
 
@@ -581,20 +585,130 @@ 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 three 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)
+- **Mesh Gate** - a mesh node that advertises external connectivity so
+  other nodes proactively maintain a path toward it
+
+In practice, a node bridging the mesh interface to a LAN is a mesh
+portal, and enabling `gate-announcements` on it makes it a mesh gate.
+
+> [!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 <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**
 
 <pre class="cli"><code>admin@example:/> <b>configure</b>
-admin@example:/config/> <b>edit interface br0</b>
-admin@example:/config/interface/br0/> <b>set type bridge</b>
-
-admin@example:/config/> <b>edit interface wifi0</b>
-admin@example:/config/interface/wifi0/> <b>set bridge-port bridge br0</b>
-admin@example:/config/interface/wifi0/> <b>leave</b>
+admin@example:/config/> <b>edit hardware component radio1 wifi-radio</b>
+admin@example:/config/hardware/component/radio1/wifi-radio/> <b>set country-code DE</b>
+admin@example:/config/hardware/component/radio1/wifi-radio/> <b>set band 5GHz</b>
+admin@example:/config/hardware/component/radio1/wifi-radio/> <b>set channel 36</b>
+admin@example:/config/hardware/component/radio1/wifi-radio/> <b>leave</b>
 </code></pre>
 
+**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:
+
+<pre class="cli"><code>admin@example:/> <b>configure</b>
+admin@example:/config/> <b>edit keystore symmetric-key mesh-secret</b>
+admin@example:/config/keystore/…/mesh-secret/> <b>set key-format passphrase-key-format</b>
+admin@example:/config/keystore/…/mesh-secret/> <b>change cleartext-symmetric-key</b>
+Passphrase: ************
+Retype passphrase: ************
+admin@example:/config/keystore/…/mesh-secret/> <b>end</b>
+</code></pre>
+
+**Step 3: Configure the mesh interface**
+
+<pre class="cli"><code>admin@example:/config/> <b>edit interface wifi-mesh</b>
+admin@example:/config/interface/wifi-mesh/> <b>set type wifi</b>
+admin@example:/config/interface/wifi-mesh/> <b>set wifi radio radio1</b>
+admin@example:/config/interface/wifi-mesh/> <b>set wifi mesh-point mesh-id my-mesh</b>
+admin@example:/config/interface/wifi-mesh/> <b>set wifi mesh-point security secret mesh-secret</b>
+admin@example:/config/interface/wifi-mesh/> <b>leave</b>
+</code></pre>
+
+**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
+- `gate-announcements`: Advertise this node as a mesh gate (default:
+  false).  Enable on nodes with a wired uplink
+- `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:
+
+<pre class="cli"><code>admin@example:/config/> <b>edit interface wifi-mesh</b>
+admin@example:/config/interface/wifi-mesh/> <b>set bridge-port bridge br0</b>
+admin@example:/config/interface/wifi-mesh/> <b>set wifi mesh-point gate-announcements true</b>
+admin@example:/config/interface/wifi-mesh/> <b>leave</b>
+</code></pre>
+
+With `gate-announcements` enabled, the node sends GANN (Gate
+Announcement) frames so other mesh nodes maintain a path toward it.
+
+### 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:
+
+```
+[Internet]
+    |
+[Node A: mesh + AP]----mesh----[Node B: mesh + AP]----mesh----[Node C: mesh + AP]
+    |                               |                              |
+  bridge (br0)                   bridge (br0)                   bridge (br0)
+    |                               |                              |
+  clients                         clients                        clients
+```
+
+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.