fips/docs/how-to/set-up-80211s-mesh-backhaul.md

Set Up an 802.11s Mesh Backhaul (OpenWrt)

Link FIPS routers over radio — no cables, no APs, no shared infrastructure — by running the Ethernet transport on an open 802.11s mesh interface. The radio layer provides nothing but L2 frames to direct neighbors; FIPS provides everything else: encryption and authentication (Noise IK), peer discovery (Ethernet beacons), and routing (the spanning tree).

For the transport design, see ../design/fips-transport-layer.md. For all transports.ethernet.* configuration keys, see ../reference/configuration.md.

Why open, why forwarding off

Two deliberate choices distinguish this from a stock 802.11s setup:

• encryption none — the mesh is open on purpose. Every FIPS peer link is already authenticated and encrypted by the Noise IK handshake, so SAE at L2 would duplicate that work, add a shared credential to provision across routers, and (on ath10k) force the firmware into its slower raw Tx/Rx mode. A stranger can form an 802.11s peering with your router and a FIPS peer link on top of it — the same open model as mDNS and BLE discovery, where the advert is only a hint and the handshake authenticates each link (no impersonation, no MITM) rather than gating who may peer. Admission is open up to the daemon's max-peers cap. What you concede: any nearby radio can peer and reach the FIPS overlay surface; L2 metadata (MAC addresses, frame sizes) is visible in the air; a hostile radio can burn airtime — all inherent to an open radio link.
• mesh_fwding 0 — disables 802.11s's own HWMP routing so each mesh link is a plain neighbor link. FIPS is the routing layer; two routing layers would fight, and broadcast discovery beacons would flood the whole mesh instead of reaching direct neighbors only.

The interface is not bridged into br-lan — the FIPS Ethernet transport binds it directly.

When to use

• Two or more OpenWrt FIPS routers within radio range of each other, where running cable is impractical.
• You want the mesh segment to keep working with zero shared credentials or per-site configuration ("flash and drop in").

It is not for connecting phones or laptops — client devices cannot join an 802.11s mesh. They enter the mesh through a normal AP on the same router (see constraints below), or over BLE.

Requirements

• OpenWrt 22.03+ with the FIPS package installed.

• A radio whose driver supports mesh point interfaces. Check with:

  iw list | grep -A 10 "Supported interface modes" | grep "mesh point"
  

  The mainstream OpenWrt chips (ath9k, ath10k, mt76) all qualify.

• Ideally a dual- or tri-band router, so one band can be dedicated to the backhaul (see constraints).

Step 1 — create the mesh interface(s)

On each router, run the helper once per radio you want in the backhaul:

fips-mesh-setup radio1

This creates an open 802.11s interface with mesh ID fips-mesh and HWMP forwarding off, attaches it to an unmanaged netifd interface (no IP configuration — none is needed), and reloads the radio. It does not touch /etc/fips/fips.yaml: the matching meshN transport ships enabled and the daemon binds the interface once it exists (see Step 2). Interfaces are named by radio index: radio0 → fips-mesh0, radio1 → fips-mesh1. Pass a second argument to use a different mesh ID.

Note: the helper runs wifi reload, which re-applies the whole wireless config and so briefly drops every client AP on all radios for a few seconds. fips-mesh-setup remove reloads the same way. Expect the blip if clients are connected.

On dual-band routers, meshing both bands is worth it: 2.4 GHz reaches further at lower rates, 5 GHz carries more over shorter links. Note this is failover, not multipath: FIPS keeps one active link per peer, so traffic uses one band at a time — the other is a standby that re-establishes the peer if the active link dies (detection via keepalive timeout, so a cutover takes seconds, not milliseconds):

fips-mesh-setup radio0
fips-mesh-setup radio1

Pin the same channel on every backhaul router, per band. Mesh points only peer on the same channel, and the mesh inherits whatever the radio is set to — with channel 'auto' (the default on many devices) each router picks its own and the mesh silently never forms. The script prints the radio's current band and channel and warns on auto:

uci set wireless.radio1.channel='36'
uci commit wireless && wifi reload

Prefer a non-DFS channel (36–48 on 5 GHz): on DFS channels the radio must wait ~60 s in CAC before transmitting after every reload.

Equivalent manual UCI (per radio), if you prefer to see what it does:

uci batch <<'EOF'
set wireless.fips_mesh_radio1=wifi-iface
set wireless.fips_mesh_radio1.device='radio1'
set wireless.fips_mesh_radio1.mode='mesh'
set wireless.fips_mesh_radio1.mesh_id='fips-mesh'
set wireless.fips_mesh_radio1.encryption='none'
set wireless.fips_mesh_radio1.mesh_fwding='0'
set wireless.fips_mesh_radio1.ifname='fips-mesh1'
set wireless.fips_mesh_radio1.network='fips_mesh_radio1'
set network.fips_mesh_radio1=interface
set network.fips_mesh_radio1.proto='none'
EOF
uci commit
wifi reload

