Previous code had the architecture completely backwards:
WRONG: ctrld takes :53, Unbound moves to :5353 as a local resolver
RIGHT: Unbound stays on :53, ctrld binds localhost:5354, Unbound
uses Query Forwarding to push external queries through ctrld
This was verified working after reboot with no manual intervention.
The old approach caused a race at boot (whichever service won :53
first would work; the other would fail until manually restarted).
Changes:
- _build_ctrld_toml: router mode listener is now 127.0.0.1:5354
(not per-VLAN gateway IPs); no split-horizon rules needed since
Unbound handles all local resolution before queries reach ctrld
- CtrldConfig: unbound_port (5353) → ctrld_port (5354)
- _ctrld_generate_opnsense_cmd: rewritten with correct 5-step guide:
install ctrld, write toml, configure Unbound Query Forwarding,
remove home.arpa local-zone (tutorial artifact causing PTR failures),
verify with dig
- All call sites updated to use ctrld_port instead of unbound_port/local_resolver
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
ctrld was only forwarding *.lan and *.local to Unbound.
Reverse DNS (PTR) queries and RFC 8375 *.home.arpa names were
leaking upstream instead of being answered by Unbound locally.
Both router-mode and proxy-mode TOML rule blocks now include:
*.home.arpa → upstream.local
*.in-addr.arpa → upstream.local (IPv4 reverse DNS)
*.ip6.arpa → upstream.local (IPv6 reverse DNS)
This ensures all local/private DNS resolves correctly after reboot
without any manual intervention or unknown/broken state.
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Root cause: OPNsense enables Unbound on 0.0.0.0:53 at boot. ctrld also
needs :53. Whoever starts second loses. After upgrades/reboots Unbound
wins and ctrld silently fails (or vice-versa).
Fix: move Unbound to localhost:5353 only, ctrld owns :53 on VLAN IPs.
Both services now start cleanly after every reboot with zero conflict.
Changes:
- CtrldConfig adds unbound_port (default 5353) and local_domain ("lan")
- _build_ctrld_toml now always receives local_resolver="127.0.0.1:5353"
in OPNsense/opnsense mode; adds [upstream.local] type=legacy so *.lan,
*.local, *.home.arpa queries still resolve through Unbound
- _ctrld_generate_opnsense_cmd emits clear step-by-step instructions:
step1_unbound — change Unbound port to 5353 + restrict to Localhost
step2_install — ctrld install command
step3_config — write ctrld.toml (includes local upstream for Unbound)
step4_dns — set DHCP option 6 to per-VLAN gateway IP
step5_verify — test both internet and local DNS after deploy
Includes unbound_warning explaining why the order matters
- save-config, toml-preview, and update-profiles all persist and reload
unbound_port + local_domain from ctrld.json
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Router mode (deploy_mode="router") — for ctrld running on OPNsense:
Each VLAN gets its own [listener.N] bound to the VLAN gateway IP
(e.g. 192.168.10.1 for VLAN 10). VLAN clients send DNS to their
gateway; ctrld receives it on that listener and routes it to the
correct upstream with zero CIDR lookup overhead. Default when
mode="opnsense".
Proxy mode (deploy_mode="proxy") — for ctrld on the management host:
Single [listener.0] on 0.0.0.0:53 with [network.N] CIDR sections
and a networks= policy array in [listener.0.policy]. Unchanged
behaviour from before, correct for non-router deployments.
CtrldVlanProfile gains optional gateway field (VLAN gateway IP) used
by router mode to set each listener.N ip. Falls back to 0.0.0.0 if
not provided so existing configs without it keep working.
CtrldConfig gains deploy_mode field; persisted in ctrld.json so
toml-preview, update-profiles, and future reloads regenerate the same
topology. All _build_ctrld_toml callers now pass deploy_mode through.
Both modes confirmed against ctrld v1.5.0 (March 2026) TOML spec.
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
TOML structural fix (critical):
- Remove wrapper [listener]/[network]/[upstream] headers; use flat
dotted-key notation ([listener.0], [network.0], etc.) that ctrld's
Go TOML v2 parser requires — the old nested style triggered a table
redefinition panic at startup
- Add 'name' field to every [upstream.N] section (required by ctrld)
- Add [listener.0.policy] name field
DoH3 and protocol support:
- CtrldVlanProfile gains protocol (default "doh3") and endpoint_url
fields; endpoint_url overrides the ControlD resolver_id URL if set
- Upstream type now uses the profile's protocol instead of hardcoded
"doh" — enables DoH3 connection-pool reuse added in ctrld 2025
Endpoint pre-flight validation:
- New _validate_doh_endpoint(): sends RFC 8484 DoH GET query over
plain HTTPS (works for DoH3 URLs too — ControlD serves both) and
measures latency; no ctrld binary or Docker required
- New POST /api/ctrld/validate-endpoints: tests all profile endpoints,
validates TOML syntax via tomllib (Python 3.11+), returns per-profile
results + toml_preview
- ctrld_save_config now runs validation before writing anything and
returns HTTP 400 with per-profile probe results on failure — configs
are never pushed with a broken endpoint
OPNsense plugin verdict: documented in code — the os-controld plugin
kills Unbound and breaks OPNsense DNS advertisement; SSH-based deploy
with our own TOML remains the correct path
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
- Add POST /api/vlan/provision: end-to-end VLAN wizard that creates the
switch VLAN, OPNsense VLAN tag, DHCP scope, and allow-outbound firewall
rule in one call; returns pending_steps for anything needing manual
OPNsense UI finish (interface assignment when opnsense_if not provided)
- Rewire POST /api/devices/push-reservation to target OPNsense DHCP when
configured (no Advanced License required); falls back to switch CLI only
if OPNsense is not set up; uses stored VLAN→interface map for iface lookup
- Rewrite POST /api/devices/push-pinhole to use OPNsense firewall/filter
API instead of switch ACLs; stores rule UUIDs in pinholes.json for clean
removal; no longer requires Advanced License
- Remove dead relay endpoints (GET/POST /api/dhcp/relay/*), RelayConfig
model, and helpers (_get_relay_status, _get_vlan_ips, _build_relay_cmds);
relay config is irrelevant when OPNsense is the DHCP server
- Add VLAN_IF_MAP_FILE and PINHOLE_FILE with load/save helpers to persist
the VLAN→OPNsense interface mapping and pinhole rule UUIDs across restarts
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Probes the switch using read-only show commands to detect whether the
Advanced Software License is installed. Base Software rejects ACL and
L3 VLAN interface commands with 'Invalid input detected'.
- GET /api/switch/capabilities: non-destructive probe (show ip access-list,
show interface vlan 1), returns acl/l3_vlan/dhcp_relay_config/
management_pinholes/dns_enforce_acls flags and license_tier. Cached 5 min.
- _require_advanced_license(): guard helper that raises HTTP 402 with a
clear message before attempting any ACL push to the switch.
- Applied guard to: POST /api/switch/acl, /api/devices/push-pinhole,
/api/dhcp/relay/configure, /api/ctrld/dns-enforce-acls.
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
The original commands were missing the 'ip' prefix. Correct ACLI syntax:
show dhcp-server -> show ip dhcp-server
show dhcp-server leases -> show ip dhcp-server leases
show dhcp-server static-binding -> show ip dhcp-server static-binding
The ERS 59100GTS-PWR+ has a DHCP server but it may need to be enabled
first ('ip dhcp-server enable' in config mode) or may require an
Advanced License. All DHCP server calls now have try/except so device
discovery falls back to ARP if the feature is not yet active.
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
- show ip route default → show ip route (parse 0.0.0.0 row for gateway)
- show ip helper-address → show ip dhcp-relay fwd-path + update parser
- ip helper-address → ip dhcp-relay fwd-path <vlan-ip> <server-ip>
(add _get_vlan_ips() to resolve VLAN interface IPs before building cmds)
- Remove all show dhcp-server / show dhcp-server leases / show dhcp-server
static-binding calls — switch has no DHCP server (show ip dhcp ? only
shows 'client'). Device discovery now uses show arp only.
- push-reservation, sync to_switch/remove_switch → 501 Not Implemented
- _get_switch_reservations() / _get_switch_dhcp_status() return empty/false
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
exec_command runs in user mode on BOSS v7.9.6; most show commands
(show vlan, show sys-info, show poe-main-status, show config, etc.)
require enable mode. Switch to invoke_shell per read command, sending
terminal length 0 and enable before each command.
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
- Replace show poe-port-status with show poe-port status ALL
- Replace show vlan members with show vlan
- Replace show running-config with show config
- Fix VLAN port format from 1/{p} to {p} (BOSS uses bare port numbers)
- Fix interface naming from GigabitEthernet 1/{p} to GigabitEthernet {p}
- Add terminal length 0 to push session setup to prevent pagination
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Replace ERS 5952 (48+4 port) config with ERS 59100GTS-PWR+:
- Port validation extended to 1–100
- All interfaces now use GigabitEthernet 1/{p} slot notation
- PoE boundary moved from port 48 to port 96
- VLAN commands updated to use 1/{p} port notation
- Key path, TOTP name, and app title updated
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
ACL backend:
- AclRule gains optional port_end field; build_acl generates
"range X Y" when both port and port_end are set (needed for RTP)
New ACL template — "SIP Phone VLAN — Asterisk / FreePBX access":
- Permits SIP signaling UDP/TCP 5060 to PBX IP
- Permits SIP/TLS TCP 5061 to PBX IP
- Permits RTP audio UDP range 10000-20000 to PBX IP (uses new range syntax)
- Blocks management VLAN 99
- Permits internet and all other traffic
- Requires entering the Asterisk server IP (restricts SIP/RTP to that
exact host, not the whole VLAN subnet)
Template description explains:
- Why OPNsense firewall rules are also needed (inter-VLAN routing)
- Exactly which OPNsense rules to add (including return RTP)
- Remote access options: WebRTC via Caddy reverse proxy (recommended)
and SIP/TLS with fail2ban for traditional SIP clients
Template modal:
- New pbxIp param field shown for VoIP template
- Description box scrollable for longer template descriptions
- Preview renders "range X Y" for port range rules
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Moves WireGuard off the management computer and onto OPNsense so any
device can VPN home without touching the management PC. Each peer is
restricted to only the VLANs you select (e.g. phone gets VLAN 10 only,
laptop gets VLAN 10 + 20). Private keys are generated on the mgmt PC
and never sent to OPNsense — only the public key is registered.
Backend (switch_backend.py):
- /api/opnsense/wireguard/status — check plugin, server, peers
- /api/opnsense/wireguard/setup-server — create wg1 on OPNsense via API
- DELETE /api/opnsense/wireguard/server — tear down server
- /api/opnsense/wireguard/add-peer — generate keypair, register peer,
link to server, return .conf
- DELETE /api/opnsense/wireguard/peer/{uuid} — revoke peer
- /api/opnsense/wireguard/peer-config/{name} — fetch saved .conf
Frontend (ers5952-manager.jsx):
- New OPNsenseWGSection component added to VPN tab below local WireGuard
- Progressive UI: not configured → plugin missing → server setup →
peer management (VLAN checkboxes) → QR/.conf download
- Firewall rules guidance panel auto-generated from active peers showing
exactly which OPNsense rules to add per VLAN
- vlans prop threaded through to WireGuardTab so VLAN names/colors
appear on peer badges and in the VLAN selector
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
- Backend: _get_relay_status() reads current ip helper-address per VLAN
- Backend: _build_relay_cmds() generates ERS 5952 relay CLI commands
- Backend: /api/dhcp/relay/status and /api/dhcp/relay/configure endpoints
- Backend: dhcp_overview now includes relay status in response
- Frontend: VLAN_MAP + VlanBadge + vlanFromIp() helpers for consistent labelling
- Frontend: RelayPanel shows per-VLAN relay status grid with push button;
VLAN 99 always shown as locked/local, VLANs 10/20/30/40/50 show live
relay target and purpose note
- Frontend: Reservations table gains VLAN column and inline purpose note
(from descr/notes or VLAN_MAP fallback)
VLAN 99 is excluded from relay at both backend and UI level — it is the
switch management / OPNsense recovery path.
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Features added:
- Port 53 conflict resolution: auto-detect/fix systemd-resolved stub listener
on Linux; instructions for OPNsense Unbound (ctrld auto-terminates it)
- DNS enforcement ACLs: generate ERS 5952 ACL commands that permit DNS only
to ctrld IP and block all other port 53/853 traffic per VLAN
- Inter-VLAN routing ACL templates: Staff, IoT, Guest, Camera profiles with
live preview and parameter inputs (ctrld IP, NVR IP, subnet)
- Local hostname resolution: dnsmasq Docker service for .lan split-horizon DNS;
manage hostname→IP mappings via UI; generates dnsmasq.conf and ctrld.toml
upstream.local block
- Fix ctrld.toml format: correct [listener.0], [network.N], [upstream.N] table
notation (was using wrong [[array]] notation); matches official docs format
- Backend docstrings: added docstrings to all previously undocumented functions
- README: new sections for port 53 conflict resolution, DNS enforcement ACLs,
ACL templates, and local hostname resolution (dnsmasq)
- Fix Python 3.11 f-string syntax errors in Avaya_5952_setup.py (backslash
in f-string expressions, same-type quote in dict access); embed now succeeds
https://claude.ai/code/session_01JR2EMK7rwrZJowpstcaxQ6
Claude