Backup e ripristino

Una copia della configurazione, un ripristino come unica transazione sicura, il daemon che continua a girare.

Cos’è

warden config backup scrive un unico archivio tar.gz della configurazione di Warden: il config.toml principale, i file che include e i pack delle tue Custom List. warden config restore <archivio> prende uno di questi archivi, lo controlla, sostituisce la configurazione attiva in un’unica transazione, poi chiede al daemon in esecuzione di ricaricarla. Serve un riavvio solo quando la configurazione ripristinata cambia un’impostazione che vale all’avvio, come l’id [node], l’indirizzo di ascolto o la cache. Finché non esegui sudo systemctl restart purge-warden, il daemon rifiuta questo ricaricamento e tutti quelli successivi.

Sono punti di controllo per l’operatore, non copie differenziali. Fanne uno prima di una modifica rischiosa (“sto per cambiare blocklist”), tieni qualche copia a rotazione su un altro disco, e ripristina la più recente valida quando qualcosa si rompe. Warden può anche crearli a orari fissi: vedi backup automatici più sotto.

Quando ti serve

• Prima di una modifica strutturale. Modificare [server], cambiare i resolver upstream, importare un nuovo insieme di blocklist: tutto ciò in cui un errore di battitura o di validazione può lasciare la LAN senza DNS. Fai prima un backup; se qualcosa va storto, lo ripristini in pochi secondi.
• Prima di un aggiornamento. Fai un backup, poi segui i passi di aggiornamento (in inglese). Gli archivi creati da Warden 0.41 o precedenti non si possono ripristinare con 0.44.0 o successive, quindi fanne uno nuovo a aggiornamento finito.
• Trasferimento su un nuovo host. Esegui warden config backup sulla vecchia macchina, copia l’archivio, esegui warden config restore sulla nuova.
• Recupero da una modifica sbagliata. Una modifica con un errore di logica è passata e te ne accorgi solo un’ora dopo? Ripristina l’ultimo archivio di prima della modifica e lascia che il daemon ricarichi.
• Backup periodico su un altro host. Un cron notturno che esegue warden config backup --out /mnt/backup/warden/ ed elimina gli archivi vecchi ti dà una finestra a rotazione. In alternativa, lascia fare allo scheduler integrato.

Backup e ripristino non servono per le blocklist scaricate, le statistiche, l’audit log o il query log. Stanno nella directory di stato, non nella configurazione (vedi sotto). Per lo stato completo del sistema, fai una copia separata di /var/lib/purge-warden/.

Dove sta la configurazione

Un’installazione nuova di 0.44.0 o successiva tiene la configurazione in /etc/purge-warden. Gli archivi di backup vanno in /var/lib/purge-warden/backups, perché gli archivi sono stato, e Warden tiene lo stato sotto /var/lib.

Un host aggiornato da 0.41.x, 0.42.0 o 0.43.0 tiene la configurazione in /var/lib/purge-warden/config.toml finché non esegui warden config relocate. Backup e ripristino funzionano allo stesso modo in entrambi i posti. Usano il primo file principale che Warden trova; vedi riferimento CLI. Dopo lo spostamento, i backup coprono la configurazione in /etc, e la directory degli archivi resta dove punta [backup] dir. Vedi Upgrade (in inglese).

Cosa contiene

Un backup è un tar.gz della directory di configurazione: la cartella che contiene il config.toml principale. Contiene:

• Il file TOML principale.
• Ogni file che la configurazione include tramite includes = [...], ovunque si trovi dentro la directory di configurazione. L’elenco viene dalla vera lista degli include, non da un elenco fisso di nomi di cartella.
• I pack delle tue Custom List, in packs/.
• Ogni altro file o cartella normale nella directory di configurazione. Un backup preferisce tenere troppo piuttosto che troppo poco.

Non contiene:

• La directory dei backup stessa.
• Gli archivi di lavoro interni di Warden, come il corpus del nodo e gli archivi del cluster e del nodo.
• Le blocklist scaricate e le statistiche, che stanno nella directory di stato (/var/lib/purge-warden/lists/, /var/lib/purge-warden/data/).
• L’audit log e il query log.
• Le voci di packs/ che non sono pack, come il file di swap di un editor (.kids.txt.swp) o una copia di riserva (kids.txt.bak). Warden legge, salva e ripristina solo i file <id>.txt posti direttamente in packs/. Il backup stampa un avviso che nomina ogni voce lasciata fuori: packs/ holds entries that are not packs and are ignored: .... Sposta quei file fuori da packs/ se vuoi tenerli.

