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)

**Il DNS che possiedi. Ovunque tu vada.** — [numa.rs](https://numa.rs)

Un resolver DNS portatile in un singolo binario. Blocca gli annunci su qualsiasi rete, assegna un nome ai tuoi servizi locali (`frontend.numa`), sovrascrivi qualsiasi hostname con ripristino automatico e sigilla ogni query in uscita con **ODoH (RFC 9230)** in modo che nessuna singola entità veda sia chi sei sia cosa hai chiesto — tutto dal tuo laptop, senza account cloud né Raspberry Pi. 

Costruito da zero in Rust. Zero librerie DNS. Caching, blocco degli annunci e domini per servizi locali inclusi. Risoluzione ricorsiva opzionale dai root nameserver con validazione completa della catena di fiducia DNSSEC, più un listener DNS-over-TLS per connessioni client cifrate (iOS Private DNS, systemd-resolved, ecc.). Esegui `numa relay` e lo stesso binario diventa anche un endpoint ODoH pubblico — la lista curata DNSCrypt attualmente ha un solo relay sopravvissuto, quindi ogni deploy di Numa espande materialmente l'ecosistema. Un binario da ~8MB, tutto incorporato. Il parser del protocollo wire è stato scritto a mano come progetto di apprendimento; le funzionalità successive (resolver ricorsivo, DNSSEC, dashboard) sono state costruite con l'assistenza dell'IA.

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

## Avvio Rapido

Tre modi per iniziare, dal meno al più impegnativo. Solo il terzo modifica il DNS di sistema.

### 1. Provalo in Docker (niente installato sull'host)

```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
```

Apri `http://localhost:5380` e accedi con un qualsiasi username e quel token. La porta 5553 aggira qualunque cosa occupi già la 53 sull'host. `numa.numa` non si risolverà qui, perché l'host non sta usando Numa per il DNS. Pulisci con `docker rm -f numa`.

### 2. Esegui in primo piano (DNS di sistema intatto)

Installa il binario:

```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 ascolta sulla porta 53, ma il tuo sistema mantiene il resolver attuale finché non esegui `numa install`, quindi testa con `dig @127.0.0.1 example.com`. La dashboard è su `http://localhost:5380`. Se la porta 53 è occupata (systemd-resolved su Ubuntu/Mint), imposta `bind_addr` in [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml) o usa Docker.

### 3. Imposta come DNS di sistema

| Piattaforma | Installazione | Disinstallazione |
|----------|---------|-----------|
| macOS | `sudo numa install` | `sudo numa uninstall` |
| Linux | `sudo numa install` | `sudo numa uninstall` |
| Windows | `numa install` (admin) + riavvio | `numa uninstall` (admin) + riavvio |

`install` registra un servizio, punta il DNS di sistema a Numa e si fida della sua CA locale. `uninstall` inverte tutte e tre le cose. Una volta installato, la dashboard è anche su **http://numa.numa**.

Su macOS e Linux, numa viene eseguito come servizio di sistema (launchd/systemd). L'unit systemd è non privilegiata (`DynamicUser=yes`, solo `CAP_NET_BIND_SERVICE`); il daemon launchd viene eseguito come root. `numa install` riconfigura systemd-resolved tramite un drop-in che `numa uninstall` rimuove; qualsiasi altro processo che occupa la porta 53 (dnsmasq, incluso quello di NetworkManager) deve essere fermato a mano. Su Windows, numa si avvia automaticamente al login tramite il registro. Windows associa anche `127.0.0.2:53` (il Dnscache integrato possiede `127.0.0.1:53`) e installa una regola NRPT per instradare le query lì — quindi modifica `bind_addr`/`api_bind_addr` su `127.0.0.2`, non `127.0.0.1`.

### Accesso

Tramite loopback (`localhost`, `127.0.0.1`, `numa.numa`) non è richiesto il login. Per qualsiasi altro caso, incluso il port mapping di Docker o l'indirizzo LAN di questa macchina, viene richiesto il token API, che Numa genera al primo avvio. Stampalo con `sudo numa token` (una shell amministratore su Windows) e accedi con un qualsiasi username. Fissa il tuo con `[server] api_token` o `NUMA_API_TOKEN`.

### Rimuovere ogni traccia

`uninstall` ripristina il DNS ma mantiene la directory dei dati, quindi una reinstallazione mantiene lo stesso token e la stessa CA. Per rimuovere tutto, disinstalla prima, poi elimina:

| Piattaforma | Cosa rimane |
|----------|-------------|
| macOS | il binario, `/usr/local/var/numa`, `/usr/local/var/log/numa.log` |
| Linux | il binario (`/usr/local/bin/numa` da install.sh), `/var/lib/numa`, `/etc/numa` |
| Windows | il binario, `%PROGRAMDATA%\numa` |

Le installazioni tramite package manager rimuovono il binario con `brew uninstall`, `pacman -R` o `cargo uninstall`. Su Linux, `numa install` copia un binario che non può eseguire dalla sua posizione originale (es. `~/.cargo/bin`) in `/usr/local/bin/numa`, e la disinstallazione lascia quella copia.

Elimina anche `~/.config/numa` se hai creato una configurazione utente, e il percorso `[server] data_dir` se ne hai impostato uno.

## Servizi Locali

Assegna un nome ai tuoi servizi di sviluppo invece di ricordare i numeri di porta:

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

Ora `https://frontend.numa` funziona nel tuo browser — lucchetto verde, certificato valido, passthrough WebSocket per HMR. Niente mkcert, niente nginx, niente `/etc/hosts`.

Aggiungi routing basato su percorso (`app.numa/api → :5001`), condividi servizi tra macchine tramite LAN discovery, o configura tutto in [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml).

## Blocco Annunci e Privacy

Blocco di annunci e tracker tramite [Hagezi Pro](https://github.com/hagezi/dns-blocklists), aggiornato quotidianamente. Funziona su qualsiasi rete — bar, hotel, aeroporti. Viaggia con il tuo laptop.

Tre modalità di risoluzione:

- **`forward`** (predefinita) — proxy trasparente verso il tuo DNS di sistema esistente. Tutto funziona come prima, solo con caching e blocco annunci in più. Captive portal, VPN, DNS aziendali — tutto rispettato.
- **`recursive`** — risolve direttamente dai root nameserver. Nessuna dipendenza upstream, nessuna singola entità vede il tuo pattern completo di query. Aggiungi `[dnssec] enabled = true` per la validazione completa della catena di fiducia.
- **`auto`** — sonda i root server all'avvio, ricorsivo se raggiungibile, altrimenti forward su DoH verso Quad9 (`https://9.9.9.9/dns-query`), che quindi vede le tue query. Usa `forward` con il tuo `[upstream]` per scegliere un provider diverso.

DNSSEC valida l'intera catena di fiducia: firme RRSIG, verifica DNSKEY, delega DS, prove di diniego NSEC/NSEC3. [Leggi come funziona →](https://numa.rs/blog/posts/dnssec-from-scratch.html)

**Listener DNS-over-TLS** (RFC 7858) — accetta query cifrate sulla porta 853 da client rigorosi come iOS Private DNS, systemd-resolved o stubby. Due modalità:

- **Self-signed** (predefinita) — numa genera automaticamente una CA locale. `numa install` la aggiunge al trust store di sistema su macOS, Linux (Debian/Ubuntu, Fedora/RHEL/SUSE, Arch) e Windows, e `numa uninstall` la rimuove. Su iOS, installa il `.mobileconfig` da `numa setup-phone`. Firefox mantiene il proprio store NSS e ignora quello di sistema — fidati della CA lì manualmente se hai bisogno di HTTPS per i servizi `.numa` in Firefox.
- **Bring-your-own cert** — punta `[dot] cert_path` / `key_path` a un certificato pubblicamente fidato (es. Let's Encrypt tramite challenge DNS-01 su un dominio che punta alla tua istanza numa). I client si connettono senza alcuna configurazione del trust store — stessa UX di AdGuard Home o Cloudflare `1.1.1.1`.

ALPN `"dot"` è annunciato e applicato in entrambe le modalità; un handshake con ALPN non corrispondente viene rifiutato come difesa contro la confusione cross-protocol.

**Oblivious DoH** (RFC 9230) — con `[upstream] mode = "odoh"` ([ricetta](https://github.com/razvandimescu/numa/blob/main/recipes/odoh-upstream.md)) ogni query è sigillata con HPKE verso il target e inviata attraverso un relay. Il relay vede il tuo IP e il ciphertext, il target vede la domanda e l'IP del relay, e un relay che reindirizza la query consegna alla nuova destinazione qualcosa che non può decifrare. Numa rifiuta un relay e un target che condividono un dominio registrabile. ODoH non nasconde la connessione che apri successivamente: il tuo ISP vede comunque l'IP di destinazione e, senza ECH, l'hostname nell'handshake TLS.

**Configurazione telefono** — punta il tuo iPhone o Android a Numa in un solo passaggio:

```bash
numa setup-phone
```

Stampa un codice QR. Scansionalo, installa il profilo, attiva la fiducia del certificato — il DNS del tuo telefono ora passa attraverso Numa su TLS. Richiede `[mobile] enabled = true` in `numa.toml`.

## LAN Discovery

Esegui Numa su più macchine. Si trovano automaticamente tramite mDNS:

```
Machine A (192.168.1.5)              Machine B (192.168.1.20)
┌──────────────────────┐             ┌──────────────────────┐
│ Numa                 │    mDNS     │ Numa                 │
│  - api (port 8000)   │◄───────────►│  - grafana (3000)    │
│  - frontend (5173)   │  discovery  │                      │
└──────────────────────┘             └──────────────────────┘
```

Dalla Macchina B: `curl http://api.numa` → inoltrato alla porta 8000 della Macchina A. Abilita con `numa lan on`.

**Modalità hub**: esegui un'istanza con `bind_addr = "0.0.0.0:53"` e punta il DNS degli altri dispositivi ad essa — ottengono blocco annunci + risoluzione `.numa` senza installare nulla. `bind_addr` accetta anche una lista per associare un sottoinsieme specifico di interfacce. Passo dopo passo: [ricetta network-wide](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 su `http://localhost:5380`. Con il port mapping o da un altro dispositivo, accedi con un qualsiasi username e il token da `docker exec numa numa token`. Il volume `numa-data` mantiene il token e la CA locale attraverso le ricreazioni del container. L'immagine associa l'API e il proxy a `0.0.0.0` per impostazione predefinita. Sovrascrivi con una configurazione personalizzata:

```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` e `linux/arm64`.

Ricette compose chiavi in mano:
- [`packaging/client/`](https://github.com/razvandimescu/numa/blob/main/packaging/client) — modalità client ODoH (DNS anonimo), Numa + `numa.toml` iniziale.
- [`packaging/relay/`](https://github.com/razvandimescu/numa/blob/main/packaging/relay) — relay ODoH pubblico, Numa + Caddy + ACME.

## Come Si Confronta

| | Pi-hole | AdGuard Home | Unbound | Numa |
|---|---|---|---|---|
| Proxy servizi locali + TLS automatico | — | — | — | domini `.numa`, HTTPS, WebSocket |
| LAN service discovery | — | — | — | mDNS, zero config |
| Override sviluppatore (REST API) | — | — | — | Auto-revert, scriptabile |
| Resolver ricorsivo | — | — | Sì | Sì, con selezione SRTT |
| Validazione DNSSEC | — | — | Sì | Sì (RSA, ECDSA, Ed25519) |
| Blocco annunci | Sì | Sì | — | Hagezi Pro |
| Regole per-client | Gruppi | Sì | Views / tags | Per CIDR (`[[client_policy]]`), solo file di configurazione |
| Web admin UI | Completa | Completa | — | Dashboard |
| Upstream cifrato (DoH/DoT) | Richiede cloudflared | Solo DoH | Solo DoT | DoH + DoT (`tls://`) |
| Client cifrati (listener DoT) | Richiede sidecar stunnel | Sì | Sì | Nativo (RFC 7858) |
| Endpoint server DoH | — | Sì | — | Sì (RFC 8484) |
| Request hedging | — | — | — | Tutti i protocolli (UDP, DoH, DoT) |
| Serve-stale + prefetch | — | — | Prefetch al 90% del TTL | RFC 8767, prefetch al 90% del TTL |
| Conditional forwarding | — | Sì | Sì | Sì (regole per-suffisso) |
| Portatile (laptop) | No (appliance) | No (appliance) | Server | Singolo binario, macOS/Linux/Windows |
| Maturità della community | 56K stelle, 10 anni | 33K stelle | 20 anni | Nuovo |

## Eseguire Numa come DNS Primario

**Se Numa si ferma.** `numa install` registra Numa con launchd (macOS) o systemd (Linux), che lo riavviano quando esce. Se Numa è il tuo unico resolver, le risoluzioni DNS falliscono finché non si riavvia. Per smettere di usare Numa e ripristinare le impostazioni DNS precedenti della macchina, esegui `sudo numa uninstall`.

Se Numa è in esecuzione ma gli upstream sono irraggiungibili, può servire risposte in cache fino a un'ora oltre il loro TTL (RFC 8767). I nomi che non ha in cache falliscono.

**Test.** Il parser DNS viene sottoposto a fuzzing su ogni pull request che lo tocca, con esecuzioni più lunghe settimanalmente ([`fuzz.yml`](https://github.com/razvandimescu/numa/blob/main/.github/workflows/fuzz.yml)). La CI esegue `cargo audit` sulle dipendenze e installa, reinstalla e disinstalla Numa su macOS e Linux.

**Hardening del resolver.** In modalità ricorsiva, Numa scarta i record di risposta al di fuori della zona interrogata, rifiuta di interrogare nameserver ad indirizzi privati o loopback, e limita le query upstream e la profondità di referral di ogni lookup. Le risposte su UDP semplice devono corrispondere all'ID di transazione casuale e alla domanda della query. Le query ANY vengono rifiutate. La validazione DNSSEC è disattivata per impostazione predefinita; `numa dnssec on` la attiva. Per segnalare una vulnerabilità in privato, vedi [SECURITY.md](https://github.com/razvandimescu/numa/blob/main/SECURITY.md).

**Cosa Numa non fa.** Niente DHCP, niente clustering, niente sincronizzazione di configurazione tra istanze. La maggior parte delle impostazioni risiede in [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml), non nella dashboard. Per un'intera rete, eseguilo su una macchina che rimane accesa.

## Prestazioni

Query in cache da 0.1ms — alla pari con Unbound e AdGuard Home. La cache a livello wire memorizza i byte grezzi con patching TTL in-place. Il request hedging elimina i picchi p99: p99 ricorsivo a freddo 538ms vs Unbound 748ms (−28%), σ 4× più stretto. [Benchmark →](https://github.com/razvandimescu/numa/blob/main/benches)

## Saperne di Più

- [Blog: Numa come resolver del tuo tailnet](https://numa.rs/blog/posts/numa-tailnet-resolver.html)
- [Blog: DNS-over-TLS da Zero in Rust](https://numa.rs/blog/posts/dot-from-scratch.html)
- [Blog: Implementare DNSSEC da Zero in Rust](https://numa.rs/blog/posts/dnssec-from-scratch.html)
- [Blog: Ho Costruito un Resolver DNS da Zero](https://numa.rs/blog/posts/dns-from-scratch.html)
- [Riferimento configurazione](https://github.com/razvandimescu/numa/blob/main/numa.toml) — tutte le opzioni documentate inline; `numa config path` mostra quale file sta usando la tua installazione, `numa config edit` lo apre
- [REST API](https://github.com/razvandimescu/numa/blob/main/src/api.rs) — override, cache, blocco, servizi, diagnostica
- [numa-metrics](https://github.com/razvandimescu/numa-metrics) — cronologia query durevole e analytics, off-host by design (nessuna scrittura su SD-card)

## Roadmap

- [x] DNS forwarding, caching, blocco annunci, override sviluppatore
- [x] Domini locali `.numa` — TLS automatico, path routing, proxy WebSocket
- [x] LAN service discovery — mDNS, DNS + proxy cross-machine
- [x] DNS-over-HTTPS — upstream cifrato + endpoint server (RFC 8484)
- [x] DNS-over-TLS — listener client cifrato (RFC 7858) + forwarding upstream (`tls://`)
- [x] Oblivious DoH — modalità client anonimizzata + relay pubblico (`numa relay`, RFC 9230)
- [x] Risoluzione ricorsiva + DNSSEC — catena di fiducia, NSEC/NSEC3
- [x] Selezione nameserver basata su SRTT
- [x] Failover multi-forwarder — upstream multipli con ranking SRTT, pool di fallback
- [x] Request hedging — richieste parallele che salvano da perdita di pacchetti e latenza di coda (tutti i protocolli)
- [x] Serve-stale + prefetch — RFC 8767, refresh in background a <10% TTL e su servizio stale
- [x] Conditional forwarding — regole per-suffisso per DNS split-horizon (Tailscale, VPN)
- [x] Cache warming — risoluzione proattiva per domini configurati
- [x] Onboarding mobile — flusso QR `setup-phone`, API mobile, profili mobileconfig
- [ ] Integrazione pkarr — DNS self-sovereign via Mainline DHT
- [ ] Nomi globali `.numa` — basati su DHT, senza registrar

## Licenza

MIT