openwrt/CLAUDE.md

OpenWRT Router Management

Hardware

Primary router:

• Device: TP-Link Archer AX23 v1
• OpenWRT: 24.10.2 (ramips/mt7621)
• Router IP: 10.0.0.1
• SSH: ssh openwrt
• No USB port — no USB WAN option

WAN failover device:

• Device: GL-XE300 (Puli)
• Firmware: GL.iNet 4.3.27 (OpenWRT 22.03.4)
• Current IP: 192.168.8.1 (to be changed to 10.0.100.1 before wiring in)
• SSH: ssh openwrtwan

Repository Layout

config/      UCI config files pulled from /etc/config/ on the router
scripts/     Backup, push, and safe-apply helpers
docs/        Network map, VLAN plan, change log

Workflow Rules

1. Never edit the router directly for anything non-trivial. Edit config/ files here, then push.
2. All network/firewall/wireless changes go through safe-apply.sh — it sets an auto-revert so a bad config can't permanently lock us out.
3. Run backup.sh before starting any work session to ensure config/ reflects the current router state.
4. Commit after every successful change. The git log is the change history.

Scripts

scripts/backup.sh              # Pull config from router → config/, prompt to commit
scripts/safe-apply.sh <name>   # Push one config file with auto-revert safety net
scripts/push-all.sh            # Push all configs (low-risk bulk changes only)

Safe-Apply Pattern

# Edit config/network in this repo, then:
./scripts/safe-apply.sh network 5   # 5-minute auto-revert window
# Test connectivity — if working, confirm at the prompt

Config Files

File	Controls
network	Interfaces, VLANs, WAN, bridges
wireless	SSIDs, radios, encryption
firewall	Zones, rules, forwarding, NAT
dhcp	DHCP pools, static leases, DNS
system	Hostname, timezone, logging
dropbear	SSH daemon

Network Overview

See docs/network-map.md for full topology, IP allocations, and device inventory.

Planned Features (not yet implemented)

• VLAN segmentation (trusted / servers / IoT / guest)
• Multiple SSIDs mapped to VLANs
• Failover WAN via ethernet-connected 4G device