In un’installazione nuova la directory di configurazione (/etc/purge-warden) contiene solo configurazione. Su un host la cui configurazione sta ancora in /var/lib/purge-warden, la directory di configurazione è anche la directory di stato, quindi un archivio può raccogliere più della sola configurazione e diventare più grande. Spostare la configurazione in /etc con warden config relocate limita gli archivi alla sola configurazione.

Un backup si rifiuta di partire se la directory di configurazione contiene un link simbolico, un file con hard link o un file speciale (un socket o un dispositivo), oppure se un file incluso sta fuori dalla directory di configurazione. L’errore nomina la voce in questione. Un backup che lascia fuori qualcosa senza dirlo sarebbe peggio di uno che si ferma.

Se la configurazione non si carica, un warden config backup manuale parte comunque, così puoi tenere una copia di una configurazione rotta prima di ripararla. Stampa un avviso e il primo errore:

warning: /etc/purge-warden/config.toml does not currently load (1 error(s)); the archive captures /etc/purge-warden as it stands, but its coverage was not verified against the declared includes.
  first error: ...

Il ripristino controlla un archivio come fa warden config lint, quindi rifiuta un archivio del genere così com’è. Per usarlo, estrailo e copia a mano quello che ti serve. Il backup pianificato non archivia una configurazione che non si carica: salta l’esecuzione. Vedi backup automatici.

Non c’è un manifest incorporato e non c’è cifratura. L’archivio è un semplice tar -czf.

CLI

La directory dei backup è [backup] dir quando è impostata, altrimenti una directory backups/ accanto al config.toml principale. Il nome del file è sempre config-YYYYMMDDTHHMMSSZ.tar.gz; solo la directory si può configurare.

Quando la configurazione non si carica, Warden legge il file principale come semplice TOML per trovare la directory:

• Se [backup] imposta un dir non vuoto, usa quel percorso così com’è scritto.
• Se [backup] non ha dir, oppure il file principale non ha né una sezione [backup] né una lista includes, la directory è backups/ accanto al file principale.
• Altrimenti la directory è backups/ nella directory di stato, /var/lib/purge-warden/backups in un’installazione standard. Succede, per esempio, quando un file incluso potrebbe contenere [backup], o quando il file principale non è TOML valido.

warden config backup, warden config restore --list, warden config restore --latest e la dashboard usano tutti la stessa regola, quindi cercano nello stesso posto.

Non c’è un output --json. Per vedere cosa puoi ripristinare, usa warden config restore --list. Per guardare dentro un archivio senza ripristinarlo, estrailo in una directory vuota di prova ed esegui warden config lint sul config.toml estratto:

mkdir /tmp/archive-check
tar --no-same-owner --no-same-permissions -xzf config-20260505T091322Z.tar.gz -C /tmp/archive-check
warden --config /tmp/archive-check/config.toml config lint

I flag --auto e --reset-auto-failure, usati solo dallo scheduler, sono descritti in backup automatici.

Dove finiscono gli archivi

Un’installazione nuova scrive [backup] dir per te:

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

Un host aggiornato da una versione precedente può non avere una sezione [backup]. I suoi archivi vanno allora in backups/ accanto al config.toml principale, cioè /var/lib/purge-warden/backups finché la configurazione sta in /var/lib. Prima di warden config relocate, imposta dir a un percorso assoluto come /var/lib/purge-warden/backups con warden config edit. Relocate si rifiuta finché dir non è impostato o è relativo.

Per mandare gli archivi altrove usa dir = "/srv/purge-backups". La riga di comando, il backup pianificato e la dashboard leggono [backup]. Il daemon legge solo dir, per indicarti gli archivi quando si rifiuta di partire. Lo imposti nel file; la dashboard non può modificarlo.

