Supercharging NGINX with LUA (Part 3)

In Supercharging NGINX with Lua (Part 2) we demonstrated how to run some basic Lua inline inside our nginx config and how to provide a custom (but simple) lua authorization handler. In this post I'll walk through some additional extensions you can use for Lua integrations.

Note that a myriad of extensions already exist (browse them in the OpenResty Github Page). For now, I'll choose two to demonstrate; the idea being that with this information you can integrate any of the other extensions based on your requirements.

As with the previous post in this series, I am assuming that you have installed NGINX capable of handling Lua scripts, and have a basic working NGINX configuration file.

Defining Lua Search Paths

Its a good idea before starting to define the location in which your lua modules reside - such that NGINX can locate them (they may not always live directly inside your NGINX configuration folder). To do this we use the lua_package_path directive.

Directly from the OpenResty Documentation - lua_package_path sets the Lua module search path used by scripts specified by set_by_lua, content_by_lua and others. The path string is in standard Lua path form, and ;; can be used to stand for the original search paths.

For this example, let us assume that all of our configs are going to be placed in /etc/nginx/lua. So we should go ahead and add this directive to the http block in our existing NGINX config:

lua_package_path  "/etc/nginx/lua/?.lua;;";  
Example 1. LRU Cache Extension

Our first example is an implementation of a Least Recently Used Cache (LRU Cache). The source project and documentation can be found here

Using this cache we can calculate and store arbitrary values for quick subsequent retrieval and rely on LRU cache to automatically expire items based on our requirement.


Clone the repository and place the file lib/lrucache.lua in /etc/nginx/lua/openresty/redis.lua. Alternatively, you can create this file from the raw file contents.

Using the Extension

Lets create a simple Lua module /etc/nginx/lua/time_cache.lua that will expose a method go - this method will return the time from the cache if it exists, or the current time if it does not.

local _M = {}  
local lrucache = require("resty.lrucache")  
-- cache time in seconds
local cachettl = 300  
-- we need to initialize the cache on the lua module level so that
-- it can be shared by all the requests served by each worker process:
-- allow up to 20 items in the cache
local c, err =  
if not c then  
    return error("failed to create the cache: " .. (err or "unknown"))

function _M.go()  
  local osclock = c:get("osclock")
  if osclock == nil then
    osclock = tostring(os.clock())
    c:set("osclock", osclock, cachettl)
  return osclock

return _M  

Then, in our NGINX config, lets call this from a location block:

location /cached_time {  
  content_by_lua_block {
    local time_cache = require("time_cache")
    local time = time_cache.go()
Example 2. Redis Data Extension

This extension allows us to query Redis for data from inside our NGINX request. The circumstances in which you would want to do this are again completely dependent on your application design and constraints. An example requirement could be for a single source of potentially externally changing data whereby you could be affected by the NGINX Worker data-sharing constraints. In a case like this an external data source (such as Redis) could be helpful.

The source project and documentation can be found here


Clone the repository and place the file lib/redis.lua in /etc/nginx/lua/openresty/redis.lua. Alternatively you can create this file from the raw file contents.

Using the Extension

The provided sample is pretty concise - so I'll replicate that here! In our NGINX config we add the following location block (Note that you will need to have a Redis instance up and running and accepting requests on

location /redis-request {  
  content_by_lua_block {
      local redis = require "resty.redis"
      local red = redis:new()

      -- 1 sec

      -- or connect to a unix domain socket file listened
      -- by a redis server:
      -- local ok, err = red:connect("unix:/path/to/redis.sock")
      local ok, err = red:connect("", 6379)
      if not ok then
          ngx.say("failed to connect: ", err)

      ok, err = red:set("dog", "an animal")
      if not ok then
          ngx.say("failed to set dog: ", err)

      ngx.say("set result: ", ok)
      local res, err = red:get("dog")
      if not res then
          ngx.say("failed to get dog: ", err)

      if res == ngx.null then
          ngx.say("dog not found.")

      ngx.say("dog: ", res)
      red:set("cat", "Marry")
      red:set("horse", "Bob")
      local results, err = red:commit_pipeline()
      if not results then
          ngx.say("failed to commit the pipelined requests: ", err)

      for i, res in ipairs(results) do
          if type(res) == "table" then
              if res[1] == false then
                  ngx.say("failed to run command ", i, ": ", res[2])
                  -- process the table value
              -- process the scalar value

      -- put it into the connection pool of size 100,
      -- with 10 seconds max idle time
      local ok, err = red:set_keepalive(10000, 100)
      if not ok then
          ngx.say("failed to set keepalive: ", err)

      -- or just close the connection right away:
      -- local ok, err = red:close()
      -- if not ok then
      --     ngx.say("failed to close: ", err)
      --     return
      -- end

Hopefully, this series will have demonstrated how to use Lua to effectively extend your NGINX capabilities. Here at Cloud 66 we're always interested in new and interesting technologies and application of those technologies, and would love to hear from you!

Part I: To learn about LUA, read part 1 article "Supercharging NGINX with LUA (Part 1)".

Part II: For examples of NGINX Lua integration, check out "Supercharging NGINX with Lua (Part 2)".