Caddy 2.8+ Knowledge Patch

Claude's baseline knowledge covers Caddy through 2.7.x. This skill provides features from 2.8.0 (May 2024) onwards.

Source: Caddy release notes at https://github.com/caddyserver/caddy/releases

Quick Reference: Breaking Changes

Old	New	Since
basicauth	basic_auth	2.8.0
skip_log	log_skip	2.8.0
buffer_requests/buffer_responses/max_buffer_size	request_buffers/response_buffers	2.8.0
forwarded option in remote_ip matcher	Use client_ip matcher instead	2.8.0
scrypt hash in basic_auth	Removed (use bcrypt or argon2id)	2.8.0
ZeroSSL as default issuer (no email)	ZeroSSL only if email is set	2.8.0
auto_https prefer_wildcard	Removed — wildcards are default	2.10.0
roll_gzip	roll_compression zstd	2.11.2

Quick Reference: New Placeholders

Placeholder	Description	Since
{file./path/to/file}	File contents (strips trailing newline)	2.8.0
{?query}	Full query string with ? prefix (empty if none)	2.9.0
{http.request.local}	Local address (also .host, .port)	2.8.0
{http.request.body_base64}	Request body (base64) for logging	2.11.1
{http.response.body}	Response body for logging	2.11.1

Caddy 2.8.0 (May 2024)

{file.*} Placeholder

Read secrets from files — avoids embedding credentials in config:

reverse_proxy {header_up Authorization "Bearer {file./run/secrets/token}"}

uri query Structured Rewrites

uri query +key value    # add
uri query -key          # delete
uri query key value     # set/replace

handle_errors Status Code Filtering

handle_errors 404 {
    respond "Not found" 404
}
handle_errors 5xx {
    respond "Server error" 500
}

log_append Handler

Adds custom fields to access logs:

log_append X-Request-ID {header.X-Request-ID}

On-demand TLS permission Module

JSON ask deprecated in favor of pluggable permission module. Caddyfile ask still works:

{
    on_demand_tls {
        ask https://auth.example.com/check
        # OR
        permission <module>
    }
}

HTTP/3 to Backends (Experimental)

reverse_proxy https://backend:443 {
    transport http {
        versions h3
    }
}

For full details, consult references/caddyfile-directives.md and references/tls-and-certificates.md.

Caddy 2.9.0 (Dec 2024)

{?query} Placeholder

Returns full query string including ? prefix (empty string if no query).

try_files Fallback Strategy

try_files {
    policy first_exist_fallback
}

Falls back to the last file if none of the earlier ones exist.

Log Sampling

{
    log {
        sampling {
            interval 1000
            first 100
            thereafter 100
        }
    }
}

header Directive Response Matching (v2.9.1)

header @response match {
    status 200
}
header @response Cache-Control "public, max-age=3600"

force_automate (Experimental)

Override wildcard cert preference: tls force_automate

For full details, consult references/caddyfile-directives.md and references/logging.md.

Caddy 2.10.0 (Apr 2025)

Encrypted ClientHello (ECH) (Major)

Encrypts domain names in TLS ClientHello. Requires DNS provider module:

{
    dns cloudflare {env.CLOUDFLARE_API_KEY}
    ech ech.example.net
}

Wildcards by Default (Major)

Caddy now uses wildcard certificates for subdomains. Override with tls force_automate. The auto_https prefer_wildcard option is removed.

Global dns Option

Configure DNS provider once for all features:

{
    dns cloudflare {env.CLOUDFLARE_API_KEY}
}

Post-Quantum Key Exchange

X25519MLKEM768 is now a default cryptographic group. No configuration needed.

request_body set

request_body {
    set "replacement body content"
}

Other Changes

• ACME profiles support (experimental, e.g., 6-day Let's Encrypt certs)
• Reverse proxy sets Via header instead of duplicate Server header

For full details, consult references/tls-and-certificates.md and references/reverse-proxy.md.

Caddy 2.11.x (Feb-Mar 2026)

SIGUSR1 Config Reload (2.11.1)

kill -USR1 $(pidof caddy)

Works if config was loaded from a file and not changed via API.

Argon2id for basic_auth (2.11.1)

basic_auth {
    user $argon2id$...
}

Time-Rolling Logs (2.11.1)

Switched from lumberjack to timberjack. New time-based rolling:

log {
    output file /var/log/caddy/access.log {
        roll_time 24h
    }
}

tls_resolvers Global Option (2.11.2)

{
    tls_resolvers 1.1.1.1 8.8.8.8
}

Security Fixes (2.11.2)

• forward_auth copy_headers now strips client-supplied identity headers (prevents privilege escalation)
• vars_regexp double-expansion fixed (could leak secrets)

For full details, consult references/logging.md, references/server-options.md, and references/tls-and-certificates.md.