Setting HTTP Request Rate Limiting in Nginx

ngx_http_limit_req_module

The ngx_http_limit_req_module module limits the request processing rate based on the defined key value, particularly for rate limiting requests from a single IP.

limit_req_zone Directive

Sets up a shared memory zone to store state information and the number of exceeded requests based on the key; the key can include text, variables, or a combination of both. If the key in the request is empty, it will not be counted towards the request number.
The limit_req_zone directive can only be set in the http block.
Syntax: limit_req_zone key zone=name:size rate=rate [sync];
Example: limit_req_zone $binary_remote_addr zone=one:10m rate=3r/s;.

$binary_remote_addr sets the client IP as the key (rate limiting based on client IP).

zone=one:10m indicates the zone is named one, with 10m of memory space; if the 10m space is exhausted, state data will be removed based on the least recently used principle, and if space is still insufficient, new requests will be rejected (returning 503).

rate=3r/s indicates a rate of 3 requests per second, where the unit r/s represents requests per second. If the desired rate is less than 1 r/s, the unit r/m can be used, representing requests per minute.

sync is used for synchronizing shared memory data between cluster nodes, which will not be covered here.

limit_req Directive

The limit_req directive is used to limit the request rate.
The limit_req directive will set up a memory area to implement/manage rate limiting, allowing you to set the zone name, space size, rate, and burst limit.
If the request rate exceeds the set limit, Nginx will process requests smoothly according to the set rate (delaying some requests to meet the set rate).
Requests exceeding the burst limit will be delayed, while requests exceeding the burst limit will not be processed and will directly return an error status code of 503. You can use the limit_req_status directive to customize the error status code.
The default burst limit is 0.
Syntax: limit_req zone=name [burst=number] [nodelay | delay=number];.

zone=name sets the zone name.

burst=number sets the burst limit.

nodelay indicates that requests should not be delayed.

delay=number indicates the number of requests to be delayed, with a default value of 0, meaning all requests exceeding the rate limit will be delayed.

7. The limit_req directive will only inherit configurations from the previous block if the current configuration block (level) does not have a limit_req directive set. 8. Multiple limit_req directives can be set, such as the following configuration: limiting the request rate for the same client IP while also limiting the request rate for the virtual host.

server {
    ...
    limit_req zone=perip burst=5 nodelay;
    limit_req zone=perserver burst=10;
}

limit_req_status Directive

Sets the status code for rejected requests, with a default value of 503. Syntax: limit_req_status code; Configurable blocks: http, server, location

limit_req_log_level Directive

1. Sets the log level for rejected and delayed requests, with the delayed processing level being one level lower than the rejected processing level. For example, limit_req_log_level notice indicates that the rejection level is notice, and the delayed processing level is one level lower at info.

2. Syntax: limit_req_log_level info | notice | warn | error; Default log level: error. Configurable blocks: http, server, location

Testing

Test 1. Limit the same IP to 3 requests per second, Nginx configuration:

limit_req_zone $binary_remote_addr zone=one:10m rate=3r/s;

server {
    listen       80;
    server_name  xxx.xxx.xxx.xxx;


    location / {
        # Rate limiting
        limit_req zone=one;
        root   html;
        index  index.html index.htm;
    }
}

In one second, 10 requests are initiated, and since the rate limit is 3r/s, 3 requests respond normally, while 7 requests return 503:

Test 2. Limit the same IP to 1 request per second, with a burst limit of 5:

# For easy viewing of limit_req effects
log_format main '$time_local,$request,$status,limit_req_status=$limit_req_status';

access_log /usr/local/nginx/logs/access.log main;


limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    listen       80;
    server_name  xxx.xxx.xxx.xxx;

      
    location /download/ {
     alias /var/www/images/;
     limit_req zone=one burst=5 nodelay;
    }
}

15 requests are initiated simultaneously from the local machine ab -n 15 -c 15 http://127.0.0.1/download/1.jpg, as requests initiated from the local machine can reach the Nginx service immediately, while client JMeter tests may have delays due to network reasons. The rate is 1r/s, allowing a burst of 5 (burst) with no delay. Out of 15 requests, 6 are processed successfully, and 9 return errors with 503, as shown in the following image: