Impostazioni globali

Le poche manopole che valgono per l’intero resolver — interfacce di ascolto, server upstream, default.

Cos’è

Le impostazioni globali sono le sezioni [server] e [upstream] di livello superiore del config.toml master. Controllano come ascolta il daemon (su quali indirizzi e porte risponde al DNS), chi è autorizzato a chiedere (allow_from), dove Warden inoltra le query che non può risolvere localmente (upstream.servers), e quale profilo si applica quando nessun altro corrisponde (default_profile).

A differenza di device, profili o blocklist — che Warden espone con verbi CLI per-entità — queste globali non hanno un setter via flag. Non esiste warden config set server.allow_from "...". Il modo supportato per modificarle è warden config edit, che apre il TOML master in $EDITOR, valida al salvataggio e (dopo un successivo warden reload) le applica al daemon in esecuzione.

Quando ti serve

• Primo avvio, dopo warden init. Scegli le interfacce di ascolto, imposta i resolver upstream, imposta allow_from sul CIDR della tua LAN. Tutto il resto può aspettare.
• Restringere l’accesso. Hai spostato Warden su una macchina raggiungibile da più reti e vuoi rifiutare le query dalla WAN. Stringi allow_from.
• Cambiare upstream. Passare dal resolver del tuo ISP a un resolver che rispetta la privacy (Quad9, Mullvad, un tuo DoT) — cambia upstream.servers, opzionalmente upstream.protocol, ricarica.
• Impostare un fallback globale. I device che non corrispondono a nessuna voce [[devices]], [[groups]] o [[subnets]] finiscono su [server].default_profile. Se non lo imposti, le query non mappate ricevono REFUSED.

Non modifichi le globali per aggiungere un’eccezione di un singolo device, schedulare una finestra di blocco o importare una nuova blocklist — sono modifiche a livello di entità, con i loro verbi CLI dedicati (warden device add, warden schedule add, warden blocklist add).

Schema

Le due sezioni rilevanti del config.toml master:

[server]
listen        = ["0.0.0.0:53", "[::]:53"]   # interfacce + porte che rispondono al DNS
allow_from    = ["192.168.1.0/24"]          # CIDR autorizzati a interrogare
default_profile = "default"                 # profilo per i client non mappati
enforce_client_mac = true                   # downgrade su mismatch MAC (vedi Devices)
log_level     = "info"                      # error|warn|info|debug|trace

[upstream]
servers       = ["9.9.9.9:53", "149.112.112.112:53"]  # lista ordinata di fallback
protocol      = "udp"                       # udp|tcp|dot|doh
timeout_ms    = 1500                        # timeout per server
retries       = 2                           # tentativi prima di NXDOMAIN

Riferimento campi [server]

Riferimento campi [upstream]

Per lo schema canonico con tutti i vincoli e i default, vedi il riferimento TOML.

Modificare il master — il flusso warden config edit

Poiché non c’è un setter via flag per [server] e [upstream], il flusso canonico è:

1. Fai prima un backup. Un’edit sbagliata di [server] può lasciare la LAN senza DNS — warden config backup impiega secondi e ti dà un rollback in un comando.
2. warden config edit apre il master in $EDITOR. Al salvataggio, l’handler esegue il validatore v1 completo. Se rifiuta la modifica, il file live è invariato e il validatore stampa file:linea problematici.
3. warden reload segnala al daemon di passare alla nuova config. A differenza dei verbi CRUD per-entità, warden config edit non triggera un reload automatico — ricarichi deliberatamente, dopo aver riletto il diff.
4. Verifica. Un warden config show --resolved rapido conferma il valore live, e warden resolve <ip-client> conferma che il resolver sceglie ancora il profilo atteso.

sudo warden config backup
sudo warden config edit
sudo warden reload
warden config show --resolved --section server

allow_from — limitare chi può interrogare

Una prima edit comune. Apri il master, poi cambia il valore:

