Riferimento CLI

Under review — wording may still change.

Il comando warden: regole generali, exit code e i verbi di warden config.

Cos’è

Un riferimento per warden, l’unico binario fornito con purge-warden. Questa pagina copre le regole che valgono per ogni comando, gli exit code su cui uno script può contare e i verbi di warden config che lavorano sulla configurazione nel suo insieme. I comandi che gestiscono un solo tipo di oggetto (warden device …, warden blocklist …, warden profile …, warden custom-list …) sono documentati nelle rispettive pagine di configurazione. Esegui warden --help o warden <comando> --help per l’elenco completo sulla tua macchina.

Warden non ha un generico config get <chiave> o config set <chiave> <valore>. Puoi cambiare la configurazione in questi modi:

warden config edit apre la configurazione in $EDITOR e la controlla quando salvi.
I comandi per i singoli oggetti (warden device add, warden blocklist set, warden profile …, warden subnet add, warden local-dns add, warden device quiet, warden custom-list … e così via). Ognuno ricarica per te il daemon in esecuzione.
warden config restore <archivio> rimette una configurazione funzionante in un’unica operazione.

Convenzioni

Quale utente. I file in /etc/purge-warden e /var/lib/purge-warden appartengono all’utente purge-warden, e il daemon parla solo con quell’utente. Il /usr/local/bin/warden installato è un piccolo wrapper che esegue per te il binario vero come quell’utente. Se lo esegui come root o con sudo, passa a purge-warden. Se lo esegui come un altro utente che può usare sudo, usa sudo -u purge-warden. Per questo warden status e sudo warden config backup funzionano così come sono scritti.
Il binario vero. Il binario è /usr/local/libexec/purge-warden/warden. Alcuni comandi devono girare come root e rifiutano l’utente del wrapper: warden init e warden config relocate. Per questi chiama il binario vero, con sudo.
Passare --config. Un --config <percorso> esplicito salta l’instradamento del wrapper. Il comando gira allora con il tuo utente. Va prima del sotto-comando: warden --config /path/config.toml config lint. Il wrapper esegue il binario con il tuo utente, senza cambiarlo, anche quando la directory corrente contiene un config.toml.
Dove si trova la configurazione. Senza --config, Warden usa il primo di questi file che riesce ad aprire:
1. ./config.toml
2. $XDG_CONFIG_HOME/purge-warden/config.toml, oppure ~/.config/purge-warden/config.toml quando $XDG_CONFIG_HOME non è impostata
3. /etc/purge-warden/config.toml
4. /var/lib/purge-warden/config.toml (la disposizione degli host installati prima della 0.44.0)
Quando root esegue warden senza --config, i primi due vengono saltati, così un file lasciato in una directory condivisa non può essere usato. Anche le unit systemd non passano --config: usano la stessa ricerca, in pratica /etc e poi /var/lib.
Scritture sicure. Ogni scrittura passa per un file temporaneo nella stessa directory, un controllo e poi una rinomina. Se il controllo fallisce, il file live resta invariato.
Ricaricare. I comandi per i singoli oggetti ricaricano il daemon da soli. warden config edit no: dopo, esegui warden reload o systemctl reload purge-warden.
Output. La maggior parte dei comandi di lettura stampa testo o tabelle. --json esiste su alcuni di loro (status, device list, stats … e logs --format json), ma non su nessun comando warden config.

Exit code

Ogni comando warden usa gli stessi exit code, così uno script può decidere in base a questi senza leggere l’output.

Codice	Significato
`0`	L’operazione è riuscita.
`1`	L’operazione è fallita: il daemon non è in esecuzione, una scrittura è stata rifiutata, un download non è finito.
`2`	La configurazione non si è potuta caricare, oppure non è valida. È anche il codice che il parser della riga di comando usa per un errore d’uso (un flag sconosciuto o un argomento mancante). Un errore d’uso stampa sempre un blocco `Usage:`.
`3`	La risposta è “no”. Solo per i controlli in sola lettura: `warden query` ha trovato il dominio bloccato, `warden resolve` ha trovato la sorgente REFUSED, `warden config diff` ha trovato una differenza.
`141`	L’output è stato chiuso prima della fine, per esempio con `warden … \| head`.

I comandi custom-list e profile mount usano 3 per un conflitto (per esempio una revisione che non corrisponde o una lista ancora montata) e aggiungono due codici propri: 4 (fallito prima del commit, oppure la risposta è andata persa) e 5 (commit eseguito, ma non ancora attivo). Vedi le loro pagine.

