b07b82e44c32825d6226ee801d2ed91555e593d1rbowen<?xml version="1.0"?>

fb51a6b789d85113d0976148685b0063c294220drbowen<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

b07b82e44c32825d6226ee801d2ed91555e593d1rbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

b07b82e44c32825d6226ee801d2ed91555e593d1rbowen

b07b82e44c32825d6226ee801d2ed91555e593d1rbowen

b07b82e44c32825d6226ee801d2ed91555e593d1rbowen<modulesynopsis metafile="mod_lua.xml.meta">

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<name>mod_lua</name>

fb51a6b789d85113d0976148685b0063c294220drbowen

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<description>Provides Lua hooks into various portions of the httpd

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenrequest processing</description>

b75b4bfd9e8ec9fbf28a95174dc0e4d420f744a8sf<status>Experimental</status>

fb51a6b789d85113d0976148685b0063c294220drbowen<sourcefile>mod_lua.c</sourcefile>

fb51a6b789d85113d0976148685b0063c294220drbowen<identifier>lua_module</identifier>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<compatibility>2.3 and later</compatibility>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<summary>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<p>This module allows the server to be extended with scripts written in the

889dc1728817c1c56d0c8d894c768614e346d86ecovenerLua programming language. The extension points (hooks) available with

889dc1728817c1c56d0c8d894c768614e346d86ecovener<module>mod_lua</module> include many of the hooks available to

889dc1728817c1c56d0c8d894c768614e346d86ecovenernatively compiled Apache HTTP Server modules, such as mapping requests to

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimfiles, generating dynamic responses, access control, authentication, and

889dc1728817c1c56d0c8d894c768614e346d86ecovenerauthorization</p>

889dc1728817c1c56d0c8d894c768614e346d86ecovener

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<p>More information on the Lua programming language can be found at the

889dc1728817c1c56d0c8d894c768614e346d86ecovener<a href="http://www.lua.org/">the Lua website</a>.</p>

fb51a6b789d85113d0976148685b0063c294220drbowen

8548ace6aa09b4d3e463254b53865fb38fbbbc78poirier<note><code>mod_lua</code> is still in experimental state.

8548ace6aa09b4d3e463254b53865fb38fbbbc78poirierUntil it is declared stable, usage and behavior may change

8ad875ad9725307fd052e36abc2938f89f56902csfat any time, even between stable releases of the 2.4.x series.

8ad875ad9725307fd052e36abc2938f89f56902csfBe sure to check the CHANGES file before upgrading.</note>

8548ace6aa09b4d3e463254b53865fb38fbbbc78poirier

fb51a6b789d85113d0976148685b0063c294220drbowen<note type="warning"><title>Warning</title>

fb51a6b789d85113d0976148685b0063c294220drbowen<p>This module holds a great deal of power over httpd, which is both a

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenstrength and a potential security risk. It is <strong>not</strong> recommended

fb51a6b789d85113d0976148685b0063c294220drbowenthat you use this module on a server that is shared with users you do not

3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowentrust, as it can be abused to change the internal workings of httpd.</p>

fb51a6b789d85113d0976148685b0063c294220drbowen</note>

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen

2219c51bf0756c2f6f7deb88a13baf30f141c12epoirier</summary>

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<section id="basicconf"><title>Basic Configuration</title>

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<p>The basic module loading directive is</p>

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<highlight language="config">

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen LoadModule lua_module modules/mod_lua.so

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen</highlight>

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<p>

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<code>mod_lua</code> provides a handler named <code>lua-script</code>,

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierwhich can be used with an <code>AddHandler</code> directive:</p>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<highlight language="config">

4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenAddHandler lua-script .lua

92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier<p>

92e5d4326ae44f79da5cb049470daba604506846poirierThis will cause <code>mod_lua</code> to handle requests for files

fb51a6b789d85113d0976148685b0063c294220drbowenending in <code>.lua</code> by invoking that file's

fb51a6b789d85113d0976148685b0063c294220drbowen<code>handle</code> function.

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</p>

889dc1728817c1c56d0c8d894c768614e346d86ecovener

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<p>For more flexibility, see <directive>LuaMapHandler</directive>.

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim</p>

889dc1728817c1c56d0c8d894c768614e346d86ecovener

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</section>

889dc1728817c1c56d0c8d894c768614e346d86ecovener

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<section id="writinghandlers"><title>Writing Handlers</title>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<p> In the Apache HTTP Server API, the handler is a specific kind of hook

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenresponsible for generating the response. Examples of modules that include a

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenhandler are <module>mod_proxy</module>, <module>mod_cgi</module>,

92e5d4326ae44f79da5cb049470daba604506846poirierand <module>mod_status</module>.</p>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than

92e5d4326ae44f79da5cb049470daba604506846poirierjust evaluating a script body CGI style. A handler function looks

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimsomething like this:</p>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

cf7d90693f7579700c4f7e663adb83196f903df1covener<highlight language="lua">

cf7d90693f7579700c4f7e663adb83196f903df1covener<strong>example.lua</strong><br/>

