Inizializzazione

Trasforma un binario nudo in uno scaffold funzionante: utente di sistema, directory e un primo config.toml

Cosa fa questo passo

warden init prepara tutto ciò che serve a un’installazione nuova prima di poter partire: l’utente di sistema purge-warden, le directory di stato e un primo config.toml. Richiede root, e senza root rifiuta subito: warden init requires root. Run with sudo.

Se hai installato con l’installer del bundle (in inglese), non esegui warden init tu stesso. L’installer lo esegue per te con le risposte che ha trovato (il range della tua LAN e il tuo resolver upstream), poi crea il token e avvia il servizio. Leggi questa pagina quando installi a mano, quando scrivi uno script di installazione o quando vuoi sapere cosa ha scritto l’installer.

init crea tre iscrizioni a blocklist e attiva subito il filtraggio. Il base di una lista vale deny se non indicato, e il profilo che init scrive non ha override, quindi eredita base.

Esegui il binario vero come root. Il comando warden nel tuo PATH gira come utente purge-warden e non può farlo:

sudo /usr/local/libexec/purge-warden/warden init

Modalità interattiva

Senza --yes, init fa quattro domande, in quest’ordine. A ognuna basta un Invio per accettare il default:

Nessun comando scrive upstreams.toml per te: crealo a mano accanto alla config se vuoi un menu curato al posto dell’inserimento libero.

Modalità non interattiva (--yes)

Le installazioni da script saltano tutte le domande:

sudo /usr/local/libexec/purge-warden/warden init --yes

--yes accetta i default incorporati per il profilo (default), le tre liste e allow_from. Il resolver upstream deve comunque arrivare da qualche parte. Senza il flag --upstream, --yes adotta ciò a cui punta già la configurazione del resolver di questa macchina, e stampa cosa ha scelto, così la trascrizione di un’installazione non lo tace:

upstream: adopting 192.168.1.1:53 (detected on this machine)

Cosa scrive

Un config.toml appena creato si presenta così, senza i commenti. Il file vero contiene anche un blocco [api] commentato ed esempi commentati di [[devices]] e [[subnets]]; vedi Cosa init non scrive più sotto.

schema_version = 5

[server]
listen = "0.0.0.0:53"
allow_from = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "127.0.0.0/8"]
log_level = "info"
default_profile = "default"

[upstream]
mode = "plain"
servers = ["192.168.1.1:53"]
timeout_ms = 5000

[lists]
sources = []
update_interval_secs = 43200

[[blocklists]]
id = "security-malicious"
display_name = "Security: malicious"
url = "https://lists.purge.cc/malicious.txt"

[[blocklists]]
id = "privacy-ads"
display_name = "Privacy: ads"
url = "https://lists.purge.cc/ads.txt"

[[blocklists]]
id = "privacy-tracking"
display_name = "Privacy: tracking"
url = "https://lists.purge.cc/tracking.txt"

[profiles.default]
display_name = "Default household profile"

[cache]
max_entries = 10000
max_ttl_secs = 3600
min_ttl_secs = 60
negative_ttl_secs = 300

[socket]
path = "/run/purge-warden/control.sock"

[backup]
dir = "/var/lib/purge-warden/backups"

[node]
id = "<a random UUID>"
name = "<this machine's host name>"

Il file viene scritto con modalità 0640.

Tre cose da sapere:

• [backup] dir viene aggiunto solo quando la config è quella standard, /etc/purge-warden/config.toml. Gli archivi vanno in /var/lib/purge-warden/backups, con il resto dello stato di Warden. Per qualsiasi altro percorso della config, init non scrive un blocco [backup] e gli archivi vanno in una directory backups/ accanto alla config.
• [node] dà a questa macchina un’identità stabile. id è un UUID casuale e non cambia mai. name è un nome visualizzato. Per default è il nome host; impostane un altro con --node-name <nome>. Il nome è indipendente dal nome host del sistema operativo.
• [lists].sources resta vuoto di proposito. Le iscrizioni stanno come voci [[blocklists]], non come slug in quel canale più vecchio.

Le tre liste predefinite

--yes, oppure un Invio alla domanda sulle iscrizioni, iscrive questi tre slug del catalogo. L’id con cui viene scritta una voce è lo slug con / sostituito da -:

Cambia l’insieme con --lists <csv> di slug del catalogo. Gli URL diretti vengono rifiutati (raw URLs are not accepted by warden init). Aggiungi una sorgente con URL dopo init con warden blocklist add <id> --url <url>. Sfoglia il catalogo completo con warden lists catalog.

Il filtraggio parte nel momento in cui parte il daemon, per tutte e tre: il base di ogni riga [[blocklists]] vale deny se non indicato, e [profiles.default] non ha override, quindi eredita base.

La domanda sul profilo predefinito

--yes fissa default_profile = "default". In modalità interattiva anche un Invio accetta default. Scrivere none non scrive alcun blocco [profiles.default] e lascia default_profile commentato in [server]. Una sorgente che non corrisponde a nessun dispositivo e a nessuna subnet riceve allora REFUSED, invece di essere filtrata da un profilo di ripiego.

Cosa init non scrive

Solo esempi commentati, nessuna voce attiva:

• Nessun [[devices]], nessun [[groups]], nessuna [[subnets]].
• Nessuna [[custom_lists]] e nessuna directory packs/ su disco.

