magicciv/scripts/lan/README.md

# LAN DNS — `*.black.lan`

Single source of truth for how every host on the LAN (and every WireGuard
VPN client) resolves `*.black.lan` to the dnsmasq at `dns.black.lan`
(`10.0.0.11`).

## Architecture

```
 ┌─────────────────────────────────────┐          ┌──────────────────────┐
 │ dns.black.lan  (= black.lan)    │          │ Remote VPN client    │
 │  10.0.0.11                          │          │  (laptop away)       │
 │                                     │          │                      │
 │  dnsmasq                            │          │  WireGuard tunnel    │
 │   - address=/black.lan/10.0.0.11  │◄─────────┤   routes 10.0.0.0/24 │
 │     (wildcard: every *.black.lan) │          │   + DNS=10.0.0.11    │
 │   - address=/dns.black.lan/       │          │                      │
 │     10.0.0.11 (explicit canonical)  │          └──────────┬───────────┘
 │                                     │                     │
 │  /etc/dnsmasq.d/lan.conf            │                     │ via VPN hub
 │  /etc/dnsmasq.d/black-local-dns-    │                     │
 │   alias.conf                        │                     ▼
 │  /etc/hosts has 10.0.0.11 aliases   │          ┌──────────────────────┐
 └─────────────────────────────────────┘          │ Iceland hub          │
             ▲         ▲                          │  (93.95.231.174      │
             │         │                          │   and 89.127.233.145)│
       ┌─────┘         └───────┐                  │  wg server           │
       │                       │                  │  peers: black, lan   │
 ┌─────┴──────┐         ┌──────┴─────┐             │                      │
 │ plum       │         │ apricot    │             └──────────────────────┘
 │ macOS      │         │ Linux      │
 │            │         │            │
 │ /etc/      │         │ /etc/      │
 │ resolver/  │         │ systemd/   │
 │ black.lan│         │ resolved.  │
 │            │         │ conf.d/    │
 │ nameserver │         │ black-     │
 │ 10.0.0.11  │         │ local.conf │
 └────────────┘         └────────────┘
```

## Components

### Server side — black (complete)

- **`/etc/dnsmasq.d/lan.conf`** — holds the wildcard rule
  `address=/black.lan/10.0.0.11`. Every `*.black.lan` lookup
  returns `10.0.0.11` via dnsmasq.
- **`/etc/dnsmasq.d/black-local-dns-alias.conf`** — explicit
  `address=/dns.black.lan/10.0.0.11` entry so the DNS service has a
  canonical first-class name (parallels `forge.black.lan`,
  `lm.black.lan`, etc.).
- **`/etc/hosts`** — `10.0.0.11 dns.black.lan` listed alongside
  other named services.

No server-side changes are required to onboard new hostnames under
`*.black.lan` — the wildcard picks them up.

### Client side — Linux + macOS (automated)

Run on any host that should resolve `*.black.lan`:

```sh
./run setup:lan-dns      # standalone re-subscribe
./run setup              # full dev-env setup (calls setup:lan-dns near the end)
bash scripts/lan/subscribe-black-dns.sh       # direct invocation (any host)
```

- **Linux (systemd-resolved)** — drops
  `/etc/systemd/resolved.conf.d/black-local.conf` with
  `DNS=10.0.0.11` + `Domains=~black.lan`, reloads resolved.
- **macOS** — drops `/etc/resolver/black.lan` with
  `nameserver 10.0.0.11`. No daemon reload.

Both paths are idempotent — safe to re-run after the LAN DNS layout
changes.

### VPN side — WireGuard hubs (manual, VPS-side)

The two Iceland WireGuard hubs that serve the LAN's two overlay
networks (10.8.0.0/24 via `93.95.231.174`, 10.9.0.0/24 via
`89.127.233.145`) need two config tweaks so traveling clients inherit
black's DNS automatically:

1. **Push `DNS = 10.0.0.11`** to the client via the server's
   per-peer `[Peer]` + `[Interface]` template. Every remote-client
   `wg-quick` config the hub hands out should include
   `DNS = 10.0.0.11` in its `[Interface]` section so the client's
   resolver uses black's dnsmasq while the tunnel is up.
2. **Include `10.0.0.0/24` in `AllowedIPs`** on the remote
   client's `[Peer]` block so traffic to black routes through the
   tunnel. Without this, `DNS=10.0.0.11` is set but the packet can't
   reach 10.0.0.11.

Example remote-client config (generated for each traveling device):

```ini
[Interface]
PrivateKey = <client-private-key>
Address = 10.8.0.<N>/32      # or 10.9.0.<N>/32 depending on hub
DNS = 10.0.0.11              # black's dnsmasq

[Peer]
PublicKey = <hub-public-key>
Endpoint = 93.95.231.174:51820   # or 89.127.233.145:51820
AllowedIPs = 10.8.0.0/24, 10.0.0.0/24   # include LAN subnet
PersistentKeepalive = 25
```

On the hub server (requires root on the Iceland VPS), after generating
each client's keypair, make sure the matching `[Peer]` block has
`AllowedIPs` that at minimum includes the client's tunnel IP — the
routing from hub → LAN (via black's wg0 back-tunnel) is already in
place.

Once those two tweaks are in a hub's config, any remote client that
connects gets the same `*.black.lan` resolution as a host physically
on the LAN. The client never needs `./run setup:lan-dns` in that
case because `DNS = 10.0.0.11` in the wg-quick config is
authoritative while the tunnel is up — but running
`subscribe-black-dns.sh` does no harm (idempotent) and also covers the
"VPN dropped, still want LAN DNS via a different route" case.

## Verifying

| Command | Expected output |
|---|---|
| `dig @dns.black.lan mc.next.black.lan` | `10.0.0.11` |
| `dig dns.black.lan` (via subscribed resolver) | `10.0.0.11` |
| `getent hosts forge.black.lan` (Linux) | `10.0.0.11 forge.black.lan` |
| `dscacheutil -q host -a name forge.black.lan` (macOS) | `ip_address: 10.0.0.11` |
| `curl -sk https://mc.next.black.lan/` | HTTP 200 |
| `resolvectl status` (Linux, in `Domains:`) | includes `~black.lan` |
| `scutil --dns \| grep -A2 black.lan` (macOS) | shows resolver file hit |