cf7d90693f7579700c4f7e663adb83196f903df1covener-- example handler

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirierrequire "string"

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier--[[

92e5d4326ae44f79da5cb049470daba604506846poirier This is the default method name for Lua handlers, see the optional

92e5d4326ae44f79da5cb049470daba604506846poirier function-name in the LuaMapHandler directive to choose a different

92e5d4326ae44f79da5cb049470daba604506846poirier entry point.

92e5d4326ae44f79da5cb049470daba604506846poirier--]]

92e5d4326ae44f79da5cb049470daba604506846poirierfunction handle(r)

92e5d4326ae44f79da5cb049470daba604506846poirier r.content_type = "text/plain"

92e5d4326ae44f79da5cb049470daba604506846poirier r:puts("Hello Lua World!\n")

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier if r.method == 'GET' then

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim for k, v in pairs( r:parseargs() ) do

92e5d4326ae44f79da5cb049470daba604506846poirier r:puts( string.format("%s: %s\n", k, v) )

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen end

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen elseif r.method == 'POST' then

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen for k, v in pairs( r:parsebody() ) do

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:puts( string.format("%s: %s\n", k, v) )

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen end

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen else

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:puts("Unsupported HTTP method " .. r.method)

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen end

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenend

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</highlight>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<p>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenThis handler function just prints out the uri or form encoded

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenarguments to a plaintext page.

92e5d4326ae44f79da5cb049470daba604506846poirier</p>

92e5d4326ae44f79da5cb049470daba604506846poirier

889dc1728817c1c56d0c8d894c768614e346d86ecovener<p>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimThis means (and in fact encourages) that you can have multiple

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimhandlers (or hooks, or filters) in the same script.

889dc1728817c1c56d0c8d894c768614e346d86ecovener</p>

889dc1728817c1c56d0c8d894c768614e346d86ecovener

889dc1728817c1c56d0c8d894c768614e346d86ecovener</section>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier<section id="writingauthzproviders">

92e5d4326ae44f79da5cb049470daba604506846poirier<title>Writing Authorization Providers</title>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier<p><module>mod_authz_core</module> provides a high-level interface to

92e5d4326ae44f79da5cb049470daba604506846poirierauthorization that is much easier to use than using into the relevant

92e5d4326ae44f79da5cb049470daba604506846poirierhooks directly. The first argument to the

bb57315f942d09c744543fe41e453bd0181fd93ecovener<directive module="mod_authz_core">Require</directive> directive gives

bb57315f942d09c744543fe41e453bd0181fd93ecovenerthe name of the responsible authorization provider. For any

bb57315f942d09c744543fe41e453bd0181fd93ecovener<directive module="mod_authz_core">Require</directive> line,

bb57315f942d09c744543fe41e453bd0181fd93ecovener<module>mod_authz_core</module> will call the authorization provider

bb57315f942d09c744543fe41e453bd0181fd93ecovenerof the given name, passing the rest of the line as parameters. The

bb57315f942d09c744543fe41e453bd0181fd93ecovenerprovider will then check authorization and pass the result as return

bb57315f942d09c744543fe41e453bd0181fd93ecovenervalue.</p>

bb57315f942d09c744543fe41e453bd0181fd93ecovener

bb57315f942d09c744543fe41e453bd0181fd93ecovener<p>The authz provider is normally called before authentication. If it needs to

bb57315f942d09c744543fe41e453bd0181fd93ecovenerknow the authenticated user name (or if the user will be authenticated at

bb57315f942d09c744543fe41e453bd0181fd93ecovenerall), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.

bb57315f942d09c744543fe41e453bd0181fd93ecovenerThis will cause authentication to proceed and the authz provider to be

bb57315f942d09c744543fe41e453bd0181fd93ecovenercalled a second time.</p>

bb57315f942d09c744543fe41e453bd0181fd93ecovener

bb57315f942d09c744543fe41e453bd0181fd93ecovener<p>The following authz provider function takes two arguments, one ip

bb57315f942d09c744543fe41e453bd0181fd93ecoveneraddress and one user name. It will allow access from the given ip address

bb57315f942d09c744543fe41e453bd0181fd93ecovenerwithout authentication, or if the authenticated user matches the second

bb57315f942d09c744543fe41e453bd0181fd93ecovenerargument:</p>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

bb57315f942d09c744543fe41e453bd0181fd93ecovener<highlight language="lua">

bb57315f942d09c744543fe41e453bd0181fd93ecovener<strong>authz_provider.lua</strong><br/>

8e9a311b466b8a3d2782af71a432a6a7ee2cd2f0covener

bb57315f942d09c744543fe41e453bd0181fd93ecovenerrequire 'apache2'

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirierfunction authz_check_foo(r, ip, user)

92e5d4326ae44f79da5cb049470daba604506846poirier if r.useragent_ip == ip then

92e5d4326ae44f79da5cb049470daba604506846poirier return apache2.AUTHZ_GRANTED

