Caddy Rate_limit Configuration

Nite included in Tutorials and Caddy Tutorial

2026-04-28 About 200 words One minute

Contents

Why Rate Limiting

Public-facing services inevitably face traffic abuse:

Crawlers scraping the entire site
Brute-force login attempts
CC attacks consuming bandwidth
Script kiddies hammering APIs

Rate limiting is the most basic defense. Caddy’s rate_limit plugin implements a token bucket algorithm, performing rate checks before requests reach the reverse proxy, preventing pressure from propagating to backend services.

Defining a Rate Limit Zone

example.com {
    rate_limit {
        zone dynamic_zone {
            key {client_ip}
            events 50
            window 10s
        }
        log_key
    }
}

Zone Parameters

key {client_ip}: Differentiate by client IP. When trusted_proxies is configured, this uses the real client IP extracted from X-Forwarded-For, not the proxy’s IP.
events 50: Maximum number of requests allowed within the window.
window 10s: Time window - 10 seconds here.

Combined: each client IP can make at most 50 requests per 10 seconds. Excess requests receive a 429 Too Many Requests response.

log_key for Debugging

log_key

When enabled, Caddy logs the rate-limited client key (IP address). Output looks like:

rate_limit exceeded for key: 192.168.1.100

When deploying a new service, enable log_key first to observe normal request patterns, then determine appropriate thresholds.