From d0b4fae25e8915d0e0ee6d201bcf99ad30298e37 Mon Sep 17 00:00:00 2001 From: jazzymc Date: Thu, 12 Mar 2026 16:18:40 +0200 Subject: [PATCH] WiFi troubleshooting guide, fix empty security overrides, update config docs Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 1 + docs/07-WIFI-CAPSMAN-CONFIG.md | 19 +-- docs/12-WIFI-TROUBLESHOOTING.md | 237 ++++++++++++++++++++++++++++++++ docs/CHANGELOG.md | 16 +++ 4 files changed, 265 insertions(+), 8 deletions(-) create mode 100644 docs/12-WIFI-TROUBLESHOOTING.md diff --git a/CLAUDE.md b/CLAUDE.md index addc811..1ac5271 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,6 +68,7 @@ infrastructure/ ├── 08-DNS-ARCHITECTURE.md # DNS failover architecture ├── 09-TAILSCALE-VPN.md # Tailscale VPN setup ├── 10-FAILOVER-NOBARA.md # VRRP failover to Nobara + ├── 12-WIFI-TROUBLESHOOTING.md # WiFi/CAPsMAN troubleshooting guide ├── CHANGELOG.md # Change history ├── archive/ # Completed/legacy docs │ └── vlan-migration/ # VLAN migration project artifacts diff --git a/docs/07-WIFI-CAPSMAN-CONFIG.md b/docs/07-WIFI-CAPSMAN-CONFIG.md index d1833a9..5096e30 100644 --- a/docs/07-WIFI-CAPSMAN-CONFIG.md +++ b/docs/07-WIFI-CAPSMAN-CONFIG.md @@ -1,6 +1,6 @@ # WiFi and CAPsMAN Configuration -**Last Updated:** 2026-02-26 +**Last Updated:** 2026-03-12 **Purpose:** Document WiFi network settings, CAPsMAN configuration, and device compatibility requirements --- @@ -23,11 +23,12 @@ | SSID | XTRM | | Band | 5GHz | | Mode | 802.11ax (WiFi 6) | -| Channel | 5180 MHz (ch 36) | -| Width | 40MHz | +| Channel | 5745 MHz (ch 149) | +| Width | 20/40/80MHz | | Security | WPA2-PSK + WPA3-PSK | | Cipher | CCMP (AES) | -| 802.11r (FT) | Enabled | +| 802.11r (FT) | Disabled | +| Skip DFS | All | | Password | `M0stW4nt3d@home` | --- @@ -44,12 +45,14 @@ Some devices (Tuya JMWZG1 gateway, Amazfit TREX3, iPad 2) require legacy setting |---------|-------|--------| | SSID | XTRM2 | | | Band | 2.4GHz | IoT compatibility | -| Mode | **802.11g** | Legacy device support | +| Mode | **802.11g** | Legacy device support (NOT 802.11n — breaks IoT) | | Channel | **1 (2412 MHz)** | Most compatible | | Width | **20MHz** | Required for old devices | | Security | **WPA-PSK + WPA2-PSK** | WPA needed for legacy | | Cipher | **TKIP + CCMP** | TKIP required for old devices | | 802.11r (FT) | **Disabled** | Causes issues with IoT | + +**CRITICAL:** Security must be set explicitly on the interface, not just the profile. Empty `security.authentication-types=""` means OPEN network, not "inherit from profile." See [12-WIFI-TROUBLESHOOTING.md](12-WIFI-TROUBLESHOOTING.md). | Password | `M0stW4nt3d@IoT` | | ### Devices Requiring WPA + TKIP @@ -140,10 +143,10 @@ The CAP runs bridge VLAN filtering to properly tag/untag WiFi client traffic bef | Interface | Radio | Band | SSID | Security | Status | |-----------|-------|------|------|----------|--------| -| cap-wifi1 | wifi2 | 5GHz | XTRM | WPA2/WPA3-PSK, CCMP | Working (Ch 52/5260, 40MHz, DFS) | -| cap-wifi2 | wifi1 | 2.4GHz | XTRM2 | WPA2-PSK, CCMP | Working (Ch 6/2437, 20MHz) | +| cap-wifi1 | MAC :BE | 2.4GHz | XTRM2 | WPA+WPA2, TKIP+CCMP | Working (Ch 13/2472, 20MHz, 802.11g) | +| cap-wifi2 | MAC :BF | 5GHz | XTRM | WPA2/WPA3-PSK, CCMP | Working (Ch 36/5180, 20/40/80MHz, 802.11ac) | -**Note:** cap-wifi2 uses WPA2+CCMP only (not WPA+TKIP like HAP's local wifi2). Legacy IoT devices requiring TKIP will only work on HAP1's local wifi2. +**Note:** CAP radios swapped after CAPsMAN re-provisioning. Identify by MAC address, not interface name. See [12-WIFI-TROUBLESHOOTING.md](12-WIFI-TROUBLESHOOTING.md) for re-provisioning procedures. --- diff --git a/docs/12-WIFI-TROUBLESHOOTING.md b/docs/12-WIFI-TROUBLESHOOTING.md new file mode 100644 index 0000000..5e3d54f --- /dev/null +++ b/docs/12-WIFI-TROUBLESHOOTING.md @@ -0,0 +1,237 @@ +# WiFi / CAPsMAN Troubleshooting Guide + +**Last Updated:** 2026-03-12 +**Purpose:** Document known pitfalls, root causes, and diagnostic procedures for WiFi and CAPsMAN issues on the MikroTik HAP ax³ + cAP XL ac setup. + +--- + +## Pitfall 1: Empty Inline Security Overrides = Open Network + +**Severity:** CRITICAL + +**Problem:** Setting `security.authentication-types=""` on a WiFi interface does NOT mean "inherit from security profile." RouterOS interprets an empty string as **no authentication (open network)**. + +**Symptoms:** +- Devices connect but show empty AUTH-TYPE in registration table +- IoT devices that try WPA/WPA2 handshake silently fail — router logs show ZERO connection attempts +- Other devices connect fine (they accept open) + +**Root Cause:** Attempting to "clear inline overrides" to inherit from the security profile by setting empty values. RouterOS treats empty string as explicit "no auth." + +**Fix:** +```routeros +# Always set explicit values on the interface +/interface wifi set wifi2 \ + security.authentication-types=wpa-psk,wpa2-psk \ + security.encryption=tkip,ccmp +``` + +**Rule:** NEVER set `security.authentication-types=""` or `security.encryption=""`. Always use explicit values matching the security profile. + +--- + +## Pitfall 2: CAPsMAN Re-Provisioning Wipes Interface Config + +**Severity:** HIGH + +**Problem:** Running `/interface wifi capsman remote-cap provision` clears all configuration from cap-wifi interfaces — security, channel, datapath, and SSID are all removed. Interfaces show "SSID not set" and remain inactive. + +**Fix:** After re-provisioning, manually re-apply full config: +```routeros +# 2.4GHz (cap-wifi1 = MAC :BE = 2.4GHz radio) +/interface wifi set cap-wifi1 \ + configuration=cfg-xtrm2 security=sec-xtrm2 datapath=dp-cap \ + channel.frequency=2472 channel.band=2ghz-g channel.width=20mhz + +# 5GHz (cap-wifi2 = MAC :BF = 5GHz radio) +/interface wifi set cap-wifi2 \ + configuration=cfg-xtrm security=sec-xtrm datapath=dp-cap \ + channel.frequency=5180 channel.band=5ghz-ac \ + channel.width=20/40/80mhz channel.skip-dfs-channels=all + +# Re-enable both +/interface wifi enable cap-wifi1 +/interface wifi enable cap-wifi2 +``` + +--- + +## Pitfall 3: Interface IDs Change After Re-Provisioning + +**Severity:** HIGH + +**Problem:** After CAPsMAN re-provisioning, cap-wifi interface internal IDs change (e.g., `*20`/`*21` become `*22`/`*23`). Access-list rules referencing old IDs stop matching. + +**Symptom:** `client was disconnected because could not assign vlan` error on CAP interfaces. + +**Fix:** +```routeros +# Check current IDs +:foreach i in=[/interface wifi find where name~"cap"] do={ + :put ([/interface wifi get $i name] . " = " . $i) +} + +# Update access-list rules +/interface wifi access-list set [find where interface=*OLD] interface=*NEW +``` + +**Best practice:** Don't use CAP-specific access-list rules. Let all clients (HAP and CAP) use the same MAC-based access list. The HAP handles VLAN assignment uniformly via CAPsMAN. + +--- + +## Pitfall 4: CAP Radio-to-Interface Mapping Swap + +**Severity:** MEDIUM + +**Problem:** After re-provisioning, `cap-wifi1` and `cap-wifi2` may swap which physical radio they map to. Assigning 5GHz config to the 2.4GHz radio (or vice versa) causes "no available channels" error. + +**Identification:** Check MAC addresses: + +| MAC suffix | Radio | Must receive | +|------------|-------|--------------| +| :BE | 2.4GHz | 2.4GHz config (XTRM2) | +| :BF | 5GHz | 5GHz config (XTRM) | + +**Fix:** Match config to the correct radio MAC, not the interface name. + +--- + +## Pitfall 5: CAP Band Must Be AC, Not AX + +**Severity:** MEDIUM + +**Problem:** The cAP XL ac only supports 802.11ac. Setting band to `5ghz-ax` results in the radio not starting. + +**Fix:** Always use `5ghz-ac` for the CAP 5GHz channel configuration. + +--- + +## Pitfall 6: IoT Devices Need Legacy WiFi Settings + +**Severity:** HIGH + +**Problem:** Many IoT devices (vacuums, smart gateways, ovens) require legacy WiFi settings to connect. Using 802.11n-only or WPA2-only silently prevents connections — the router sees zero attempts. + +**Required XTRM2 (2.4GHz) settings:** + +| Setting | Value | Reason | +|---------|-------|--------| +| Band | `2ghz-g` | NOT `2ghz-n` — IoT devices may only support 802.11g | +| Auth | `wpa-psk,wpa2-psk` | Some devices need WPA1 available | +| Encryption | `tkip,ccmp` | Some devices need TKIP | +| Channel width | `20mhz` | Maximum compatibility | +| FT (802.11r) | Disabled | Causes issues with IoT | + +**Known devices requiring legacy support:** +- Roborock S7 Vacuum (B0:4A:39:3F:9A:14) +- Tuya Smart Gateway JMWZG1 (38:1F:8D:04:6F:E4) +- Bosch Oven (94:27:70:1E:0C:EE) +- Various other IoT appliances + +--- + +## 5GHz Channel Separation + +HAP and CAP must use different 5GHz channels to avoid co-channel interference: + +| Device | Channel | Frequency | Band | +|--------|---------|-----------|------| +| HAP wifi1 | 149 | 5745 MHz | 5ghz-ax | +| CAP cap-wifi2 | 36 | 5180 MHz | 5ghz-ac | + +Both use `skip-dfs-channels=all` to avoid radar detection disconnects. + +--- + +## Diagnostic Checklist + +When devices can't connect to WiFi, check in this order: + +### Step 1: Check Security (Most Common Issue) +```routeros +# Check if AUTH-TYPE is empty in registration table (= open network!) +/interface wifi registration-table print + +# Check inline security overrides +:put [/interface wifi get wifi2 security.authentication-types] +:put [/interface wifi get wifi2 security.encryption] +# If empty → security is broken, set explicit values +``` + +### Step 2: Check Band Compatibility +```routeros +/interface wifi monitor wifi2 once +# If channel shows /n → change to /g for IoT compatibility +``` + +### Step 3: Enable Debug Logging +```routeros +/system logging add topics=wireless,debug action=memory +# Then check: /log print where topics~"wireless" +``` + +### Step 4: Check CAP Interface IDs +```routeros +# Verify access-list rules reference current IDs +:foreach i in=[/interface wifi find where name~"cap"] do={ + :put ([/interface wifi get $i name] . " = " . $i) +} +/interface wifi access-list print where interface~"\\*" +``` + +### Step 5: Check Radio-MAC Mapping +```routeros +# Verify cap interfaces are assigned to correct radios +/interface wifi print where name~"cap" proplist=name,mac-address,channel.band +``` + +### Step 6: If Router Sees ZERO Attempts +This means: +- **Security mismatch** — device won't even try (most likely empty auth = open) +- **Band incompatibility** — 802.11n-only blocks 802.11g devices +- **Device-side issue** — power cycle device, re-do WiFi setup from scratch + +--- + +## Quick Recovery Commands + +### Restore XTRM2 (2.4GHz) to known working state +```routeros +/interface wifi security set sec-xtrm2 \ + authentication-types=wpa-psk,wpa2-psk encryption=tkip,ccmp + +/interface wifi set wifi2 \ + security.authentication-types=wpa-psk,wpa2-psk \ + security.encryption=tkip,ccmp \ + security.ft=no security.ft-over-ds=no + +/interface wifi channel set ch-2g-hap \ + frequency=2412 band=2ghz-g width=20mhz +``` + +### Restore XTRM (5GHz) to known working state +```routeros +/interface wifi security set sec-xtrm \ + authentication-types=wpa2-psk,wpa3-psk encryption=ccmp + +/interface wifi set wifi1 \ + security.authentication-types=wpa2-psk,wpa3-psk \ + security.encryption=ccmp \ + security.ft=no security.ft-over-ds=no + +/interface wifi channel set ch-5g-hap \ + frequency=5745 band=5ghz-ax width=20/40/80mhz skip-dfs-channels=all +``` + +### Restore CAP interfaces after re-provisioning +```routeros +/interface wifi set cap-wifi1 \ + configuration=cfg-xtrm2 security=sec-xtrm2 datapath=dp-cap \ + channel.frequency=2472 channel.band=2ghz-g channel.width=20mhz +/interface wifi set cap-wifi2 \ + configuration=cfg-xtrm security=sec-xtrm datapath=dp-cap \ + channel.frequency=5180 channel.band=5ghz-ac \ + channel.width=20/40/80mhz channel.skip-dfs-channels=all +/interface wifi enable cap-wifi1 +/interface wifi enable cap-wifi2 +``` diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 6d3b6fe..b79e276 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,6 +2,22 @@ **Purpose:** Major infrastructure events only. Minor changes are in git commit messages. +--- +## 2026-03-12 + +### WiFi Optimization & Troubleshooting +- **[WIFI]** Moved HAP 5GHz from ch 36 (5180) to ch 149 (5745), skip-dfs-channels=all +- **[WIFI]** Moved CAP 5GHz from ch 52 (5260) to ch 36 (5180), band corrected from ax to ac +- **[WIFI]** Separated HAP/CAP 5GHz channels to avoid co-channel interference +- **[WIFI]** Fixed sec-xtrm2 security: WPA+WPA2 with TKIP+CCMP for IoT compatibility +- **[WIFI]** Fixed critical bug: empty inline security.authentication-types="" caused wifi2 to run as open network — IoT devices silently failed to connect +- **[WIFI]** Set explicit encryption on all interfaces and security profiles (never leave empty) +- **[WIFI]** Removed CAP-specific access-list catch-all rules — all clients now use unified MAC-based access list +- **[WIFI]** Fixed CAP interface IDs in access-list after re-provisioning (*20/*21 → *22/*23) +- **[WIFI]** Restored 2.4GHz band to 2ghz-g (was changed to 2ghz-n, breaking IoT devices) +- **[WIFI]** Disabled FT (802.11r) on wifi1 (5GHz) for stability +- **[DOCS]** Added 12-WIFI-TROUBLESHOOTING.md with diagnostic checklist and recovery commands + --- ## 2026-02-28