Profili

Un profilo è la policy. Dispositivi, gruppi e subnet sono il modo in cui Warden decide quale policy applicare.

Cos’è

Un profilo è un insieme con nome di comportamenti di filtraggio: cosa succede ai domini di ogni lista, quali Custom List montare sopra, che forma prende la risposta preconfezionata quando una query viene negata e, se vuoi, record DNS statici, riscritture di nomi, SafeSearch e una policy EDNS Client Subnet. Ogni entità che porta a una decisione di filtraggio (dispositivi, gruppi, subnet e il default_profile globale) punta a un profilo tramite il suo id.

Un profilo non si iscrive alle blocklist. Ogni lista configurata raggiunge già ogni profilo; ciò che un profilo controlla è la direzione che ogni lista prende per lui (deny, allow o ignore), scritta come override per lista nella sua mappa lists. Un id senza voce eredita il base della lista stessa. Quell’override è la cosa più importante di questa pagina; tutto il resto è dettaglio.

Questa pagina spiega quando aggiungere una voce [profiles.<id>], ogni dimensione che puoi regolare, le superfici CLI, TUI e API che leggono e scrivono i profili, e come viene decisa una query dentro un profilo. Per il quadro generale di come una query viene abbinata a un profilo, vedi il processo di filtraggio e l’ordine di precedenza più sotto.

Quando ti serve

Crea un profilo per ogni comportamento di filtraggio che vuoi esprimere, non uno per dispositivo. Una configurazione tipica finisce con tre-cinque profili:

• Un profilo default per tutto ciò che sta sulla LAN, senza alcun override: ogni lista si applica al suo base.
• Un profilo kids che porta una lista di contenuti per adulti da ignore a deny, nega alcuni domini specifici, reindirizza i motori di ricerca con regole di riscrittura e imposta la risposta di blocco a nxdomain, così le app iOS smettono di riprovare.
• Un profilo kids-night (block_all = true più una Custom List di regole allow), legato a una pianificazione tra le 21:00 e le 07:00.
• Un profilo iot che attiva solo per sé una lista di telemetria dei produttori, così le app della smart TV smettono di chiamare casa.
• Un profilo work ricavato dal profilo dei bambini, con i domini della scuola riaggiunti.

Non ti serve un profilo separato per le eccezioni isolate. Un singolo dominio da bloccare o da permettere va in una Custom List montata sul profilo: vedi regole personalizzate (in inglese).

Ti serve un profilo separato ogni volta che un’eccezione non deve estendersi ad altri. I profili sono piatti: non c’è extends, né ereditarietà, né fusione di due profili. Una Custom List raggiunge tutto ciò che è legato al profilo che la monta. Dalla 0.44.0 i dispositivi non hanno regole proprie, quindi un’eccezione per un dispositivo significa un profilo per quel dispositivo.

Schema

Un profilo è una mappa TOML indicizzata per id: a differenza di [[devices]], [[blocklists]] o [[subnets]], i profili usano [profiles.<id>], non un array-of-tables. L’id (la parte dopo il punto) è ciò a cui si riferiscono tutte le altre entità.

[profiles.kids]
display_name     = "Profilo bambini"
lists            = { adult-content = "deny" }
block_response   = "nxdomain"
blocked_ttl_secs = 300
custom_lists     = ["kids-allow-classroom"]
block_all        = false

Con lists = { … } in linea, l’ordine delle chiavi non conta. Se invece scrivi lists come sotto-tabella [profiles.<id>.lists], metti custom_lists e ogni altra chiave sopra quell’intestazione: in TOML le chiavi semplici di una tabella finiscono alla prima sotto-tabella.

Come si agganciano le liste: l’override per profilo

Ogni riga [[blocklists]] ha un base, che vale deny se la riga non dice altro. Quel base è ciò che un profilo riceve per default. Un profilo lo cambia una lista alla volta.

effective(profile, list) = profile.lists[list.id]   when the key is present
                         = list.base                otherwise

Tre direzioni, tre significati:

Tre conseguenze da tenere a mente:

• Un nuovo profilo filtra subito. Non c’è un passo di iscrizione. Un profilo senza la chiave lists eredita il base di ogni lista, e base vale deny se non l’hai cambiato.
• Aggiungere una lista non richiede di toccare i profili. Una nuova riga [[blocklists]] inizia a filtrare per ogni profilo al reload successivo. Modifichi un profilo solo per ritagliare un’eccezione.
• Un errore di battitura è un errore, non un’alzata di spalle. Le chiavi di lists sono id di blocklist, verificati al caricamento. Un profilo che nomina un id che nessuna riga [[blocklists]] ha viene rifiutato: vedi risoluzione problemi.