Permessi della directory dei backup. I backup girano come utente del daemon (purge-warden), che partano dalla CLI, dal timer o dalla dashboard. La directory deve essere scrivibile da quell’utente, altrimenti tar fallisce con Permission denied. Per /var/lib/purge-warden/backups non c’è niente da fare. Quando la configurazione sta in /etc, come in ogni installazione nuova, il primo backup crea la directory, di proprietà di purge-warden con modo 0750. Su un host la cui configurazione sta ancora in /var/lib, la prepara l’installer. Gli archivi contengono la tua configurazione privata e l’elenco dei dispositivi, quindi gli altri utenti non possono leggere quella directory.

Se punti dir altrove, per esempio su un volume dedicato, i permessi di quel percorso sono responsabilità tua. Tienilo privato anche lì:

sudo install -d -m 0750 -o purge-warden -g purge-warden /srv/purge-backups

Anche il servizio di backup gira in una sandbox. Può scrivere solo in /etc/purge-warden e /var/lib/purge-warden. Un dir personalizzato fuori da questi due percorsi funziona per un warden config backup --out manuale, ma il backup pianificato non può scriverci finché non estendi ReadWritePaths= nella unit con un drop-in di systemd. Vedi servizio systemd.

Esempi

Un punto di controllo manuale prima di una modifica:

sudo warden config backup
# backup written: /var/lib/purge-warden/backups/config-20260505T091322Z.tar.gz
sudo warden config edit

Il comando elenca anche ogni voce che ha salvato.

Un backup notturno a rotazione su un mount esterno. Il mount deve essere scrivibile dall’utente purge-warden:

# Copia notturna della configurazione di Warden, rotazione dopo 30 giorni.
15 3 * * *  root  /usr/local/bin/warden config backup --out /mnt/backup/warden/ && \
                  find /mnt/backup/warden/ -name 'config-*.tar.gz' -mtime +30 -delete

Un trasferimento su un nuovo host:

# sul vecchio host
sudo warden config backup --out /tmp/
scp /tmp/config-*.tar.gz newhost:/tmp/

# sul nuovo host, a installazione finita
sudo warden config restore /tmp/config-20260505T091322Z.tar.gz
sudo systemctl restart purge-warden

L’archivio porta con sé l’id [node] del vecchio host, che vale solo all’avvio, quindi il daemon rifiuta il ricaricamento fino a questo riavvio. L’installer scrive un nuovo id [node] su ogni host, quindi ogni trasferimento lo cambia.

Sul nuovo host il ripristino non deve cambiare l’appartenenza al cluster; vedi le regole del ripristino.

Un recupero da una modifica sbagliata: elenca i punti di ripristino, poi prendi il più recente. Controlla prima le date: se dopo la modifica sbagliata è stato fatto un backup (uno manuale, oppure uno pianificato mentre la configurazione modificata si carica ancora), anche l’archivio più recente la contiene.

sudo warden config restore --list
# 3 restore point(s) in /var/lib/purge-warden/backups:
#   config-20260505T091322Z.tar.gz  (14.2 KiB)
#   config-20260504T031500Z.tar.gz  (14.1 KiB)
#   config-20260503T031500Z.tar.gz  (13.9 KiB)

sudo warden config restore --latest

Dalla dashboard

La scheda Settings della TUI usa lo stesso motore:

• b: apre una conferma; premi y per fare il backup. Il risultato, con il percorso dell’archivio, compare in una scheda di esito.
• R: apre la scelta del punto di ripristino. Mostra ogni punto con data, età relativa e dimensione, dal più recente. Scegline uno, premi Enter, conferma con y; Warden lo ripristina e chiede al daemon di ricaricare. La conferma ricorda che il ripristino non tiene una copia della configurazione attuale, e che cancella i pack e i file inclusi che l’archivio non dichiara.

Backup automatici

Tutto quanto sopra è manuale. Warden può anche fare backup a orari fissi. Un timer di systemd avvia il binario ogni ora, e warden config backup --auto decide se un backup è davvero dovuto. Lo scheduler è solo uno strumento: il daemon non c’entra.

Configurazione

Aggiungi alla tabella [backup] esistente fino a cinque campi facoltativi. Un’installazione nuova ha già la tabella con dir; una seconda tabella [backup] impedisce di caricare il file.

