FAQ
From GitHub issues, PR discussions and questions that came up while writing the docs. Fewer good questions beat a round number of filler.
What is the difference between --watch, --follow and tail?
--watch is the 8-tab TUI dashboard (bubbles, alt-screen, q to quit). --follow is root-level streaming to stdout (like tail -f). tail is a subcommand that streams colorized log lines; tail --detect adds inline severity highlight. Use --watch to explore, --follow or tail to pipe/filter.
Why does --ip 10.0.0.1 return 0 results when the log clearly has that IP?
The filter matches EffectiveClientIP: last public X-Forwarded-For hop if --trust-forwarded is set, else RemoteIP. If Caddy is behind a CDN/proxy without --trust-forwarded, you are filtering the proxy IP, not the client. Also check CIDR vs single IP and whether GeoIP enrichment ran first (needed for --country/--asn but not for --ip).
Why does --country IT return 0?
Requires a GeoIP mmdb. Auto-download fetches to ~/.config/caddy-analyzer/GeoLite2-*.mmdb on first run; behind a proxy or with --no-auto-download it fails silently and all lookups are unknown. Check ls ~/.config/caddy-analyzer/*.mmdb and pass --geoip-db /path.mmdb. Private IPs (10/192.168/127) are always unknown and are dropped by allowlists, kept by denylists.
Guard is running but not blocking — why?
Common: Caddy runs in Docker and guard uses iptables (INPUT) while traffic hits DOCKER-USER. Use --firewall-backend hybrid or auto (detects Docker). Check --detect-confidence 8 — low-confidence hits are not blocked. Check --never-block — your IP may be allowlisted. See guard and Troubleshooting → iptables.
Why does docker://caddy show no logs?
Two fixes from 0.5.1: Caddy writes access logs to stderr, and the reader now merges stdout+stderr. If still empty: check docker ps | grep caddy for the name, and docker logs caddy --tail 5 for raw output. Also check docker.sock permissions (sudo usermod -aG docker $USER).
Does --detect block IPs?
No. --detect only reports (table/json/html, grouped by IP with confidence and MITRE tags). Only guard (and manual block) modify firewall rules. Use --detect -f html to review before enabling guard.
Will a 1M-line log OOM?
No — counters are capped (--max-cardinality 100k per key, GeoIP LRU 50k, histogram 1k buckets). 1M lines ~138 MB and ~7K lines/sec with --detect (~70K parse-only). See Architecture → memory bounds.
Why does update require cosign?
update is fail-closed: it verifies the cosign keyless signature on checksums.txt plus SHA256 of the archive. If cosign is missing it is auto-downloaded (0.6.1); any verification failure aborts with nothing installed. See Installation → Update.
Why does --country-block CN error on start?
It fails fast if no mmdb is discoverable and auto-download is off (--no-auto-download or no network). Fix: allow auto-download or pass --geoip-db. Same for top country/asn.