FAQ
Da issue GitHub, discussioni sulle PR e domande emerse durante la scrittura della documentazione. Meglio poche domande valide che un numero tondo di riempitivi.
Qual e la differenza tra --watch, --follow e tail?
--watch e la dashboard TUI a 8 schede (bubbles, schermo alternativo, q per uscire). --follow e lo streaming a livello root su stdout (come tail -f). tail e un sottocomando che trasmette righe di log colorate; tail --detect aggiunge l'evidenziazione inline della gravita. Usa --watch per esplorare, --follow o tail per pipe e filtri.
Perche --ip 10.0.0.1 restituisce 0 risultati quando il log contiene chiaramente quell'IP?
Il filtro confronta EffectiveClientIP: l'ultimo hop pubblico X-Forwarded-For se e impostato --trust-forwarded, altrimenti RemoteIP. Se Caddy e dietro una CDN/proxy senza --trust-forwarded, stai filtrando l'IP del proxy, non del client. Controlla anche CIDR rispetto a IP singolo e se l'arricchimento GeoIP e stato eseguito prima (necessario per --country/--asn, ma non per --ip).
Perche --country IT restituisce 0?
Richiede un mmdb GeoIP. Il download automatico recupera ~/.config/caddy-analyzer/GeoLite2-*.mmdb alla prima esecuzione; dietro un proxy o con --no-auto-download fallisce silenziosamente e tutte le ricerche sono unknown. Controlla ls ~/.config/caddy-analyzer/*.mmdb e passa --geoip-db /path.mmdb. Gli IP privati (10/192.168/127) sono sempre unknown e vengono scartati dalle allowlist, mantenuti dalle denylist.
Guard e in esecuzione ma non blocca: perche?
Causa comune: Caddy e in Docker e guard usa iptables (INPUT), mentre il traffico passa da DOCKER-USER. Usa --firewall-backend hybrid o auto (rileva Docker). Controlla --detect-confidence 8: gli hit a bassa confidenza non vengono bloccati. Controlla --never-block: il tuo IP potrebbe essere nella allowlist. Consulta guard e Risoluzione dei problemi → iptables.
Perche docker://caddy non mostra log?
Due correzioni dalla 0.5.1: Caddy scrive gli access log su stderr e il reader ora unisce stdout+stderr. Se e ancora vuoto: controlla il nome con docker ps | grep caddy e l'output grezzo con docker logs caddy --tail 5. Controlla anche i permessi di docker.sock (sudo usermod -aG docker $USER).
--detect blocca gli IP?
No. --detect si limita a riportare i dati (table/json/html, raggruppati per IP con confidenza e tag MITRE). Solo guard (e block manuale) modifica le regole firewall. Usa --detect -f html per rivedere prima di abilitare guard.
Un log da 1M righe causa OOM?
No: i contatori hanno un limite (--max-cardinality 100k per chiave, LRU GeoIP 50k, istogramma 1k bucket). 1M righe occupano ~138 MB e vengono elaborate a ~7K righe/sec con --detect (~70K solo parsing). Consulta Architettura → limiti di memoria.
Perche update richiede cosign?
update e fail-closed: verifica la firma cosign keyless su checksums.txt piu SHA256 dell'archivio. Se cosign manca, viene scaricato automaticamente (0.6.1); qualsiasi errore di verifica interrompe l'operazione senza installare nulla. Consulta Installazione → Aggiornamento.
Perche --country-block CN genera un errore all'avvio?
Fallisce subito se non e individuabile alcun mmdb e il download automatico e disattivato (--no-auto-download o assenza di rete). Soluzione: consenti il download automatico o passa --geoip-db. Lo stesso vale per top country/asn.