Creating hooks and scripts with mod_lua

Introduction

What is mod_lua

Stuff about what mod_lua is goes here.

What we will be discussing in this document

This document will discuss how you can bla bla bla. In the first chapter, we will bla bla

In the second part of this document, we will be looking at bla bla bla

Prerequisites

First and foremost, you are expected to have a basic knowledge of how the Lua programming language works. In most cases, we will try to be as pedagogical as possible and link to documents describing the functions used in the examples, but there are also many cases where it is necessary to either just assume that "it works" or do some digging yourself into what the hows and whys of various function calls.

Enabling mod_lua

LoadModule lua_module modules/mod_lua.so

Example 1: A basic remapping module

LuaHookTranslateName /path/too/foo.lua remap

--[[
    Simple remap example.
    This example will rewrite /foo/test.bar to the physical file
    /internal/test, somewhat like how mod_alias works.
]]--
require 'apache2'
require 'string'

function remap(r)
    -- Test if the URI matches our criteria
    local barFile =  r.uri:match("/foo/([a-zA-Z0-9]+%.bar)")
    if barFile then
        r.filename = "/internal/" .. barFile
    end
    return apache2.OK
end

--[[
    Advanced remap example.
    This example will evaluate some conditions, and based on that, 
    remap a file to one of two destinations, using a rewrite map.
    
]]--
require 'apache2'
require 'string'

local map = {
      photos = {   
                   source = [[^/photos/(.+)\.png$]], 
                   destination = [[/uploads/www/$1.png]],
                   proxy = false
                },
      externals = {
                   source = [[^/ext/(.*)$]],
                   destination = [[http://www.example.com/$1]],
                   proxy = true
                }
}

function interpolateString(s,v)
    return s:gsub("%$(%d+)", function(a) return v[tonumber(a)] end)
end
        
function remap(r)
    -- browse through the rewrite map
    for key, entry in pairs(map) do
        -- Match source regex against URI
        local match = apache2.regex(r, entry.source, r.uri) then
        if match and match[0] then
            r.filename = interpolateString(entry.destination, match)
            -- Is this a proxied remap?
            if entry.proxy then
                r.handler = "proxy-server" -- tell mod_proxy to handle this
                r.proxyreq = apache2.PROXYREQ_REVERSE -- We'll want to do a reverse proxy
                r.filename = "proxy:" .. r.filename -- Add the proxy scheme to the destination
            end
            return apache2.OK
        end
    end
    return apache2.DECLINED
end

bla bla

Example 2: Mass virtual hosting

LuaHookTranslateName /path/too/foo.lua mass_vhost

--[[
    Simple mass vhost script
    This example will check a map for a virtual host and rewrite filename and 
    document root accordingly.
]]--
require 'apache2'
require 'string'

local vhosts = {
    { domain = "example.com", home = "/www/example.com" },
    { domain = "example.org", home = "/nfs/ext1/example.org" }
}

function mass_vhost(r)
    -- Match against our hostname
    for key, entry in pairs(vhosts) do
        -- match against either host or *.host:
        if apache2.strcmp_match(r.hostname, entry.domain) or
           apache2.strcmp_match(r.hostname, "*." .. entry.domain) then
            -- If it matches, rewrite filename and set document root
            local filename = r.filename:sub(r.document_root:len()+1)
            r.filename = entry.home .. filename
            apahce2.set_document_root(entry.home)
            return apache2.OK
        end
    end
    return apache2.DECLINED
end

--[[
    Advanced mass virtual hosting
    This example will query a database for vhost entries and save them for
    60 seconds before checking for updates. For best performance, such scripts
    should generally be run with LuaScope set to 'thread' or 'server'
]]--
require 'apache2'
require 'string'

local cached_vhosts = {}
local timeout = 60

-- Function for querying the database for saved vhost entries
function query_vhosts(host)
    if not cached_vhosts[host] or (cached_vhosts[host] and cached_vhosts[host].updated < os.time() - timeout) then
        local db = apache2.dbopen(r,"mod_dbd")
        local _host = db:escape(_host)
        local res, err = db:query( ("SELECT `destination` FROM `vhosts` WHERE `hostname` = '%s' LIMIT 1"):format(_host) )
        if res and #res == 1 then
            cached_vhosts[host] = { updated = os.time(), destination = res[1][1] }
        else
            cached_vhosts[host] = nil
        end
        db:close()
    end
    if cached_vhosts[host] then 
        return cached_vhosts[host].destination
    else
        return nil
    end
end
        
function mass_vhost(r)
    -- Check whether the hostname is in our database
    local destination = query_vhosts(r.hostname)
    if destination then
        -- If found, rewrite and change document root
        local filename = r.filename:sub(r.document_root:len()+1)
        r.filename = destination .. filename
        apahce2.set_document_root(destination)
        return apache2.OK
    end
    return apache2.DECLINED
end

bla bla

Example 3: A basic authorization hook

LuaHookAuthChecker /path/too/foo.lua check_auth

require 'apache2'
require 'string'

local accounts = {
    bob  = 'somePassword',
    jane = 'Iloveponies'
}

-- Function for parsing the Authorization header into a username and a password
function parse_auth(str)
    local user,pass = nil, nil
    if str and str:len() > 0 then
        str = apache2.base64_decode(auth):sub(7));
        user, pass = auth:match("([^:]+)%:([^:]+)")
    end
    return user, pass
end

-- The authentication hook
function check_auth(r)
    local user, pass = parse_auth(r.headers_in['Authorization'])
    local authenticated = false
    if user and pass then
        if accounts[user] and accounts[user] == pass then
            authenticated = true
            r.user = user
        end
    end
    r.headers_out["WWW-Authenticate"] = 'Basic realm="Super secret zone"'
    if not authenticated then
        return 401
    else
        return apache2.OK
    end
end

-- An advanced authentication checker with a database backend,
-- caching account entries for 1 minute
require 'apache2'
require 'string'

local timeout = 60 -- Set account info to be refreshed every minute
local accounts = {}

-- Function for parsing the Authorization header into a username and a password
function parse_auth(str)
    local user,pass = nil, nil
    if str and str:len() > 0 then
        str = apache2.base64_decode(auth):sub(7));
        user, pass = auth:match("([^:]+)%:([^:]+)")
    end
    return user, pass
