Master Nginx Rate Limiting: From Basics to Advanced Configurations

Rate limiting (rate‑limiting) in Nginx is a practical feature that controls the number of HTTP requests a client can make within a given time window, useful for security, DDoS mitigation, and protecting upstream servers.

Nginx Rate‑Limiting Mechanism

Nginx implements rate limiting using the leaky‑bucket algorithm, which works like a bucket that leaks at a constant rate; excess requests overflow and are dropped.

Basic Configuration

The two main directives are limit_req_zone and limit_req. limit_req_zone defines a shared memory zone and parameters (key, zone size, rate), while limit_req activates the limit in a specific context.

limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;
server {
    location /login/ {
        limit_req zone=mylimit;
        proxy_pass http://my_upstream;
    }
}

Key: request attribute (e.g., $binary_remote_addr). Zone: shared memory for IP states. Rate: maximum request rate (10 r/s in the example).

Handling Bursts

Using the burst parameter allows a temporary queue for excess requests. Adding nodelay makes queued requests forwarded immediately without waiting, while still respecting the overall rate.

location /login/ {
    limit_req zone=mylimit burst=20 nodelay;
    proxy_pass http://my_upstream;
}

Advanced Examples

Combining rate limiting with geo and map directives enables whitelisting. Requests from whitelisted IPs receive an empty key, bypassing the limit, while others are limited.

geo $limit {
    default 1;
    10.0.0.0/8 0;
    192.168.0.0/64 0;
}
map $limit $limit_key {
    0 "";
    1 $binary_remote_addr;
}
limit_req_zone $limit_key zone=req_zone:10m rate=5r/s;
server {
    location / {
        limit_req zone=req_zone burst=10 nodelay;
    }
}

Multiple limit_req directives in one location apply the most restrictive limit; combining zones with different rates allows separate limits for whitelisted and regular traffic.

Logging and Error Codes

Nginx logs limited requests with details such as zone, client IP, and excess count. The default response is 503, but limit_req_status can change it (e.g., to 444). The log level can be adjusted with limit_req_log_level.

location /login/ {
    limit_req zone=mylimit burst=20 nodelay;
    limit_req_log_level warn;
    limit_req_status 444;
    proxy_pass http://my_upstream;
}

Overall, Nginx rate limiting provides fine‑grained control over request rates, burst handling, whitelisting, logging, and custom error responses.