92e5d4326ae44f79da5cb049470daba604506846poirier elseif r.user == nil then

92e5d4326ae44f79da5cb049470daba604506846poirier return apache2.AUTHZ_DENIED_NO_USER

92e5d4326ae44f79da5cb049470daba604506846poirier elseif r.user == user then

92e5d4326ae44f79da5cb049470daba604506846poirier return apache2.AUTHZ_GRANTED

92e5d4326ae44f79da5cb049470daba604506846poirier else

92e5d4326ae44f79da5cb049470daba604506846poirier return apache2.AUTHZ_DENIED

92e5d4326ae44f79da5cb049470daba604506846poirier end

92e5d4326ae44f79da5cb049470daba604506846poirierend

92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<p>The following configuration registers this function as provider

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<code>foo</code> and configures it for URL <code>/</code>:</p>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<highlight language="config">

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenLuaAuthzProvider foo authz_provider.lua authz_check_foo

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen&lt;Location /&gt;

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen Require foo 10.1.2.3 john_doe

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim&lt;/Location&gt;

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</highlight>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier</section>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<section id="writinghooks"><title>Writing Hooks</title>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<p>Hook functions are how modules (and Lua scripts) participate in the

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierprocessing of requests. Each type of hook exposed by the server exists for

249cc9b3d83d3c60666269b90ecb9f1390d32165poiriera specific purposes such as mapping requests to the filesystem,

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierperforming access control, or setting mimetypes:</p>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<table border="1" style="zebra">

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <th>Hook phase</th>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <th>mod_lua directive</th>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <th>Description</th>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Quick handler</td>

fc57cc74ee4e73618f74a7a62ea6ac77546666dacovener <td><directive module="mod_lua">LuaQuickHandler</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This is the first hook that will be called after a request has

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier been mapped to a host or virtual host</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Translate name</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookTranslateName</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This phase translates the requested URI into a filename on the

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier system. Modules such as <module>mod_alias</module> and

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <module>mod_rewrite</module> operate in this phase.</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Map to storage</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookMapToStorage</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This phase maps files to their physical, cached or external/proxied storage.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier It can be used by proxy or caching modules</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Check Access</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookAccessChecker</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This phase checks whether a client has access to a resource. This

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier phase is run before the user is authenticated, so beware.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Check User ID</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookCheckUserID</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This phase it used to check the negotiated user ID</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Check Authorization</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookAuthChecker</directive> or

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <directive module="mod_lua">LuaAuthzProvider</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This phase authorizes a user based on the negotiated credentials, such as

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier user ID, client certificate etc.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Check Type</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookTypeChecker</directive></td>

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <td>This phase checks the requested file and assigns a content type and

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener a handler to it</td>

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener </tr>

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <tr>

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <td>Fixups</td>

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <td><directive module="mod_lua">LuaHookFixups</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This is the final "fix anything" phase before the content handlers

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier are run. Any last-minute changes to the request should be made here.</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Content handler</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>fx. <code>.lua</code> files or through <directive module="mod_lua">LuaMapHandler</directive></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This is where the content is handled. Files are read, parsed, some are run,

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier and the result is sent to the client</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Logging</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>(none)</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>Once a request has been handled, it enters several logging phases,

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier which logs the request in either the error or access log</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</table>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<p>Hook functions are passed the request object as their only argument.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierThey can return any value, depending on the hook, but most commonly

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierthey'll return OK, DONE, or DECLINED, which you can write in lua as

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<code>apache2.OK</code>, <code>apache2.DONE</code>, or

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<code>apache2.DECLINED</code>, or else an HTTP status code.</p>

92e5d4326ae44f79da5cb049470daba604506846poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<highlight language="lua">

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<strong>translate_name.lua</strong><br/>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier-- example hook that rewrites the URI to a filesystem path.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierrequire 'apache2'

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierfunction translate_name(r)

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier if r.uri == "/translate-name" then

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier r.filename = r.document_root .. "/find_me.txt"

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier return apache2.OK

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener end

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener -- we don't care about this URL, give another module a chance

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener return apache2.DECLINED

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovenerend

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener</highlight>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<highlight language="lua">

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<strong>translate_name2.lua</strong><br/>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier--[[ example hook that rewrites one URI to another URI. It returns a

8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener apache2.DECLINED to give other URL mappers a chance to work on the

8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener substitution, including the core translate_name hook which maps based

8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener on the DocumentRoot.

8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener

8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener Note: Use the early/late flags in the directive to make it run before

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier or after mod_alias.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier--]]

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierrequire 'apache2'

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierfunction translate_name(r)

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier if r.uri == "/translate-name" then

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier r.uri = "/find_me.txt"

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier return apache2.DECLINED

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier end

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier return apache2.DECLINED