end

-- Function for querying the database for the account's password (stored as a salted SHA-1 hash)
function fetch_password(user)
    if not accounts[user] or (accounts[user] and accounts[user].updated < os.time() - timeout) then
        local db = apache2.dbopen(r, "mod_dbd")
        local usr = db:escape(user)
        local res, err = db:query( ("SELECT `password` FROM `accounts` WHERE `user` = '%s' LIMIT 1"):format(usr) )
        if res and #res == 1 then
            accounts[user] = { updated = os.time(), password = res[1][1] }
        else
            accounts[user] = nil
        end
        db:close()
    end
    if accounts[user] then 
        return accounts[user].password
    else
        return nil
    end
end
    
-- The authentication hook
function check_auth(r)
    local user, pass = parse_auth(r.headers_in['Authorization'])
    local authenticated = false
    if user and pass then
        pass = apache2.sha1("addSomeSalt" .. pass)
        local stored_pass = fetch_password(user)
        if stored_pass and pass == stored_pass then
            authenticated = true
            r.user = user
        end
    end
    r.headers_out["WWW-Authenticate"] = 'Basic realm="Super secret zone"'
    if not authenticated then
        return 401
    else
        return apache2.OK
    end
end

Example 4: Authorization using LuaAuthzProvider

LuaAuthzProvider rights /path/to/lua/script.lua rights_handler
<Directory /www/private>
    Require rights member
</Directory>
<Directory /www/admin>
    Require rights admin
</Directory>

local members = { "rbowen", "humbedooh", "igalic", "covener" }
local admins = { "humbedooh" }