[server]
allow_from = ["192.168.1.0/24"]

Più range vanno elencati come voci di un array TOML. Sono accettati CIDR v4 e v6; una lista vuota (allow_from = []) rifiuta ogni client e serve normalmente solo in ambienti di test.

# anteprima, edit, reload
sudo warden config diff /etc/purge-warden/backups/config-20260505T091322Z.tar.gz
sudo warden config edit
sudo warden reload

upstream.servers — cambiare i resolver upstream

Stesso flusso, nella sezione [upstream]:

[upstream]
servers = ["9.9.9.9:53", "149.112.112.112:53"]
protocol = "udp"

Per DoT / DoH le voci hanno la forma hostname:port e il validatore applica vincoli specifici per protocollo — vedi il riferimento TOML.

default_profile — il fallback globale

Un’edit breve, ma rifletti prima di salvare: è il profilo che riceve qualsiasi client non identificato, incluso un telefono che si unisce alla VLAN guest per la prima volta.

[server]
default_profile = "guest"

Se lo lasci non impostato e un client non corrisponde nemmeno a una subnet, Warden risponde REFUSED — silenzioso, ma tende a confondere gli utenti meno tecnici.

CLI

Le globali non hanno CRUD per-entità. I verbi rilevanti sono tutti sotto warden config:

Per backup e restore intorno a edit rischiose, vedi backup e ripristino. Per la superficie completa di warden config, vedi il riferimento CLI.

Precedenza decisionale

[server].default_profile è livello 5 — il più basso nella catena del resolver. Qualsiasi match di device, schedule, group o subnet vince su di esso. È intenzionale: le globali sono il pavimento, non il soffitto.

[server].listen e [upstream].* non fanno parte della catena del resolver — governano come le query vengono ricevute e inoltrate, non quale profilo viene applicato. Cambiarli ha effetto su ogni client allo stesso modo.

Per la catena completa, vedi Devices → Precedenza decisionale.

Sicurezza

• allow_from è applicato a livello di listener. I client rifiutati non ricevono nulla — niente risposta REFUSED, solo un pacchetto scartato — e compaiono nel log di audit sotto LISTENER_REFUSED.
• Credenziali upstream. Se usi un endpoint DoH che richiede un token, salva il token in un file *.secret e referenzialo dal TOML — gli archivi di backup non includono mai *.secret.
• enforce_client_mac è ergonomico, non crittografico. Un attaccante determinato con accesso fisico può falsificare qualunque MAC. Il flag serve a fermare un adolescente curioso che cambia il proprio IP statico per evadere il profilo “kids”. Vedi il threat model per la garanzia precisa.

Troubleshooting

warden config edit esce con 0 ma il daemon serve ancora il vecchio upstream. Hai saltato warden reload. I verbi CRUD per-entità ricaricano automaticamente; warden config edit no.

La validazione rifiuta il nuovo TOML e indica un CIDR che non hai toccato. Verifica che allow_from e upstream.servers siano array TOML (parentesi quadre, separati da virgola), non stringhe singole. Il validatore è rigido sui tipi.

I client sulla LAN ricevono improvvisamente REFUSED per ogni query. Probabilmente hai stretto allow_from e dimenticato di includere il CIDR della LAN. Lancia warden config show --section server per vedere il valore live; ripristina dal backup pre-edit se serve.

Il daemon non parte con bind: address already in use. Un altro processo è sulla porta 53. O lo fermi (systemd-resolved è il colpevole abituale su Debian/Ubuntu — vedi systemd service) o cambi [server].listen.

Per altro, vedi troubleshooting.

Vedi anche

• Riferimento warden config — ogni verbo config.
• Backup e ripristino — rollback per edit rischiose.
• Riferimento TOML — ogni campo, ogni vincolo.
• Devices — profilo per-device, il livello sopra il default globale.
• Threat model — cosa garantisce davvero enforce_client_mac.