Inizializzazione

warden init trasforma un binario nudo in uno scaffold funzionante — utente di sistema, directory e un primo config.toml — con un solo comando.

Ogni guida di installazione lo esegue già per te, come uno dei tanti passi. Questa pagina è dedicata al comando in sé: cosa crea, cosa chiede, e cosa fare quando si rifiuta.

Cosa crea

Eseguito senza --config, warden init predispone il layout storico:

Passa --config <percorso> e ognuno di questi si sposta con il percorso indicato — directory, socket e master. Fonte: src/cli/commands/init/mod.rs (InitLayout::for_config).

warden init richiede root, e si rifiuta subito se non viene eseguito come root: warden init requires root. Run with sudo.

Eseguirlo

Ci sono due modalità: rispondere a quattro domande, o saltarle tutte con --yes e flag per singola voce.

Interattivo

Senza --yes, init fa quattro domande in quest’ordine — resolver upstream, profilo default, sottoscrizioni blocklist, reti client consentite — e ognuna accetta un Invio a vuoto per il proprio default:

Il menu upstream elenca ciò a cui punta già il /etc/resolv.conf di questa macchina (o, in mancanza, resolvectl status), più eventuali voci da un file upstreams.toml accanto alla config — nessun comando lo scrive per te; lo crei a mano se vuoi un menu curato. Scegliere 0 permette di digitare un indirizzo che non compare in nessuno dei due elenchi.

Non interattivo (--yes)

Le installazioni scriptate saltano ogni prompt:

sudo warden init --yes

--yes accetta i default incorporati per il profilo (default), le liste (le tre sotto) e allow_from (RFC 1918 + loopback) — ma non per il resolver upstream. Senza flag --upstream, --yes adotta quanto già indicato dalla configurazione DNS di questa macchina, e stampa cosa ha scelto così da non essere silenzioso in un transcript di installazione:

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

Se non viene rilevato nulla, o ogni indirizzo rilevato risulta essere il listener di Warden stesso, --yes si rifiuta invece di inventare un valore — vedi Risoluzione problemi.

Flag

Fonte: src/cli/mod.rs (Commands::Init), src/cli/commands/init/mod.rs, src/cli/commands/init/upstream.rs.

Le tre liste di default

--yes, o un Invio a vuoto al prompt di sottoscrizione, sottoscrive queste — indicate qui con l’id di entità con cui vengono generate, perché è quello che serve a un successivo warden blocklist tag add <id> …:

--lists accetta solo id di catalogo — non URL diretti, né slug sconosciuti; entrambi sono errori bloccanti prima di scrivere qualunque cosa. Sfoglia il catalogo completo con warden lists catalog; aggiungi una sorgente con URL dopo l’init con warden blocklist add <id> --url <url>. Vedi Blocklist e Tag — ogni lista sottoscritta viene taggata uncategorized, il sentinel riservato di sistema, così il filtraggio è attivo di default ancora prima che tu nomini i tuoi tag.

Nessun upstream di default, di proposito

--upstream non ha alcun resolver incorporato. Versioni precedenti avevano un provider di default: questo significava che ogni nuova installazione instradava l’intero flusso DNS della famiglia verso un’unica azienda scelta da Warden, non dall’operatore. Non esiste un default non vuoto neutrale — qualsiasi indirizzo favorisce qualcuno — quindi lo scaffold parte vuoto e chiede. Ometti il flag e init rileva ciò che questa macchina già usa (interattivo: offerto per primo nel menu; --yes: adottato automaticamente), oppure si rifiuta e indica esattamente cosa passare. Fonte: src/cli/commands/init/mod.rs (UPSTREAM_MISSING, NO_DEFAULT_UPSTREAMS).

Rieseguire init (--force)

Senza --force, init si rifiuta prima di toccare qualunque cosa se la config target esiste già:

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

Con --force, il file esistente viene rinominato — config.toml diventa config.toml.pre-init-20260731T140502Z — prima che il nuovo venga scritto, quindi una re-init per errore è recuperabile con una rinomina, non equivale a un file perso. warden init --force ricrea comunque l’utente di sistema e fa chown -R sulla directory di stato; su un’installazione live con dati già in lists/ e data/, quella ricorsione è sicura sui symlink (chown -R -h) ma tocca comunque la proprietà di tutto ciò che c’è sotto.

Dopo init

init scrive la config ma non crea nessun token IPC — ogni comando mutante o admin (stop, reload, ogni verbo che modifica la config) si rifiuta senza uno. Il comando stesso stampa i tre passi successivi:

Se [server].listen si lega a una porta sotto la 1024 (il default dello scaffold, 0.0.0.0:53, lo fa), il daemon ha bisogno di CAP_NET_BIND_SERVICE per legarsi — sudo -u purge-warden da solo non concede quella capability. init aggiunge il rimedio esatto ai passi stampati:

setcap cap_net_bind_service=+ep /usr/local/bin/warden

— oppure esegui il daemon dall’unit systemd pacchettizzata, che concede la stessa capability via AmbientCapabilities= e non richiede alcun setcap. Vedi servizio systemd.

Risoluzione problemi

no upstream resolver configured — init --yes si rifiuta del tutto. Non è stato trovato nulla di utilizzabile su questa macchina (nessuna voce in /etc/resolv.conf, resolvectl assente o vuoto). Passane uno esplicitamente:

sudo warden init --yes --upstream 192.0.2.53:53

the only resolver(s) this machine uses are warden itself (…) — un rifiuto diverso, stesso comando. È lo stato normale di un’installazione già funzionante che viene re-inizializzata: una volta che la rete punta già a Warden e la vecchia voce resolver è sparita, /etc/resolv.conf nomina solo l’indirizzo di Warden stesso, e adottarlo farebbe sì che Warden interroghi se stesso. È un messaggio distinto dal precedente di proposito — non trattarlo come “nulla rilevato”. Passa --upstream con un resolver esterno a questa macchina.

config already exists: … Atteso — vedi Rieseguire init. Aggiungi --force, oppure punta --config a un percorso nuovo se volevi tenere quella vecchia.

--lists rifiuta una voce con “raw URLs are not accepted”. --lists accetta solo id di catalogo. Sottoscrivi per id, poi aggiungi una sorgente URL personalizzata dopo con warden blocklist add <id> --url <url>.

Un comando mutante fallisce dopo init con errore di autenticazione / “no token”. Atteso — init non ne crea mai uno. Esegui warden token generate come mostrato in Dopo init.

sudo -u purge-warden warden start --daemon fallisce con un errore di bind / permessi sulla porta 53. Vedi il passo setcap in Dopo init, oppure usa l’unit systemd pacchettizzata.

Per altro, vedi risoluzione problemi.

Vedi anche

• Avvio rapido — il percorso in quattro tappe di cui questo comando è la prima.
• Impostazioni globali — modificare [server] / [upstream] dopo init, con warden config edit.
• Blocklist e Tag — il modello di sottoscrizione a cui si agganciano le liste dello scaffold.
• Backup e ripristino — warden config backup, prima di una re-init con --force.
• Servizio systemd — l’alternativa a un setcap manuale.
• Riferimento CLI — ordine di risoluzione del percorso config e il resto della superficie warden config.