Verbi ritirati

Alcuni verbi delle versioni precedenti compaiono ancora in --help. Sono ritirati nella 0.44.0. Accettano i vecchi argomenti, non scrivono nulla e ti indicano cosa usare al loro posto. Non usarli negli script.

Ritirato	Al suo posto
`warden profile allow`, `warden profile deny`, `warden profile admin-rule …`	Una Custom List montata sul profilo.
`warden device allow`, `warden device deny`, `warden device rules …`	Lo stesso.
`warden group profile-allow`, `warden group profile-deny`	Lo stesso.
`warden subnet profile-allow`, `warden subnet profile-deny`	Lo stesso.
`warden default allow`, `warden default deny`	Lo stesso.
`warden rule undo`	Lo stesso.
`warden tags …`	Niente. I tag non decidono più quali liste si applicano; usa `warden profile list-policy`.

Usa warden custom-list per scrivere le regole e warden profile mount per collegare la lista. Vedi Custom rules (in inglese).

`warden config`

I comandi di configurazione stanno sotto warden config. Sono otto:

Comando	Scopo
`warden config show`	Stampa la configurazione.
`warden config edit`	Modifica una copia in `$EDITOR`; la applica solo se è valida.
`warden config lint`	Valida senza modificare nulla.
`warden config diff`	Confronta la configurazione live con un altro file.
`warden config backup`	Scrive uno snapshot `tar.gz`.
`warden config restore`	Sostituisce la configurazione live da un archivio.
`warden config render-default`	Stampa la configurazione predefinita incorporata.
`warden config relocate`	Sposta la configurazione da `/var/lib` a `/etc`.

`warden config show`

text

warden config show [--resolved] [--annotate] [--section <nome>]

Stampa la configurazione come un unico TOML, con i file inclusi già uniti.

Flag	Effetto
`--resolved`	Stampa a cosa si risolve ogni dispositivo e ogni subnet, come lo sceglierebbe la ricerca a cinque livelli.
`--annotate`	Stampa, prima della configurazione, un blocco di commenti che indica il file e la riga da cui arriva ogni entità.
`--section <nome>`	Stampa una sola sezione di livello superiore, per esempio `server`, `upstream`, `devices`, `profiles`, `subnets` o `cache`. Con `--resolved` si possono mostrare solo `devices`, `subnets` e `server`.

Senza --resolved l’output è TOML. Con --resolved è un resoconto in testo. Per l’uso da parte di un programma, passa il TOML semplice a uno strumento per TOML come tomlq o yq -p toml.

`warden config edit`

text

warden config edit

Apre una copia privata della configurazione in $EDITOR (vi se non è impostata). Il file live non viene mai aperto nell’editor. Quando salvi ed esci, Warden controlla la copia. La configurazione live cambia solo se la copia è valida.

Se la copia viene rifiutata, o l’editor esce con un errore, la configurazione live resta com’era, la copia viene conservata e il comando ne stampa il percorso. Su un secondario del cluster, una modifica alla policy che arriva dal primario viene rifiutata; fai quella modifica sul primario.

Questo comando non ricarica il daemon. Fallo seguire da un reload:

bash

sudo warden config edit && sudo systemctl reload purge-warden

Exit	Significato
`0`	La configurazione salvata è valida.
`1`	La modifica non si è potuta fare o scrivere (errore dell’editor, di lettura, di scrittura o del lock).
`2`	La configurazione salvata non è valida, oppure un secondario l’ha rifiutata. Gli errori vengono stampati.

`warden config lint`

text

warden config lint [--strict]

Carica e controlla la configurazione senza toccare il daemon in esecuzione. Gli avvisi vengono stampati su stderr. Di default non fanno fallire il comando, perché un avviso significa che il daemon parte e risponde comunque.

Flag	Effetto
`--strict`	Tratta gli avvisi come un fallimento: exit `2` su una configurazione valida che ha avvisi.

Exit	Significato
`0`	La configurazione è valida. Gli eventuali avvisi sono stati stampati.
`2`	La configurazione ha errori o non si è potuta caricare. Ogni errore viene stampato con il suo file e la sua riga.

Puoi usarlo come condizione prima di un deploy: warden config lint && systemctl reload purge-warden.

`warden config diff`

text

warden config diff <altro>