249cc9b3d83d3c60666269b90ecb9f1390d32165poirierend

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</highlight>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</section>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<section id="datastructures"><title>Data Structures</title>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<dl>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<dt>request_rec</dt>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <dd>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>The request_rec is mapped in as a userdata. It has a metatable

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier which lets you do useful things with it. For the most part it

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier has the same fields as the request_rec struct, many of which are writeable as

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier well as readable. (The table fields' content can be changed, but the

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier fields themselves cannot be set to different tables.)</p>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <table border="1" style="zebra">

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <th><strong>Name</strong></th>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <th><strong>Lua type</strong></th>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <th><strong>Writable</strong></th>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <th><strong>Description</strong></th>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><code>ap_auth_type</code></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>string</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>no</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>If an authentication check was made, this is set to the type

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier of authentication (f.x. <code>basic</code>)</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><code>args</code></td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>string</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>yes</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>The query string arguments extracted from the request

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier (f.x. <code>foo=bar&amp;name=johnsmith</code>)</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><code>assbackwards</code></td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>boolean</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>no</td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>Set to true if this is an HTTP/0.9 style request

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen (e.g. <code>GET /foo</code> (with no headers) )</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen </tr>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <tr>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td><code>canonical_filename</code></td>

92e5d4326ae44f79da5cb049470daba604506846poirier <td>string</td>

b60ba9fb00026d3dbca744c6c19afe63cba3a3d1covener <td>no</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>The canonical filename of the request</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen </tr>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <tr>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td><code>content_encoding</code></td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>string</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>no</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>The content encoding of the current request</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen </tr>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <tr>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td><code>content_type</code></td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>string</td>

e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>yes</td>

92e5d4326ae44f79da5cb049470daba604506846poirier <td>The content type of the current request, as determined in the

92e5d4326ae44f79da5cb049470daba604506846poirier type_check phase (f.x. <code>image/gif</code> or <code>text/html</code>)</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><code>context_prefix</code></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>string</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>no</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><code>context_document_root</code></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>string</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>no</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier </tr>

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener

7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <tr>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><code>document_root</code></td>

92e5d4326ae44f79da5cb049470daba604506846poirier <td>string</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>no</td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>The document root of the host</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <td><code>err_headers_out</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>table</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>no</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>MIME header environment for the response, printed even on errors and

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic persist across internal redirects</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>filename</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

2219c51bf0756c2f6f7deb88a13baf30f141c12epoirier <td>yes</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be

fb51a6b789d85113d0976148685b0063c294220drbowen changed in the translate-name or map-to-storage phases of a request to allow the

fb51a6b789d85113d0976148685b0063c294220drbowen default handler (or script handlers) to serve a different file than what was requested.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>handler</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <td>yes</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The name of the <a href="/handler.html">handler</a> that should serve this request, f.x.

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <code>lua-script</code> if it is to be served by mod_lua. This is typically set by the

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <directive module="mod_mime">AddHandler</directive> or <directive module="core">SetHandler</directive>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic directives, but could also be set via mod_lua to allow another handler to serve up a specific request

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic that would otherwise not be served by it.

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td><code>headers_in</code></td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>table</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>yes</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>MIME header environment from the request. This contains headers such as <code>Host,

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim User-Agent, Referer</code> and so on.</td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim </tr>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <tr>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td><code>headers_out</code></td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>table</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>yes</td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>MIME header environment for the response.</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>hostname</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>The host name, as set by the <code>Host:</code> header or by a full URI.</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen </tr>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>is_https</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>boolean</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>Whether or not this request is done via HTTPS</td>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td><code>log_id</code></td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>string</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>no</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>The ID to identify request in access and error log.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>method</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The request method, f.x. <code>GET</code> or <code>POST</code>.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>notes</code></td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>table</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>yes</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>A list of notes that can be passed on from one module to another.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td><code>path_info</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The PATH_INFO extracted from this request.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>protocol</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The protocol used, f.x. <code>HTTP/1.1</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <td><code>proxyreq</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>yes</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>Denotes whether this is a proxy request or not. This value is generally set in

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic the post_read_request/translate_name phase of a request.</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td><code>range</code></td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>string</td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>no</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>The contents of the <code>Range:</code> header.</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td><code>subprocess_env</code></td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>table</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>yes</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The environment variables set for this request.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <td><code>status</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>number</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>yes</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>The (current) HTTP return code for this request, f.x. <code>200</code> or <code>404</code>.</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </tr>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>the_request</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>The request string as sent by the client, f.x. <code>GET /foo/bar HTTP/1.1</code>.</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen </tr>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <tr>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td><code>unparsed_uri</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>no</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>The unparsed URI of the request</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>uri</code></td>

249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>string</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>yes</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>The URI after it has been parsed by httpd</td>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </tr>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>user</code></td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>string</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>yes</td>

fb51a6b789d85113d0976148685b0063c294220drbowen <td>If an authentication check has been made, this is set to the name of the authenticated user.</td>

fb51a6b789d85113d0976148685b0063c294220drbowen </tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <tr>

fb51a6b789d85113d0976148685b0063c294220drbowen <td><code>useragent_ip</code></td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>string</td>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>no</td>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>The IP of the user agent making the request</td>