function rights_handler(r, what)
    if r.user == nil then
        return apache2.AUTHZ_AUTHZ_DENIED_NO_USER
    end
    if what == "member" then
        for k, v in pairs(members) do
            if r.user == v then
                return apache2.AUTHZ_GRANTED
            end
        end
    elseif what == "admin" then
        for k, v in pairs(admins) do
            if r.user == v then
                return apache2.AUTHZ_GRANTED
            end
        end
    end
    return apache2.AUTHZ_DENIED
end

Example 5: Overlays using LuaMapHandler

LuaMaphandler ^/portal/([a-z]+)/   /path/to/lua/script.lua handle_$1

Example 6: Basic Lua scripts

HTTPd bindings: String manipulation

apache2.base64_encode
apache2.base64_decode
apache2.escape
apache2.unescape
apache2.escapehtml
apache2.md5
apache2.sha1
apache2.os_escape_path
apache2.escape_logitem

apache2.base64_decode( request_rec r,  string string )

Decodes a base64-encoded string

Arguments:

Return value(s):
The base64-decoded string.

Example:

local str = "This is a test"
local encoded = apache2.base64_encode(str)
local decoded = apache2.base64_decode(encoded)
        

apache2.base64_encode( request_rec r,  string string )

Encodes a string using the base64 encoding scheme.

Arguments:

Example:

local str = "This is a test"
local encoded = apache2.base64_encode(str)
local decoded = apache2.base64_decode(encoded)
        

apache2.escape( request_rec r,  string string )

url-escapes a string

Arguments:

Return value(s):
The URL-escaped string.

Example:

local str = "This is a test"
local escaped = apache2.escape(str)
print(escaped) -- prints "This+is+a+test"
        

apache2.escape_logitem( request_rec r,  string path )

Escape a string for logging

Arguments:

Return value(s):
The converted string

apache2.escapehtml( request_rec r,  string html,  boolean toasc )

Escapes HTML entities.

Arguments:

Return value(s):
The escaped HTML code.

Example:

local html = "<b>Testing!</b>"
local escaped = apache2.escapehtml(html)
r:puts(escaped) -- prints "&lt;b&gt;Testing!&lt;/b&gt;"
        

apache2.md5( request_rec r,  string string )

Computes an MD5 digest sum based on a string (binary safe)

Arguments:

Return value(s):
The MD5 digest sum of the data provided

Example:

local text = "The quick brown fox jumps over the lazy dog"
local md5 = apache2.md51(text)
r:puts(md5) -- prints out "9e107d9d372bb6826bd81d3542a419d6"
        

apache2.os_escape_path( request_rec r,  string path,  boolean partial )

convert an OS path to a URL in an OS dependant way.

Arguments:

Return value(s):
The converted URL

Example:

local path = ap_os_escape_path("C:/foo/bar.txt")
        

apache2.sha1( request_rec r,  string string )

Computes an SHA-1 digest sum based on a string (binary safe)

Arguments:

Return value(s):
The SHA-1 digest sum of the data provided

Example:

local text = "The quick brown fox jumps over the lazy dog"
local sha1 = apache2.sha1(text)
r:puts(sha1) -- prints out "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
        

apache2.unescape( request_rec r,  string string )

unescapes an URL-escaped string

Arguments:

Return value(s):
The URL-unescaped string

Example:

local str = "This+is+a+test"
local unescaped = apache2.unescape(str)
print(unescaped) -- prints "This is a test"
        

HTTPd bindings: Request handling

apache2.sendfile
apache2.port
apache2.getenv
apache2.setenv
apache2.options
apache2.allowoverrides
apache2.requestbody
apache2.add_input_filter
apache2.add_output_filter
apache2.get_basic_auth_pw
apache2.get_limit_req_body
apache2.request_has_body
apache2.set_document_root
apache2.some_auth_required
apache2.context_document_root
apache2.context_prefix
apache2.set_context_prefix
apache2.set_keepalive
apache2.make_etag
apache2.flush
apache2.send_interim_response
apache2.get_server_name
apache2.auth_type
apache2.auth_name
apache2.satisfies

apache2.add_input_filter( request_rec r,  string filter )

Adds an input filter to the request

Arguments:

Example:

