This page is about Caddy 1, but Caddy 2 is now in beta. Click here for Caddy 2. Thank you for your patience as we transition!

User Guide

http.ratelimit
Plugin

ratelimit is used to limit the request processing rate based on client's IP address/request header. Excessive requests will be terminated with an error 429 (Too Many Requests) and X-RateLimit-RetryAfter header will be returned.

Full documentation

Examples

For single resource:
ratelimit methods path rate burst unit

methods are the request methods it will match (comma separately); path is the file or directory to apply rate limit; rate is the limited request in every time unit (r/s, r/m, r/h, r/d, r/w) (e.g. 1); burst is the maximum burst size client can exceed; burst >= rate (e.g. 2); unit is the time interval (currently support: second, minute, hour, day, week).

For multiple resources:
ratelimit methods rate burst unit { whitelist CIDR,CIDR limit_by_header xxx status xxx,xxx resources }

whitelist is the keyword for whitelisting your trusted ips (comma separately). CIDR is the IP range you don't want to perform rate limit, whitelist is a general rule, it won't target for specific resources; limit_by_header is the keyword for matching the request header. Like whitelist, it's also a general rule (normally you shouldn't apply this rule unless the default 'limit by ip' is not what you want and you want to 'limit by request header'); status is the keyword for matching the response status code (comma separately). If this rule is triggered, all subsequent requests from that client will be blocked regardless of which status code is returned or which resource is requested (this won't block resources not defined in ratelimit's config); resources is a list of files/directories to apply rate limit, one per line. Note: If you don't want to apply rate limit on some special resources, add ^ in front of the path.

Limit clients to 2 requests per second (bursts of 3) to any methods and any resources under /r:
ratelimit * /r 2 3 second
Don't perform rate limit if requests come from 1.2.3.4 or 192.168.1.0/30(192.168.1.0 ~ 192.168.1.3), for the listed paths, limit clients to 2 requests per minute (bursts of 2) if the request method is GET or POST and always ignore /dist/app.js:
ratelimit 2 2 minute { whitelist 1.2.3.4/32,192.168.1.0/30 status * /foo.html /api ^/dist/app.js }
Related Links
Documentation

Access the full documentation for this plugin off-site:

Docs
Plugin Help

Get help from the maintainers of the http.ratelimit plugin:

Support
Plugin Website

Visit http.ratelimit's website for more information:

Website
Plugin Author: jsxqf
Last Updated: 31 Mar 2019, 1:25 AM
This plugin is independent of the Caddy project and is not endorsed or maintained by Caddy developers. Use at your own risk. Do not file issues for this plugin on Caddy's bug tracker.