# Openwrt Network Topology

> OpenWrt bridge ordering and WAN detection patterns. Use when managing Proxmox bridges, configuring WAN/LAN interfaces, or debugging OpenWrt network topology issues.

- Skill: `krmorehead/openwrt-network-topology` (Agent Skill)
- Install (CLI): `npx skillmds@latest add krmorehead/openwrt-network-topology`
- Raw SKILL.md: https://api.skillmd.com/api/skills/krmorehead/openwrt-network-topology/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: krmorehead (https://skillmd.com/u/krmorehead)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/krmorehead/openwrt-network-topology

---


# OpenWrt Network Topology Rules

## Bridge Assignment Rules

1. OpenWrt gets ALL bridges: WAN on `net0`/`eth0`, remaining bridges as LAN ports. Most other VMs need only ONE LAN bridge.
2. The WAN bridge is auto-detected by `proxmox_bridges` via the host's default route. NEVER hardcode a bridge as WAN. Override with `openwrt_wan_bridge` in `host_vars` only if auto-detection fails.
3. Order bridges so WAN is always `net0`/`eth0`:
   ```yaml
   _ordered_bridges: [_wan_bridge] + (proxmox_all_bridges | difference([_wan_bridge]) | sort)
   ```

## Bridge Ordering Bug Prevention

4. Previous bug: alphabetical bridge sorting made `vmbr0` always WAN. When the modem was on `vmbr0`, the Proxmox GUI became unreachable from LAN nodes.
5. NEVER sort bridges alphabetically. Always use explicit ordering with WAN first.

## Auto-Subnet Selection

6. To avoid collisions between WAN subnet and OpenWrt LAN subnet:
   - Detect upstream gateway prefix from Proxmox host's default route
   - Pass it to OpenWrt via `add_host` as `upstream_wan_prefix`
   - Iterate `openwrt_lan_subnet_candidates` and pick first whose prefix differs from WAN

## Proxmox Management IP

7. When OpenWrt is primary router, Proxmox host needs predictable IP on LAN bridge:
   - Compute LAN IP from OpenWrt's LAN subnet + offset (default `.2`)
   - `ip addr add` on LAN bridge (immediate, current session)
   - Upgrade LAN bridge in `ansible-bridges.conf` from `inet manual` to `inet dhcp`
   - Add DHCP static reservation mapping Proxmox host's LAN bridge MAC to computed IP
   - On reboot: DHCP client requests IP, OpenWrt assigns reserved one

8. NEVER use separate config file with `iface <bridge> inet dhcp`. It conflicts with `inet manual` stanza in bridges config.

9. NEVER leave stale IPs on non-LAN bridges in same subnet as LAN bridge. Two routes for same /24 on different bridges causes kernel to use wrong interface, breaking LAN VM connectivity.

## Bootstrap Connectivity Pattern

10. To reach OpenWrt at default `192.168.1.1` during initial setup:
    - Add temporary IP (`192.168.1.2`) to WAN bridge on Proxmox
    - SSH through ProxyJump via Proxmox host
    - After Phase 1 network restart, OpenWrt's LAN moves to non-WAN bridges
    - Remove bootstrap IP from WAN bridge, add to LAN bridge
    - After Phase 2, clean up bootstrap IP entirely

11. Previous bug: excluded `vmbr0` and tried connecting through `vmbr1` (which had no IP in OpenWrt's default config).

12. On re-runs (VM already configured), the bootstrap IP `192.168.1.1` no longer exists — the VM's LAN is on 10.10.10.1. The `openwrt_vm` role MUST probe the configured LAN IP first and skip bootstrap if reachable.

13. OpenWrt LXC containers (bridge, mesh) boot with the default LAN IP 192.168.1.1 on br-lan. On WAN-bridged hosts, this IP is on the same L2 segment as the router VM's bootstrap target. The bridge LXC role MUST override the default LAN IP to the Proxmox-assigned container IP during provisioning.

14. Previous bug: Bridge LXC containers on bridge-1 and bridge-2 had 192.168.1.1 on the WAN bridge. When the openwrt_vm role added 192.168.1.2/24 to vmbr0 and SSHed to 192.168.1.1, it connected to the bridge container (1 eth interface) instead of the VM (3 interfaces). The configure role then failed with "No LAN devices found."