2N/A<?xml version="1.0"?>

2N/A<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

2N/A

2N/A

2N/A<modulesynopsis metafile="mod_lua.xml.meta">

2N/A

2N/A<name>mod_lua</name>

2N/A

2N/A<description>Provides Lua hooks into various portions of the httpd

2N/Arequest processing</description>

2N/A<status>Experimental</status>

2N/A<sourcefile>mod_lua.c</sourcefile>

2N/A<identifier>lua_module</identifier>

2N/A<compatibility>2.3 and later</compatibility>

2N/A

2N/A<summary>

2N/A<p>This module allows the server to be extended with scripts written in the

2N/ALua programming language. The extension points (hooks) available with

2N/A<module>mod_lua</module> include many of the hooks available to

2N/Anatively compiled Apache HTTP Server modules, such as mapping requests to

2N/Afiles, generating dynamic responses, access control, authentication, and

2N/Aauthorization</p>

2N/A

2N/A<p>More information on the Lua programming language can be found at the

2N/A<a href="http://www.lua.org/">the Lua website</a>.</p>

2N/A

2N/A<note><code>mod_lua</code> is still in experimental state.

2N/AUntil it is declared stable, usage and behavior may change

2N/Aat any time.</note>

2N/A

2N/A</summary>

2N/A

2N/A<section id="basicconf"><title>Basic Configuration</title>

2N/A

2N/A<p>The basic module loading directive is</p>

2N/A

2N/A<example>

2N/A LoadModule lua_module modules/mod_lua.so

2N/A</example>

2N/A

2N/A<p>

2N/A<code>mod_lua</code> provides a handler named <code>lua-script</code>,

2N/Awhich can be used with an <code>AddHandler</code> directive:</p>

2N/A

2N/A<example>

2N/AAddHandler lua-script .lua

2N/A</example>

2N/A

2N/A<p>

2N/AThis will cause <code>mod_lua</code> to handle requests for files

2N/Aending in <code>.lua</code> by invoking that file's

2N/A<code>handle</code> function.

2N/A</p>

2N/A

2N/A<p>For more flexibility, see <directive>LuaMapHandler</directive>.

2N/A</p>

2N/A

2N/A</section>

2N/A

2N/A<section id="writinghandlers"><title>Writing Handlers</title>

2N/A<p> In the Apache HTTP Server API, the handler is a specific kind of hook

2N/Aresponsible for generating the response. Examples of modules that include a

2N/Ahandler are <module>mod_proxy</module>, <module>mod_cgi</module>,

2N/Aand <module>mod_status</module>.</p>

2N/A

2N/A<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than

2N/Ajust evaluating a script body CGI style. A handler function looks

2N/Asomething like this:</p>

2N/A

2N/A<example><title>example.lua</title><pre>

2N/A-- example handler

2N/A

2N/Arequire "string"

2N/A

2N/A--[[

2N/A This is the default method name for Lua handlers, see the optional

2N/A function-name in the LuaMapHandler directive to choose a different

2N/A entry point.

2N/A--]]

2N/Afunction handle(r)

2N/A r.content_type = "text/plain"

2N/A r:puts("Hello Lua World!\n")

2N/A

2N/A if r.method == 'GET' then

2N/A for k, v in pairs( r:parseargs() ) do

2N/A r:puts( string.format("%s: %s", k, v) )

2N/A end

2N/A elseif r.method == 'POST' then

2N/A for k, v in pairs( r:parsebody() ) do

2N/A r:puts( string.format("%s: %s", k, v) )

2N/A end

2N/A else

2N/A r:puts("unknown HTTP method " .. r.method)

2N/A end

2N/Aend

2N/A</pre></example>

2N/A

2N/A<p>

2N/AThis handler function just prints out the uri or form encoded

2N/Aarguments to a plaintext page.

2N/A</p>

2N/A

2N/A<p>

2N/AThis means (and in fact encourages) that you can have multiple

2N/Ahandlers (or hooks, or filters) in the same script.

2N/A</p>

2N/A

2N/A</section>

2N/A

2N/A<section id="writinghooks"><title>Writing Hooks</title>

2N/A

2N/A<p>Hook functions are how modules (and Lua scripts) participate in the

2N/Aprocessing of requests. Each type of hook exposed by the server exists for

2N/Aa specific purposes such as mapping requests to the filesystem,

2N/Aperforming access control, or setting mimetypes. General purpose hooks

2N/Athat simply run at handy times in the request lifecycle exist as well.</p>

2N/A

2N/A<p>Hook functions are passed the request object as their only argument.

2N/AThey can return any value, depending on the hook, but most commonly

2N/Athey'll return OK, DONE, or DECLINED, which you can write in lua as

2N/A<code>apache2.OK</code>, <code>apache2.DONE</code>, or

