numa

# Numa

[![CI](https://github.com/razvandimescu/numa/actions/workflows/ci.yml/badge.svg)](https://github.com/razvandimescu/numa/actions)
[![crates.io](https://img.shields.io/crates/v/numa.svg)](https://crates.io/crates/numa)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**DNS, der dir gehört. Überall, wo du hingehst.** — [numa.rs](https://numa.rs)

Ein portabler DNS-Resolver in einer einzigen Binary. Blockiere Werbung in jedem Netzwerk, benenne deine lokalen Dienste (`frontend.numa`), überschreibe jeden Hostnamen mit automatischem Zurücksetzen und versiegle jede ausgehende Abfrage mit **ODoH (RFC 9230)**, sodass keine einzelne Partei sowohl sieht, wer du bist, als auch, was du gefragt hast — alles von deinem Laptop aus, ohne Cloud-Konto oder Raspberry Pi.

Von Grund auf in Rust entwickelt. Keine DNS-Bibliotheken. Caching, Werbeblockierung und lokale Dienst-Domains von Haus aus. Optionale rekursive Auflösung von Root-Nameservern mit vollständiger DNSSEC-Vertrauenskette-Validierung, plus ein DNS-over-TLS-Listener für verschlüsselte Client-Verbindungen (iOS Private DNS, systemd-resolved, etc.). Führe `numa relay` aus und dieselbe Binary wird auch zu einem öffentlichen ODoH-Endpunkt — die kuratierte DNSCrypt-Liste hat derzeit nur einen überlebenden Relay, also erweitert jedes Numa-Deployment das Ökosystem materiell. Eine ~8MB Binary, alles eingebettet. Der Wire-Protocol-Parser wurde als Lernprojekt von Hand geschrieben; spätere Features (rekursiver Resolver, DNSSEC, Dashboard) wurden mit KI-Unterstützung gebaut.

![Numa dashboard](https://assets.kitploit.com/production/public/readmes/13090/5d6f10865bf168b1b4d4b8a8223ff961e66cfc2fe7f91754e71f105f2f921cc0.gif)

## Schnellstart

Drei Wege hinein, von am wenigsten bis am meisten Verbindlichkeit. Nur der dritte ändert dein System-DNS.

### 1. In Docker ausprobieren (nichts auf dem Host installiert)

```bash
docker run -d --name numa -p 127.0.0.1:5553:53/udp -p 127.0.0.1:5553:53/tcp \
  -p 127.0.0.1:5380:5380 ghcr.io/razvandimescu/numa
dig @127.0.0.1 -p 5553 example.com
docker exec numa numa token            # dashboard password
```

Öffne `http://localhost:5380` und melde dich mit einem beliebigen Benutzernamen und diesem Token an. Port 5553 umgeht alles, was auf dem Host bereits 53 belegt. `numa.numa` wird hier nicht aufgelöst, weil der Host Numa nicht für DNS verwendet. Aufräumen mit `docker rm -f numa`.

### 2. Im Vordergrund ausführen (System-DNS unberührt)

Installiere die Binary:

```bash
# macOS
brew install razvandimescu/tap/numa

# Linux
curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh

# Arch Linux
pacman -S numa

# Windows — download from GitHub Releases
# All platforms
cargo install numa

# Nix
nix run github:razvandimescu/numa
```

```bash
sudo numa                              # Ctrl-C to stop (port 53 requires root/admin)
```

Numa lauscht auf Port 53, aber dein System behält seinen aktuellen Resolver, bis du `numa install` ausführst, also teste mit `dig @127.0.0.1 example.com`. Das Dashboard ist unter `http://localhost:5380` erreichbar. Wenn Port 53 belegt ist (systemd-resolved unter Ubuntu/Mint), setze `bind_addr` in [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml) oder verwende Docker.

### 3. Als System-DNS einrichten

| Plattform | Installation | Deinstallation |
|----------|---------|-----------|
| macOS | `sudo numa install` | `sudo numa uninstall` |
| Linux | `sudo numa install` | `sudo numa uninstall` |
| Windows | `numa install` (admin) + reboot | `numa uninstall` (admin) + reboot |

`install` registriert einen Dienst, richtet das System-DNS auf Numa aus und vertraut dessen lokaler CA. `uninstall` macht alle drei rückgängig. Nach der Installation ist das Dashboard auch unter **http://numa.numa** erreichbar.

Unter macOS und Linux läuft numa als Systemdienst (launchd/systemd). Die systemd-Unit ist unprivilegiert (`DynamicUser=yes`, nur `CAP_NET_BIND_SERVICE`); der launchd-Daemon läuft als root. `numa install` konfiguriert systemd-resolved über ein Drop-in um, das `numa uninstall` entfernt; jeder andere Prozess, der Port 53 belegt (dnsmasq, einschließlich des von NetworkManager), muss manuell gestoppt werden. Unter Windows startet numa automatisch bei der Anmeldung über die Registry. Windows bindet außerdem `127.0.0.2:53` (der integrierte Dnscache besitzt `127.0.0.1:53`) und installiert eine NRPT-Regel, um Abfragen dorthin zu leiten — also bearbeite `bind_addr`/`api_bind_addr` gegen `127.0.0.2`, nicht `127.0.0.1`.

### Anmelden

Über Loopback (`localhost`, `127.0.0.1`, `numa.numa`) ist keine Anmeldung erforderlich. Bei allem anderen, einschließlich Docker-Port-Mapping oder der LAN-Adresse dieser Maschine, wird das API-Token verlangt, das Numa beim ersten Start generiert. Gib es mit `sudo numa token` aus (unter Windows eine Administrator-Shell) und melde dich mit einem beliebigen Benutzernamen an. Lege dein eigenes fest mit `[server] api_token` oder `NUMA_API_TOKEN`.

### Jede Spur entfernen

`uninstall` stellt DNS wieder her, behält aber das Datenverzeichnis, sodass eine Neuinstallation dasselbe Token und dieselbe CA behält. Um alles zu entfernen, zuerst deinstallieren, dann löschen:

| Plattform | Zurückgelassen |
|----------|-------------|
| macOS | die Binary, `/usr/local/var/numa`, `/usr/local/var/log/numa.log` |
| Linux | die Binary (`/usr/local/bin/numa` von install.sh), `/var/lib/numa`, `/etc/numa` |
| Windows | die Binary, `%PROGRAMDATA%\numa` |

Paketmanager-Installationen entfernen die Binary mit `brew uninstall`, `pacman -R` oder `cargo uninstall`. Unter Linux kopiert `numa install` eine Binary, die es von ihrem ursprünglichen Speicherort (z. B. `~/.cargo/bin`) nicht ausführen kann, nach `/usr/local/bin/numa`, und die Deinstallation lässt diese Kopie zurück.

Lösche außerdem `~/.config/numa`, wenn du eine Benutzerkonfiguration erstellt hast, und den Pfad `[server] data_dir`, wenn du einen festgelegt hast.

## Lokale Dienste

Benenne deine Dev-Dienste, statt dir Portnummern zu merken:

```bash
curl -X POST localhost:5380/services \
  -d '{"name":"frontend","target_port":5173}'
```

Jetzt funktioniert `https://frontend.numa` in deinem Browser — grünes Schloss, gültiges Zertifikat, WebSocket-Passthrough für HMR. Kein mkcert, kein nginx, keine `/etc/hosts`.

Füge pfadbasiertes Routing hinzu (`app.numa/api → :5001`), teile Dienste über Maschinen hinweg via LAN-Discovery oder konfiguriere alles in [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml).

## Werbeblockierung & Datenschutz

Werbung- und Tracker-Blockierung via [Hagezi Pro](https://github.com/hagezi/dns-blocklists), täglich aktualisiert. Funktioniert in jedem Netzwerk — Cafés, Hotels, Flughäfen. Reist mit deinem Laptop.

Drei Auflösungsmodi:

- **`forward`** (Standard) — transparenter Proxy zu deinem bestehenden System-DNS. Alles funktioniert wie zuvor, nur mit Caching und Werbeblockierung obendrauf. Captive Portals, VPNs, Corporate DNS — alles respektiert.
- **`recursive`** — direkt von Root-Nameservern auflösen. Keine Upstream-Abhängigkeit, keine einzelne Entität sieht dein vollständiges Abfragemuster. Füge `[dnssec] enabled = true` für vollständige Vertrauenskette-Validierung hinzu.
- **`auto`** — Root-Server beim Start prüfen, rekursiv wenn erreichbar, sonst Forward über DoH zu Quad9 (`https://9.9.9.9/dns-query`), das dann deine Abfragen sieht. Verwende `forward` mit deinem eigenen `[upstream]`, um einen anderen Anbieter zu wählen.

DNSSEC validiert die vollständige Vertrauenskette: RRSIG-Signaturen, DNSKEY-Verifikation, DS-Delegation, NSEC/NSEC3-Verweigerungsnachweise. [Lies, wie es funktioniert →](https://numa.rs/blog/posts/dnssec-from-scratch.html)

**DNS-over-TLS-Listener** (RFC 7858) — akzeptiere verschlüsselte Abfragen auf Port 853 von strikten Clients wie iOS Private DNS, systemd-resolved oder stubby. Zwei Modi:

- **Selbstsigniert** (Standard) — numa generiert automatisch eine lokale CA. `numa install` fügt sie dem System-Trust-Store unter macOS, Linux (Debian/Ubuntu, Fedora/RHEL/SUSE, Arch) und Windows hinzu, und `numa uninstall` entfernt sie. Unter iOS installiere die `.mobileconfig` von `numa setup-phone`. Firefox führt seinen eigenen NSS-Store und ignoriert den System-Store — vertraue der CA dort manuell, wenn du HTTPS für `.numa`-Dienste in Firefox benötigst.
- **Eigenes Zertifikat mitbringen** — richte `[dot] cert_path` / `key_path` auf ein öffentlich vertrauenswürdiges Zertifikat (z. B. Let's Encrypt via DNS-01-Challenge auf einer Domain, die auf deine numa-Instanz zeigt). Clients verbinden sich ohne jegliche Trust-Store-Einrichtung — gleiche UX wie AdGuard Home oder Cloudflare `1.1.1.1`.

ALPN `"dot"` wird in beiden Modi beworben und erzwungen; ein Handshake mit nicht übereinstimmendem ALPN wird als Cross-Protocol-Confusion-Verteidigung abgelehnt.

**Oblivious DoH** (RFC 9230) — mit `[upstream] mode = "odoh"` ([Rezept](https://github.com/razvandimescu/numa/blob/main/recipes/odoh-upstream.md)) wird jede Abfrage HPKE-versiegelt an das Ziel gesendet und durch einen Relay geleitet. Der Relay sieht deine IP und den Chiffretext, das Ziel sieht die Frage und die IP des Relays, und ein Relay, der die Abfrage umleitet, übergibt dem neuen Ziel etwas, das es nicht entschlüsseln kann. Numa lehnt einen Relay und ein Ziel ab, die sich eine registrierbare Domain teilen. ODoH verbirgt nicht die Verbindung, die du danach öffnest: Dein ISP sieht weiterhin die Ziel-IP und, ohne ECH, den Hostnamen im TLS-Handshake.

**Telefon-Einrichtung** — richte dein iPhone oder Android in einem Schritt auf Numa aus:

```bash
numa setup-phone
```

Gibt einen QR-Code aus. Scanne ihn, installiere das Profil, aktiviere das Zertifikatsvertrauen — das DNS deines Telefons läuft jetzt über Numa via TLS. Erfordert `[mobile] enabled = true` in `numa.toml`.

## LAN-Discovery

Betreibe Numa auf mehreren Maschinen. Sie finden sich automatisch 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  │                      │
└──────────────────────┘             └──────────────────────┘
```

Von Maschine B: `curl http://api.numa` → weitergeleitet an Port 8000 von Maschine A. Aktivieren mit `numa lan on`.

**Hub-Modus**: Betreibe eine Instanz mit `bind_addr = "0.0.0.0:53"` und richte das DNS anderer Geräte darauf aus — sie erhalten Werbeblockierung + `.numa`-Auflösung, ohne etwas zu installieren. `bind_addr` akzeptiert auch eine Liste, um eine bestimmte Teilmenge von Interfaces zu binden. Schritt für Schritt: [netzwerkweites Rezept](https://github.com/razvandimescu/numa/blob/main/recipes/network-wide.md).

## Docker

```bash
# Recommended — host networking (Linux)
docker run -d --name numa --network host -v numa-data:/var/lib/numa ghcr.io/razvandimescu/numa

# Port mapping (macOS/Windows Docker Desktop)
docker run -d --name numa -p 53:53/udp -p 53:53/tcp -p 5380:5380 -v numa-data:/var/lib/numa ghcr.io/razvandimescu/numa
```

Dashboard unter `http://localhost:5380`. Bei Port-Mapping oder von einem anderen Gerät aus melde dich mit einem beliebigen Benutzernamen und dem Token von `docker exec numa numa token` an. Das Volume `numa-data` behält das Token und die lokale CA über Container-Neuerstellungen hinweg. Das Image bindet die API und den Proxy standardmäßig an `0.0.0.0`. Überschreibe mit einer benutzerdefinierten Konfiguration:

```bash
docker run -d --name numa --network host -v numa-data:/var/lib/numa \
  -v /path/to/numa.toml:/root/.config/numa/numa.toml \
  ghcr.io/razvandimescu/numa
```

Multi-Arch: `linux/amd64` und `linux/arm64`.

Turnkey-Compose-Rezepte:
- [`packaging/client/`](https://github.com/razvandimescu/numa/blob/main/packaging/client) — ODoH-Client-Modus (anonymes DNS), Numa + Starter-`numa.toml`.
- [`packaging/relay/`](https://github.com/razvandimescu/numa/blob/main/packaging/relay) — öffentlicher ODoH-Relay, Numa + Caddy + ACME.

## Wie es sich vergleicht

| | Pi-hole | AdGuard Home | Unbound | Numa |
|---|---|---|---|---|
| Lokaler Dienst-Proxy + Auto-TLS | — | — | — | `.numa`-Domains, HTTPS, WebSocket |
| LAN-Dienst-Discovery | — | — | — | mDNS, Zero-Config |
| Entwickler-Overrides (REST API) | — | — | — | Auto-Revert, skriptbar |
| Rekursiver Resolver | — | — | Ja | Ja, mit SRTT-Auswahl |
| DNSSEC-Validierung | — | — | Ja | Ja (RSA, ECDSA, Ed25519) |
| Werbeblockierung | Ja | Ja | — | Hagezi Pro |
| Pro-Client-Regeln | Gruppen | Ja | Views / Tags | Nach CIDR (`[[client_policy]]`), nur Konfigurationsdatei |
| Web-Admin-UI | Vollständig | Vollständig | — | Dashboard |
| Verschlüsselter Upstream (DoH/DoT) | Benötigt cloudflared | Nur DoH | Nur DoT | DoH + DoT (`tls://`) |
| Verschlüsselte Clients (DoT-Listener) | Benötigt stunnel-Sidecar | Ja | Ja | Nativ (RFC 7858) |
| DoH-Server-Endpunkt | — | Ja | — | Ja (RFC 8484) |
| Request-Hedging | — | — | — | Alle Protokolle (UDP, DoH, DoT) |
| Serve-Stale + Prefetch | — | — | Prefetch bei 90% TTL | RFC 8767, Prefetch bei 90% TTL |
| Conditional Forwarding | — | Ja | Ja | Ja (Regeln pro Suffix) |
| Portabel (Laptop) | Nein (Appliance) | Nein (Appliance) | Server | Einzelne Binary, macOS/Linux/Windows |
| Community-Reife | 56K Stars, 10 Jahre | 33K Stars | 20 Jahre | Neu |

## Numa als primäres DNS betreiben

**Wenn Numa stoppt.** `numa install` registriert Numa bei launchd (macOS) oder systemd (Linux), die es bei Beendigung neu starten. Wenn Numa dein einziger Resolver ist, schlagen DNS-Abfragen fehl, bis es neu startet. Um Numa nicht mehr zu verwenden und die vorherigen DNS-Einstellungen der Maschine wiederherzustellen, führe `sudo numa uninstall` aus.

Wenn Numa läuft, aber Upstreams nicht erreichbar sind, kann es gecachte Antworten bis zu einer Stunde über deren TTL hinaus ausliefern (RFC 8767). Namen, die es nicht gecacht hat, schlagen fehl.

**Testen.** Der DNS-Parser wird bei jedem Pull Request, der ihn berührt, gefuzzt, mit längeren Läufen wöchentlich ([`fuzz.yml`](https://github.com/razvandimescu/numa/blob/main/.github/workflows/fuzz.yml)). CI führt `cargo audit` auf Abhängigkeiten aus und installiert, reinstalled und deinstalliert Numa unter macOS und Linux.

**Resolver-Härtung.** Im rekursiven Modus verwirft Numa Antwortdatensätze außerhalb der abgefragten Zone, weigert sich, Nameserver an privaten oder Loopback-Adressen abzufragen, und begrenzt die Upstream-Abfragen und die Referral-Tiefe jeder Suche. Antworten über einfaches UDP müssen mit der zufälligen Transaktions-ID und der Frage der Abfrage übereinstimmen. ANY-Abfragen werden abgelehnt. DNSSEC-Validierung ist standardmäßig aus; `numa dnssec on` schaltet sie ein. Um eine Schwachstelle privat zu melden, siehe [SECURITY.md](https://github.com/razvandimescu/numa/blob/main/SECURITY.md).

**Was Numa nicht tut.** Kein DHCP, kein Clustering, keine Konfigurationssynchronisation zwischen Instanzen. Die meisten Einstellungen leben in [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml), nicht im Dashboard. Für ein ganzes Netzwerk betreibe es auf einer Maschine, die eingeschaltet bleibt.

## Leistung

0,1ms gecachte Abfragen — gleichauf mit Unbound und AdGuard Home. Der Wire-Level-Cache speichert Rohbytes mit In-Place-TTL-Patching. Request-Hedging eliminiert p99-Spitzen: kalte rekursive p99 538ms vs Unbound 748ms (−28%), σ 4× enger. [Benchmarks →](https://github.com/razvandimescu/numa/blob/main/benches)

## Mehr erfahren

- [Blog: Numa als dein Tailnet-Resolver](https://numa.rs/blog/posts/numa-tailnet-resolver.html)
- [Blog: DNS-over-TLS von Grund auf in Rust](https://numa.rs/blog/posts/dot-from-scratch.html)
- [Blog: DNSSEC von Grund auf in Rust implementieren](https://numa.rs/blog/posts/dnssec-from-scratch.html)
- [Blog: Ich habe einen DNS-Resolver von Grund auf gebaut](https://numa.rs/blog/posts/dns-from-scratch.html)
- [Konfigurationsreferenz](https://github.com/razvandimescu/numa/blob/main/numa.toml) — alle Optionen inline dokumentiert; `numa config path` zeigt, welche Datei deine Installation verwendet, `numa config edit` öffnet sie
- [REST API](https://github.com/razvandimescu/numa/blob/main/src/api.rs) — Overrides, Cache, Blockierung, Dienste, Diagnose
- [numa-metrics](https://github.com/razvandimescu/numa-metrics) — dauerhafte Abfragehistorie & Analytik, by design außerhalb des Hosts (keine SD-Karten-Schreibvorgänge)

## Roadmap

- [x] DNS-Forwarding, Caching, Werbeblockierung, Entwickler-Overrides
- [x] `.numa`-lokale Domains — Auto-TLS, Pfad-Routing, WebSocket-Proxy
- [x] LAN-Dienst-Discovery — mDNS, maschinenübergreifendes DNS + Proxy
- [x] DNS-over-HTTPS — verschlüsselter Upstream + Server-Endpunkt (RFC 8484)
- [x] DNS-over-TLS — verschlüsselter Client-Listener (RFC 7858) + Upstream-Forwarding (`tls://`)
- [x] Oblivious DoH — anonymisierter Client-Modus + öffentlicher Relay (`numa relay`, RFC 9230)
- [x] Rekursive Auflösung + DNSSEC — Vertrauenskette, NSEC/NSEC3
- [x] SRTT-basierte Nameserver-Auswahl
- [x] Multi-Forwarder-Failover — mehrere Upstreams mit SRTT-Ranking, Fallback-Pool
- [x] Request-Hedging — parallele Anfragen retten Paketverlust und Tail-Latenz (alle Protokolle)
- [x] Serve-Stale + Prefetch — RFC 8767, Hintergrund-Aktualisierung bei <10% TTL und bei Stale-Serve
- [x] Conditional Forwarding — Regeln pro Suffix für Split-Horizon-DNS (Tailscale, VPNs)
- [x] Cache-Warming — proaktive Auflösung für konfigurierte Domains
- [x] Mobile Onboarding — `setup-phone` QR-Flow, Mobile-API, mobileconfig-Profile
- [ ] pkarr-Integration — selbstsouveränes DNS via Mainline DHT
- [ ] Globale `.numa`-Namen — DHT-gestützt, kein Registrar

## Lizenz

MIT