Una sola implementazione decide la coppia, e la leggono il resolver, il validator, warden resolve e warden blocklist list: src/config/schema/blocklist.rs → effective_direction().

Da dove arriva una lista, e dove si imposta il suo base, è spiegato in Import lists (in inglese).

Dimensioni

Un profilo è un vettore lungo questi assi indipendenti. Ogni dimensione ha un default sensato ed è facoltativa, tranne l’id.

Cose che sembrano dimensioni di un profilo ma non lo sono:

• Iscrizioni esplicite alle blocklist. Rimosse. blocklists e categories non sono più campi, e la chiave tags che li ha sostituiti per poco è stata ritirata a sua volta. blocklists e categories vengono rifiutati al caricamento; tags viene rimosso al caricamento con un avviso e non applica nulla. Un profilo nomina una lista solo per cambiarne la direzione.
• Ereditarietà tra profili. I profili sono piatti: non c’è extends. Il resolver sceglie esattamente un profilo per query, e la mappa lists di quel profilo è l’intera policy delle liste per la query.
• Il TTL della cache è globale ([cache]): solo il TTL della risposta di blocco è per profilo.
• La scelta del forwarder upstream è globale ([[forwarding]]): non puoi fissare “kids usa Quad9, work usa Cloudflare”. ECS è l’unica manopola upstream che è per profilo.
• Limiti di frequenza per profilo: RRL è globale ([security]).

Riferimento dei campi

I campi sconosciuti vengono rifiutati: un errore di battitura fallisce al caricamento della config. Lo stesso vale per ogni chiave ritirata tranne tags: un profilo con blocklists, categories o admin_rules viene rifiutato, non migrato sul posto. Vedi risoluzione problemi per come convertirli. Una chiave tags viene rimossa al caricamento con un avviso e non applica nulla. Fonte: src/config/schema/target_v5.rs → ProfileV5, src/config/schema/retired_keys.rs → strip_retired_tag_keys(), src/config/loader.rs → normalise_deprecated_keys().

Varianti della risposta di blocco

Tutte e quattro si impostano dalla CLI, più clear per tornare al valore globale del server.

Esempi

Un default per la casa: nessun override, quindi ogni lista si applica al suo base, con una rinuncia rapida in caso di blocco.

[profiles.default]
display_name   = "Predefinito di casa"
block_response = "zero"

Le liste con cui filtra sono dichiarate per conto loro e non chiedono nulla al profilo. La terza è parcheggiata su ignore, così raggiunge solo i profili che la attivano:

[[blocklists]]
id           = "oisd-basic"
display_name = "OISD basic"
url          = "https://big.oisd.nl/domainswild"
base         = "deny"

[[blocklists]]
id           = "urlhaus"
display_name = "URLhaus"
url          = "https://urlhaus.abuse.ch/downloads/hostfile/"
base         = "deny"

[[blocklists]]
id           = "adult-content"
display_name = "Contenuti per adulti"
url          = "https://lists.purge.cc/adult.txt"
base         = "ignore"

Un profilo per i bambini: una lista portata da ignore a deny, NXDOMAIN per troncare i tentativi, una Custom List della scuola sopra:

[profiles.kids]
display_name     = "Bambini"
custom_lists     = ["kids-allow-classroom"]
lists            = { adult-content = "deny" }
block_response   = "nxdomain"
blocked_ttl_secs = 300

Un profilo notturno per i bambini, legato a una pianificazione: nega tutto tranne una Custom List ristretta di regole allow. Il profilo non cambia nessuna lista: con block_all lo strato delle liste è irrilevante, perché non ci arriva nulla. La voce local_records si risolve comunque, perché i record locali ricevono risposta prima che parta il filtro.

[profiles.kids-night]
display_name = "Bambini, notte"
block_all    = true
custom_lists = ["kids-night-bedtime-audio"]

[[profiles.kids-night.local_records]]
domain = "homework.lan"
type   = "A"
value  = "192.168.1.20"

[[schedules]]
id           = "kids-bedtime"
display_name = "Bambini: buonanotte"
target_type  = "group"
target_id    = "kids"
profile      = "kids-night"
days         = ["mon", "tue", "wed", "thu", "sun"]
hours        = "21:00-07:00"

Un profilo IoT che attiva solo per sé una lista di telemetria, disattiva ECS così il CDN del produttore non scopre nulla della LAN, e lega il nome dell’hub smart-home al suo indirizzo nella LAN. Un record locale non può sostituire un blocco: Warden rifiuta un record che punta a 0.0.0.0, 127.0.0.1 o a un altro indirizzo riservato, quindi il blocco resta compito della lista di telemetria.

