Configuration

How the tool itself is configured. For how to connect to each log source, see Log Sources.

Config file — where it lives

Two locations, first hit wins:

~/.config follows XDG_CONFIG_HOME if set, else os.UserConfigDir(). Dirs are created 0750, files 0600.

Schema

{
  "source": "docker://caddy",
  "namespace": "production",
  "blocklist": {
    "no_defaults": false,
    "custom_sources": [{ "name": "My List", "url": "https://example.com/list.txt" }],
    "remove_sources": ["tor-exit-nodes"]
  },
  "tuning": {
    "geo_cache_ttl": "24h",
    "geo_cache_size": 50000,
    "iptables_timeout": "10s"
  }
}

Manage it

caddy-analyze config                    # show active file + source
caddy-analyze config /var/log/caddy/access.log          # set local
caddy-analyze config docker://caddy --global            # set global
caddy-analyze config k8s://caddy-xxx -n production     # with namespace
caddy-analyze config reset              # remove local
caddy-analyze config reset --global     # remove global
caddy-analyze blocklist init            # persist blocklist flags to config
caddy-analyze whitelist --init          # persist never-block to /etc/caddy-analyzer/whitelist.txt

blocklist init writes current --no-default-blocklists / --blocklist-config / --blocklist-remove into the same file so guard picks them up without CLI flags.

Tuning — precedence

Config file values are defaults; CLI flags override when explicitly set. The three tunables:

# example: keep GeoIP results longer on a busy host
caddy-analyze --geo-cache-ttl 48h --geo-cache-size 100000 /var/log/caddy/access.log

Environment & XDG

Caches & state (not config)

Override with flags: --cache-dir, --geoip-db, --state-file, --audit-log, --never-block-file.

Resolution order (no source arg)

1. ./caddy-analyzer.json → ~/.config/…/config.json
2. Stdin pipe if data is piped
3. 5 candidates: ./access.log, ./caddy.log, ./caddy-access.log, /var/log/caddy/access.log, /var/log/caddy/caddy.log

↑