L’esempio commentato di [[devices]] nel file mostra comunque i campi che un dispositivo può avere. Togli il commento e adattalo per legare una sorgente a un profilo.

Riferimento CLI

Questi flag vanno dopo init.

--config <path> è un flag di primo livello. Va prima di init, non dopo. Sposta tutta la struttura; vedi Cosa crea.

Cosa crea

Senza --config, warden init prepara la struttura standard:

Passa --config <path> e tutte queste posizioni si spostano con lui. Una config sotto /etc/<nome>/ tiene il suo stato modificabile sotto /var/lib/<nome>/. Qualsiasi altra posizione della config tiene lo stato accanto alla config.

Un host che ha già una config in /var/lib

Le versioni precedenti tenevano la config in /var/lib/purge-warden/config.toml. Se quel file esiste, warden init senza --config rifiuta, anche con --force:

legacy config already exists: /var/lib/purge-warden/config.toml. Refusing to create /etc/purge-warden/config.toml and shadow existing policy. Keep using the existing master; Warden does not move it. To explicitly reinitialize the legacy master, run `warden --config /var/lib/purge-warden/config.toml init --force`.

Una seconda config sotto /etc nasconderebbe la tua policy vera. Continua a usare il file esistente. Per spostarlo in /etc di proposito, usa warden config relocate; vedi Upgrade (in inglese).

Rieseguire init (--force)

Senza --force, init rifiuta prima di toccare qualsiasi cosa se la config di destinazione esiste già:

config already exists: /etc/purge-warden/config.toml. Pass --force to overwrite
(the existing file will be copied with a .pre-init-<ts> suffix).

Con --force, il vecchio file viene prima salvato accanto al nuovo come config.toml.pre-init-<timestamp UTC>, per esempio config.toml.pre-init-20260731T140502Z, e init stampa saved previous config to <path>. Quella copia riguarda solo il file della config. Non copre i pacchetti delle Custom List né gli altri file inclusi. Esegui prima warden config backup; vedi Backup e ripristino.

Nodi di un cluster

init non prepara più un secondario di cluster. I vecchi flag --cluster-secondary e --peer sono ritirati e nascosti. Stampano solo legacy secondary scaffolding is retired; initialize a standalone node, then use cluster join with an invitation. Inizializza il nodo come un normale nodo autonomo, poi uniscilo a un primario con un invito: warden cluster join --peer <origine https del primario> --invitation-file <file>.

Dopo init

init scrive la config ma non crea alcun token IPC. Ogni comando che modifica qualcosa o di amministrazione rifiuta senza token. Il comando stampa da solo i passi successivi, seguiti, quando [server].listen usa una porta sotto 1024, da una nota su setcap cap_net_bind_service:

Se hai installato con l’installer del bundle, i passi 2 e 3 li fa lui, tramite l’unità systemd.

Se avvii il daemon a mano e [server].listen usa una porta sotto 1024 (il default, 0.0.0.0:53, lo fa), il daemon ha bisogno di CAP_NET_BIND_SERVICE per aprirla:

sudo setcap cap_net_bind_service=+ep /usr/local/libexec/purge-warden/warden

Oppure avvia il daemon dall’unità systemd, che concede la stessa capability con AmbientCapabilities= e non richiede il passo setcap. Vedi servizio systemd (in inglese).

Prossimo passo: Import lists (in inglese).

Nella TUI

warden init è un comando CLI da root: non esiste un equivalente nella TUI, e nulla nella TUI lo esegue per te. Una volta eseguito e avviato il daemon, warden dashboard apre la TUI, e la sezione Configuration è dove continua il resto della configurazione. 5 la apre sulla prima foglia, Labels; g e salta direttamente alla foglia Settings.

Risoluzione problemi

no upstream resolver configured: init --yes rifiuta subito. Su questa macchina non è stato trovato nulla di utilizzabile. Passane uno in modo esplicito:

sudo /usr/local/libexec/purge-warden/warden init --yes --upstream 192.0.2.53:53

the only resolver(s) this machine uses are warden itself (…): un rifiuto diverso, stessa soluzione. È la situazione normale quando si reinizializza un’installazione funzionante: la rete punta già a warden, quindi adottare l’indirizzo rilevato farebbe interrogare warden a se stesso. Passa --upstream con un resolver esterno a questo host.

config already exists: … È previsto: vedi Rieseguire init. Aggiungi --force, oppure punta --config a un percorso nuovo se volevi tenere quello vecchio.

legacy config already exists: … È previsto su un host aggiornato da una versione precedente. Vedi Un host che ha già una config in /var/lib.

--lists rifiuta una voce con “raw URLs are not accepted”. --lists accetta solo slug del catalogo. Iscriviti per slug, poi aggiungi una sorgente con URL personalizzato con warden blocklist add <id> --url <url>.

Un comando che modifica qualcosa fallisce dopo init con un errore “no token” o di autenticazione. È previsto: init non ne crea mai uno. Esegui warden token generate come mostrato in Dopo init.

Per tutto ciò che non è elencato qui, warden config lint indica il problema e la riga in cui si trova.

Vedi anche

• Import lists (in inglese): il passo successivo del percorso di base.
• Configurazione di base: dove sta la config, e come validarla e ricaricarla dopo una modifica.
• Backup e ripristino: warden config backup, prima di un nuovo init con --force.
• Riferimento CLI: l’ordine di ricerca del percorso della config e il resto della superficie warden config.