http-lua

Script request handling with LuaJIT

dynamic moduleBSD-2-Clausesource

Overview

lua-nginx-module embeds LuaJIT into nginx and runs Lua code inside the request lifecycle. Handlers hook into the rewrite, access, content, header filter, body filter, and log phases. It is the core component of OpenResty.

Lua code runs on the nginx event loop, and the ngx.* API performs network I/O without blocking a worker. That makes it practical to write authentication checks, dynamic routing, request and response rewriting, or full API endpoints in nginx configuration instead of a separate application server.

The module requires the nginx development kit (NDK), so load ndk_http_module.so before ngx_http_lua_module.so. Workers can share state through lua_shared_dict shared memory zones.

Key directives

content_by_lua_blockRuns Lua as the content handler for a location and generates the response with ngx.say and related calls.

access_by_lua_blockRuns Lua in the access phase to allow or reject a request, for example custom authentication.

rewrite_by_lua_blockRuns Lua in the rewrite phase to change the URI, arguments, or other request properties before routing.

set_by_lua_blockComputes the value of an nginx variable with a short blocking Lua expression.

lua_shared_dictDeclares a shared memory dictionary that all worker processes can read and write.

init_by_lua_blockRuns Lua once at configuration load time, before workers fork, to preload modules and shared data.

Example

nginx.conf

load_module modules/ndk_http_module.so; load_module modules/ngx_http_lua_module.so; http { lua_shared_dict counters 1m; server { listen 80; location /hello { default_type text/plain; content_by_lua_block { local hits = ngx.shared.counters:incr("hits", 1, 0) ngx.say("hello, visit #", hits) } } } }

Availability

Ships as a dynamic module in libnginx-mod-http-lua, installed automatically with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.