Step 2 — check the FIPS transport binding

The fips.yaml shipped in the OpenWrt package carries one transport entry per radio, enabled and marked optional: true. The daemon treats a named interface that is not there as absent rather than as a failure, and optional: true is what keeps a stock install that never runs this helper quiet and un-Degraded about a radio it was never going to have. There is normally nothing to do here. If you maintain your own config (or ran the manual UCI above instead of the helper), make sure the entries are present:

transports:
  ethernet:
    mesh0:
      interface: "fips-mesh0"
      optional: true
      listen: true
      announce: true
      auto_connect: true
      accept_connections: true
    mesh1:
      interface: "fips-mesh1"
      listen: true
      announce: true
      auto_connect: true
      accept_connections: true

listen: was called discovery: before v0.5.0; the old spelling still parses as an alias, so an existing config keeps working (see ../reference/configuration.md).

Step 3 — no restart needed

The daemon binds an interface when it appears. A transport whose interface is missing is absent, not skipped: it waits, binds within a second of the interface coming up, unbinds if it goes away, and rebinds when it returns. Order does not matter, and neither /etc/init.d/fips restart nor any hotplug rule is part of this procedure.

Watch it happen:

fipsctl show transports

The transport's interface block reports presence (absent / binding / present), policy (required / optional) and how long it has held that state.

If you changed a config value above rather than only creating an interface, that does need a restart — configuration is read at startup, interfaces are not:

/etc/init.d/fips restart

Verify

L2 first — the 802.11s peering, with a second configured router in range:

iw dev fips-mesh0 station dump

You should see one station entry per neighbor router, with signal levels. No entries means a radio problem, not a FIPS problem — triage in this order:

1. Channel mismatch (the most common cause): compare iw dev fips-mesh0 info on both routers — mesh ID and channel must match exactly.

2. The mesh interface never joined — iw dev fips-meshX info shows type mesh point but no channel line, and station dump is empty. Usual cause: a client (sta) interface on the same radio. A STA must follow its upstream AP's channel, the whole radio follows the STA, and a mesh pinned to a different channel silently stays down. Check for a STA sharing the radio (iw dev, look for type managed on the same phy), compare iw dev <sta-iface> info | grep channel, and re-pin the mesh channel to match — on every backhaul router.

3. Is the other router transmitting at all?

   iw dev fips-mesh0 scan | grep -i -B4 "MESH ID"
   

   Its mesh ID visible → transmission works, peering is failing (mesh ID typo, or one side has encryption set). Nothing visible → check wifi status on the other router, remember the ~60 s DFS CAC wait, and confirm the country code is set (uci get wireless.radio1.country) — an unset regdomain can block channels entirely.

4. logread | grep -iE "mesh|fips-mesh0" on both sides.

Then the FIPS layer on top:

logread | grep -i beacon        # beacons flowing on the new transport
fipsctl show peers              # neighbor authenticated and connected
fipsctl show links              # link on the 'ethernet' transport

Discovery is automatic: each node beacons its pubkey every few seconds, and auto_connect initiates the Noise handshake on first sight.

Constraints

• Airtime is shared per radio. All virtual interfaces on one radio (AP + mesh) share one channel, and multi-hop forwarding on a single radio roughly halves throughput per hop. On dual/tri-band hardware, dedicate one band to fips-mesh0 and serve clients on the others.
• AP + mesh coexistence is driver-dependent. It works on the mainstream chips (this is the standard Freifunk/Gluon setup), but check iw list under "valid interface combinations" for your hardware.
• Clients can't join. Phones and laptops reach the mesh through the router's normal AP or via BLE — never through the 802.11s interface.
• Radio links are lossy. A neighbor at the edge of range will form an 802.11s peering yet deliver a fraction of its frames. Expect link-quality effects that don't exist on wired Ethernet.
• A client (STA) uplink on the same radio owns the channel. The STA must follow whatever channel its upstream AP uses; every other interface on that radio follows the STA. A mesh pinned to a different channel silently never joins, and it does not recover when the STA disconnects — a wifi reload (plus a fips restart) is needed. A roaming uplink (travel-router / hotspot-chasing setups) is fundamentally incompatible with a fixed-channel mesh on the same radio: dedicate the mesh to the radio the STA never uses, and treat any mesh sharing a STA radio as best-effort.