nginx rate limiting: limit_req and limit_conn

nginx rate limiting is built from two modules: one caps how fast requests arrive per key, the other caps how many connections a key holds at once. Both have a dry run switch, so the same limit can be written, watched and only then enforced.

Section Rate limiting Updated Two modules limit_req and limit_conn

Two modules, one order

nginx rate limiting is built from two modules. ngx_http_limit_req_module caps how fast requests may arrive per key, and ngx_http_limit_conn_module caps how many connections a key may hold at once. Both keep their counters in a shared memory zone, and both have a dry run switch, so the same limit can be written, watched and only then enforced. That is the order this page follows, and it is the same off, monitor, block sequence that Bridge WAF uses.

  • Request rate: limit_req_zone declares the zone and the rate, limit_req applies it to a context.
  • Connections: limit_conn_zone declares the zone, limit_conn sets the allowed number.
  • Rejected requests: both modules answer with status 503 unless limit_req_status or limit_conn_status says otherwise.
  • Dry run: limit_req_dry_run exists since nginx 1.17.1, limit_conn_dry_run since 1.17.6.
  • Memory: one megabyte of zone keeps about 16 thousand 64-byte states, or about 8 thousand 128-byte states.

A minimal limit_req configuration

Two lines are the whole nginx rate limiting mechanism: one declares what is counted in a shared memory zone, one says where the limit applies.

limit_req: one zone, one location
http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    server {
        location /search/ {
            limit_req zone=one burst=5;
        }
    }
}

limit_req_zone sits at the http level. The first argument is the key: the thing each counter belongs to. Here it is the client address, written as $binary_remote_addr, a variable whose size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. A key can contain text, variables and combinations of them, and a request with an empty key value is not counted at all.

zone=one:10m names the zone and sizes it. rate=1r/s is the sustained rate. A rate below one request per second is written per minute, so half a request per second is 30r/m. The limit_req line then attaches the zone to /search/. Unlike the zone declaration, it is valid in http, server and location.

If the zone fills up, nginx removes the least recently used state. If a new state still cannot be created, the request is terminated with an error.

How burst and nodelay change the result

With burst=5, the example allows an average of one request per second with bursts not exceeding five requests. Requests above the rate are delayed so they are processed at the defined rate, and once the burst size is exceeded the request is terminated with an error. By default the burst size is zero.

Delaying is not always wanted. Adding nodelay serves the excess requests immediately instead of spacing them out, while still refusing everything past the burst. The delay= parameter, available since nginx 1.15.7, sets how many excess requests pass before delaying starts.

The reasoning behind the two numbers, and how to pick them from your own traffic, is covered in burst / nodelay. The module documentation names its method as the “leaky bucket”; how that method compares with the others is described in rate limiting algorithms.

Several limit_req directives can stand at one level, for example one keyed on the client address and one keyed on the virtual server. They are inherited from the previous configuration level only if the current level defines none of its own.

Directives that shape the response

limit_req directives: what each sets and its default
DirectiveWhat it setsDefault
limit_req_zoneZone name, size, key and ratenone, http level only
limit_reqZone, burst, nodelay or delay=none
limit_req_statusStatus code for rejected requests503
limit_req_log_levelLog level for refusals; delays are logged one level lowererror
limit_req_dry_runDry run switchoff

The default is 503, not 429. Setting limit_req_status 429; changes it. What the status should mean to a client, and what a well-behaved client does with it, is described in 429 Too Many Requests.

nginx does not add a wait hint on its own. To tell clients when to come back, add the header yourself, and add it with the always parameter, because without it add_header applies only to the listed success and redirect codes, not to a 429 or 503:

a 429 status with a wait hint
limit_req_status 429;
add_header Retry-After 1 always;

The value is an example for a one request per second limit. The header’s semantics are in Retry-After header.

limit_conn: limiting concurrent connections

limit_req counts arrival rate; limit_conn counts how many connections are open at the same moment, again in a shared memory zone. The pair of lines has the same shape as in limit_req:

limit_conn: one connection per client address
limit_conn_zone $binary_remote_addr zone=addr:10m;

location /download/ {
    limit_conn addr 1;
}

This allows one connection per client address at a time. Only connections with a request being processed are counted, and only once the whole request header has been read. In HTTP/2 and HTTP/3 each concurrent request counts as a separate connection, so a limit of one on such a listener restricts concurrent requests rather than client sockets.

The module follows the same conventions as the rate module: the default rejection status is 503, limit_conn_status 429; changes it, limit_conn_dry_run on; switches on dry run, and several limit_conn directives, such as one per client address and one per virtual server, can be combined.

The module documentation applies limit_conn to a /download/ location and limit_req to /search/. The two answer different questions and can run side by side.

Off, monitor, block in nginx

A limit written straight into a live location starts refusing at once. Dry run lets nginx follow the same three steps as a managed rollout:

Off, monitor and block as nginx configuration
Stepnginx configuration
OffNo limit_req or limit_conn in the location
MonitorThe limit is written, and limit_req_dry_run on; is set
Blocklimit_req_dry_run off;, which is the default

In dry run the request processing rate is not limited, but the number of excessive requests is accounted in the shared memory zone as usual. The documentation describes the accounting, not the log output, so check what your nginx build writes to the error log in this state before you rely on it as the watch step. Monitor mode describes why the watching step comes before enforcement, and testing rate limits describes how to check a limit against real request patterns before the switch to block.

When the limit moves from monitor to block, change only the switch. The zone, key, rate and burst you watched stay the same, so the behaviour you reviewed is the behaviour that gets enforced.

What the platform provides

This page describes configuration of nginx servers you run yourself. nginx directives do not configure Bridge WAF.

Bridge WAF applies rate limiting per domain and offers the same three modes, off, monitor and block, so monitor mode is a setting rather than a dry run directive in a configuration file. Its activity log records the requests the WAF flagged. It is not a volumetric DDoS statistics view.

Sources

Questions

How do I set up rate limiting in nginx?

Declare a zone with limit_req_zone at the http level, giving it a key, a size and a rate, then apply it with limit_req zone=name burst=N; inside http, server or location. A rate below one request per second is written per minute, for example 30r/m.

What status code does nginx return when a rate limit is exceeded?

503 by default, for both limit_req and limit_conn. The limit_req_status and limit_conn_status directives change it, for example to 429.

What does burst do in nginx limit_req?

It sets how many requests above the rate are accepted. Those requests are delayed so that processing stays at the defined rate, and once the burst size is exceeded the request is terminated with an error. The default burst is zero. Adding nodelay serves the burst immediately instead of delaying it.

Can I test an nginx rate limit without blocking anyone?

Yes. Dry run is the nginx counterpart of monitor mode: limit_req_dry_run on; from nginx 1.17.1, or limit_conn_dry_run on; from nginx 1.17.6. The rate is not limited in dry run, while excess requests are still accounted in the zone.

What is the difference between limit_req and limit_conn?

limit_req limits how fast requests arrive for a key. limit_conn limits how many connections a key holds at the same time.