2N/A<code>apache2.DECLINED</code>, or else an HTTP status code.</p>

2N/A

2N/A<example><title>translate_name.lua</title><pre>

2N/A-- example hook that rewrites the URI to a filesystem path.

2N/A

2N/Arequire 'apache2'

2N/A

2N/Afunction translate_name(r)

2N/A if r.uri == "/translate-name" then

2N/A r.filename = r.document_root .. "/find_me.txt"

2N/A return apache2.OK

2N/A end

2N/A -- we don't care about this URL, give another module a chance

2N/A return apache2.DECLINED

2N/Aend

2N/A</pre></example>

2N/A

2N/A<example><title>translate_name2.lua</title><pre>

2N/A--[[ example hook that rewrites one URI to another URI. It returns a

2N/A apache2.DECLINED to give other URL mappers a chance to work on the

2N/A substitution, including the core translate_name hook which maps based

2N/A on the DocumentRoot.

2N/A

2N/A Note: It is currently undefined as to whether this runs before or after

2N/A mod_alias.

2N/A--]]

2N/A

2N/Arequire 'apache2'

2N/A

2N/Afunction translate_name(r)

2N/A if r.uri == "/translate-name" then

2N/A r.uri = "/find_me.txt"

2N/A return apache2.DECLINED

2N/A end

2N/A return apache2.DECLINED

2N/Aend

2N/A</pre></example>

2N/A</section>

2N/A

2N/A<section id="datastructures"><title>Data Structures</title>

2N/A

2N/A<dl>

2N/A<dt>request_rec</dt>

2N/A <dd>

2N/A <p>The request_rec is mapped in as a userdata. It has a metatable

2N/A which lets you do useful things with it. For the most part it

2N/A has the same fields as the request_rec struct (see httpd.h

2N/A until we get better docs here) many of which are writeable as

2N/A well as readable. (The table fields' content can be changed, but the

2N/A fields themselves cannot be set to different tables.)</p>

2N/A

2N/A <table border="1">

2N/A

2N/A <tr>

2N/A <th><strong>Name</strong></th>

2N/A <th><strong>Lua type</strong></th>

2N/A <th><strong>Writable</strong></th>

2N/A </tr>

2N/A <tr>

2N/A <td><code>ap_auth_type</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>args</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>assbackwards</code></td>

2N/A <td>boolean</td>

2N/A <td>no</td>

2N/A </tr>

2N/A

2N/A <tr>

2N/A <td><code>canonical_filename</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>content_encoding</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>content_type</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A

2N/A <tr>

2N/A <td><code>document_root</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>err_headers_out</code></td>

2N/A <td>table</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>filename</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>handler</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A

2N/A <tr>

2N/A <td><code>headers_in</code></td>

2N/A <td>table</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>headers_out</code></td>

2N/A <td>table</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>hostname</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>method</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>notes</code></td>

2N/A <td>table</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>path_info</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>protocol</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>proxyreq</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>range</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>subprocess_env</code></td>

2N/A <td>table</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>status</code></td>

2N/A <td>number</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>the_request</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>unparsed_uri</code></td>

2N/A <td>string</td>

2N/A <td>no</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>uri</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A <tr>

2N/A <td><code>user</code></td>

2N/A <td>string</td>

2N/A <td>yes</td>

2N/A </tr>

2N/A </table>

2N/A

2N/A <p>The request_rec has (at least) the following methods:</p>

2N/A

2N/A <example>

2N/A r:addoutputfilter(name|function) -- add an output filter

2N/A </example>

2N/A

2N/A <example>

2N/A r:parseargs() -- returns a lua table containing the request's

2N/A query string arguments

2N/A </example>

2N/A

2N/A <example>

2N/A r:parsebody() -- parse the request body as a POST and return

2N/A a lua table

2N/A </example>

2N/A

2N/A <example>

2N/A r:puts("hello", " world", "!") -- print to response body

2N/A </example>

2N/A

2N/A <example>

2N/A r:write("a single string") -- print to response body

2N/A </example>

2N/A </dd>

2N/A </dl>

2N/A

2N/A</section>

2N/A

2N/A<section id="logging"><title>Logging Functions</title>

2N/A

2N/A<example>

2N/A -- examples of logging messages<br />

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

2N/A r:debug("This is a debug log message")<br />

2N/A r:info("This is an info log message")<br />

2N/A r:notice("This is an notice log message")<br />

2N/A r:warn("This is an warn log message")<br />

2N/A r:err("This is an err log message")<br />

2N/A r:alert("This is an alert log message")<br />

2N/A r:crit("This is an crit log message")<br />

2N/A r:emerg("This is an emerg log message")<br />

2N/A</example>

2N/A

2N/A</section>

2N/A

2N/A<section id="apache2"><title>apache2 Package</title>

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