[backup]
dir                    = "/var/lib/purge-warden/backups"
auto_interval          = "24h"   # off when absent. "<N>h" or "<N>d", range 1h..720h (30d).
on_change              = false   # reserved for a future release; parsed but inert.
retention_count        = 30      # keep at most N archives (0 = unbounded).
retention_days         = 90      # drop archives older than D days (0 = unbounded).
disable_after_failures = 3       # auto-disable after N consecutive failures (0 = never).

Sono tutti facoltativi. Senza auto_interval lo scheduler non fa niente. retention_count e retention_days si combinano: un archivio viene eliminato se supera uno qualsiasi dei due limiti. La retention elimina solo i file config-*.tar.gz; i file .lock e .auto_state non vengono mai eliminati.

Come gira la pianificazione

Due unit di systemd, installate entrambe per te:

• purge-warden-backup.timer scatta ogni ora (OnUnitActiveSec=1h, OnBootSec=15min) e recupera all’avvio se la macchina era spenta quando era dovuto uno scatto.
• purge-warden-backup.service è Type=oneshot ed esegue warden config backup --auto come utente del daemon.

Il timer non conosce il tuo intervallo. Ogni esecuzione di --auto legge la configurazione e il file di stato, e decide:

1. La configurazione non si carica: salta l’esecuzione ed esce con 0 (vedi sotto).
2. Nessun auto_interval valido: esce con 0.
3. Prende il lock. Se un altro backup lo tiene: esce con 75.
4. disabled = true: esce con 0.
5. now - last_attempt < auto_interval: esce con 0 (“not due”).
6. Altrimenti: fa il backup, aggiorna lo stato, applica la retention.

Una modifica a auto_interval vale dallo scatto orario successivo. Non servono systemctl daemon-reload né una reinstallazione.

Una configurazione che non si carica darebbe un archivio che il ripristino rifiuta, quindi l’esecuzione pianificata non scrive niente. Non prende il lock, lascia com’erano il file di stato e il conteggio dei fallimenti, e stampa:

warning: /etc/purge-warden/config.toml does not load (1 error(s)); the scheduled backup is skipped and writes nothing. Run `warden config lint` to see every error.
  first error: ...

Il messaggio è in journalctl -u purge-warden-backup.service. Correggi la configurazione, e lo scatto successivo torna a fare il backup.

I backup automatici sono spenti finché non imposti auto_interval. Attivarli è una delle abitudini descritte in Risoluzione dei problemi, nella sezione su come prevenire un’interruzione del DNS.

File di stato

<directory-backup>/.auto_state è JSON, scritto in modo atomico, e si può leggere senza rischi:

sudo cat /var/lib/purge-warden/backups/.auto_state
# {
#   "consecutive_failures": 0,
#   "last_attempt": "2026-05-29T03:00:00Z",
#   "last_outcome": { "kind": "ok" },
#   "disabled": false
# }

• consecutive_failures: quante esecuzioni di --auto di fila sono fallite. Un warden config backup o un’esecuzione di --auto riusciti lo riportano a zero. Un backup manuale fallito non conta. Un backup dalla dashboard non legge e non scrive .auto_state. Un successo non azzera disabled.
• last_attempt: ora UTC in formato RFC 3339 dell’ultima esecuzione. Anche un warden config backup manuale la aggiorna, anche quando la scrittura dell’archivio fallisce, quindi un backup manuale fallito in questo modo rimanda il prossimo backup automatico di un intervallo intero.
• last_outcome: {"kind":"ok"} oppure {"kind":"err","message":"..."}.
• disabled: true dopo disable_after_failures fallimenti di fila. I backup manuali lo ignorano e partono comunque.

Riattivare dopo la disattivazione automatica

Dopo disable_after_failures fallimenti di fila lo scheduler imposta disabled = true, e gli scatti successivi non fanno niente. Per azzerarlo:

sudo -u purge-warden warden config backup --reset-auto-failure

Azzera consecutive_failures e disabled, non scrive alcun archivio e conserva la cronologia (last_attempt e last_outcome). Eseguirlo due volte non fa danni. Lo scatto successivo di --auto riprova, e il banner rosso nella scheda Settings sparisce.

File di lock

<directory-backup>/.lock viene creato all’inizio di ogni backup, manuale o automatico, e rimosso alla fine:

