679b346246
* fix: prevent self-referential DNS backup on re-install
The install flow previously captured current system DNS servers
verbatim into the backup file. If numa was already installed, current
DNS was 127.0.0.1, so the "backup" recorded 127.0.0.1 as the "original"
— making a subsequent uninstall a no-op self-reference.
Reproduced 2026-04-08 during v0.10.0 brew dogfood: after
`sudo numa uninstall; sudo /opt/homebrew/bin/numa install`,
`sudo numa uninstall` printed `restored DNS for "Wi-Fi" -> 127.0.0.1`
because the brew binary's install step had overwritten the backup with
the already-stub state.
Fix (all three platforms):
- macOS/Windows: if the existing backup already contains at least one
non-loopback/non-stub upstream, preserve it as-is. If writing a fresh
backup, filter loopback/stub addresses first so a capture from
already-numa-managed state isn't self-referential.
- Linux (resolv.conf fallback path): detect numa-managed or all-loopback
resolv.conf content and skip the file copy in that case; preserve an
existing useful backup rather than overwriting it. systemd-resolved
path is unaffected (uses a drop-in, no backup file).
Adds three unit tests for the predicates: macOS HashMap detection,
Windows interface filter, and resolv.conf parsing (real upstream,
self-referential, numa-marker, systemd stub, mixed).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: share iter_nameservers helper and reuse resolv.conf content
Post-review simplifications on the stale-backup fix:
- Extract iter_nameservers(&str) helper used by both parse_resolv_conf
and resolv_conf_has_real_upstream. Eliminates the duplicated
line-by-line nameserver parsing (findings from reuse review).
- install_linux: reuse the already-read resolv.conf content via
std::fs::write instead of a second read via std::fs::copy.
- install_macos / install_windows: flatten the conditional eprintln
pattern — always print a blank line, conditionally print the save
message. Equivalent output, less branching.
Net −12 lines. All 130 tests still pass, clippy clean.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: drop redundant trim before split_whitespace
CI caught `clippy::trim_split_whitespace` on Rust 1.94: `split_whitespace()`
already skips leading/trailing whitespace, so `.trim()` first is redundant.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: extract load_backup helper
Remove duplicated read+deserialize boilerplate shared by install_macos
and install_windows. The two call sites each had an identical 4-line
chain of read_to_string().ok().and_then(serde_json::from_str).ok() —
collapse into a single generic helper load_backup<T>().
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Revert "refactor: extract load_backup helper"
This reverts commit a54fb99428.
* test: drop windows_backup_filters_loopback
The test inlined the 3-line filter block from install_windows rather
than calling a production helper, so it was testing stdlib Vec::retain
+ is_loopback_or_stub — both already covered elsewhere. Deleting it
removes a test that would silently pass even if install_windows stopped
filtering altogether.
The predicate logic for macOS-shaped backups stays covered by
macos_backup_real_upstream_detection (same inner Vec<String> type).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add windows_backup_filters_loopback unit test
The PR description mentioned this test but it was missing from the
diff, leaving backup_has_real_upstream_windows untested. Mirrors the
shape of macos_backup_real_upstream_detection: empty map → false,
all-loopback (127.0.0.1, ::1, 0.0.0.0) → false, one real entry
alongside loopback → true.
Also relax the cfg gate on backup_has_real_upstream_windows from
cfg(windows) to cfg(any(windows, test)) so the test compiles
cross-platform, matching how backup_has_real_upstream_macos and
the resolv_conf helpers are gated.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Numa
DNS you own. Everywhere you go. — numa.rs
A portable DNS resolver in a single binary. Block ads on any network, name your local services (frontend.numa), and override any hostname with auto-revert — all from your laptop, no cloud account or Raspberry Pi required.
Built from scratch in Rust. Zero DNS libraries. RFC 1035 wire protocol parsed by hand. Caching, ad blocking, and local service domains out of the box. Optional recursive resolution from root nameservers with full DNSSEC chain-of-trust validation, plus a DNS-over-TLS listener for encrypted client connections (iOS Private DNS, systemd-resolved, etc.). One ~8MB binary, everything embedded.
Quick Start
# macOS
brew install razvandimescu/tap/numa
# Linux
curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh
# Windows — download from GitHub Releases
# All platforms
cargo install numa
sudo numa # run in foreground (port 53 requires root/admin)
Open the dashboard: http://numa.numa (or http://localhost:5380)
Set as system DNS:
| Platform | Install | Uninstall |
|---|---|---|
| macOS | sudo numa install |
sudo numa uninstall |
| Linux | sudo numa install |
sudo numa uninstall |
| Windows | numa install (admin) + reboot |
numa uninstall (admin) + reboot |
On macOS and Linux, numa runs as a system service (launchd/systemd). On Windows, numa auto-starts on login via registry.
Local Services
Name your dev services instead of remembering port numbers:
curl -X POST localhost:5380/services \
-d '{"name":"frontend","target_port":5173}'
Now https://frontend.numa works in your browser — green lock, valid cert, WebSocket passthrough for HMR. No mkcert, no nginx, no /etc/hosts.
Add path-based routing (app.numa/api → :5001), share services across machines via LAN discovery, or configure everything in numa.toml.
Ad Blocking & Privacy
385K+ domains blocked via Hagezi Pro. Works on any network — coffee shops, hotels, airports. Travels with your laptop.
Three resolution modes:
forward(default) — transparent proxy to your existing system DNS. Everything works as before, just with caching and ad blocking on top. Captive portals, VPNs, corporate DNS — all respected.recursive— resolve directly from root nameservers. No upstream dependency, no single entity sees your full query pattern. Add[dnssec] enabled = truefor full chain-of-trust validation.auto— probe root servers on startup, recursive if reachable, encrypted DoH fallback if blocked.
DNSSEC validates the full chain of trust: RRSIG signatures, DNSKEY verification, DS delegation, NSEC/NSEC3 denial proofs. Read how it works →
DNS-over-TLS listener (RFC 7858) — accept encrypted queries on port 853 from strict clients like iOS Private DNS, systemd-resolved, or stubby. Two modes:
- Self-signed (default) — numa generates a local CA automatically.
numa installadds it to the system trust store on macOS, Linux (Debian/Ubuntu, Fedora/RHEL/SUSE, Arch), and Windows. On iOS, install the.mobileconfigfromnuma setup-phone. Firefox keeps its own NSS store and ignores the system one — trust the CA there manually if you need HTTPS for.numaservices in Firefox. - Bring-your-own cert — point
[dot] cert_path/key_pathat a publicly-trusted cert (e.g., Let's Encrypt via DNS-01 challenge on a domain pointing at your numa instance). Clients connect without any trust-store setup — same UX as AdGuard Home or Cloudflare1.1.1.1.
ALPN "dot" is advertised and enforced in both modes; a handshake with mismatched ALPN is rejected as a cross-protocol confusion defense.
LAN Discovery
Run Numa on multiple machines. They find each other automatically via mDNS:
Machine A (192.168.1.5) Machine B (192.168.1.20)
┌──────────────────────┐ ┌──────────────────────┐
│ Numa │ mDNS │ Numa │
│ - api (port 8000) │◄───────────►│ - grafana (3000) │
│ - frontend (5173) │ discovery │ │
└──────────────────────┘ └──────────────────────┘
From Machine B: curl http://api.numa → proxied to Machine A's port 8000. Enable with numa lan on.
Hub mode: run one instance with bind_addr = "0.0.0.0:53" and point other devices' DNS to it — they get ad blocking + .numa resolution without installing anything.
How It Compares
| Pi-hole | AdGuard Home | Unbound | Numa | |
|---|---|---|---|---|
| Local service proxy + auto TLS | — | — | — | .numa domains, HTTPS, WebSocket |
| LAN service discovery | — | — | — | mDNS, zero config |
| Developer overrides (REST API) | — | — | — | Auto-revert, scriptable |
| Recursive resolver | — | — | Yes | Yes, with SRTT selection |
| DNSSEC validation | — | — | Yes | Yes (RSA, ECDSA, Ed25519) |
| Ad blocking | Yes | Yes | — | 385K+ domains |
| Web admin UI | Full | Full | — | Dashboard |
| Encrypted upstream (DoH) | Needs cloudflared | Yes | — | Native |
| Encrypted clients (DoT listener) | Needs stunnel sidecar | Yes | Yes | Native (RFC 7858) |
| Portable (laptop) | No (appliance) | No (appliance) | Server | Single binary, macOS/Linux/Windows |
| Community maturity | 56K stars, 10 years | 33K stars | 20 years | New |
Performance
691ns cached round-trip. ~2.0M qps throughput. Zero heap allocations in the hot path. Recursive queries average 237ms after SRTT warmup (12x improvement over round-robin). ECDSA P-256 DNSSEC verification: 174ns. Benchmarks →
Learn More
- Blog: Implementing DNSSEC from Scratch in Rust
- Blog: I Built a DNS Resolver from Scratch
- Configuration reference — all options documented inline
- REST API — 27 endpoints across overrides, cache, blocking, services, diagnostics
Roadmap
- DNS forwarding, caching, ad blocking, developer overrides
.numalocal domains — auto TLS, path routing, WebSocket proxy- LAN service discovery — mDNS, cross-machine DNS + proxy
- DNS-over-HTTPS — encrypted upstream
- DNS-over-TLS listener — encrypted client connections (RFC 7858, ALPN strict)
- Recursive resolution + DNSSEC — chain-of-trust, NSEC/NSEC3
- SRTT-based nameserver selection
- pkarr integration — self-sovereign DNS via Mainline DHT
- Global
.numanames — DHT-backed, no registrar
License
MIT