| name | openwrt-mac-conflict |
| description | OpenWrt WAN MAC address conflict detection and deferred application. Use when managing MAC addresses, cloning WAN MACs, or debugging network connectivity issues. |
OpenWrt MAC Conflict Detection Rules
MAC Application Process
-
The WAN_MAC env variable is optional. NEVER apply it at the Proxmox NIC level during VM creation (qm set --net0 macaddr=...). ALWAYS go through the MAC conflict detection flow during the final configure phase.
-
If no conflict is detected, apply via UCI (uci set network.wan.macaddr). If a conflict IS detected, defer the MAC to /etc/openwrt_wan_mac_deferred on the VM. An init script auto-applies it on next boot when conflict is gone.
Three-Layer Conflict Detection
- Before applying a cloned WAN MAC, run a three-layer conflict check:
Layer 1: Exact MAC in ARP table (/proc/net/arp): catches direct L2 duplicates
Layer 2: EUI-64 in IPv6 neighbor table (ip -6 neigh): catches SLAAC address collisions where MAC itself isn't visible but its derived IPv6 address is
Layer 3: Gateway OUI match: if the WAN gateway's MAC shares the first 3 bytes (OUI) with the cloned MAC, the devices are almost certainly from the same router — a conflict waiting to happen
- If any check triggers, save MAC to
/etc/openwrt_wan_mac_deferred and NOT apply to UCI. Deploy /etc/init.d/wan_mac_apply — an OpenWrt init script (START=99) that runs on every boot.
Deferred MAC Application
-
The init script re-runs the same three-layer conflict detection and, if conflict is gone (old router removed), applies the MAC via UCI and restarts network automatically. No manual intervention required.
-
The deferred file is cleaned at start of each run (rm -f) for idempotency. VM destruction during cleanup also removes it. The init script self-cleans by removing deferred file after applying MAC.
MAC Conflict Bug Prevention
-
Duplicate MAC addresses on same L2 segment cause IPv6 DAD failures, corrupt uclient/libubox state, and cause wget/opkg segfaults — even when ICMP ping works.
-
Consumer routers use sequential MACs across ports — the WAN MAC and LAN MAC often share same OUI and differ by ±1 in last byte.
-
Previous bug: WAN MAC 08:B4:B1:1A:63:08 was applied while old router (LAN MAC 08:B4:B1:1A:63:09, same OUI) was still on segment. IPv6 SLAAC generated same global address → DAD failure → corrupted network stack → wget EPERM, opkg failures, DNS timeouts. ICMP still worked, making root cause non-obvious without dmesg diagnostics.
