mysticalsoap/aqomui
Watch
1
0
Fork
You've already forked aqomui
 0
Code Issues 36 Pull requests 1 Releases 2 Packages Wiki Activity Actions

docs: document the split-horizon DNS setup #94

Merged
mysticalsoap merged 1 commit from change/split-horizon-dns-docs into trunk 2026-08-20 15:59:52 -04:00
Conversation 1 Commits 1 Files changed 1 +1 -1
mysticalsoap commented 2026-08-20 15:18:32 -04:00
Owner
Copy link

Problem

#34 decided split-horizon support is the documented alternative-DNS recipe, but the README said nothing about it — every split-horizon user hits "internal names resolve to public addresses under VPN" with no breadcrumb.

Fix

A "Split-horizon DNS" section under the DNS options: the failure mode, the alt-DNS recipe (local resolver first, public fallback second), and two caveats — the resolver must be reachable outside the tunnel (LAN traffic is allowed unless "Block LAN" is set), and systemd-resolved's sticky failover can leave the system on the fallback after a transient blip.

Verification

Live-tested 2026-08-20 on a real split-horizon LAN: with the tunnel up, the tun link carried both servers plus ~. and internal names resolved to their LAN addresses. The stickiness caveat is not theoretical — a ping-restart reconnect during that same test rotated resolved to the fallback, where it silently stayed until the server list was changed (an identical re-apply does not reset selection).

Closes #34

**Problem** #34 decided split-horizon support is the documented alternative-DNS recipe, but the README said nothing about it — every split-horizon user hits "internal names resolve to public addresses under VPN" with no breadcrumb. **Fix** A "Split-horizon DNS" section under the DNS options: the failure mode, the alt-DNS recipe (local resolver first, public fallback second), and two caveats — the resolver must be reachable outside the tunnel (LAN traffic is allowed unless "Block LAN" is set), and systemd-resolved's sticky failover can leave the system on the fallback after a transient blip. **Verification** Live-tested 2026-08-20 on a real split-horizon LAN: with the tunnel up, the tun link carried both servers plus `~.` and internal names resolved to their LAN addresses. The stickiness caveat is not theoretical — a ping-restart reconnect during that same test rotated resolved to the fallback, where it silently stayed until the server list was changed (an identical re-apply does not reset selection). Closes #34
docs: document the split-horizon DNS setup
All checks were successful
ci / test (pull_request) Successful in 45s
Details
8609aad980
 
Closes #34: the supported path for split-horizon networks is the
existing alternative-DNS setting pointed at the local resolver, with a
public fallback in the second slot. No per-domain exemption feature; a
"~." opt-out is off the table because it reopens the leak the routing
domain exists to close.

Live-tested on a real split-horizon LAN: with the tunnel up the tun
link carries both servers plus "~." and internal names resolve to
their LAN addresses. The same test surfaced the resolved failover
stickiness documented as a caveat: a tunnel reconnect rotated resolved
to the fallback server, where it stayed — silently returning public
answers — until the server list was changed, since re-applying an
identical list does not reset server selection.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
mysticalsoap force-pushed change/split-horizon-dns-docs from 8609aad980
All checks were successful
ci / test (pull_request) Successful in 45s
Details
to fd40dca6f5
All checks were successful
ci / test (pull_request) Successful in 30s
Details
ci / test (push) Successful in 29s
Details
2026-08-20 15:58:30 -04:00 Compare
mysticalsoap commented 2026-08-20 15:58:38 -04:00
Author
Owner
Copy link

Reshaped after #96: the standalone section is gone. What survives is three sentences on the "Always use alternative DNS servers" bullet itself — the failure mode, the local-resolver-first recipe, and the reachable-outside-the-tunnel/Block-LAN caveat. The sticky-failover caveat and its manual resolvectl fix are cut entirely: #96 makes recovery automatic, so documenting the workaround would describe a bug that no longer exists. Net diff is now one line.

Reshaped after #96: the standalone section is gone. What survives is three sentences on the "Always use alternative DNS servers" bullet itself — the failure mode, the local-resolver-first recipe, and the reachable-outside-the-tunnel/Block-LAN caveat. The sticky-failover caveat and its manual resolvectl fix are cut entirely: #96 makes recovery automatic, so documenting the workaround would describe a bug that no longer exists. Net diff is now one line.
mysticalsoap deleted branch change/split-horizon-dns-docs 2026-08-20 15:59:52 -04:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
architecture
Structural change, not a local fix

  
bug
Defect in existing behaviour

  
cleanup
Tidying with no behaviour change

  
docs
Documentation and repo standards

  
packaging
distro packages and their build tooling

  
security
Vulnerability or hardening

  
testing
Test coverage or infrastructure

  
upstream
Needs action on someone else's project

  
ux
Interface behaviour and clarity

No labels
architecture
bug
cleanup
docs
packaging
security
testing
upstream
ux
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
mysticalsoap/aqomui!94
No description provided.