apache2.add_input_filter(r, "SPAM_FILTER") -- Check input for spam..?
        

apache2.add_output_filter( request_rec r,  string filter )

Adds an output filter to the request

Arguments:

Example:

apache2.add_input_filter(r, "INCLUDES") -- Turn out output into an SSI-enabled document.
        

apache2.allowoverrides( request_rec r )

Returns the currently allowed overrides for this context (AuthCfg, Options etc)

Arguments:

Return value(s):
The currently allowed overrides for this context (AuthCfg, Options etc)

Example:

local ctx = apache2.allowoverrides(r)
if ctx:match("AuthCfg") then
    r:puts("You are allowed to override AuthCfg stuff in your .htaccess")
end
        

apache2.auth_name( request_rec r )

Returns the current Authorization realm

Arguments:

Return value(s):
The current authorization realm

apache2.auth_type( request_rec r )

Returns the current authentication type used in the request

Arguments:

Return value(s):
The current Authorization type used in the request

apache2.context_document_root( request_rec r )

Get the context_document_root for a request. This is a generalization of the document root, which is too limited in the presence of mappers like mod_userdir and mod_alias. The context_document_root is the directory on disk that maps to the context_prefix URI prefix.

Arguments:

apache2.context_prefix( request_rec r )

Get the context_prefix for a request. The context_prefix URI prefix maps to the context_document_root on disk.

Arguments:

apache2.flush( request_rec r )

Flushes the content buffer, writing everything to the client immediately.

Arguments:

Example:

r:puts("This is buffered")
apache2.flush(r) -- now it's written to the client.
        

apache2.get_basic_auth_pw( request_rec r )

Returns the password from a basic authorization request or nil if none was supplied

Arguments:

Return value(s):
The password from a basic authorization request or nil if none was supplied

apache2.get_limit_req_body( request_rec r )

Returns the current request body size limit

Arguments:

Return value(s):
The current request body size limit

Example:

local limit = apache2.get_limit_req_body(r)
r:puts("You can't upload files bigger than ", limit, " bytes!")
        

apache2.get_server_name( )

Returns the current server name from the request

Arguments:

None

Return value(s):
The server name

Example:

local name = apache2.get_server_name(r)
r:puts("The ServerName is set to: ", name)
        

apache2.getenv( request_rec r,  string key )

Returns the value of an environment variable

Arguments:

Return value(s):
The queried value

Example:

local env = apache2.getenv("HTTP_HOST")
if env and env:len() > 0 then
    r:puts("HTTP_HOST equals ", env)
end
        

apache2.make_etag( request_rec r,  boolean force_weak )

Constructs an entity tag from the resource information. If it's a real file, build in some of the file characteristics.

Arguments:

Return value(s):
The entity tag

apache2.options( request_rec r )

Returns the currently allowed options for this context (Indexes, MultiViews etc)

Arguments:

Return value(s):
The currently allowed options for this context.

Example:

local ctx = apache2.options(r)
if ctx:match("MultiViews") then
    r:puts("MultiViews is enabled!")
end
        

apache2.port( request_rec r )

Returns the port currently being used by the request

Arguments:

Return value(s):
The current port used by the request

Example:

local port = apache2.port(r)
r:puts("We are listening on port ", port)
        

apache2.request_has_body( request_rec r )

Returns true if the request has a body(POST/PUT), false otherwise

Arguments:

Return value(s):
True if the request has a body(POST/PUT), false otherwise

Example:

if apache2.request_has_body(r) then
    -- do stuff with the req body
end
        

apache2.requestbody( request_rec r,  string filename )

Reads the request body. If a filename is specified, the request body will be written to that file and the number of bytes written returned, otherwise, the full request body will be returned as a string.

Arguments:

Return value(s):
The number of bytes written if a filename was specified, otherwise it returns the entire request body as a string.

Example:

if tonumber(r.headers_in['Content-Length'] or 0) < 10000 then
    local smallfile = apache2.requestbody(r) -- fetch a small file into memory
    r:puts("I saved the uploaded file in memory")
