mod_lua.xml revision b75b4bfd9e8ec9fbf28a95174dc0e4d420f744a8
530eba85dbd41b8a0fa5255d3648d1440199a661slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Provides Lua hooks into various portions of the httpd
530eba85dbd41b8a0fa5255d3648d1440199a661sliverequest processing</description>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<p>Someone needs to write this.
5ae609a8a09239d20f48a4a95c4f21b713995babwroweInclude a link to <a href="http://www.lua.org/">the Lua website</a>.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<section id="basicconf"><title>Basic Configuration</title>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<code>mod_lua</code> provides a handler named <code>lua-script</code>,
5ae609a8a09239d20f48a4a95c4f21b713995babwrowewhich can be used with an <code>AddHandler</code> directive:</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernaAddHandler lua-script .lua
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernaThis will cause <code>mod_lua</code> to handle requests for files
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<p>For more flexibility, see <directive>LuaMapHandler</directive>.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<section id="writinghandlers"><title>Writing Handlers</title>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<p><code>mod_lua</code> always looks to invoke a function for the handler, rather than
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernajust evaluating a script body CGI style. A handler function looks
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernasomething like this:</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna-- example handler
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernarequire "string"
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernafunction handle_something(r)
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe r:puts("Hello Lua World!\n")
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe if r.method == 'GET' then
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe for k, v in pairs( r:parseargs() ) do
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe r:puts( string.format("%s: %s", k, v) )
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe elseif r.method == 'POST' then
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe for k, v in pairs( r:parsebody() ) do
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe r:puts( string.format("%s: %s", k, v) )
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe r:puts("unknown HTTP method " .. r.method)
5ae609a8a09239d20f48a4a95c4f21b713995babwroweThis handler function just prints out the uri or form encoded
5ae609a8a09239d20f48a4a95c4f21b713995babwrowearguments to a plaintext page.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernaThis means (and in fact encourages) that you can have multiple
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernahandlers (or hooks, or filters) in the same script.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<section id="writinghooks"><title>Writing Hooks</title>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<p>Hook functions are passed the request object as their only argument.
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveThey can return any value, depending on the hook, but most commonly
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivethey'll return OK, DONE, or DECLINED, which you can write in lua as
18b4b0fd6056093002ddef488636bf5ebe415ef0erikabele<code>apache2.OK</code>, <code>apache2.DONE</code>, or
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive-- example hook
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliverequire 'apache2'
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivefunction translate_name(r)
fb77c505254b6e9c925e23e734463e87574f8f40kess if r.uri == "/translate-name" then
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<section id="datastructures"><title>Data Structures</title>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The request_rec is mapped in as a userdata. It has a metatable
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive which lets you do useful things with it. For the most part it
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive has the same fields as the request_rec struct (see httpd.h
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive until we get better docs here) many of which are writeable as
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive well as readable. (The table fields' content can be changed, but the
fb77c505254b6e9c925e23e734463e87574f8f40kess fields themselves cannot be set to different tables.)</p>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <p>The request_rec has (at least) the following methods:</p>
58699879a562774640b95e9eedfd891f336e38c2nd r:addoutputfilter(name|function) -- add an output filter
58699879a562774640b95e9eedfd891f336e38c2nd </example>
58699879a562774640b95e9eedfd891f336e38c2nd r:parseargs() -- returns a lua table containing the request's
58699879a562774640b95e9eedfd891f336e38c2nd query string arguments
58699879a562774640b95e9eedfd891f336e38c2nd </example>
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive r:parsebody() -- parse the request body as a POST and return
58699879a562774640b95e9eedfd891f336e38c2nd a lua table
fb77c505254b6e9c925e23e734463e87574f8f40kess </example>
fb77c505254b6e9c925e23e734463e87574f8f40kess r:puts("hello", " world", "!") -- print to response body
fb77c505254b6e9c925e23e734463e87574f8f40kess </example>
58699879a562774640b95e9eedfd891f336e38c2nd r:write("a single string") -- print to response body
58699879a562774640b95e9eedfd891f336e38c2nd </example>
fb77c505254b6e9c925e23e734463e87574f8f40kess -- examples of logging messages<br />
fb77c505254b6e9c925e23e734463e87574f8f40kess r:debug("This is a debug log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:info("This is an info log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:notice("This is an notice log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:warn("This is an warn log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:err("This is an err log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:alert("This is an alert log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:crit("This is an crit log message")<br />
58699879a562774640b95e9eedfd891f336e38c2nd r:emerg("This is an emerg log message")<br />
9b5e2c5e769dc678a1aca06df75c32022b2f1492trawick<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <dd>internal constant OK. Handlers should return this if they've
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding handled the request.</dd>
4a7affccb2f1f5b94cab395e1bf3825aed715ebcnd <dd>internal constant DECLINED. Handlers should return this if
4a7affccb2f1f5b94cab395e1bf3825aed715ebcnd they are not going to handle the request.</dd>
9583adab6bc4b3758e41963c905d9dad9f067131nd<directivesynopsis>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<description>Specify the base path for resolving relative paths for mod_lua directives</description>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<contextlist><context>server config</context><context>virtual host</context>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd</contextlist>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <p>Specify the base path which will be used to evaluate all
77ead9e0262e4f08ec336d1a65b2edef7705c839nd relative paths within mod_lua. If not specified they
77ead9e0262e4f08ec336d1a65b2edef7705c839nd will be resolved relative to the current working directory,
77ead9e0262e4f08ec336d1a65b2edef7705c839nd which may not always work well for a server.</p>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd</directivesynopsis>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<directivesynopsis>
9b5e2c5e769dc678a1aca06df75c32022b2f1492trawick<description>One of once, request, conn, server -- default is once</description>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<syntax>LuaScope once|request|conn|server [max|min max]</syntax>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<contextlist><context>server config</context><context>virtual host</context>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Specify the lifecycle scope of the Lua interpreter which will
003f0c9fda6664daf5092a0e42f65ede20098153slive be used by handlers in this "Directory." The default is "once"</p>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <dt>request:</dt> <dd>use the interpreter to handle anything based on
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive the same file within this request, which is also
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive request scoped.</dd>
fb77c505254b6e9c925e23e734463e87574f8f40kess <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess <dt>server:</dt> <dd>This one is different than others because the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive server scope is quite long lived, and multiple threads
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess will have the same server_rec. To accommodate this
10673857794a4b3d9568ca2d983722a87ed352f1rbowen server scoped interpreter are stored in an apr
fb77c505254b6e9c925e23e734463e87574f8f40kess resource list. The min and max arguments are intended
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd to specify the pool size, but are unused at this time.</dd>
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd</directivesynopsis>
10673857794a4b3d9568ca2d983722a87ed352f1rbowen<directivesynopsis>
fb77c505254b6e9c925e23e734463e87574f8f40kess<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
fb77c505254b6e9c925e23e734463e87574f8f40kess<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
fb77c505254b6e9c925e23e734463e87574f8f40kess <p>This directive matches a uri pattern to invoke a specific
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive handler function in a specific file. It uses PCRE regular
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd expressions to match the uri, and supports interpolating
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive match groups into both the file path and the function name
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive be careful writing your regular expressions to avoid security
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive issues.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz handler function handle_show on the lua vm after
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz loading that file.</p>
9cd3b05d7b70f07a742bbaf548fa4fa2bdbe5ce6noodl <p>This would invoke the "handle" function, which
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive is the default if no specific function name is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive provided.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<directivesynopsis>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<description>Add a directory to lua's package.path</description>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<contextlist><context>server config</context><context>virtual host</context>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<context>directory</context><context>.htaccess</context>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding</contextlist>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <usage><p>Add a path to lua's module search path. Follows the same
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem conventions as lua. This just munges the package.path in the
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem lua vms.</p>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem</directivesynopsis>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<directivesynopsis>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<description>Add a directory to lua's package.cpath</description>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<contextlist><context>server config</context><context>virtual host</context>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<context>directory</context><context>.htaccess</context>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Add a path to lua's shared library search path. Follows the same
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive conventions as lua. This just munges the package.cpath in the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive lua vms.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Configure the compiled code cache.</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Specify the behavior of the in-memory code cache. The default
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive is stat, which stats the top level script (not any included
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive ones) each time that file is needed, and reloads it if the
9ed9eaf871c58d281af02e76125ceadb5060afa5nd modified time indicates it is newer than the one it has
9ed9eaf871c58d281af02e76125ceadb5060afa5nd already loaded. The other values cause it to keep the file
9ed9eaf871c58d281af02e76125ceadb5060afa5nd cached forever (don't stat and replace) or to never cache the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>In general stat or forever is good for production, and stat or never
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive for development.</p>
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna LuaCodeCache stat<br />
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna LuaCodeCache forever<br />
f23fb63b05f89f47d7a3099491f2c68dcce432e9kess LuaCodeCache never<br />
f23fb63b05f89f47d7a3099491f2c68dcce432e9kess </example>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<description>Provide a hook for the translate name phase of request processing</description>
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name</syntax>
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd<contextlist><context>server config</context><context>virtual host</context>
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd</contextlist>
da637bcae7b6e150470e701af29da5604a34a17erbowen Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
da637bcae7b6e150470e701af29da5604a34a17erbowen request processing. The hook function receives a single
da637bcae7b6e150470e701af29da5604a34a17erbowen argument, the request_rec, and should return a status code,
da637bcae7b6e150470e701af29da5604a34a17erbowen which is either an HTTP error code, or the constants defined
da637bcae7b6e150470e701af29da5604a34a17erbowen in the apache2 module: apache2.OK, apache2.DECLINED, or
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>For those new to hooks, basically each hook will be invoked
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive until one of them returns apache2.OK. If your hook doesn't
54bcd0e21a5c79158afd3b78bf707a493a5fb33crbowen want to do the translation it should just return
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive apache2.DECLINED. If the request should stop processing, then
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholesLuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholesrequire "apache2"
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholesfunction silly_mapper(r)
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes if r.uri == "/" then
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess<directivesynopsis>
fb77c505254b6e9c925e23e734463e87574f8f40kess<description>Provide a hook for the fixups phase of request
fb77c505254b6e9c925e23e734463e87574f8f40kessprocessing</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Just like LuaHookTranslateName, but executed at the fixups phase
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Provide a hook for the map_to_storage phase of request processing</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd</directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Provide a hook for the check_user_id phase of request processing</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name</syntax>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Provide a hook for the type_checker phase of request processing</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<contextlist><context>server config</context><context>virtual host</context>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<context>directory</context><context>.htaccess</context>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding</contextlist>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Provide a hook for the auth_checker phase of request processing</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<p>Invoke a lua function in the auth_checker phase of processing
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivea request. This can be used to implement arbitrary authentication
e4881891552e185a7408318dfc7f62ebabe73cf6niqand authorization checking. A very simple example:
e4881891552e185a7408318dfc7f62ebabe73cf6niqrequire 'apache2'
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding-- fake authcheck hook
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding-- If request has no auth info, set the response header and
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding-- return a 401 to ask the browser for basic auth info.
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding-- If request has auth info, don't actually look at it, just
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding-- pretend we got userid 'foo' and validated it.
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding-- Then check if the userid is 'foo' and accept the request.
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fieldingfunction authcheck_hook(r)
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding -- look for auth info
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive auth = r.headers_in['Authorization']
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive if auth ~= nil then
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive -- fake the user
6e483e0b8aa3fa574288a7452221392a03e2b9a3noodl if r.user == nil then
6e483e0b8aa3fa574288a7452221392a03e2b9a3noodl r:debug("authcheck: user is nil, returning 401")
6e483e0b8aa3fa574288a7452221392a03e2b9a3noodl r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
ccf2a600dd72cc3c3c44f5d4126d9bb60fa83894takashi elseif r.user == "foo" then
ccf2a600dd72cc3c3c44f5d4126d9bb60fa83894takashi r:debug('user foo: OK')
6e483e0b8aa3fa574288a7452221392a03e2b9a3noodl r:debug("authcheck: user='" .. r.user .. "'")
6e483e0b8aa3fa574288a7452221392a03e2b9a3noodl r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Provide a hook for the access_checker phase of request processing</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name</syntax>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context><context>virtual host</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<context>directory</context><context>.htaccess</context>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<p>Add your hook to the access_checker phase. An access checker
003f0c9fda6664daf5092a0e42f65ede20098153slivehook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
fb77c505254b6e9c925e23e734463e87574f8f40kess<directivesynopsis>
003f0c9fda6664daf5092a0e42f65ede20098153slive<description>Provide a hook for the insert_filter phase of request processing</description>
003f0c9fda6664daf5092a0e42f65ede20098153slive<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<contextlist><context>server config</context><context>virtual host</context>
130d299c4b2b15be45532a176604c71fdc7bea5bnd</contextlist>
130d299c4b2b15be45532a176604c71fdc7bea5bnd</directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<description>Provide a hook for the quick handler of request processing</description>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<contextlist><context>server config</context><context>virtual host</context>
fb77c505254b6e9c925e23e734463e87574f8f40kess</contextlist>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd</directivesynopsis>
030108b1816bcda3d925df65357feabdce83bc94slive</modulesynopsis>