Master Nginx Rate Limiting: Request & Connection Control with Practical Configs

Introduction

In web application development, Nginx is commonly used as an entry‑level rate‑limiting tool. The entry layer refers to the traffic entry point. Nginx implements rate limiting mainly via two built‑in modules: ngx_http_limit_conn_module for connection limiting and ngx_http_limit_req_module, which uses a leaky‑bucket algorithm for request limiting.

Request Rate Limiting (limit_req)

limit_req limits requests based on a key (e.g., IP). Example configuration:

http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    limit_conn_log_level error;
    limit_conn_status 503;
    ...
    server {
        location /limit {
            limit_req zone=one burst=5 nodelay;
        }
    }
}

limit_req : configures the limiting zone, burst capacity (default 0), and delay mode (default delayed).

limit_req_zone : defines the key, shared memory size, and fixed request rate. The key $binary_remote_addr represents the client IP. Rates such as 10r/s or 60r/m are converted to a per‑second rate.

limit_conn_status : status code returned when a request is limited (default 503).

limit_conn_log_level : log level for limited requests (default error).

The execution process of limit_req is:

When a request arrives, Nginx checks whether the time since the last request requires limiting.

If no burst is configured, the bucket capacity is 0 and requests are processed at the fixed rate; excess requests receive the configured error code.

If a burst is configured and nodelay is not set, the bucket can absorb bursts; excess requests are delayed according to the rate.

If a burst is configured with nodelay, bursts are processed immediately up to the burst size; excess requests are rejected.

If the request is not limited, it proceeds normally.

Nginx periodically expires some limit keys to reclaim memory.

Connection Limiting (limit_conn)

limit_conn limits the total number of concurrent connections for a given key (e.g., IP or domain). Only connections that have been fully read by Nginx are counted.

Configuration example:

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    limit_conn_log_level error;
    limit_conn_status 503;
    ...
    server {
        location /limit {
            limit_conn addr 1;
        }
    }
}

limit_conn : defines the shared memory zone and the maximum number of connections for the key.

limit_conn_zone : configures the key and memory size; the key can be $binary_remote_addr (IP) or $server_name (domain).

limit_conn_status : status code returned when the limit is exceeded.

limit_conn_log_level : log level for limited connections.

The execution flow of limit_conn:

On request entry, Nginx checks whether the current connection count for the key exceeds the configured maximum.

If exceeded, the request is rejected with limit_conn_status; otherwise the count is incremented and a callback is registered.

The request is processed.

When the request finishes, the callback decrements the connection count.

Whitelist Configuration

Internal trusted traffic can be exempted from rate limiting using a whitelist. Nginx provides ngx_http_geo_module and ngx_http_map_module for this purpose.

geo $limit {
    default 1;
    10.0.0.0/8 0;
    192.168.0.0/24 0;
    172.16.30.73 0;
}
map $limit $limit_key {
    0 "";
    1 $binary_remote_addr;
}
limit_req_zone $limit_key zone=myRateLimit:10m rate=10r/s;

Explanation:

geo returns 0 for whitelisted subnets/IPs and 1 for others.

map converts $limit to $limit_key; a value of 0 yields an empty key, bypassing rate limiting.

limit_req_zone now uses $limit_key, so only non‑whitelisted clients are rate‑limited.

References

《亿级流量网站架构核心技术》

Nginx official blog: “Rate Limiting with NGINX and NGINX Plus”

ngx_http_geo_module documentation

ngx_http_map_module documentation