Add 'Remote Access (VPN)' user-guide page

[mairas]

Why

The dominant motivation for HaLOS's multi-hostname support is "access the device from a network other than the LAN it's plugged into" — typically over a VPN. The mechanics exist (per-hostname Authelia cookies, per-hostname OIDC redirect_uris, path-only Traefik routing), but there is no user-facing page that pulls them together into a task-oriented "I want to access HaLOS away from home" workflow. Today an operator has to read three architecture docs and a hostnames.conf comment block to assemble the picture.

Proposed page

Location: docs/user-guide/remote-access-vpn.md, listed in mkdocs.yml nav after Networking in the User Guide.

Outline:

1. Why VPN access — short framing: ssh works, but Cockpit/Homarr/Signal K behind SSO need an OIDC bounce, and the OIDC issuer is *.local by default, which doesn't resolve over most VPNs.
2. The name-resolution requirement — the device needs at least one hostname that resolves to its IP both from the LAN and from the VPN. The page should explain why this is unavoidable (single-issuer OIDC constraint, brief) and what the failure mode looks like (browser shows DNS error when clicking Login).
3. Recipe: Tailscale (recommended) — easiest because MagicDNS gives every device a name that resolves from anywhere on the tailnet without extra DNS setup. Worked example: install Tailscale, get halosdev.<tailnet>.ts.net, add it to /etc/halos/hostnames.conf as the first line, sudo systemctl restart halos-core-containers.service, verify by browsing from a Tailscale-connected client.
4. Recipe: WireGuard + split-horizon DNS — for users running their own VPN. Same shape, but the user is responsible for ensuring the chosen hostname resolves on both networks (e.g., dnsmasq sidecar on the WireGuard server, internal DNS A record). Less hand-holding than Tailscale.
5. Recipe: /etc/hosts on each client — the escape hatch. Not recommended but documented because it always works.
6. Gotchas:
   • DoH (Firefox, mobile browsers): the browser's resolver may bypass the VPN's DNS entirely. Test from the actual client browser, not just nslookup.
   • Mobile clients on cellular: Tailscale works; raw WireGuard requires the client to be configured with the VPN's DNS.
   • mDNS does not cross VPN tunnels by default (and shouldn't be made to — mDNS reflection has its own footguns).
7. Verifying it works — nslookup halosdev.<vpn-name> from a VPN client, then full browser login flow, then check that the URL bar stays on the VPN hostname end-to-end (not just the Authelia bounce).
8. Reverting — move ${hostname}.local back to the first line in hostnames.conf, restart. Active OIDC sessions will need to re-authenticate (cookies are scoped to the old canonical).

Cross-links to add

• user-guide/networking.md → "For remote access over a VPN, see Remote Access (VPN)."
• architecture/sso.md → "The single-issuer constraint shapes how VPN access works in practice — see Remote Access (VPN)."

Out of scope (separate issues if wanted)

• Documenting hostnames.conf syntax exhaustively (the in-file comments already do a decent job; could be promoted to a Reference page later).
• Tailscale subnet routes vs. direct device-on-tailnet trade-offs (audience overlap is small enough to defer).

[mairas]

Correction to the outline above — the original "Tailscale-as-canonical works for everyone" framing is wrong. If halosdev.<tailnet>.ts.net is canonical, then a LAN client without Tailscale installed cannot complete OIDC login: it can reach Homarr via mDNS at halosdev.local, but the post-Login redirect to the Tailscale name fails with NXDOMAIN because the LAN client's resolver doesn't have MagicDNS.

The general principle the page should lead with: canonical must resolve from every network any user logs in from. Single-issuer OIDC means there's exactly one name the browser is forced through during login. There is no canonical choice that automatically works for "LAN clients without VPN" and "remote VPN clients" — they require either (a) every LAN client to also have the VPN running, or (b) DNS infrastructure that serves the same name across both networks.

Revised outline:

1. The constraint — single-issuer OIDC means canonical must resolve from every login network. State up front.
2. Where this matters and where it doesn't — LAN-only users: keep the default, ignore this page. Add VPN access: this page.
3. Recommended path: Tailscale on all clients — install Tailscale on the device and on every client that will log in (including LAN clients). Now halosdev.<tailnet>.ts.net works from everywhere. State the requirement clearly: this only works if all your clients are on the tailnet.
4. Alternative: split-horizon DNS — for users who don't want to put every LAN client on a VPN. Requires running a DNS server on the LAN (or a router that supports custom DNS records) that returns the device's LAN IP for the canonical name; the VPN pushes a DNS rule that returns the VPN-side IP for the same name. Sketch with dnsmasq/Pi-hole/router-builtin examples.
5. Alternative: dynamic DNS + port forwarding — halosdev.duckdns.org (or equivalent) → device's WAN IP, with port forwarding 443 → device. Works from any internet-connected client without VPN. Security trade-offs: device's web stack is exposed; Authelia rate-limiting and MFA matter more here. Not recommended for the default case but worth covering as an option.
6. Escape hatch: /etc/hosts per client — always works, tedious.
7. Gotchas — DoH bypassing the LAN/VPN resolver (Firefox default in some regions), mobile clients on cellular, why mDNS reflection across VPN is a footgun.
8. Apply the change — one-line reorder of hostnames.conf, sudo systemctl restart halos-core-containers.service, expectation that existing OIDC sessions invalidate.
9. Verify — nslookup canonical from each client, full browser walkthrough, watch URL bar stays consistent.
10. Revert — same thing in reverse.

The "Tailscale (recommended)" framing in the original outline was glossing over a real requirement (every-client-on-tailnet). The corrected version is honest about the trade-off and doesn't oversell.

[mairas]

Two more refinements for the eventual writer:

Example-domain choice. Don't use .boat in examples — it's a real registered gTLD (operated by Dot Boat Domain Registry, used by marine-related sites). Picking a real TLD as an example invites readers to copy-paste a name that could collide with public DNS.

Use halos.example / halos.example.com for placeholders. RFC 2606 reserves .example for documentation exactly this purpose — it can't ever conflict with real names, signals "this is a placeholder" to any reader familiar with the convention, and grep'able as "definitely-not-real."

If marine flavour is wanted in specific recipes, .myboat / .boatname / .mydevice work as obvious fill-in-the-blank placeholders, but .example should be the default.

Avoid: .local (mDNS reserved), .lan (see below), and any real gTLD.

The .lan default trap. Many consumer routers default DHCP option 15 to .lan. It's tempting to "just use the default" and have the device be halos.lan, but this fails the multi-network test in a sneaky way: when a user's home LAN and the boat's LAN both call themselves .lan, anything VPN-bridging them (or a laptop carrying DNS cache between networks) gets ambiguous resolution. A name only buys cross-network uniqueness if it's actually unique across the networks you care about. Worth a half-sentence in the "naming considerations" part of the page: "Avoid .lan even though it's a common default — its ubiquity means VPN/multi-network setups hit collisions."

Same reasoning rules out .home, .localnet, and other widely-used informal defaults. RFC 8375's .home.arpa is the spec-compliant private-network option if the writer wants to mention one; otherwise a unique placeholder suits the example-driven format better.