else
    local read = apache2.requestbody(r, "/path/to/tmp")
    r:puts("I saved the uploaded file in a temp directory. Total bytes written was: ", read)
end
        

apache2.satisfies( request_rec r )

Returns how the requires lines must be met.

Arguments:

Return value(s):
How the requirements must be met (SATISFY_ANY, SATISFY_ALL, SATISFY_NOSPEC).

Example:

local how = apache2.satisfies(r)
if how == "SATISFY_ANY" then
    -- ...
end
        

apache2.send_interim_response( request_rec r,  boolean send_headers )

Sends an interim (HTTP 1xx) response immediately.

Arguments:

Example:

apache2.send_interim_response(r, false)
        

apache2.sendfile( request_rec r,  string filename )

Sends a file to the client via sendfile() if possible.

Arguments:

Example:

apache2.sendfile(r, "/foo/bar/test.png") -- sends /foo/bar/test.png via sendfile
        

apache2.set_context_prefix( request_rec r,  string prefix,  string document )

Set context_prefix and context_document_root for a request.

Arguments:

apache2.set_document_root( request_rec r,  string root )

Sets the document root of the request.

Arguments:

Example:

-- Suppose our real document root is /var/bar, then...
if r.hostname == "www.foo.com" then
    apache2.set_document_root(r, "/www/foo") -- change document root on the fly
end
        

apache2.set_keepalive( request_rec r )

Sets the keepalive status for this request

Arguments:

Return value(s):
True if keepalive can be set, false otherwise

apache2.setenv( request_rec r,  string key,  string val )

Sets the value of an environment variable

Arguments:

Example:

apache2.setenv("FOO_VAL", "bar and stuff")
        

apache2.some_auth_required( request_rec r )

Returns true if authorization is required for this request

Arguments:

Return value(s):
True if auth is required, false if not.

Example:

if apache2.some_auth_required(r) then
    print("debug: auth is required for this request\n")
end
        

HTTPd bindings: Parser functions

apache2.expr
apache2.regex
apache2.strcmp_match

apache2.expr( request_rec r,  string expression )

Evaluates an ap_expr (think <If ...>) expression and returns true if the expression is true, false otherwise. A second value containing an error string is returned if the expression is invalid.

Arguments:

Return value(s):
True if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string.

Example:

if apache2.expr("%{REQUEST_URI} =~ /force-gzip") then
    apache2.add_output_filter(r, "DEFLATE")
end
        

apache2.regex( request_rec r,  string expression,  string source )

Evaluates a regular expression and, if it matches the source string, captures the variables and returns the matches as a table. On error, it returns nil.

Arguments:

Return value(s):
True if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string.

Example:

local matches = apache2.regex(r, [[(\S+) kitty]], "Hello kitty")
if matches and matches[1] then 
    r:puts("You said ", matches[1], " to kitty")
end
        

apache2.strcmp_match( string str,  string expexted,  boolean ignoreCase )

Determines if a string matches a pattern containing the wildcards '?' or '*'

Arguments:

Return value(s):
True if the two strings match, false otherwise.

Example:

if apache2.strcmp_match("foo.bar", "foo.*") then
    r:puts("It matches!")
end
        

HTTPd bindings: Server settings

apache2.add_version_component
apache2.banner
apache2.mpm_query
apache2.terminate
apache2.scoreboard_process
apache2.scoreboard_worker
apache2.started
apache2.module_info
apache2.get_server_built
apache2.is_initial_req
apache2.loaded_modules
apache2.runtime_dir_relative
apache2.server_info
apache2.state_query
apache2.custom_response
apache2.exists_config_define

apache2.add_version_component( request_rec r,  string component )

Adds a component to the server description and banner strings

Arguments:

Example:

if not apache2.banner():match("FooModule") then -- Make sure we haven't added it already
    apache2.add_version_component(r, "FooModule/1.0")
end
        

apache2.banner( )

Returns the server banner

Arguments:

None

Return value(s):
The server banner

apache2.custom_response( request_rec r,  number status,  string string )

Install a custom response handler for a given status

