diff --git a/numa.toml b/numa.toml index 2138dd2..57d0249 100644 --- a/numa.toml +++ b/numa.toml @@ -51,8 +51,8 @@ api_port = 5380 # relay_ip = "178.104.229.30" # optional: pin IPs so numa doesn't leak the # target_ip = "104.16.249.249" # relay/target hostnames via the bootstrap # # resolver on cold boot when numa is its -# # own system DNS. See docs/implementation/ -# # bootstrap-resolver.md. +# # own system DNS. See +# # recipes/odoh-upstream.md. # root_hints = [ # only used in recursive mode # "198.41.0.4", # a.root-servers.net (Verisign) # "199.9.14.201", # b.root-servers.net (USC-ISI) diff --git a/packaging/client/README.md b/packaging/client/README.md index f6e76c0..f66359f 100644 --- a/packaging/client/README.md +++ b/packaging/client/README.md @@ -2,10 +2,10 @@ Single-container deploy that runs Numa as an ODoH (RFC 9230) client: every DNS query routes through an independent relay + target so neither operator -sees both your IP and your question. See the [ODoH integration doc][odoh] -for the full protocol and privacy trade-offs. +sees both your IP and your question. See the [ODoH upstream recipe][odoh] +for the protocol details and the bootstrap-pinning trade-offs. -[odoh]: ../../docs/implementation/odoh-integration.md +[odoh]: ../../recipes/odoh-upstream.md ## Prerequisites diff --git a/packaging/client/numa.toml b/packaging/client/numa.toml index 039d723..64b9268 100644 --- a/packaging/client/numa.toml +++ b/packaging/client/numa.toml @@ -1,7 +1,7 @@ # Numa — ODoH client mode (docker-compose starter). # Sends every DNS query through an independent relay + target pair so # neither operator sees both your IP and your question. See -# docs/implementation/odoh-integration.md for the protocol details and +# recipes/odoh-upstream.md for the protocol details and # packaging/client/README.md for deploy notes. [server] diff --git a/recipes/README.md b/recipes/README.md new file mode 100644 index 0000000..fa05c2d --- /dev/null +++ b/recipes/README.md @@ -0,0 +1,11 @@ +# Recipes + +Scenario-driven configs for common Numa deployments. Each recipe is self-contained: copy the snippet, adjust the marked fields, reload. + +## Transport / encryption + +- [DoH on the LAN](doh-on-lan.md) — expose Numa's built-in DNS-over-HTTPS to local clients. +- [dnsdist in front of Numa](dnsdist-front.md) — terminate public TLS externally, keep Numa on loopback. +- [ODoH upstream with bootstrap pinning](odoh-upstream.md) — oblivious DNS client mode without leaking the relay/target hostnames. + +Missing a scenario? Open an issue or PR — these are plain Markdown with no build step. diff --git a/recipes/dnsdist-front.md b/recipes/dnsdist-front.md new file mode 100644 index 0000000..310b53c --- /dev/null +++ b/recipes/dnsdist-front.md @@ -0,0 +1,64 @@ +# dnsdist in front of Numa + +For public DoH with a real (ACME-signed) cert, terminate TLS outside Numa and forward plain DNS (or loopback-only DoH) to the resolver. Cert renewal, rate-limiting, and load-balancing live in the front-end; Numa stays focused on resolution. + +## When to use this + +- Public hostname (`dns.example.com`) with a Let's Encrypt or internal PKI cert. +- You want a dedicated front-end for DoH/DoT/DoQ while Numa stays loopback-bound. +- You plan to run multiple Numa instances behind one endpoint. + +## Architecture + +``` + public 443/DoH ┐ + public 853/DoT ├─► dnsdist ─► 127.0.0.1:53 (Numa UDP/TCP) + public 443/DoQ ┘ +``` + +## dnsdist config + +```lua +-- /etc/dnsdist/dnsdist.conf + +newServer({address="127.0.0.1:53", name="numa", checkType="A", checkName="numa.rs."}) + +addDOHLocal( + "0.0.0.0:443", + "/etc/letsencrypt/live/dns.example.com/fullchain.pem", + "/etc/letsencrypt/live/dns.example.com/privkey.pem", + "/dns-query", + {doTCP=true, reusePort=true} +) + +addTLSLocal( + "0.0.0.0:853", + "/etc/letsencrypt/live/dns.example.com/fullchain.pem", + "/etc/letsencrypt/live/dns.example.com/privkey.pem" +) + +addAction(AllRule(), PoolAction("", false)) +``` + +## Numa config + +```toml +[proxy] +enabled = true # keep if you still use *.numa service routing +bind_addr = "127.0.0.1" # stays default +``` + +No changes to `[server]` — Numa keeps serving plain DNS on UDP/TCP 53, which dnsdist forwards. + +## Caveat: client IPs + +Without PROXY protocol support in Numa, the query log shows the front-end's IP on every query, not the real client. dnsdist can emit PROXY v2 (`useProxyProtocol=true` on `newServer`), but Numa doesn't yet parse it — tracked in the wish-list under #143. Until then, accept the blind spot or correlate against dnsdist's own logs. + +## Verify + +```bash +kdig +https @dns.example.com example.com +kdig +tls @dns.example.com example.com +``` + +Both should return clean answers. Numa's `/queries` API should show the request landing, sourced from the front-end IP. diff --git a/recipes/doh-on-lan.md b/recipes/doh-on-lan.md new file mode 100644 index 0000000..70b607e --- /dev/null +++ b/recipes/doh-on-lan.md @@ -0,0 +1,61 @@ +# DoH on the LAN + +Numa ships an RFC 8484 DoH endpoint (`POST /dns-query`) on the `[proxy]` HTTPS listener. By default it binds `127.0.0.1:443` with a self-signed cert — invisible to anything off the box. Three changes make it reachable from the LAN. + +## When to use this + +- Your phone/laptop is on the same network as Numa and you want encrypted DNS without a cloud resolver. +- You're OK installing Numa's self-signed CA on every client (one-time, via `/ca.pem` + the mobileconfig flow). + +For a publicly-trusted cert, see [dnsdist in front of Numa](dnsdist-front.md) instead. + +## Minimal config + +```toml +[proxy] +enabled = true # default +bind_addr = "0.0.0.0" # was 127.0.0.1 — expose to LAN +tls_port = 443 # default; DoH is served here +tld = "numa" # default — self-resolving, see below +``` + +`tld` is the DoH gate: Numa accepts the DoH request only when the `Host` header is loopback or equals (or is a subdomain of) `tld`. Clients therefore dial `https://numa/dns-query`. + +With the default `tld = "numa"`, there's no DNS bootstrap to configure: Numa already resolves `numa` and `*.numa` to its own LAN IP for remote clients (that's how the `*.numa` service-proxy feature works). Any client that uses Numa as its resolver will resolve `numa` correctly on first try. + +If you'd rather use a hostname that resolves via normal DNS (e.g. you want DoH-only clients that never talk plain DNS to Numa), set `tld = "dns.example.com"` and add a matching A record in whichever DNS your clients consult before reaching Numa. + +## Trust the CA on each client + +Numa generates a self-signed CA at startup. Fetch it once, import it wherever you'll run the DoH client: + +```bash +curl -o numa-ca.pem http://:5380/ca.pem +``` + +- **macOS** — `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain numa-ca.pem` +- **iOS** — install the mobileconfig from the API (same CA, signed profile). Flip *Settings → General → About → Certificate Trust Settings* on after install. +- **Linux** — drop into `/usr/local/share/ca-certificates/` and run `sudo update-ca-certificates`. +- **Android** — requires the user-installed CA path; browsers may still refuse it for DoH. Consider the [dnsdist front](dnsdist-front.md) route instead. + +## Verify + +```bash +kdig +https @numa example.com +``` + +Without `+https` kdig uses plain DNS. With `+https` the same answers should flow over port 443. + +Raw check: + +```bash +curl -H 'accept: application/dns-message' \ + --data-binary @query.bin \ + https://numa/dns-query +``` + +## Gotchas + +- Port 443 is privileged on Linux/macOS. Run Numa via the provided service units, or grant `CAP_NET_BIND_SERVICE` (`sudo setcap 'cap_net_bind_service=+ep' /path/to/numa`). +- Non-matching `Host` header → HTTP 404 from the proxy's fallback handler. Double-check `tld`. +- ChromeOS enrollment rejects user-installed CAs for some flows — known pain point, see issue #136. diff --git a/recipes/odoh-upstream.md b/recipes/odoh-upstream.md new file mode 100644 index 0000000..0469bca --- /dev/null +++ b/recipes/odoh-upstream.md @@ -0,0 +1,59 @@ +# ODoH upstream with bootstrap pinning + +Numa can run as an Oblivious DoH (RFC 9230) client: the relay sees your IP but not the question, the target sees the question but not your IP. Neither party alone can re-identify a query. This recipe covers the minimal config and the bootstrap leak that `relay_ip` / `target_ip` close. + +## When to use this + +- You want split-trust encrypted DNS without a single provider seeing both who you are and what you asked. +- Numa is your system resolver (so there's no "other" DNS to ask). + +## Minimal config + +```toml +[upstream] +mode = "odoh" +relay = "https://odoh-relay.numa.rs/relay" +target = "https://odoh.cloudflare-dns.com/dns-query" +strict = true # refuse to fall back to a non-oblivious path on relay failure +``` + +`strict = true` means a relay-level HTTPS failure returns SERVFAIL instead of silently downgrading. Set it to `false` and configure `[upstream].fallback` if you'd rather keep resolving (at the cost of the oblivious property). + +## The bootstrap leak + +When Numa is the system resolver and needs to reach the relay/target, *something* has to translate `odoh-relay.numa.rs` → IP. If Numa asks itself, you deadlock. If Numa asks a bootstrap resolver (1.1.1.1, 9.9.9.9), that resolver learns which ODoH endpoint you use in cleartext — it can't see your questions, but it sees the destination. That's the leak ODoH was supposed to close. + +`relay_ip` and `target_ip` tell Numa the IPs directly, so it never asks anyone: + +```toml +[upstream] +mode = "odoh" +relay = "https://odoh-relay.numa.rs/relay" +target = "https://odoh.cloudflare-dns.com/dns-query" +relay_ip = "178.104.229.30" # pin the relay — no hostname lookup +target_ip = "104.16.249.249" # pin the target — no hostname lookup +``` + +Numa still validates TLS against the hostnames in `relay` / `target`, so a hijacked IP can't masquerade — pinning skips only the DNS step. + +## Finding current IPs + +```bash +dig +short odoh-relay.numa.rs +dig +short odoh.cloudflare-dns.com +``` + +Re-pin when an operator rotates. The community-maintained list at is a useful cross-reference. + +## Verify + +```bash +kdig @127.0.0.1 example.com +``` + +Numa's `/queries` API and startup banner should label the upstream as `odoh://`. Look for `ODoH relay returned ...` errors in the logs if routing fails. + +## Known gotchas + +- **Same-operator refused.** Numa's eTLD+1 check blocks configs where the relay and target belong to the same operator (pointless — same party sees both sides). Override only when testing. +- **Single relay.** Current config accepts one relay and one target. Multi-entry rotation/failover is tracked in #140. diff --git a/src/bootstrap_resolver.rs b/src/bootstrap_resolver.rs index c3be8bd..44214e4 100644 --- a/src/bootstrap_resolver.rs +++ b/src/bootstrap_resolver.rs @@ -2,8 +2,7 @@ //! relay/target, blocklist CDN). When numa is its own system resolver //! (`/etc/resolv.conf → 127.0.0.1`, HAOS add-on, Pi-hole-style container), //! the default `getaddrinfo` path loops back through numa before numa can -//! answer — a chicken-and-egg that deadlocks cold boot. See issue #122 and -//! `docs/implementation/bootstrap-resolver.md`. +//! answer — a chicken-and-egg that deadlocks cold boot. See issue #122. //! //! Resolution order per hostname: //! 1. Per-hostname overrides (e.g. ODoH `relay_ip` / `target_ip`) → return diff --git a/src/forward.rs b/src/forward.rs index e3f307b..1c39292 100644 --- a/src/forward.rs +++ b/src/forward.rs @@ -175,8 +175,7 @@ pub fn parse_upstream( /// /// Uses the system resolver. Callers running inside `serve::run` pass the /// shared [`crate::bootstrap_resolver::NumaResolver`] via -/// [`build_https_client_with_resolver`] to avoid the self-loop documented -/// in `docs/implementation/bootstrap-resolver.md`. +/// [`build_https_client_with_resolver`] to avoid the self-loop (issue #122). pub fn build_https_client() -> reqwest::Client { build_https_client_with_resolver(1, None) } diff --git a/src/health.rs b/src/health.rs index 5767f4b..30cad9a 100644 --- a/src/health.rs +++ b/src/health.rs @@ -7,11 +7,10 @@ //! Both handlers call [`HealthResponse::build`] to assemble the JSON //! response from `HealthMeta` + live inputs. //! -//! JSON schema is documented in `docs/implementation/ios-companion-app.md` -//! §4.2. The iOS companion app's `HealthInfo` struct is the canonical -//! consumer; any change to this response must keep that struct decoding -//! cleanly (all consumed fields are optional on the Swift side, but -//! `lan_ip` is load-bearing for the pipeline). +//! The iOS companion app's `HealthInfo` struct is the canonical consumer; +//! any change to this response must keep that struct decoding cleanly (all +//! consumed fields are optional on the Swift side, but `lan_ip` is +//! load-bearing for the pipeline). use std::net::Ipv4Addr; use std::path::Path; diff --git a/src/serve.rs b/src/serve.rs index c76d174..e20ebe8 100644 --- a/src/serve.rs +++ b/src/serve.rs @@ -52,7 +52,6 @@ pub async fn run(config_path: String) -> crate::Result<()> { // Routes numa-originated HTTPS (DoH upstream, ODoH relay/target, blocklist // CDN) away from the system resolver so lookups don't loop back through // numa when it's its own system DNS. - // See `docs/implementation/bootstrap-resolver.md`. let resolver_overrides = match config.upstream.mode { crate::config::UpstreamMode::Odoh => config .upstream