2N/A<dl>

2N/A <dt>apache2.OK</dt>

2N/A <dd>internal constant OK. Handlers should return this if they've

2N/A handled the request.</dd>

2N/A <dt>apache2.DECLINED</dt>

2N/A <dd>internal constant DECLINED. Handlers should return this if

2N/A they are not going to handle the request.</dd>

2N/A <dt>apache2.DONE</dt>

2N/A <dd>internal constant DONE.</dd>

2N/A <dt>apache2.version</dt>

2N/A <dd>Apache HTTP server version string</dd>

2N/A <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>

2N/A <dd>HTTP status code</dd>

2N/A <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>

2N/A <dd>internal constants used by <module>mod_proxy</module></dd>

2N/A</dl>

2N/A<p>(Other HTTP status codes are not yet implemented.)</p>

2N/A</section>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaRoot</name>

2N/A<description>Specify the base path for resolving relative paths for mod_lua directives</description>

2N/A<syntax>LuaRoot /path/to/a/directory</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A

2N/A<usage>

2N/A <p>Specify the base path which will be used to evaluate all

2N/A relative paths within mod_lua. If not specified they

2N/A will be resolved relative to the current working directory,

2N/A which may not always work well for a server.</p>

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaScope</name>

2N/A<description>One of once, request, conn, server -- default is once</description>

2N/A<syntax>LuaScope once|request|conn|server [max|min max]</syntax>

2N/A<default>LuaScope once</default>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A

2N/A<usage>

2N/A <p>Specify the lifecycle scope of the Lua interpreter which will

2N/A be used by handlers in this "Directory." The default is "once"</p>

2N/A

2N/A <dl>

2N/A <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>

2N/A

2N/A <dt>request:</dt> <dd>use the interpreter to handle anything based on

2N/A the same file within this request, which is also

2N/A request scoped.</dd>

2N/A

2N/A <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>

2N/A

2N/A <dt>server:</dt> <dd>This one is different than others because the

2N/A server scope is quite long lived, and multiple threads

2N/A will have the same server_rec. To accommodate this

2N/A server scoped interpreter are stored in an apr

2N/A resource list. The min and max arguments are intended

2N/A to specify the pool size, but are unused at this time.</dd>

2N/A </dl>

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaMapHandler</name>

2N/A<description>Map a path to a lua handler</description>

2N/A<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A<usage>

2N/A <p>This directive matches a uri pattern to invoke a specific

2N/A handler function in a specific file. It uses PCRE regular

2N/A expressions to match the uri, and supports interpolating

2N/A match groups into both the file path and the function name

2N/A be careful writing your regular expressions to avoid security

2N/A issues.</p>

2N/A <example><title>Examples:</title>

2N/A LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2

2N/A </example>

2N/A <p>This would match uri's such as /photos/show?id=9

2N/A to the file /scripts/photos.lua and invoke the

2N/A handler function handle_show on the lua vm after

2N/A loading that file.</p>

2N/A

2N/A<example>

2N/A LuaMapHandler /bingo /scripts/wombat.lua

2N/A</example>

2N/A <p>This would invoke the "handle" function, which

2N/A is the default if no specific function name is

2N/A provided.</p>

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaPackagePath</name>

2N/A<description>Add a directory to lua's package.path</description>

2N/A<syntax>LuaPackagePath /path/to/include/?.lua</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A <usage><p>Add a path to lua's module search path. Follows the same

2N/A conventions as lua. This just munges the package.path in the

2N/A lua vms.</p>

2N/A

2N/A <example><title>Examples:</title>

2N/A LuaPackagePath /scripts/lib/?.lua<br />

2N/A LuaPackagePath /scripts/lib/?/init.lua

2N/A </example>

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaPackageCPath</name>

2N/A<description>Add a directory to lua's package.cpath</description>

2N/A<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A

2N/A<usage>

2N/A <p>Add a path to lua's shared library search path. Follows the same

2N/A conventions as lua. This just munges the package.cpath in the

2N/A lua vms.</p>

2N/A

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaCodeCache</name>

2N/A<description>Configure the compiled code cache.</description>

2N/A<syntax>LuaCodeCache stat|forever|never</syntax>

2N/A<default>LuaCodeCache stat</default>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A

2N/A<usage><p>

2N/A Specify the behavior of the in-memory code cache. The default

2N/A is stat, which stats the top level script (not any included

2N/A ones) each time that file is needed, and reloads it if the

2N/A modified time indicates it is newer than the one it has

2N/A already loaded. The other values cause it to keep the file

