redis-rate-limit: Redis backed rate limit module for Nginx

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-redis-rate-limit provided by the GetPageSpeed Extras repository.

1. Configure the APT repository as described in APT repository setup.
2. Install the module:

sudo apt-get update
sudo apt-get install nginx-module-redis-rate-limit

Show suites and architectures

| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

---

A Redis backed rate limit module for Nginx web servers.

This implementation is based on the following Redis module:

• redis-rate-limiter

Which offers a straightforward implementation of the fairly sophisticated generic cell rate algorithm, in 130 lines of C, without external dependencies.

Status

This module is production ready.

Synopsis

upstream redis {
   server 127.0.0.1:6379;

   # Or: server unix:/var/run/redis/redis.sock;

   # a pool with at most 1024 connections
   keepalive 1024;
}

geo $limit {
    default 1;
    10.0.0.0/8 0;
    192.168.0.0/24 0;
}

map $limit $limit_key {
    0 "";
    1 $remote_addr;
}

rate_limit_status 429;

location = /limit {
    rate_limit $limit_key requests=15 period=1m burst=20;
    rate_limit_pass redis;
}

location = /limit_b {
    rate_limit $limit_key requests=20 period=1m burst=25;
    rate_limit_prefix b;
    rate_limit_pass redis;
}

location = /quota {
    rate_limit $limit_key requests=15 period=1m burst=20;
    rate_limit_quantity 0;
    rate_limit_pass redis;
    rate_limit_headers on;
}

Here we assume you would install you nginx under /opt/nginx/.

./configure --prefix=/opt/nginx \ --add-module=rate-limit-nginx-module/

make -j$(nproc) make install

## Test suite

The following dependencies are required to run the test suite:

* Nginx version >= 1.9.11

* Perl modules:
    * [Test::Nginx](https://metacpan.org/pod/Test::Nginx::Socket)

* Nginx modules:
    * ngx_http_rate_limit_module (i.e., this module)

* Redis modules:
    * [redis-rate-limiter](https://github.com/onsigntv/redis-rate-limiter)

* Applications:
    * redis: listening on the default port, 6379.

To run the whole test suite in the default testing mode:
```bash
cd /path/to/rate-limit-nginx-module
export PATH=/path/to/your/nginx/sbin:$PATH
prove -I/path/to/test-nginx/lib -r t

To run specific test files:

cd /path/to/rate-limit-nginx-module
export PATH=/path/to/your/nginx/sbin:$PATH
prove -I/path/to/test-nginx/lib t/sanity.t

To run a specific test block in a particular test file, add the line --- ONLY to the test block you want to run, and then use the prove utility to run that .t file.