92e5d4326ae44f79da5cb049470daba604506846poirier </tr>

3a602d0ba8536a79a780655bb92133b571e38378poirier </table>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <p>The request_rec has (at least) the following methods:</p>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <highlight language="lua">

c994f52ac80f9664d2940e5ccd9e77466572013frbowen r:addoutputfilter(name|function) -- add an output filter

c994f52ac80f9664d2940e5ccd9e77466572013frbowen </highlight>

c994f52ac80f9664d2940e5ccd9e77466572013frbowen

c994f52ac80f9664d2940e5ccd9e77466572013frbowen <highlight language="lua">

fb51a6b789d85113d0976148685b0063c294220drbowen r:parseargs() -- returns a Lua table containing the request's query string arguments

fb51a6b789d85113d0976148685b0063c294220drbowen </highlight>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen <highlight language="lua">

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen r:parsebody() -- parse any POST data in the request and return it as a Lua table

457256c49209d6e56bfe63b411688ad9cb2a8429covener </highlight>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic

457256c49209d6e56bfe63b411688ad9cb2a8429covener <highlight language="lua">

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic r:puts("hello", " world", "!") -- print to response body

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </highlight>

247c1db2eb82d5c836df7bafc7380887890e11a2rjung

fb51a6b789d85113d0976148685b0063c294220drbowen <highlight language="lua">

fb51a6b789d85113d0976148685b0063c294220drbowen r:write("a single string") -- print to response body

fb51a6b789d85113d0976148685b0063c294220drbowen </highlight>

fb51a6b789d85113d0976148685b0063c294220drbowen

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <highlight language="lua">

fb51a6b789d85113d0976148685b0063c294220drbowen r:escape_html("&lt;html&gt;test&lt;/html&gt;") -- Escapes HTML code and returns the escaped result

fb51a6b789d85113d0976148685b0063c294220drbowen </highlight>

fb51a6b789d85113d0976148685b0063c294220drbowen </dd>

fb51a6b789d85113d0976148685b0063c294220drbowen </dl>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen</section>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<section id="logging"><title>Logging Functions</title>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<highlight language="lua">

fb51a6b789d85113d0976148685b0063c294220drbowen -- examples of logging messages<br />