Arguments:

Example:

apache2.custom_response(r, 404, "Not found!!")
        

apache2.exists_config_define( string name )

Checks for a definition from the server command line

Arguments:

Example:

if apache2.exists_config_define("FOO") then
    r:puts("This server was started with -DFOO")
end
        

apache2.get_server_built( )

Returns the date the server was built

Arguments:

None

Return value(s):
The date the server was built

apache2.is_initial_req( request_rec r )

Returns true if this is the main request, false if it is a sub-request

Arguments:

Return value(s):
True if this is the main request, false if it is a sub-request

apache2.loaded_modules( )

Returns a table containing the name (c filename) of all loaded modules

Arguments:

None

Return value(s):
A table containing the name (c filename) of all loaded modules

apache2.module_info( string c,  string file )

Returns information about a specific module (if loaded)

Arguments:

Return value(s):
The various commands available to this module as a table, or nil if the module wasn't found.

apache2.mpm_query( number i )

Queries the MPM for a specific value

Arguments:

Return value(s):
The queried value

apache2.runtime_dir_relative( request_rec r,  string file )

Returns the path of a file relative to the default runtime directory

Arguments:

Return value(s):
The path of a file relative to the default runtime directory

apache2.scoreboard_process( request_rec r,  number child )

Returns the scoreboard for a server daemon as a table

Arguments:

Return value(s):
The scoreboard for a server daemon as a table

apache2.scoreboard_worker( request_rec r,  number child,  number thread )

Returns the scoreboard for a single thread as a table

Arguments:

Return value(s):
The scoreboard for a single thread as a table

apache2.server_info( )

Returns a table with information about the server program

Arguments:

None

Return value(s):
A table with information about the server program

apache2.started( request_rec r )

Returns the time when the server was (re)started

Arguments:

Return value(s):
The time when the server was (re)started

apache2.state_query( number field )

Query the server for some state information

Arguments:

Example:

local gen = apache2.state_query(2)
r:puts("This is generation no. " .. gen .. " of the top-level parent")
        

apache2.terminate( )

Kills off a server process. This has no other use than to show how dangerous mod_lua can be ;)

Arguments:

None

HTTPd bindings: Database connectivity

apache2.dbopen
db:query
db:do
db:close

apache2.dbopen( request_rec r,  string dbtype,  string conn_string )

Opens up a new database connection.

Arguments:

Return value(s):
The database connection as a table with functions, or nil if the connection failed. If a connection failed, a second argument (string) with the error code is returned.

Example:

local db, error = apache2.dbopen(r, "mod_dbd")
if error then
    r:puts("DB error: ", error)
else
    -- DB stuff here
end
        

db:close( request_rec r )

Closes a database connection

Arguments:

Example:

local db = apache2.dbopen(r, "mod_dbd") -- open a db connection
db:close() -- close it down
        

db:do( request_rec r,  string query )

Executes a statement that doesn't return a result set

Arguments:

Return value(s):
If the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message.

Example:

local db = apache2.dbopen(r, "mod_dbd")
local affected = db:do("DELETE FROM `table` WHERE 1")
if affected then
    r:puts("Affected ", affected, " rows")
end
        

db:query( request_rec r,  string query )

Queries the database for information using the specified statement.

Arguments:

Return value(s):
If the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message.

Example:

local db = apache2.dbopen(r, "mod_dbd")
local result, error = db:query("SELECT * FROM `table` WHERE 1")
if result then
    for key, value in pairs(result)
        r:puts( ("row %s: %s\n"):format(key, table.concat(value, ", ")) )
    end
end
        

HTTPd bindings: Miscellaneous

apache2.clock
apache2.sleep

apache2.clock( )

Returns the current time in microseconds.

Arguments:

None

Return value(s):
The current time in microseconds.

apache2.sleep( number seconds )

Sleeps for a while. Floating point values can be used to sleep for less than a second.

Arguments:

Example:

r:puts("this is ")
apache2.flush(r)
apache2.sleep(0.25) -- sleep for a quarter second.
r:puts("delayed")