• Se un altro backup è già in corso, il comando esce con 75 (EX_TEMPFAIL) e scrive backup in progress (lock held since <ts>) su stderr.
• Un lock vecchio (più di 5 minuti, lasciato da un’esecuzione interrotta) viene rimosso dall’esecuzione successiva.

Controllare lo scheduler

systemctl status purge-warden-backup.timer    # quando scatta la prossima volta
systemctl status purge-warden-backup.service  # ultimo scatto ed exit code
journalctl -u purge-warden-backup.service     # storico degli scatti, compresi "not due" e "disabled"

Come funziona il ripristino

Il ripristino è una transazione della policy: o finisce del tutto o lascia la configurazione attiva com’era. In ordine:

1. Estrazione. Warden copia l’archivio in una directory di lavoro privata sotto la directory temporanea di sistema, poi estrae quella copia. La directory di lavoro viene rimossa all’uscita, anche in caso di errore.
2. Controllo dei limiti. Un archivio più grande di 1 GiB, che dichiara più di 1 GiB di contenuto o che elenca più di 10.000 file viene rifiutato.
3. Validazione. Il file principale estratto viene caricato con il controllo completo dello schema 5, lo stesso di warden config lint. Se fallisce, la configurazione attiva non viene toccata. Exit code 1; gli errori vengono stampati con file e riga. Un archivio di Warden 0.41 o precedenti viene rifiutato con un messaggio che inizia con schema-4 archive (Warden 0.41 or earlier); live config untouched.
4. Controllo dell’appartenenza al cluster. Un ripristino non cambia mai se questo nodo è standalone, primario o secondario, né a quale cluster appartiene. Se l’appartenenza nell’archivio è diversa da quella attiva, il ripristino viene rifiutato con refusing restore: it would change this node's .... Per appartenenza si intende standalone o membro, il ruolo e, per un membro, l’identità del cluster e l’id [node]. Un archivio standalone si ripristina su un nodo standalone anche se [node] è diverso. L’id del nodo vale solo all’avvio: il daemon rifiuta allora questo ricaricamento e tutti quelli successivi fino a sudo systemctl restart purge-warden. Per cambiare appartenenza usa warden cluster (leave, join o create), poi ripristina un archivio fatto con l’appartenenza attuale.
5. Applicazione in un’unica transazione. Warden mette al loro posto i file che il file principale ripristinato dichiara: il file principale, i suoi include e i pack delle Custom List. Scrive la modifica con una copia di recupero, quindi un errore a metà viene annullato. Un ripristino fallito lo dice, per esempio restore rolled back after a commit failure (transaction <id>): live config unchanged.
6. Richiesta di ricaricamento al daemon. Se un daemon è in esecuzione, il comando invia SIGHUP. Se nessun daemon è in esecuzione (per esempio, la unit è fallita), i file ripristinati valgono al prossimo avvio. Esegui sudo systemctl reset-failed purge-warden e sudo systemctl start purge-warden; systemctl reload non funziona su una unit ferma. Se non è stato possibile inviare il segnale a un daemon in esecuzione, esegui sudo systemctl reload purge-warden. In entrambi i casi il ripristino è comunque riuscito, e il comando stampa una nota che nomina systemctl reload.

Se l’archivio coincide già con la configurazione attiva, il comando stampa config already matches the archive; no reload requested ed esce con 0.

Se la configurazione attiva non si carica (un file principale rotto), il ripristino la ripara dall’archivio. Il comando stampa repaired invalid config at <path>; unnamed paths retained.

Il ripristino sostituisce solo i file che il file principale dell’archivio dichiara. Un file nella directory di configurazione a cui nessun include fa riferimento resta com’è. Un file che la configurazione attiva usa ma l’archivio no viene cancellato: un file incluso, o il pack di una Custom List che l’archivio non dichiara. Quando il ripristino ripara una configurazione che non si carica, non cancella niente. Su un secondario di cluster, il ripristino rifiuta qualsiasi modifica ai file che il primario replica; fai quelle modifiche sul primario.

Se un ripristino viene interrotto in un modo che Warden non sa sistemare da solo, stampa restore state is uncertain e ti chiede di eseguire systemctl restart purge-warden. Il recupero all’avvio completa o annulla la transazione prima di qualsiasi altra scrittura.

Exit code

Sicurezza

