Dynamic IP Blacklist with Nginx, Lua, and Redis: A Step‑by‑Step Guide

Requirement

To block certain crawlers or malicious users, we need a dynamic IP blacklist that denies service for listed IPs and supports configurable block expiration time.

Environment Preparation

Linux (CentOS7 / Ubuntu, etc.)

Redis 5.0.5

Nginx (OpenResty)

Design方案

There are several ways to implement an IP blacklist:

OS level (iptables)

Pros: simple and direct at the network layer.

Cons: manual changes on each server, cumbersome and inflexible.

Web server level (Nginx deny or Lua plugin)

Pros: dynamic blocking, can set expiration time for distributed bans.

Cons: requires Lua knowledge and Nginx configuration.

Application level (code check before handling request)

Pros: easy to maintain with code.

Cons: may become verbose and affect performance under high concurrency.

We choose the Nginx + Lua + Redis architecture for its simplicity, low performance impact, and ability to share the blacklist across multiple servers.

Configure nginx.conf

location / {
    # optional static file check
    # if ($request_uri ~ .*\\.(html|htm|jpg|js|css)) {
    #     access_by_lua_file /usr/local/lua/access_limit.lua;
    # }
    access_by_lua_file /usr/local/lua/access_limit.lua;
    alias /usr/web/;
    index index.html index.htm;
}

Configure Lua Script

local pool_max_idle_time = 10000
local pool_size = 100
local redis_connection_timeout = 100
local redis_host = "your redis host ip"
local redis_port = "your redis port"
local redis_auth = "your redis authpassword"
local ip_block_time = 120
local ip_time_out = 1
local ip_max_count = 3

local function errlog(msg, ex)
    ngx.log(ngx.ERR, msg, ex)
end

local function close_redis(red)
    if not red then return end
    local ok, err = red:set_keepalive(pool_max_idle_time, pool_size)
    if not ok then
        ngx.say("redis connct err:", err)
        return red:close()
    end
end

local redis = require "resty.redis"
local client = redis:new()
local ok, err = client:connect(redis_host, redis_port)
if not ok then
    close_redis(client)
    ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end
client:set_timeout(redis_connection_timeout)

local connCount, err = client:get_reused_times()
if connCount == 0 then
    local ok, err = client:auth(redis_auth)
    if not ok then
        errlog("failed to auth: ", err)
        return
    end
end

local function getIp()
    local clientIP = ngx.req.get_headers()["X-Real-IP"]
    if not clientIP then
        clientIP = ngx.req.get_headers()["x_forwarded_for"]
    end
    if not clientIP then
        clientIP = ngx.var.remote_addr
    end
    return clientIP
end

local cliendIp = getIp()
local incrKey = "limit:count:" .. cliendIp
local blockKey = "limit:block:" .. cliendIp

local is_block, err = client:get(blockKey)
if tonumber(is_block) == 1 then
    ngx.exit(ngx.HTTP_FORBIDDEN)
    close_redis(client)
end

local ip_count, err = client:incr(incrKey)
if tonumber(ip_count) == 1 then
    client:expire(incrKey, ip_time_out)
end

if tonumber(ip_count) > tonumber(ip_max_count) then
    client:set(blockKey, 1)
    client:expire(blockKey, ip_block_time)
end

close_redis(client)

Summary

The Nginx+Lua+Redis solution provides a lightweight, easily configurable IP blacklist with dynamic updates, shared across multiple servers, and minimal performance impact.

Advantages

Simple configuration, low performance overhead.

Multiple servers can share the blacklist via Redis.

Dynamic management—blacklist entries can be added manually or automatically.

Extensions

Typical use cases include preventing malicious access, blocking crawlers, mitigating DDoS attacks, and rate‑limiting abusive IPs.