[profiles.iot]
display_name   = "IoT"
lists          = { telemetry = "deny" }
block_response = "soa_nodata"

[profiles.iot.ecs]
mode = "off"

[[profiles.iot.local_records]]
domain           = "hub.lan"
type             = "A"
value            = "192.168.1.10"
match_subdomains = true

CLI

Il sottocomando è warden profile (al singolare). add, set, remove e list-policy set|clear passano dal daemon in esecuzione via IPC e richiedono il token di amministrazione. Stampano la risposta del daemon, oppure daemon refused: <message>. Anche mount e unmount passano dal daemon, a meno che tu non passi --offline. list, show e list-policy show leggono la config in locale e funzionano senza il daemon.

I local_records e le rewrite_rules di un profilo hanno comandi propri: warden local-dns add|remove|list --profile <id> e warden rewrite add|remove|list --profile <id>. Non esiste warden profile blocklists: è stato rimosso insieme al campo che scriveva.

warden profile allow, deny e admin-rule add|remove sono ritirati. Falliscono senza scrivere nulla. Le regole ora stanno nelle Custom List; vedi regole personalizzate (in inglese).

Schemi comuni:

# Disattiva una lista per il profilo work, senza toccare gli altri profili
sudo warden profile list-policy set work oisd-basic ignore

# Guarda la direzione in vigore di ogni lista per un profilo, e da dove arriva
warden profile list-policy show kids

# Blocca un dominio solo sul profilo dei bambini
sudo warden custom-list create kids-extra --display-name "Extra bambini"
sudo warden custom-list add kids-extra tiktok.com --deny
sudo warden profile mount kids --custom-list kids-extra

# Cambia la forma del RCODE così gli stub iOS non passano a un secondario
sudo warden profile set kids block_response nxdomain

# Controlla cosa succederebbe per un IP, senza bisogno del daemon
warden resolve 192.168.1.107

TUI

Esiste una tab Profiles dedicata: è la foglia predefinita della sezione Filters (4, oppure g p), una vista master/detail su [profiles] che funziona anche offline.

Il Resolver inspector (Shift+S da qualsiasi foglia) prende un IP sorgente e mostra l’intera catena: dispositivo abbinato, livello del match, profilo attivo, pianificazione attiva. È il modo più veloce di rispondere a “perché questo client riceve quel profilo?”.

Le scritture sui profili dalla TUI fanno la stessa strada della CLI: IpcCommand::ProfileUpdate porta la modifica, e il daemon valida di nuovo l’intera config prima che la scrittura arrivi su disco. Fonte: src/tui/app.rs, src/ipc/socket_server.rs.

API REST