Confronta la configurazione live con <altro>, il percorso di un altro file di configurazione. “Sono diverse” è una risposta riuscita, quindi ha un suo exit code:

Exit	Significato
`0`	Le due configurazioni sono identiche.
`3`	Sono diverse. Le differenze vengono stampate.
`2`	Una delle due non si è potuta caricare.

`warden config backup`

text

warden config backup [--out <dir> | --auto | --reset-auto-failure]

Scrive config-<UTC-timestamp>.tar.gz nella [backup] dir, oppure in una directory backups/ accanto al master quando dir non è impostata. Con --out <dir> scrive lì. Quando la configurazione non si carica, la directory segue la regola di Dove finiscono gli archivi. --auto e --reset-auto-failure servono al backup pianificato. I tre flag si escludono a vicenda.

Exit 0 in caso di successo, di un’esecuzione automatica non ancora dovuta, o di un’esecuzione --auto che ha saltato una configurazione che non si carica. Exit 75 se è in corso un altro backup.

Per il contenuto di un archivio, la pianificazione e i limiti, vedi Backup e ripristino.

`warden config restore`

text

warden config restore <archivio>
warden config restore --list
warden config restore --latest

Controlla l’archivio, poi sostituisce la configurazione live in un’unica transazione e chiede al daemon di ricaricarla. Non cambia mai l’appartenenza del nodo al cluster. Rifiuta un archivio di Warden 0.41 o precedente.

Exit	Significato
`0`	Ripristinato, oppure la configurazione live corrispondeva già.
`1`	L’archivio non ha superato la validazione (la configurazione live è invariata), oppure il ripristino non è stato completato.

Il ripristino non conserva una copia della configurazione attuale: se potresti volerla di nuovo, esegui prima warden config backup. Per i passaggi e i rifiuti, vedi Come funziona il ripristino.

`warden config render-default`

text

warden config render-default

Stampa su stdout la configurazione predefinita incorporata. Non richiede root, non scrive nessun file e ignora quale configurazione Warden userebbe altrimenti. Serve a confrontare la tua configurazione con quella predefinita fornita:

bash

warden config render-default > /tmp/default.toml
warden config diff /tmp/default.toml

`warden config relocate`

text

sudo /usr/local/libexec/purge-warden/warden config relocate [--dry-run] [--reverse]

Sposta l’insieme dei file di configurazione da /var/lib/purge-warden a /etc/purge-warden. Gira offline, come root, con il binario vero, e rifiuta --config. --dry-run esegue tutti i controlli e non sposta nulla. --reverse riporta indietro l’insieme, oppure annulla un’esecuzione in avanti rimasta incompleta.

Exit	Significato
`0`	Spostato, annullato, oppure il dry run non ha trovato nulla da rifiutare.
`1`	Rifiutato, fermato a metà, oppure il relabel è fallito.
`2`	La configurazione non si carica.

La procedura completa, con i rifiuti, è in Upgrade (in inglese).

`warden reload`

text

warden reload

Chiede al daemon in esecuzione, tramite il suo socket di controllo autenticato, di ricaricare la configurazione e le liste. Usalo dopo warden config edit. Qui il reload è l’intera operazione, quindi un daemon che non è in esecuzione è un fallimento.

Exit	Significato
`0`	Il daemon ha accettato la richiesta di reload. Il reload vero e proprio avviene dopo: se il daemon poi lo rifiuta, per esempio perché un campo cambiato richiede un riavvio, il comando esce comunque con `0` e stampa `daemon reloaded — config and lists are live`. Il motivo compare solo in `journalctl -u purge-warden` e nel log di audit (`warden audit tail`).
`1`	Non l’ha accettata: il daemon non è in esecuzione, manca il token, oppure il reload è stato rifiutato.

`warden migrate`

warden migrate v4-to-v5 è la migrazione dallo schema 4 allo schema 5. L’aggiornamento la esegue per te dentro la sua transazione. La forma manuale esiste solo come strumento di recupero; vedi Upgrade (in inglese).

Vedi anche

Backup e ripristino: la guida operativa per config backup e config restore.
Upgrade (in inglese): install.sh --upgrade e warden config relocate.
Configurazione base: dove si trova la configurazione, e come validarla e ricaricarla.
Percorsi file: dove Warden legge e scrive su disco.
Variabili d’ambiente: $EDITOR, $XDG_CONFIG_HOME e le impostazioni dell’installer.