fb51a6b789d85113d0976148685b0063c294220drbowen r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:debug("This is a debug log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:info("This is an info log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:notice("This is an notice log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:warn("This is an warn log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:err("This is an err log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:alert("This is an alert log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:crit("This is an crit log message")<br />

92e5d4326ae44f79da5cb049470daba604506846poirier r:emerg("This is an emerg log message")<br />

76c23dcc502f814f6b988038d600719db07d28becovener</highlight>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier</section>

92e5d4326ae44f79da5cb049470daba604506846poirier

92e5d4326ae44f79da5cb049470daba604506846poirier<section id="apache2"><title>apache2 Package</title>

92e5d4326ae44f79da5cb049470daba604506846poirier<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>

92e5d4326ae44f79da5cb049470daba604506846poirier<dl>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dt>apache2.OK</dt>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dd>internal constant OK. Handlers should return this if they've

457256c49209d6e56bfe63b411688ad9cb2a8429covener handled the request.</dd>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dt>apache2.DECLINED</dt>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dd>internal constant DECLINED. Handlers should return this if

457256c49209d6e56bfe63b411688ad9cb2a8429covener they are not going to handle the request.</dd>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dt>apache2.DONE</dt>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dd>internal constant DONE.</dd>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <dt>apache2.version</dt>

fb51a6b789d85113d0976148685b0063c294220drbowen <dd>Apache HTTP server version string</dd>

fb51a6b789d85113d0976148685b0063c294220drbowen <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>

fb51a6b789d85113d0976148685b0063c294220drbowen <dd>HTTP status code</dd>

fb51a6b789d85113d0976148685b0063c294220drbowen <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <dd>internal constants used by <module>mod_proxy</module></dd>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <dd>internal constants used by <module>mod_authz_core</module></dd>

fb51a6b789d85113d0976148685b0063c294220drbowen

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</dl>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic<p>(Other HTTP status codes are not yet implemented.)</p>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</section>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic

3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowen<directivesynopsis>

3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowen<name>LuaRoot</name>

fb51a6b789d85113d0976148685b0063c294220drbowen<description>Specify the base path for resolving relative paths for mod_lua directives</description>

3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowen<syntax>LuaRoot /path/to/a/directory</syntax>

3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowen<contextlist><context>server config</context><context>virtual host</context>

fb51a6b789d85113d0976148685b0063c294220drbowen<context>directory</context><context>.htaccess</context>

fb51a6b789d85113d0976148685b0063c294220drbowen</contextlist>

fb51a6b789d85113d0976148685b0063c294220drbowen<override>All</override>

fb51a6b789d85113d0976148685b0063c294220drbowen

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen<usage>

fb51a6b789d85113d0976148685b0063c294220drbowen <p>Specify the base path which will be used to evaluate all

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic relative paths within mod_lua. If not specified they

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic will be resolved relative to the current working directory,

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic which may not always work well for a server.</p>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</usage>

fb51a6b789d85113d0976148685b0063c294220drbowen</directivesynopsis>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<directivesynopsis>

fb51a6b789d85113d0976148685b0063c294220drbowen<name>LuaScope</name>

fb51a6b789d85113d0976148685b0063c294220drbowen<description>One of once, request, conn, thread -- default is once</description>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen<syntax>LuaScope once|request|conn|thread</syntax>

457256c49209d6e56bfe63b411688ad9cb2a8429covener<default>LuaScope once</default>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic<contextlist><context>server config</context><context>virtual host</context>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic<context>directory</context><context>.htaccess</context>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</contextlist>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic<override>All</override>

247c1db2eb82d5c836df7bafc7380887890e11a2rjung

457256c49209d6e56bfe63b411688ad9cb2a8429covener<usage>

457256c49209d6e56bfe63b411688ad9cb2a8429covener <p>Specify the lifecycle scope of the Lua interpreter which will

457256c49209d6e56bfe63b411688ad9cb2a8429covener be used by handlers in this "Directory." The default is "once"</p>

457256c49209d6e56bfe63b411688ad9cb2a8429covener

fb51a6b789d85113d0976148685b0063c294220drbowen <dl>

fb51a6b789d85113d0976148685b0063c294220drbowen <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen <dt>request:</dt> <dd>use the interpreter to handle anything based on

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen the same file within this request, which is also

fb51a6b789d85113d0976148685b0063c294220drbowen request scoped.</dd>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic handling the request (only available with threaded MPMs).</dd>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic </dl>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</usage>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</directivesynopsis>

247c1db2eb82d5c836df7bafc7380887890e11a2rjung

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<directivesynopsis>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<name>LuaMapHandler</name>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<description>Map a path to a lua handler</description>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<contextlist><context>server config</context><context>virtual host</context>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<context>directory</context><context>.htaccess</context>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</contextlist>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<override>All</override>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<usage>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier <p>This directive matches a uri pattern to invoke a specific

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier handler function in a specific file. It uses PCRE regular

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier expressions to match the uri, and supports interpolating

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier match groups into both the file path and the function name

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier be careful writing your regular expressions to avoid security

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier issues.</p>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier <example><title>Examples:</title>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier <highlight language="config">

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier </highlight>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier </example>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier <p>This would match uri's such as /photos/show?id=9

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier to the file /scripts/photos.lua and invoke the

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier handler function handle_show on the lua vm after

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier loading that file.</p>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<highlight language="config">

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier LuaMapHandler /bingo /scripts/wombat.lua

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</highlight>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier <p>This would invoke the "handle" function, which

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier is the default if no specific function name is

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier provided.</p>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</usage>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</directivesynopsis>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<directivesynopsis>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<name>LuaPackagePath</name>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<description>Add a directory to lua's package.path</description>

457256c49209d6e56bfe63b411688ad9cb2a8429covener<syntax>LuaPackagePath /path/to/include/?.lua</syntax>

457256c49209d6e56bfe63b411688ad9cb2a8429covener<contextlist><context>server config</context><context>virtual host</context>

768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier<context>directory</context><context>.htaccess</context>

fb51a6b789d85113d0976148685b0063c294220drbowen</contextlist>

fb51a6b789d85113d0976148685b0063c294220drbowen<override>All</override>

fb51a6b789d85113d0976148685b0063c294220drbowen <usage><p>Add a path to lua's module search path. Follows the same

fb51a6b789d85113d0976148685b0063c294220drbowen conventions as lua. This just munges the package.path in the

9cd56c73a0fd508522ba2f6bc6c9839c478c61c3rbowen lua vms.</p>

457256c49209d6e56bfe63b411688ad9cb2a8429covener

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <example><title>Examples:</title>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <highlight language="config">

99e316bc4b9b2b5754165939ac14b6d16132cce1igalicLuaPackagePath /scripts/lib/?.lua

99e316bc4b9b2b5754165939ac14b6d16132cce1igalicLuaPackagePath /scripts/lib/?/init.lua

247c1db2eb82d5c836df7bafc7380887890e11a2rjung </highlight>

92e5d4326ae44f79da5cb049470daba604506846poirier </example>

92e5d4326ae44f79da5cb049470daba604506846poirier</usage>

92e5d4326ae44f79da5cb049470daba604506846poirier</directivesynopsis>

457256c49209d6e56bfe63b411688ad9cb2a8429covener

457256c49209d6e56bfe63b411688ad9cb2a8429covener<directivesynopsis>

92e5d4326ae44f79da5cb049470daba604506846poirier<name>LuaPackageCPath</name>

fb51a6b789d85113d0976148685b0063c294220drbowen<description>Add a directory to lua's package.cpath</description>

fb51a6b789d85113d0976148685b0063c294220drbowen<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>

fb51a6b789d85113d0976148685b0063c294220drbowen<contextlist><context>server config</context><context>virtual host</context>

fb51a6b789d85113d0976148685b0063c294220drbowen<context>directory</context><context>.htaccess</context>

9cd56c73a0fd508522ba2f6bc6c9839c478c61c3rbowen</contextlist>

fb51a6b789d85113d0976148685b0063c294220drbowen<override>All</override>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic<usage>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <p>Add a path to lua's shared library search path. Follows the same

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic conventions as lua. This just munges the package.cpath in the

fb51a6b789d85113d0976148685b0063c294220drbowen lua vms.</p>

fb51a6b789d85113d0976148685b0063c294220drbowen

fb51a6b789d85113d0976148685b0063c294220drbowen</usage>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener</directivesynopsis>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<directivesynopsis>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<name>LuaCodeCache</name>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<description>Configure the compiled code cache.</description>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<syntax>LuaCodeCache stat|forever|never</syntax>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<default>LuaCodeCache stat</default>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<contextlist>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<context>server config</context><context>virtual host</context>

448a4db8228c5b9f6c1d3693e7a6b07b8b2b0c5erjung<context>directory</context><context>.htaccess</context>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener</contextlist>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<override>All</override>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener

ae600ca541efc686b34f8b1f21bd3d0741d37674covener<usage><p>

ae600ca541efc686b34f8b1f21bd3d0741d37674covener Specify the behavior of the in-memory code cache. The default

ae600ca541efc686b34f8b1f21bd3d0741d37674covener is stat, which stats the top level script (not any included

ae600ca541efc686b34f8b1f21bd3d0741d37674covener ones) each time that file is needed, and reloads it if the

ae600ca541efc686b34f8b1f21bd3d0741d37674covener modified time indicates it is newer than the one it has

ae600ca541efc686b34f8b1f21bd3d0741d37674covener already loaded. The other values cause it to keep the file

ae600ca541efc686b34f8b1f21bd3d0741d37674covener cached forever (don't stat and replace) or to never cache the

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen file.</p>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen <p>In general stat or forever is good for production, and stat or never

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen for development.</p>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic

448a4db8228c5b9f6c1d3693e7a6b07b8b2b0c5erjung <example><title>Examples:</title>

99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <highlight language="config">

99e316bc4b9b2b5754165939ac14b6d16132cce1igalicLuaCodeCache stat

457256c49209d6e56bfe63b411688ad9cb2a8429covenerLuaCodeCache forever

457256c49209d6e56bfe63b411688ad9cb2a8429covenerLuaCodeCache never

457256c49209d6e56bfe63b411688ad9cb2a8429covener </highlight>

457256c49209d6e56bfe63b411688ad9cb2a8429covener </example>

457256c49209d6e56bfe63b411688ad9cb2a8429covener

457256c49209d6e56bfe63b411688ad9cb2a8429covener</usage>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen</directivesynopsis>

6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen

fb51a6b789d85113d0976148685b0063c294220drbowen<directivesynopsis>

<name>LuaHookTranslateName</name>

<description>Provide a hook for the translate name phase of request processing</description>

<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<override>All</override>

<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>

<usage><p>

Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of

request processing. The hook function receives a single

argument, the request_rec, and should return a status code,

which is either an HTTP error code, or the constants defined

in the apache2 module: apache2.OK, apache2.DECLINED, or

apache2.DONE. </p>

<p>For those new to hooks, basically each hook will be invoked

until one of them returns apache2.OK. If your hook doesn't

want to do the translation it should just return

apache2.DECLINED. If the request should stop processing, then

return apache2.DONE.</p>

<p>Example:</p>

<highlight language="config">

# httpd.conf

LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper

</highlight>

<highlight language="lua">

-- /scripts/conf/hooks.lua --

require "apache2"

function silly_mapper(r)

if r.uri == "/" then

r.filename = "/var/www/home.lua"

return apache2.OK

else

return apache2.DECLINED

end

end

</highlight>

<note><title>Context</title><p>This directive is not valid in <directive

type="section" module="core">Directory</directive>, <directive

type="section" module="core">Files</directive>, or htaccess

context.</p></note>

<note><title>Ordering</title><p>The optional arguments "early" or "late"

control when this script runs relative to other modules.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookFixups</name>

<description>Provide a hook for the fixups phase of a request

processing</description>

<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<usage>

<p>

Just like LuaHookTranslateName, but executed at the fixups phase

</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookMapToStorage</name>

<description>Provide a hook for the map_to_storage phase of request processing</description>

<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<usage>

<p>Like <directive>LuaHookTranslateName</directive> but executed at the

map-to-storage phase of a request. Modules like mod_cache run at this phase,

which makes for an interesting example on what to do here:</p>

<highlight language="config">

LuaHookMapToStorage /path/to/lua/script.lua check_cache

</highlight>

<highlight language="lua">

require"apache2"

cached_files = {}

function read_file(filename)

local input = io.open(filename, "r")

if input then

local data = input:read("*a")

cached_files[filename] = data

file = cached_files[filename]

input:close()

end

return cached_files[filename]

end

function check_cache(r)

if r.filename:match("%.png$") then -- Only match PNG files

local file = cached_files[r.filename] -- Check cache entries

if not file then

file = read_file(r.filename) -- Read file into cache

end

if file then -- If file exists, write it out

r.status = 200

r:write(file)

r:info(("Sent %s to client from cache"):format(r.filename))

return apache2.DONE -- skip default handler for PNG files

end

end

return apache2.DECLINED -- If we had nothing to do, let others serve this.

end

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookCheckUserID</name>

<description>Provide a hook for the check_user_id phase of request processing</description>

<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>

<usage><p>...</p>

<note><title>Ordering</title><p>The optional arguments "early" or "late"

control when this script runs relative to other modules.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookTypeChecker</name>

<description>Provide a hook for the type_checker phase of request processing</description>

<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<usage><p>

This directive provides a hook for the type_checker phase of the request processing.

This phase is where requests are assigned a content type and a handler, and thus can

be used to modify the type and handler based on input:

</p>

<highlight language="config">

LuaHookTypeChecker /path/to/lua/script.lua type_checker

</highlight>

<highlight language="lua">

function type_checker(r)

if r.uri:match("%.to_gif$") then -- match foo.png.to_gif

r.content_type = "image/gif" -- assign it the image/gif type

r.handler = "gifWizard" -- tell the gifWizard module to handle this

r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested

return apache2.OK

end

return apache2.DECLINED

end

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookAuthChecker</name>

<description>Provide a hook for the auth_checker phase of request processing</description>

<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>

<usage>

<p>Invoke a lua function in the auth_checker phase of processing

a request. This can be used to implement arbitrary authentication

and authorization checking. A very simple example:

</p>

<highlight language="lua">

require 'apache2'

-- fake authcheck hook

-- If request has no auth info, set the response header and

-- return a 401 to ask the browser for basic auth info.

-- If request has auth info, don't actually look at it, just

-- pretend we got userid 'foo' and validated it.

-- Then check if the userid is 'foo' and accept the request.

function authcheck_hook(r)

-- look for auth info

auth = r.headers_in['Authorization']

if auth ~= nil then

-- fake the user

r.user = 'foo'

end

if r.user == nil then

r:debug("authcheck: user is nil, returning 401")

r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'

return 401

elseif r.user == "foo" then

r:debug('user foo: OK')

else

r:debug("authcheck: user='" .. r.user .. "'")

r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'

return 401

end

return apache2.OK

end

</highlight>

<note><title>Ordering</title><p>The optional arguments "early" or "late"

control when this script runs relative to other modules.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookAccessChecker</name>

<description>Provide a hook for the access_checker phase of request processing</description>

<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>

<usage>

<p>Add your hook to the access_checker phase. An access checker

hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>

<note><title>Ordering</title><p>The optional arguments "early" or "late"

control when this script runs relative to other modules.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookInsertFilter</name>

<description>Provide a hook for the insert_filter phase of request processing</description>

<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<usage><p>Not Yet Implemented</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaInherit</name>

<description>Controls how parent configuration sections are merged into children</description>

<syntax>LuaInherit none|parent-first|parent-last</syntax>

<default>LuaInherit parent-first</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context>

</contextlist>

<override>All</override>

<compatibility>2.4.0 and later</compatibility>

<usage><p>By default, if LuaHook* directives are used in overlapping

Directory or Location configuration sections, the scripts defined in the

more specific section are run <em>after</em> those defined in the more

generic section (LuaInherit parent-first). You can reverse this order, or

make the parent context not apply at all.</p>

<p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*

directives from parent configuration sections.</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaQuickHandler</name>

<description>Provide a hook for the quick handler of request processing</description>

<syntax>LuaQuickHandler /path/to/script.lua hook_function_name</syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<override>All</override>

<usage><p>...</p>

<note><title>Context</title><p>This directive is not valid in <directive

type="section" module="core">Directory</directive>, <directive

type="section" module="core">Files</directive>, or htaccess

context.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaAuthzProvider</name>

<description>Plug an authorization provider function into <module>mod_authz_core</module>

</description>

<syntax>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</syntax>

<contextlist><context>server config</context> </contextlist>

<compatibility>2.5.0 and later</compatibility>

<usage>

<p>After a lua function has been registered as authorization provider, it can be used

with the <directive module="mod_authz_core">Require</directive> directive:</p>

<highlight language="config">

LuaRoot /usr/local/apache2/lua

LuaAuthzProvider foo authz.lua authz_check_foo

&lt;Location /&gt;

Require foo johndoe

&lt;/Location&gt;

</highlight>

<highlight language="lua">

require "apache2"

function authz_check_foo(r, who)

if r.user ~= who then return apache2.AUTHZ_DENIED

return apache2.AUTHZ_GRANTED

end

</highlight>

</usage>

</directivesynopsis>

</modulesynopsis>