Tutte le rotte /api/* sono protette da Bearer token (Authorization: Bearer ps_<64hex>), verificato a tempo costante, con un blocco di 5 minuti dopo 10 tentativi falliti. Ogni rotta autenticata ha un timeout di 30 secondi.

Non esiste un CRUD REST per i profili. Tutto il resto passa dalla CLI, dalla TUI, o da una modifica a mano seguita da un reload.

IPC

Sul socket Unix esistono tre verbi per i profili, tutti nel livello Mutating (serve il token di amministrazione):

• ProfileCreate { id, display_name }: rifiuta se l’id esiste.
• ProfileUpdate { id, patch }: la modifica porta display_name, block_response, blocked_ttl_secs, block_all, ecs e lists (un ListPolicyPatch con le mappe set e clear; set viene applicata per prima, quindi un id nominato in entrambe finisce rimosso).
• ProfileDelete { id }: rifiuta se un dispositivo, un gruppo, una subnet, una pianificazione o [server].default_profile usa ancora l’id. La risposta è il rifiuto generico del validator; i dettagli vanno nel log del daemon.

I campi modificati a mano arrivano su disco e il daemon li legge tramite IpcCommand::Reload { token }, la stessa strada di ogni modifica della CLI. DeviceUpdate e DevicePromote hanno un campo profile facoltativo per legare un dispositivo a un altro profilo. Fonte: src/api/handlers.rs → get_config(), src/ipc/protocol.rs → IpcCommand::ProfileCreate, ProfileUpdate, ProfileDelete.

Ordine di precedenza

Una query passa per due fasi in ordine: scegliere il profilo, poi valutare dentro il profilo.

Scegliere il profilo

Cinque livelli, vince il primo match. La tabella mostra l’ordine di valutazione a runtime accanto al nome interno di ogni livello. warden resolve stampa invece etichette numerate: 1 (direct device profile), 2 (active schedule override), 3 (group membership), 4 (subnet longest-prefix), 5 (global default_profile). I numeri non seguono l’ordine di valutazione, e questo confonde molti.

Una pianificazione attiva viene controllata prima del profilo del dispositivo, quindi vince dentro la sua finestra. L’ordine è voluto: un operatore che scrive una pianificazione per un dispositivo che ha anche un profilo fisso chiede chiaramente che vinca la pianificazione, altrimenti la pianificazione non farebbe nulla. I test fissano questa scelta.

Con enforce_device_mac = true, un MAC nella tabella ARP che non è né il mac del dispositivo né uno dei suoi mac_aliases declassa il dispositivo al livello della subnet per quella query: pianificazione, profilo diretto e gruppo vengono tutti saltati. Un dispositivo con ip e senza mac viene escluso allo stesso modo, a meno che la tabella ARP non mostri al suo indirizzo uno dei suoi mac_aliases. Un MAC che appartiene a un altro dispositivo configurato identifica quel dispositivo, che poi percorre la catena con la propria pianificazione, il proprio profilo e i propri gruppi. Vedi il controllo del MAC.

È la stessa catena descritta in dispositivi e gruppi. Fonte: src/profiles/resolver.rs → ProfileResolver::resolve().

Valutare dentro il profilo

Prima di tutto questo, il gestore delle query controlla i local_records del profilo. Una corrispondenza riceve subito risposta e salta del tutto il filtro, la cache e l’upstream: non viene “lasciata passare” dal filtro, non ci arriva mai. Questo vale anche con block_all, ed è ciò che tiene raggiungibile homework.lan nell’esempio notturno qui sopra. Partecipano solo A, AAAA e CNAME; ogni altro tipo di query passa alla tabella globale [local_dns] e poi all’upstream. Fonte: src/dns/handler.rs → handle_inner() (il controllo dei local_records del profilo), src/dns/local_profile.rs → ProfileLocalRecords::lookup_with_apex().

Se non c’è corrispondenza, il filtro percorre queste fasi. Vince la prima decisione.

1. Regole delle Custom List. Vengono raccolte tutte le regole delle Custom List montate sul profilo che corrispondono al nome. Vince la più forte:

2. Nessuna corrispondenza. Se block_all = true, la query viene bloccata. Altrimenti viene bloccata solo quando una lista in direzione deny corrisponde e nessuna lista in direzione allow corrisponde. Qualsiasi corrispondenza in direzione allow inoltra la query, anche quando corrisponde anche una lista in direzione deny.

Con block_all, un allow di una Custom List inoltra comunque. È così che funziona un profilo fatto solo di allow. Regole allow e deny nella stessa lista hanno lo stesso peso che in due liste montate sullo stesso profilo. La grammatica delle regole è in regole personalizzate (in inglese).

Dopo il verdetto e prima dell’inoltro si applicano le rewrite_rules. Questo ordine impedisce di usare una riscrittura per sfuggire a una corrispondenza di blocklist sul nome originale. Vedi SafeSearch e riscritture per la risposta che riceve il client.

I dispositivi non hanno regole sovrapposte

Prima della 0.44.0 un dispositivo poteva avere allow_rules, deny_rules e override_profile_deny. Lo schema 5 non ha nessuno di questi campi, e una config che li contiene viene rifiutata. L’aggiornamento trasforma le regole di un dispositivo in una Custom List più una copia del profilo che la monta. Un dispositivo contribuisce solo con la sua scelta di profilo.

Note di sicurezza

• Solo le Custom List riconoscono @@, $important e le regex. Le blocklist esterne sono isolate: possono negare, ma non possono scavalcare altre regole né usare pattern ancorati o regex. Così una fonte di liste ostile o compromessa non può aprire varchi nei tuoi override.
• I local_records per costruzione non vengono filtrati. Un record di profilo viene servito prima del filtro, della cache e dell’upstream: nessuna blocklist, nessuna regola di Custom List e nessun block_all si applica. Tratta l’elenco come una piccola allowlist voluta che in più risponde, non come una comodità per fissare nomi che vuoi ancora controllare.
• Il filtraggio è attivo per default; spegnerlo è l’atto esplicito. Senza override ogni lista si applica al suo base, quindi nessun profilo finisce per non filtrare nulla per dimenticanza. Escludere una lista richiede di scrivere lists = { <id> = "ignore" }.
• allow è l’unica direzione che richiede consenso. Fa sì che un profilo permetta i domini di qualcun altro, quindi viene rifiutata a meno che la lista non sia trust = "local" o la sua riga non abbia accept_unsigned_allow = true. deny e ignore restringono soltanto ciò che un profilo permette.
• block_unmapped_clients non esiste più. Per “negare i client non mappati” lascia [server].default_profile non impostato, così la catena restituisce REFUSED al livello del default globale. La vecchia chiave viene rifiutata al caricamento.
• Il log delle query registra l’orario, client_ip, client_name, il dominio richiesto, il tipo di query, il risultato, il tempo di risposta e, quando c’è, la sorgente CNAME o della riscrittura. Non registra il profilo né il MAC.
• Le modifiche ai profili finiscono nel journal, non in audit.log. Creazione, aggiornamento e cancellazione scrivono ciascuno una riga di journal con target audit (per esempio profile.delete.v1) e l’uid di chi ha chiamato; vedi journalctl -u purge-warden. audit.log riceve solo la riga generica reload che segue.
• warden audit tail [-n N] stampa le righe di audit recenti come righe allineate con tabulazioni: orario, evento, uid, ok / rejected, dettaglio.
• Il controllo del MAC è ergonomico, non crittografico. Un attaccante determinato sulla LAN può falsificare un MAC. Vedi il threat model (in inglese).

Risoluzione problemi

Un reload fallisce per un id di lista sconosciuto. La mappa lists nomina un id che nessuna riga [[blocklists]] ha:

profile "kids" sets lists.adult but no [[blocklists]] entry has id "adult"

È un errore, non un avviso: il daemon rifiuta la config, resta sull’ultima valida e segnala tutti gli id sconosciuti insieme. Aggiungi una voce [[blocklists]] con quell’id, oppure togli la chiave.

Con un comando lo stesso errore viene intercettato prima che arrivi al file: un set che nomina due liste con un refuso non ne scrive nessuna.

profile "kids" names blocklist "adult" in its list policy, but no [[blocklists]] entry with that id is configured. Run `warden blocklist list` to see what is.

Un reload fallisce per una chiave ritirata. Un profilo che ha ancora blocklists o categories viene rifiutato, non migrato. (Una chiave tags rimasta non fa fallire il reload: viene rimossa con un avviso.) Converti a mano: una lista che usavano tutti diventa una riga semplice con base = "deny" e niente sul profilo; una lista che volevano solo alcuni profili diventa base = "ignore" più lists = { <id> = "deny" } su quei profili.

Un reload fallisce con “profile X not found”. Qualche entità si riferisce a un profilo che non esiste più: di solito un refuso, a volte un profilo cancellato. Il validator rifiuta il reload e il daemon resta sulla config valida precedente. Esegui warden config lint, oppure cerca nell’albero della config:

grep -RnE 'profile\s*=\s*"[^"]+"' /etc/purge-warden

warden profile remove viene rifiutato. Un dispositivo, un gruppo, una subnet, una pianificazione o [server].default_profile lo usa ancora. La CLI stampa solo daemon refused: the change would leave the configuration invalid; see daemon log for the validator's full report. The change was NOT saved — the original file is unchanged. Il rapporto del validator, con i riferimenti, è in journalctl -u purge-warden. Riassegna prima quelle entità.

[server].default_profile non è impostato e i client non mappati falliscono. L’ultimo livello restituisce REFUSED per tutto. Sintomo: un portatile ospite riceve RCODE=REFUSED per ogni nome. Imposta default_profile a un id esplicito, oppure accetta questa come policy: impedisce a un resolver aperto di inoltrare per conto di sconosciuti.

Un reload fallisce su admin_rules o override_profile_deny. Lo schema 5 non ha né l’uno né l’altro. Sposta le regole in una Custom List e montala; vedi regole personalizzate (in inglese).

Un dispositivo viene risolto sul profilo giusto ma salta tutte le liste. Controlla unfiltered. Un dispositivo con unfiltered = true è escluso dal filtraggio a qualunque livello venga risolto, compresi i livelli subnet e default globale, mentre risoluzione DNS, log delle query e statistiche continuano a funzionare: il dispositivo sembra sano ma su di lui non si applica nulla.

Per altro, vedi risoluzione problemi (in inglese).

Vedi anche

• Import lists (in inglese): da dove arriva una lista, e dove si imposta il suo base.
• Dispositivi: legare un host a un profilo.
• Gruppi: assegnare un profilo a molti dispositivi insieme.
• Subnet: profilo di fallback per le sorgenti senza riga dispositivo.
• Pianificazioni: cambi di profilo in base all’orario.
• Regole personalizzate (in inglese): l’unico posto dove vivono @@, $important e le regex.
• SafeSearch e riscritture: rewrite_rules e cosa vede il client.
• Riferimento CLI: l’intera superficie warden profile ….