openresty/lua-nginx-module

★ 11,757CAudience · ops devopsComplexity · 4/5Setup · hard

Mindmap

mindmap
  root((lua-nginx-module))
    What it does
      Nginx scripting
      Dynamic responses
      Request interception
    Request phases
      Access phase
      Content phase
      Rewrite phase
    Use cases
      IP blocklisting
      Dynamic API serving
    Audience
      Nginx engineers
      Backend developers

mindmap root((lua-nginx-module)) What it does Nginx scripting Dynamic responses Request interception Request phases Access phase Content phase Rewrite phase Use cases IP blocklisting Dynamic API serving Audience Nginx engineers Backend developers

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Block specific IP addresses during the Nginx access phase using a Lua script instead of static config rules

USE CASE 2

Generate API responses dynamically from Lua code without running a separate backend application server

USE CASE 3

Read and inspect incoming request bodies inside Nginx before deciding whether to forward them upstream

USE CASE 4

Build a high-performance rate limiter or auth check that runs inside Nginx's event loop using coroutines

Tech stack

CLuaLuaJITNginx

Getting it running

Difficulty · hard Time to first run · 1h+

Must be compiled into Nginx at build time or installed via the OpenResty distribution, dropping it into a standard Nginx binary is not possible.

License terms are not stated in the explanation.

In plain English

lua-nginx-module is a plugin for the Nginx web server that lets you write request-handling logic in Lua, a lightweight scripting language. Instead of configuring Nginx purely through its static config file, you can write small Lua scripts that run at different points in the request lifecycle, such as when a request first arrives, when Nginx checks whether access is allowed, or when it is time to generate the response. The module is a core part of OpenResty, which is a distribution of Nginx bundled with this module and a collection of Lua libraries for building web applications and API servers. The README notes that using this module is essentially the same as using OpenResty. It embeds LuaJIT, a fast implementation of Lua, directly into Nginx's worker processes. The standard Lua interpreter is no longer supported as of version 0.10.16. The configuration examples in the README show how Lua code can be placed inline in the Nginx config file inside blocks like content_by_lua_block or rewrite_by_lua_block. You can also point Nginx to a separate .lua file instead of writing the code inline. From inside a Lua script, you have access to the incoming request, the request body, Nginx variables, and the ability to make internal sub-requests to other locations defined in the Nginx config. Typical uses described in the README include checking client IP addresses against a blocklist during the access phase, reading and inspecting request bodies, and generating response content dynamically without a separate application server. Because it runs inside Nginx's event loop, Lua code that does network calls uses coroutines rather than blocking threads, which keeps the server responsive under high load. The module is described as production ready. Community support is available through English and Chinese mailing lists. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1

Using lua-nginx-module, write a content_by_lua_block that reads a URL query parameter and returns a JSON response directly from Nginx without hitting any upstream server.

Prompt 2

Using lua-nginx-module, write an access_by_lua_block that checks the client IP address against a Lua table blocklist and returns a 403 response if the IP is found.

Prompt 3

Show me how to read the raw POST request body inside a lua-nginx-module script and write it to the Nginx error log before forwarding the request upstream.

Prompt 4

Using OpenResty with lua-nginx-module, set up a simple shared dictionary cache so that an expensive Lua computation is only performed once per Nginx worker process.

Prompt 5

Explain the difference between content_by_lua_block and rewrite_by_lua_block in lua-nginx-module and give a concrete example of when to use each one.

Open on GitHub → Explain another repo

← openresty on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.