2N/A cached forever (don't stat and replace) or to never cache the

2N/A file.</p>

2N/A

2N/A <p>In general stat or forever is good for production, and stat or never

2N/A for development.</p>

2N/A

2N/A <example><title>Examples:</title>

2N/A LuaCodeCache stat<br />

2N/A LuaCodeCache forever<br />

2N/A LuaCodeCache never<br />

2N/A </example>

2N/A

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookTranslateName</name>

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

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

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context>

2N/A</contextlist>

2N/A<override>All</override>

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

2N/A

2N/A<usage><p>

2N/A Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of

2N/A request processing. The hook function receives a single

2N/A argument, the request_rec, and should return a status code,

2N/A which is either an HTTP error code, or the constants defined

2N/A in the apache2 module: apache2.OK, apache2.DECLINED, or

2N/A apache2.DONE. </p>

2N/A

2N/A <p>For those new to hooks, basically each hook will be invoked

2N/A until one of them returns apache2.OK. If your hook doesn't

2N/A want to do the translation it should just return

2N/A apache2.DECLINED. If the request should stop processing, then

2N/A return apache2.DONE.</p>

2N/A

2N/A <p>Example:</p>

2N/A

2N/A<example><pre>

2N/A# httpd.conf

2N/ALuaHookTranslateName /scripts/conf/hooks.lua silly_mapper

2N/A

2N/A-- /scripts/conf/hooks.lua --

2N/Arequire "apache2"

2N/Afunction silly_mapper(r)

2N/A if r.uri == "/" then

2N/A r.filename = "/var/www/home.lua"

2N/A return apache2.OK

2N/A else

2N/A return apache2.DECLINED

2N/A end

2N/Aend

2N/A</pre></example>

2N/A

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

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

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

2N/A context.</p></note>

2N/A

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

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

2N/A

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookFixups</name>

2N/A<description>Provide a hook for the fixups phase of request

2N/Aprocessing</description>

2N/A<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A<usage>

2N/A<p>

2N/A Just like LuaHookTranslateName, but executed at the fixups phase

2N/A</p>

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookMapToStorage</name>

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

2N/A<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A <usage><p>...</p></usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookCheckUserID</name>

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

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

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

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

2N/A<usage><p>...</p>

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

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

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookTypeChecker</name>

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

2N/A<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A <usage><p>...</p></usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookAuthChecker</name>

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

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

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

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

2N/A<usage>

2N/A<p>Invoke a lua function in the auth_checker phase of processing

2N/Aa request. This can be used to implement arbitrary authentication

2N/Aand authorization checking. A very simple example:

2N/A</p>

2N/A<example><pre>

2N/Arequire 'apache2'

2N/A

2N/A-- fake authcheck hook

2N/A-- If request has no auth info, set the response header and

2N/A-- return a 401 to ask the browser for basic auth info.

2N/A-- If request has auth info, don't actually look at it, just

2N/A-- pretend we got userid 'foo' and validated it.

2N/A-- Then check if the userid is 'foo' and accept the request.

2N/Afunction authcheck_hook(r)

2N/A

2N/A -- look for auth info

2N/A auth = r.headers_in['Authorization']

2N/A if auth ~= nil then

2N/A -- fake the user

2N/A r.user = 'foo'

2N/A end

2N/A

2N/A if r.user == nil then

2N/A r:debug("authcheck: user is nil, returning 401")

2N/A r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'

2N/A return 401

2N/A elseif r.user == "foo" then

2N/A r:debug('user foo: OK')

2N/A else

2N/A r:debug("authcheck: user='" .. r.user .. "'")

2N/A r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'

2N/A return 401

2N/A end

2N/A return apache2.OK

2N/Aend

2N/A</pre></example>

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

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

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookAccessChecker</name>

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

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

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

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

2N/A<usage>

2N/A<p>Add your hook to the access_checker phase. An access checker

2N/Ahook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>

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

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

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaHookInsertFilter</name>

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

2N/A<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A <usage><p>Not Yet Implemented</p></usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaInherit</name>

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

2N/A<syntax>LuaInherit none|parent-first|parent-last</syntax>

2N/A<default>LuaInherit parent-first</default>

2N/A<compatibility>2.5.0 and later</compatibility>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context><context>.htaccess</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A <usage><p>By default, if LuaHook* directives are used in overlapping

2N/A Directory or Location configuration sections, the scripts defined in the

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

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

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

2N/A

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

2N/A directives from parent configuration sections.</p></usage>

2N/A</directivesynopsis>

2N/A

2N/A<directivesynopsis>

2N/A<name>LuaQuickHandler</name>

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

2N/A<syntax></syntax>

2N/A<contextlist><context>server config</context><context>virtual host</context>

2N/A<context>directory</context>

2N/A</contextlist>

2N/A<override>All</override>

2N/A<usage><p>...</p>

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

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

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

2N/A context.</p></note>

2N/A</usage>

2N/A</directivesynopsis>

2N/A

2N/A</modulesynopsis>

2N/A