From 30d67ebd4f81b3999a3731870046dd605dec8721 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Mar 2026 16:57:08 +0000 Subject: [PATCH] Overhaul README to reflect unified switch + OPNsense management MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tool now actively manages OPNsense alongside the switch. Updated: - Title: "Switch + OPNsense Network Manager" - Description: mentions VLANs, firewall, DHCP, DNS, VPN, backups - Tabs: updated from 8 to 17 with descriptions for all new tabs (Dashboard, Network, Firewall, Services, Port Fwd, PoE, Topology, Backups, Alerts) - OPNsense: changed from "optional/read-only" to core integration - VPN: OPNsense WireGuard as recommended, ControlD DNS auto-applied - "Does Not Do": removed "does not manage OPNsense" (it does now) - Files table: added 15 new config files (policies, services, backups, schedules, NAT rules, etc.) - Backup note: back up entire /etc/switch-manager/ directory - Endpoint count: 34 → ~60 - Component count: 8 tabs → 17 tabs, 38 components https://claude.ai/code/session_01Do9bsN39MTuy2GVv7yzSrE --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ab69859..1d89d5f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Avaya / Extreme ERS Switch Manager +# Avaya / Extreme ERS Switch + OPNsense Network Manager -A browser-based management interface for Avaya / Extreme Networks ERS switches. You click buttons. The software figures out the CLI. You never type a switch command. +A browser-based unified management interface for Avaya / Extreme Networks ERS switches and OPNsense routers. Manages VLANs, firewall policies, DHCP, DNS filtering, WireGuard VPN, port forwarding, service proxying, backups, and scheduling — across both devices from one place. You click buttons. The software figures out the CLI and API calls. You never type a switch command or log into the OPNsense GUI separately. Compatible with: ERS 5928, ERS 5948, ERS 5952, ERS 5952-PWR+, ERS 59100GTS-PWR+ @@ -261,7 +261,27 @@ sudo ip link set eth0.99 up --- -## The Interface — Eight Tabs +## The Interface — 17 Tabs + +### Dashboard + +Health overview showing switch and OPNsense connectivity, VLAN summary, and system status at a glance. + +### Network + +Unified VLAN provisioning — create a VLAN across both the switch and OPNsense in one operation. Select ports, set PoE per-port, auto-configure DHCP scope and firewall rules on OPNsense. Auto-backup before every change. + +### Firewall + +Inter-VLAN policy matrix — visual grid showing what each VLAN can reach. Click a cell to set the policy between two VLANs. Generates both switch ACLs and OPNsense firewall rules. Presets: Printer VLAN (one-way, other VLANs can print but printers can't reach out), IoT isolated (internet only), Guest isolated, Camera NVR-only, LAN-access-all. + +### Services + +Reverse proxy management for Caddy (running on a separate LAN services computer). Add services by FQDN and backend URL. Deploy writes the Caddyfile, verifies NAT reflection and WAN port forward on OPNsense. Isolated VLANs reach services via public FQDNs — NAT reflection handles it internally, no VLAN isolation broken. + +### Port Fwd + +OPNsense NAT port forwards for non-HTTP services (game servers, SSH, mail). For HTTP services, use the Services tab (Caddy handles routing by hostname on port 443). ### Port Map @@ -319,8 +339,8 @@ Unified view of all DHCP reservations across switch and OPNsense (if configured) - Use OPNsense for all other VLANs — integrates with DNS, firewall rules, lease history - Never run both for the same VLAN -**OPNsense integration (optional):** -Auto-detects OPNsense at your gateway IP. If found, prompts for API key. Once connected, shows reservations from both switch and OPNsense in one table, colour-coded by source. +**OPNsense integration:** +Auto-detects OPNsense at your gateway IP. Prompts for API key and SSH key. Once connected, the tool manages both devices together — VLANs, DHCP, firewall rules, port forwards, DNS, WireGuard, and backups. DHCP tab shows reservations from both switch and OPNsense in one table, colour-coded by source. **Conflict detection:** If the same MAC has reservations in both places, a badge appears — red for IP conflicts (same MAC, different IP), yellow for duplicates (same MAC, same IP). Each conflict has a Resolve button with four options: Switch wins, OPNsense wins, Remove from switch, Remove from OPNsense. @@ -353,19 +373,35 @@ Generates the `ctrld.toml` config and install command. You install wherever you ### VPN -Manages WireGuard VPN for remote access to the management interface from outside the management VLAN. +Manages WireGuard VPN on OPNsense (recommended) or locally on the management computer (fallback). -**Add clients:** Enter a name (laptop, phone, tablet) and the tool generates a keypair, adds the peer to the server config, reloads WireGuard live, and displays a QR code to scan with the WireGuard app. Also saves a `.conf` file for desktop import. +**OPNsense WireGuard (recommended):** Creates a WireGuard server on OPNsense via plugin API. Peers select which VLANs they can access — OPNsense routes between the tunnel and VLANs per firewall rules. VLAN isolation preserved. ControlD DNS profiles auto-applied via ctrld — when you select a VLAN for a peer, the DNS profile is auto-set to match. -**Revoke clients:** Disconnects the peer immediately and removes it from the server config. +**Add clients:** Enter a name, select VLAN access, and the tool generates a keypair, registers the peer on OPNsense, and displays a QR code. Private key never leaves the management computer. DNS is set to OPNsense so Unbound → ctrld → ControlD filtering applies. This also solves the Android Private DNS conflict — WireGuard's DNS setting overrides it. -**Connected peers:** Shows last handshake time and transfer stats for each peer. +**Local WireGuard (fallback):** Runs on the management computer. Peers can only reach VLAN 99. Use when OPNsense is being reconfigured. **SSH tunnel alternative:** For power users — one command gives secure access without WireGuard installed: ```bash ssh -L 8765:localhost:8765 user@management-computer-ip ``` +### PoE + +Power budget dashboard. Visual bar showing total/used/remaining watts with colour-coded thresholds. Per-port power draw grid. Warning when budget exceeds 85%. + +### Topology + +Auto-generated network diagram: OPNsense router → trunk link → switch → VLAN fan-out with port counts, device counts, and live status for each node. + +### Backups + +Automatic backup before every change (VLAN provisioning, policy push, service deploy). OPNsense full XML config export via API. Switch running-config capture via SSH. Manual backup/restore with download. Restore creates a safety backup first. Keeps last 50 per device. + +### Alerts + +ntfy push notifications for network events (connectivity loss, PoE budget warning). VLAN time-based schedules — disable/enable internet access per VLAN on a schedule (Guest WiFi off midnight–6am, Business off after hours). Scheduled backups and connectivity checks. + --- ## Making Changes — Step by Step @@ -466,8 +502,8 @@ The switch is never being polled when nobody is looking at the dashboard. | File | Location | Purpose | |---|---|---| -| `switch_backend.py` | Project folder | Python API server (34 endpoints) | -| `ers5952-manager.jsx` | Project folder | React app source (8 tabs) | +| `switch_backend.py` | Project folder | Python API server (~60 endpoints) | +| `ers5952-manager.jsx` | Project folder | React app source (17 tabs, 38 components) | | `README.md` | Project folder | This file | | `Dockerfile` | Project folder | Docker image definition | | `docker-compose.yml` | Project folder | Caddy + switch manager services | @@ -485,10 +521,25 @@ The switch is never being polled when nobody is looking at the dashboard. | `wg_server_public` | `/etc/switch-manager/` | WireGuard server public key | | `clients/` | `/etc/switch-manager/` | WireGuard client .conf files | | `switch-manager.service` | `/etc/systemd/system/` | Systemd service (native mode) | +| `opnsense_key` | `/etc/switch-manager/` | OPNsense SSH private key (chmod 600) | +| `opnsense_known_hosts` | `/etc/switch-manager/` | Pinned OPNsense host key | +| `opnsense_wg.json` | `/etc/switch-manager/` | WireGuard server/peer state (chmod 600) | +| `vlan-if-map.json` | `/etc/switch-manager/` | VLAN ID → OPNsense interface mapping | +| `vlan-policies.json` | `/etc/switch-manager/` | Inter-VLAN firewall policies | +| `service-proxies.json` | `/etc/switch-manager/` | Caddy reverse proxy service entries | +| `services-config.json` | `/etc/switch-manager/` | Services box LAN IP config | +| `Caddyfile.services` | `/etc/switch-manager/` | Auto-generated Caddy service proxy entries | +| `service-nat-rules.json` | `/etc/switch-manager/` | Tracked OPNsense NAT rule UUIDs | +| `port-forwards.json` | `/etc/switch-manager/` | Managed port forward rules | +| `pinholes.json` | `/etc/switch-manager/` | Firewall pinhole rule UUIDs | +| `schedules.json` | `/etc/switch-manager/` | Scheduled operations (backups, VLAN toggles) | +| `ntfy.json` | `/etc/switch-manager/` | ntfy alert configuration | +| `backups/switch/` | `/etc/switch-manager/` | Switch running-config backups | +| `backups/opnsense/` | `/etc/switch-manager/` | OPNsense XML config backups | | `local-hostnames.json` | `/etc/switch-manager/` | User-defined hostname→IP mappings (optional) | | `dnsmasq.conf` | `/etc/switch-manager/` | Generated dnsmasq config (optional) | -**Back up `/etc/switch-manager/totp_secret`** — if the management computer fails and you have not backed this up you will need to regenerate the TOTP secret and re-scan it into your authenticator app. +**Back up the entire `/etc/switch-manager/` directory** — it contains SSH keys, TOTP secrets, OPNsense credentials, WireGuard keys, and all configuration state. The Backups tab automatically saves switch and OPNsense configs before every change, but the management computer's own config directory should also be backed up externally. --- @@ -743,10 +794,10 @@ Useful when reviewing long `show config` or `show interfaces` output during cons ## What This Tool Does Not Do -- Does not manage OPNsense, pfSense, or any other device directly (OPNsense integration is read/sync only) +- Does not manage UniFi, pfSense, or non-OPNsense routers (OPNsense is the supported router platform) - Does not provide a terminal or shell — there is no way to type arbitrary commands through the main interface (CLI mode in settings is available for advanced users but still runs through the safety pipeline) - Does not support multiple switches simultaneously -- Does not provide traffic analytics or bandwidth graphs +- Does not provide deep traffic analytics or bandwidth graphs (PoE budget and port status are available) - Does not automatically discover or adopt new network devices ---