razvandimescu/numaRésolveur DNS portable en Rust — domaines locaux .numa, blocage des publicités, remplacements pour développeurs
# Numa
[](https://github.com/razvandimescu/numa/actions)
[](https://crates.io/crates/numa)
[](LICENSE)
**Votre DNS, partout où vous allez.** — [numa.rs](https://numa.rs)
Un résolveur DNS portable dans un seul binaire. Bloquez les publicités sur n'importe quel réseau, nommez vos services locaux (`frontend.numa`), remplacez n'importe quel nom d'hôte avec rétablissement automatique, et scellez chaque requête sortante avec **ODoH (RFC 9230)** afin qu'aucune entité unique ne voie à la fois qui vous êtes et ce que vous avez demandé — le tout depuis votre ordinateur portable, sans compte cloud ni Raspberry Pi requis.
Construit de zéro en Rust. Zéro bibliothèque DNS. Mise en cache, blocage de publicités et domaines de services locaux dès la sortie de la boîte. Résolution récursive optionnelle depuis les serveurs de noms racines avec validation complète de la chaîne de confiance DNSSEC, plus un écouteur DNS-over-TLS pour les connexions client chiffrées (iOS Private DNS, systemd-resolved, etc.). Lancez `numa relay` et le même binaire devient aussi un point de terminaison ODoH public — la liste DNSCrypt sélectionnée ne compte actuellement qu'un seul relais survivant, donc chaque déploiement de Numa élargit matériellement l'écosystème. Un binaire d'environ 8 Mo, tout intégré. Le parseur de protocole réseau a été écrit à la main comme projet d'apprentissage ; les fonctionnalités ultérieures (résolveur récursif, DNSSEC, tableau de bord) ont été construites avec l'aide de l'IA.
## Démarrage rapide
Trois façons de commencer, du moins engageant au plus engageant. Seule la troisième modifie le DNS de votre système.
### 1. Essayez-le dans Docker (rien d'installé sur l'hôte)
```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
```
Ouvrez `http://localhost:5380` et connectez-vous avec n'importe quel nom d'utilisateur et ce jeton. Le port 5553 contourne ce qui occupe déjà le port 53 sur l'hôte. `numa.numa` ne se résoudra pas ici, car l'hôte n'utilise pas Numa pour le DNS. Nettoyez avec `docker rm -f numa`.
### 2. Exécuter au premier plan (DNS système intact)
Installez le binaire :
```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 écoute sur le port 53, mais votre système conserve son résolveur actuel jusqu'à ce que vous exécutiez `numa install`, donc testez avec `dig @127.0.0.1 example.com`. Le tableau de bord est à `http://localhost:5380`. Si le port 53 est pris (systemd-resolved sur Ubuntu/Mint), définissez `bind_addr` dans [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml) ou utilisez Docker.
### 3. Définir comme DNS système
| Plateforme | Installation | Désinstallation |
|----------|---------|-----------|
| macOS | `sudo numa install` | `sudo numa uninstall` |
| Linux | `sudo numa install` | `sudo numa uninstall` |
| Windows | `numa install` (admin) + reboot | `numa uninstall` (admin) + reboot |
`install` enregistre un service, pointe le DNS système vers Numa et fait confiance à son CA local. `uninstall` annule les trois. Une fois installé, le tableau de bord est aussi à **http://numa.numa**.
Sur macOS et Linux, numa s'exécute comme service système (launchd/systemd). L'unité systemd est non privilégiée (`DynamicUser=yes`, seulement `CAP_NET_BIND_SERVICE`) ; le démon launchd s'exécute en tant que root. `numa install` reconfigure systemd-resolved via un drop-in que `numa uninstall` supprime ; tout autre processus occupant le port 53 (dnsmasq, y compris celui de NetworkManager) doit être arrêté manuellement. Sur Windows, numa démarre automatiquement à la connexion via le registre. Windows lie également `127.0.0.2:53` (le Dnscache intégré possède `127.0.0.1:53`) et installe une règle NRPT pour y router les requêtes — donc modifiez `bind_addr`/`api_bind_addr` par rapport à `127.0.0.2`, pas `127.0.0.1`.
### Se connecter
Via loopback (`localhost`, `127.0.0.1`, `numa.numa`), aucune connexion n'est nécessaire. Tout le reste, y compris le mappage de port Docker ou l'adresse LAN de cette machine, demande le jeton API, que Numa génère au premier démarrage. Affichez-le avec `sudo numa token` (un shell administrateur sous Windows) et connectez-vous avec n'importe quel nom d'utilisateur. Épinglez le vôtre avec `[server] api_token` ou `NUMA_API_TOKEN`.
### Supprimer toute trace
`uninstall` restaure le DNS mais conserve le répertoire de données, donc une réinstallation conserve le même jeton et CA. Pour tout supprimer, désinstallez d'abord, puis supprimez :
| Plateforme | Ce qui reste |
|----------|-------------|
| macOS | le binaire, `/usr/local/var/numa`, `/usr/local/var/log/numa.log` |
| Linux | le binaire (`/usr/local/bin/numa` depuis install.sh), `/var/lib/numa`, `/etc/numa` |
| Windows | le binaire, `%PROGRAMDATA%\numa` |
Les installations via gestionnaire de paquets suppriment le binaire avec `brew uninstall`, `pacman -R` ou `cargo uninstall`. Sur Linux, `numa install` copie un binaire qu'il ne peut pas exécuter depuis son emplacement d'origine (par ex. `~/.cargo/bin`) vers `/usr/local/bin/numa`, et la désinstallation laisse cette copie.
Supprimez aussi `~/.config/numa` si vous avez créé une configuration utilisateur, et le chemin `[server] data_dir` si vous en avez défini un.
## Services locaux
Nommez vos services de développement au lieu de mémoriser des numéros de port :
```bash
curl -X POST localhost:5380/services \
-d '{"name":"frontend","target_port":5173}'
```
Maintenant `https://frontend.numa` fonctionne dans votre navigateur — cadenas vert, certificat valide, passthrough WebSocket pour HMR. Pas de mkcert, pas de nginx, pas de `/etc/hosts`.
Ajoutez un routage basé sur le chemin (`app.numa/api → :5001`), partagez des services entre machines via la découverte LAN, ou configurez tout dans [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml).
## Blocage de publicités et confidentialité
Blocage des publicités et traqueurs via [Hagezi Pro](https://github.com/hagezi/dns-blocklists), actualisé quotidiennement. Fonctionne sur n'importe quel réseau — cafés, hôtels, aéroports. Voyage avec votre ordinateur portable.
Trois modes de résolution :
- **`forward`** (par défaut) — proxy transparent vers votre DNS système existant. Tout fonctionne comme avant, juste avec la mise en cache et le blocage de publicités en plus. Portails captifs, VPN, DNS d'entreprise — tous respectés.
- **`recursive`** — résolution directement depuis les serveurs de noms racines. Aucune dépendance en amont, aucune entité unique ne voit votre schéma de requêtes complet. Ajoutez `[dnssec] enabled = true` pour une validation complète de la chaîne de confiance.
- **`auto`** — sonde les serveurs racines au démarrage, récursif si joignable, sinon forward via DoH vers Quad9 (`https://9.9.9.9/dns-query`), qui voit alors vos requêtes. Utilisez `forward` avec votre propre `[upstream]` pour choisir un autre fournisseur.
DNSSEC valide la chaîne de confiance complète : signatures RRSIG, vérification DNSKEY, délégation DS, preuves de déni NSEC/NSEC3. [Lire comment ça fonctionne →](https://numa.rs/blog/posts/dnssec-from-scratch.html)
**Écouteur DNS-over-TLS** (RFC 7858) — accepte les requêtes chiffrées sur le port 853 de clients stricts comme iOS Private DNS, systemd-resolved ou stubby. Deux modes :
- **Auto-signé** (par défaut) — numa génère automatiquement un CA local. `numa install` l'ajoute au magasin de confiance du système sur macOS, Linux (Debian/Ubuntu, Fedora/RHEL/SUSE, Arch) et Windows, et `numa uninstall` le supprime. Sur iOS, installez le `.mobileconfig` depuis `numa setup-phone`. Firefox conserve son propre magasin NSS et ignore celui du système — faites confiance au CA manuellement si vous avez besoin de HTTPS pour les services `.numa` dans Firefox.
- **Apportez votre propre certificat** — pointez `[dot] cert_path` / `key_path` vers un certificat publiquement approuvé (par ex., Let's Encrypt via un challenge DNS-01 sur un domaine pointant vers votre instance numa). Les clients se connectent sans aucune configuration de magasin de confiance — même expérience que AdGuard Home ou Cloudflare `1.1.1.1`.
ALPN `"dot"` est annoncé et appliqué dans les deux modes ; une poignée de main avec un ALPN non correspondant est rejetée comme défense contre la confusion inter-protocoles.
**Oblivious DoH** (RFC 9230) — avec `[upstream] mode = "odoh"` ([recette](https://github.com/razvandimescu/numa/blob/main/recipes/odoh-upstream.md)) chaque requête est scellée en HPKE vers la cible et envoyée via un relais. Le relais voit votre IP et le texte chiffré, la cible voit la question et l'IP du relais, et un relais qui redirige la requête remet à la nouvelle destination quelque chose qu'elle ne peut pas déchiffrer. Numa refuse un relais et une cible qui partagent un domaine enregistrable. ODoH ne masque pas la connexion que vous ouvrez ensuite : votre FAI voit toujours l'IP de destination et, sans ECH, le nom d'hôte dans la poignée de main TLS.
**Configuration du téléphone** — pointez votre iPhone ou Android vers Numa en une étape :
```bash
numa setup-phone
```
Affiche un code QR. Scannez-le, installez le profil, activez la confiance du certificat — le DNS de votre téléphone passe maintenant par Numa en TLS. Nécessite `[mobile] enabled = true` dans `numa.toml`.
## Découverte LAN
Exécutez Numa sur plusieurs machines. Elles se trouvent automatiquement 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 │ │
└──────────────────────┘ └──────────────────────┘
```
Depuis la Machine B : `curl http://api.numa` → proxifié vers le port 8000 de la Machine A. Activez avec `numa lan on`.
**Mode hub** : exécutez une instance avec `bind_addr = "0.0.0.0:53"` et pointez le DNS des autres appareils vers elle — ils obtiennent le blocage de publicités + la résolution `.numa` sans rien installer. `bind_addr` accepte aussi une liste pour lier un sous-ensemble spécifique d'interfaces. Pas à pas : [recette réseau complet](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
```
Tableau de bord à `http://localhost:5380`. Avec le mappage de port ou depuis un autre appareil, connectez-vous avec n'importe quel nom d'utilisateur et le jeton de `docker exec numa numa token`. Le volume `numa-data` conserve le jeton et le CA local à travers les recréations de conteneur. L'image lie l'API et le proxy à `0.0.0.0` par défaut. Remplacez avec une configuration personnalisée :
```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` et `linux/arm64`.
Recettes compose clés en main :
- [`packaging/client/`](https://github.com/razvandimescu/numa/blob/main/packaging/client) — mode client ODoH (DNS anonyme), Numa + `numa.toml` de démarrage.
- [`packaging/relay/`](https://github.com/razvandimescu/numa/blob/main/packaging/relay) — relais ODoH public, Numa + Caddy + ACME.
## Comparaison
| | Pi-hole | AdGuard Home | Unbound | Numa |
|---|---|---|---|---|
| Proxy de service local + TLS auto | — | — | — | domaines `.numa`, HTTPS, WebSocket |
| Découverte de services LAN | — | — | — | mDNS, zéro configuration |
| Remplacements développeur (API REST) | — | — | — | Rétablissement auto, scriptable |
| Résolveur récursif | — | — | Oui | Oui, avec sélection SRTT |
| Validation DNSSEC | — | — | Oui | Oui (RSA, ECDSA, Ed25519) |
| Blocage de publicités | Oui | Oui | — | Hagezi Pro |
| Règles par client | Groupes | Oui | Vues / tags | Par CIDR (`[[client_policy]]`), fichier de configuration uniquement |
| Interface d'administration web | Complète | Complète | — | Tableau de bord |
| Upstream chiffré (DoH/DoT) | Nécessite cloudflared | DoH uniquement | DoT uniquement | DoH + DoT (`tls://`) |
| Clients chiffrés (écouteur DoT) | Nécessite un sidecar stunnel | Oui | Oui | Natif (RFC 7858) |
| Point de terminaison serveur DoH | — | Oui | — | Oui (RFC 8484) |
| Request hedging | — | — | — | Tous les protocoles (UDP, DoH, DoT) |
| Serve-stale + prefetch | — | — | Prefetch à 90% du TTL | RFC 8767, prefetch à 90% du TTL |
| Forwarding conditionnel | — | Oui | Oui | Oui (règles par suffixe) |
| Portable (ordinateur portable) | Non (appliance) | Non (appliance) | Serveur | Binaire unique, macOS/Linux/Windows |
| Maturité communautaire | 56K étoiles, 10 ans | 33K étoiles | 20 ans | Nouveau |
## Utiliser Numa comme DNS principal
**Si Numa s'arrête.** `numa install` enregistre Numa auprès de launchd (macOS) ou systemd (Linux), qui le redémarrent à sa sortie. Si Numa est votre seul résolveur, les résolutions DNS échouent jusqu'à son redémarrage. Pour arrêter d'utiliser Numa et restaurer les paramètres DNS précédents de la machine, exécutez `sudo numa uninstall`.
Si Numa fonctionne mais que les upstreams sont injoignables, il peut servir des réponses en cache jusqu'à une heure au-delà de leur TTL (RFC 8767). Les noms qu'il n'a pas mis en cache échouent.
**Tests.** Le parseur DNS est fuzzé à chaque pull request qui le touche, avec des exécutions plus longues chaque semaine ([`fuzz.yml`](https://github.com/razvandimescu/numa/blob/main/.github/workflows/fuzz.yml)). La CI exécute `cargo audit` sur les dépendances et installe, réinstalle et désinstalle Numa sur macOS et Linux.
**Durcissement du résolveur.** En mode récursif, Numa abandonne les enregistrements de réponse en dehors de la zone interrogée, refuse d'interroger les serveurs de noms à des adresses privées ou loopback, et plafonne les requêtes upstream et la profondeur de renvoi de chaque recherche. Les réponses en UDP simple doivent correspondre à l'ID de transaction aléatoire et à la question de la requête. Les requêtes ANY sont refusées. La validation DNSSEC est désactivée par défaut ; `numa dnssec on` l'active. Pour signaler une vulnérabilité en privé, voir [SECURITY.md](https://github.com/razvandimescu/numa/blob/main/SECURITY.md).
**Ce que Numa ne fait pas.** Pas de DHCP, pas de clustering, pas de synchronisation de configuration entre instances. La plupart des paramètres résident dans [`numa.toml`](https://github.com/razvandimescu/numa/blob/main/numa.toml), pas dans le tableau de bord. Pour un réseau entier, exécutez-le sur une machine qui reste allumée.
## Performance
0,1 ms pour les requêtes en cache — équivalent à Unbound et AdGuard Home. Le cache au niveau du protocole stocke les octets bruts avec un patch TTL en place. Le request hedging élimine les pics p99 : p99 récursif à froid 538 ms vs Unbound 748 ms (−28%), σ 4× plus serré. [Benchmarks →](https://github.com/razvandimescu/numa/blob/main/benches)
## En savoir plus
- [Blog : Numa comme résolveur de votre tailnet](https://numa.rs/blog/posts/numa-tailnet-resolver.html)
- [Blog : DNS-over-TLS de zéro en Rust](https://numa.rs/blog/posts/dot-from-scratch.html)
- [Blog : Implémenter DNSSEC de zéro en Rust](https://numa.rs/blog/posts/dnssec-from-scratch.html)
- [Blog : J'ai construit un résolveur DNS de zéro](https://numa.rs/blog/posts/dns-from-scratch.html)
- [Référence de configuration](https://github.com/razvandimescu/numa/blob/main/numa.toml) — toutes les options documentées en ligne ; `numa config path` montre quel fichier votre installation utilise, `numa config edit` l'ouvre
- [API REST](https://github.com/razvandimescu/numa/blob/main/src/api.rs) — remplacements, cache, blocage, services, diagnostics
- [numa-metrics](https://github.com/razvandimescu/numa-metrics) — historique et analytique de requêtes durables, hors hôte par conception (pas d'écritures sur carte SD)
## Feuille de route
- [x] Forwarding DNS, mise en cache, blocage de publicités, remplacements développeur
- [x] Domaines locaux `.numa` — TLS auto, routage par chemin, proxy WebSocket
- [x] Découverte de services LAN — mDNS, DNS + proxy inter-machines
- [x] DNS-over-HTTPS — upstream chiffré + point de terminaison serveur (RFC 8484)
- [x] DNS-over-TLS — écouteur client chiffré (RFC 7858) + forwarding upstream (`tls://`)
- [x] Oblivious DoH — mode client anonymisé + relais public (`numa relay`, RFC 9230)
- [x] Résolution récursive + DNSSEC — chaîne de confiance, NSEC/NSEC3
- [x] Sélection de serveurs de noms basée sur SRTT
- [x] Basculement multi-forwarder — plusieurs upstreams avec classement SRTT, pool de secours
- [x] Request hedging — requêtes parallèles pour pallier la perte de paquets et la latence de queue (tous protocoles)
- [x] Serve-stale + prefetch — RFC 8767, rafraîchissement en arrière-plan à <10% du TTL et lors du service périmé
- [x] Forwarding conditionnel — règles par suffixe pour le DNS split-horizon (Tailscale, VPN)
- [x] Préchargement du cache — résolution proactive pour les domaines configurés
- [x] Intégration mobile — flux QR `setup-phone`, API mobile, profils mobileconfig
- [ ] Intégration pkarr — DNS auto-souverain via Mainline DHT
- [ ] Noms `.numa` globaux — adossés au DHT, sans registrar
## Licence
MIT