The basic module loading directive is

mod_lua provides a handler named lua-script, which can be used with an AddHandler directive:

This will cause mod_lua to handle requests for files ending in .lua by invoking that file's handle function.

For more flexibility, see LuaMapHandler.

In the Apache HTTP Server API, the handler is a specific kind of hook responsible for generating the response. Examples of modules that include a handler are mod_proxy, mod_cgi, and mod_status.

mod_lua always looks to invoke a Lua function for the handler, rather than just evaluating a script body CGI style. A handler function looks something like this:

This handler function just prints out the uri or form encoded arguments to a plaintext page.

This means (and in fact encourages) that you can have multiple handlers (or hooks, or filters) in the same script.

mod_authz_core provides a high-level interface to authorization that is much easier to use than using into the relevant hooks directly. The first argument to the Require directive gives the name of the responsible authorization provider. For any Require line, mod_authz_core will call the authorization provider of the given name, passing the rest of the line as parameters. The provider will then check authorization and pass the result as return value.

The authz provider is normally called before authentication. If it needs to know the authenticated user name (or if the user will be authenticated at all), the provider must return apache2.AUTHZ_DENIED_NO_USER. This will cause authentication to proceed and the authz provider to be called a second time.

The following authz provider function takes two arguments, one ip address and one user name. It will allow access from the given ip address without authentication, or if the authenticated user matches the second argument:

The following configuration registers this function as provider foo and configures it for URL /:

Hook functions are how modules (and Lua scripts) participate in the processing of requests. Each type of hook exposed by the server exists for a specific purposes such as mapping requests to the filesystem, performing access control, or setting mimetypes:

Hook functions are passed the request object as their only argument. They can return any value, depending on the hook, but most commonly they'll return OK, DONE, or DECLINED, which you can write in lua as apache2.OK, apache2.DONE, or apache2.DECLINED, or else an HTTP status code.

request_rec

The request_rec is mapped in as a userdata. It has a metatable which lets you do useful things with it. For the most part it has the same fields as the request_rec struct, many of which are writeable as well as readable. (The table fields' content can be changed, but the fields themselves cannot be set to different tables.)

Name	Lua type	Writable	Description
ap_auth_type	string	no	If an authentication check was made, this is set to the type of authentication (f.x. basic)
args	string	yes	The query string arguments extracted from the request (f.x. foo=bar&name=johnsmith)
assbackwards	boolean	no	Set to true if this is an HTTP/0.9 style request (e.g. GET /foo (with no headers) )
canonical_filename	string	no	The canonical filename of the request
content_encoding	string	no	The content encoding of the current request
content_type	string	yes	The content type of the current request, as determined in the type_check phase (f.x. image/gif or text/html)
context_prefix	string	no
context_document_root	string	no
document_root	string	no	The document root of the host
err_headers_out	table	no	MIME header environment for the response, printed even on errors and persist across internal redirects
filename	string	yes	The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be changed in the translate-name or map-to-storage phases of a request to allow the default handler (or script handlers) to serve a different file than what was requested.
handler	string	yes	The name of the handler that should serve this request, f.x. lua-script if it is to be served by mod_lua. This is typically set by the AddHandler or SetHandler directives, but could also be set via mod_lua to allow another handler to serve up a specific request that would otherwise not be served by it.
headers_in	table	yes	MIME header environment from the request. This contains headers such as Host, User-Agent, Referer and so on.
headers_out	table	yes	MIME header environment for the response.
hostname	string	no	The host name, as set by the Host: header or by a full URI.
is_https	boolean	no	Whether or not this request is done via HTTPS
log_id	string	no	The ID to identify request in access and error log.
method	string	no	The request method, f.x. GET or POST.
notes	table	yes	A list of notes that can be passed on from one module to another.
path_info	string	no	The PATH_INFO extracted from this request.
protocol	string	no	The protocol used, f.x. HTTP/1.1
proxyreq	string	yes	Denotes whether this is a proxy request or not. This value is generally set in the post_read_request/translate_name phase of a request.
range	string	no	The contents of the Range: header.
subprocess_env	table	yes	The environment variables set for this request.
status	number	yes	The (current) HTTP return code for this request, f.x. 200 or 404.
the_request	string	no	The request string as sent by the client, f.x. GET /foo/bar HTTP/1.1.
unparsed_uri	string	no	The unparsed URI of the request
uri	string	yes	The URI after it has been parsed by httpd
user	string	yes	If an authentication check has been made, this is set to the name of the authenticated user.
useragent_ip	string	no	The IP of the user agent making the request

The request_rec has (at least) the following methods:

r:addoutputfilter(name|function) -- add an output filter r:parseargs() -- returns a Lua table containing the request's query string arguments r:parsebody() -- parse any POST data in the request and return it as a Lua table r:puts("hello", " world", "!") -- print to response body r:write("a single string") -- print to response body r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result

A package named apache2 is available with (at least) the following contents.

apache2.OK

internal constant OK. Handlers should return this if they've handled the request.

apache2.DECLINED

internal constant DECLINED. Handlers should return this if they are not going to handle the request.

apache2.DONE

internal constant DONE.

apache2.version

Apache HTTP server version string

apache2.HTTP_MOVED_TEMPORARILY

HTTP status code

apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE

internal constants used by mod_proxy

apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER

internal constants used by mod_authz_core

(Other HTTP status codes are not yet implemented.)