• Gli archivi contengono la configurazione in chiaro, compresi i segreti che hai scritto nel TOML. Trattali come dati sensibili; non metterli in un repository Git pubblico, e preferisci chmod 600 sulla directory di destinazione.
• Nessuna cifratura. Per un backup cifrato su un altro host, cifra tu l’archivio con gpg --encrypt o age, oppure tienilo su un filesystem cifrato.
• Nessuna firma. Oltre al controllo dello schema, il ripristino si fida dell’archivio. Non ripristinare archivi da fonti non fidate.
• Nessun record di audit. Backup e ripristino non scrivono record nell’audit log. Il ricaricamento del daemon dopo un ripristino viene registrato come evento di reload.

Risoluzione dei problemi

warden config restore fallisce con schema-4 archive (Warden 0.41 or earlier). L’archivio è stato fatto da Warden 0.41 o precedenti. 0.44.0 e successive ripristinano solo archivi dello schema 5. La configurazione attiva non è toccata. Per riusare le impostazioni, estrai l’archivio in una nuova directory vuota e copia quello che ti serve nella configurazione attuale con warden config edit. L’errore stampa il comando tar esatto.

refusing restore: it would change this node's .... L’archivio è stato fatto quando il nodo aveva un altro ruolo nel cluster, o apparteneva a un altro cluster. Ripristina un archivio fatto con l’appartenenza attuale, oppure cambia prima l’appartenenza con warden cluster.

refusing restore: this node's cluster membership is unknown. Il file principale attivo non si carica, e il nodo sembra un membro di un cluster. Esegui warden config lint, correggi a mano il file principale, poi ripristina di nuovo.

warden config restore esce con 0 ma il daemon serve ancora la vecchia configurazione. Esegui sudo warden audit tail -n 20 o journalctl -u purge-warden per vedere che fine ha fatto il ricaricamento:

• Il ricaricamento è rejected con reload requires daemon restart, per esempio perché l’archivio ha un id [node] diverso. Esegui sudo systemctl restart purge-warden. systemctl reload viene rifiutato allo stesso modo.
• Non risulta nessun ricaricamento. Il SIGHUP è andato perso. Esegui sudo systemctl reload purge-warden.
• La unit era fallita. Esegui sudo systemctl reset-failed purge-warden e sudo systemctl start purge-warden.

warden config backup esce con 75 e backup in progress. Un altro backup tiene il lock, di solito un’esecuzione pianificata che si sovrappone a quella manuale. Aspetta un momento e riprova. Un .lock più vecchio di 5 minuti viene rimosso all’esecuzione successiva.

I backup pianificati non vengono più fatti. Le cause più comuni sono due:

• La configurazione non si carica. Ogni scatto salta l’esecuzione, e journalctl -u purge-warden-backup.service mostra the scheduled backup is skipped and writes nothing. Esegui sudo warden config lint e correggi l’errore. Lo scatto successivo torna a fare il backup.
• Lo scheduler si è disattivato da solo dopo ripetuti fallimenti. Controlla in sudo cat <directory-backup>/.auto_state se c’è "disabled": true e il messaggio di last_outcome, correggi la causa (di solito i permessi della directory), poi esegui sudo -u purge-warden warden config backup --reset-auto-failure.

tar: Cannot open: Permission denied da warden config backup. La directory dei backup non è scrivibile dall’utente del daemon. Creala con il proprietario giusto (vedi dove finiscono gli archivi) oppure scegli un --out scrivibile.

backup refuses symlink member ... o backup refuses hard-linked member .... Qualcosa nella directory di configurazione è un link o un file speciale. Sostituiscilo con un file normale, oppure spostalo fuori dalla directory di configurazione.

Il file di backup cresce nel tempo. Un file inutilizzato si è accumulato nella directory di configurazione. Controllala e rimuovi quello che non ti serve più.

Per altri problemi di esercizio, vedi risoluzione dei problemi.

Vedi anche

• Riferimento warden config: tutti i comandi di configurazione in un colpo d’occhio.
• Upgrade (in inglese): fai prima un backup, e sposta la configurazione in /etc.
• Percorsi dei file: dove Warden legge e scrive su disco.
• Servizio systemd: le unit del timer e del servizio.
• Risoluzione dei problemi: procedure di recupero più ampie.