mod_lua.xml revision 457256c49209d6e56bfe63b411688ad9cb2a8429
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames<!-- $LastChangedRevision$ -->
f5610d5460e701dd3f3514395867a6b5241fda81bnicholes Licensed to the Apache Software Foundation (ASF) under one or more
f5610d5460e701dd3f3514395867a6b5241fda81bnicholes contributor license agreements. See the NOTICE file distributed with
f5610d5460e701dd3f3514395867a6b5241fda81bnicholes this work for additional information regarding copyright ownership.
f5610d5460e701dd3f3514395867a6b5241fda81bnicholes The ASF licenses this file to You under the Apache License, Version 2.0
f5610d5460e701dd3f3514395867a6b5241fda81bnicholes (the "License"); you may not use this file except in compliance with
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames the License. You may obtain a copy of the License at
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames Unless required by applicable law or agreed to in writing, software
2f408250e9111c4b85b2b4b9b8836e83987efdefstoddard distributed under the License is distributed on an "AS IS" BASIS,
2f408250e9111c4b85b2b4b9b8836e83987efdefstoddard WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2f408250e9111c4b85b2b4b9b8836e83987efdefstoddard See the License for the specific language governing permissions and
2f408250e9111c4b85b2b4b9b8836e83987efdefstoddard limitations under the License.
6646a289c2d4778c8cd43d62b5a1cc966a356f85jerenkrantz<description>Provides Lua hooks into various portions of the httpd
6646a289c2d4778c8cd43d62b5a1cc966a356f85jerenkrantzrequest processing</description>
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe<p>This module allows the server to be extended with scripts written in the
ad451e2e428a069086d1c18c9e3372f8846ec617wroweLua programming language. The extension points (hooks) available with
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe<module>mod_lua</module> include many of the hooks available to
367cefc17f8dcfe65651c9c16cb3151589c6cecetrawicknatively compiled Apache HTTP Server modules, such as mapping requests to
367cefc17f8dcfe65651c9c16cb3151589c6cecetrawickfiles, generating dynamic responses, access control, authentication, and
ad877cddc14be8c8171938ba61338c6c7b896bbdtrawickauthorization</p>
ad877cddc14be8c8171938ba61338c6c7b896bbdtrawick<p>More information on the Lua programming language can be found at the
ad877cddc14be8c8171938ba61338c6c7b896bbdtrawick<a href="http://www.lua.org/">the Lua website</a>.</p>
ad877cddc14be8c8171938ba61338c6c7b896bbdtrawick<note><code>mod_lua</code> is still in experimental state.
367cefc17f8dcfe65651c9c16cb3151589c6cecetrawickUntil it is declared stable, usage and behavior may change
367cefc17f8dcfe65651c9c16cb3151589c6cecetrawickat any time.</note>
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe<section id="basicconf"><title>Basic Configuration</title>
52435ceaabd1670b2c3a062acc191159a64fb7a1wrowe<code>mod_lua</code> provides a handler named <code>lua-script</code>,
e199d79647c689a85951f19b08a08082263f4df8brianpwhich can be used with an <code>AddHandler</code> directive:</p>
ad451e2e428a069086d1c18c9e3372f8846ec617wroweAddHandler lua-script .lua
ad451e2e428a069086d1c18c9e3372f8846ec617wroweThis will cause <code>mod_lua</code> to handle requests for files
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe<p>For more flexibility, see <directive>LuaMapHandler</directive>.
1e1e5c477f92840ffbcb8acd0003305022e5468atrawick<section id="writinghandlers"><title>Writing Handlers</title>
1e1e5c477f92840ffbcb8acd0003305022e5468atrawick<p> In the Apache HTTP Server API, the handler is a specific kind of hook
1e1e5c477f92840ffbcb8acd0003305022e5468atrawickresponsible for generating the response. Examples of modules that include a
1e1e5c477f92840ffbcb8acd0003305022e5468atrawickhandler are <module>mod_proxy</module>, <module>mod_cgi</module>,
c998c5be82bf2b41f8fc27de9376ba10651c74bcrederpj<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
c998c5be82bf2b41f8fc27de9376ba10651c74bcrederpjjust evaluating a script body CGI style. A handler function looks
c998c5be82bf2b41f8fc27de9376ba10651c74bcrederpjsomething like this:</p>
c998c5be82bf2b41f8fc27de9376ba10651c74bcrederpj-- example handler
58eb8d7cca552570577aa8b636349a695ff193datrawickrequire "string"
ecf435f0c6379df7ed83285d5597fc9aa39c6f6dbrianp This is the default method name for Lua handlers, see the optional
ecf435f0c6379df7ed83285d5597fc9aa39c6f6dbrianp function-name in the LuaMapHandler directive to choose a different
ecf435f0c6379df7ed83285d5597fc9aa39c6f6dbrianp entry point.
480f2a1b2fb27a8284e66e60a5bbaee6bc1ccb04trawickfunction handle(r)
480f2a1b2fb27a8284e66e60a5bbaee6bc1ccb04trawick r:puts("Hello Lua World!\n")
acc9093ae1f3c97acc635bd5b2c7c0969da21183trawick if r.method == 'GET' then
acc9093ae1f3c97acc635bd5b2c7c0969da21183trawick for k, v in pairs( r:parseargs() ) do
acc9093ae1f3c97acc635bd5b2c7c0969da21183trawick r:puts( string.format("%s: %s", k, v) )
2fa5f4c38890220c6ea439317e7dcb9e8b3c76f7jwoolley elseif r.method == 'POST' then
2fa5f4c38890220c6ea439317e7dcb9e8b3c76f7jwoolley for k, v in pairs( r:parsebody() ) do
95d00ea81131488769296fa5765ed745cbf45207trawick r:puts( string.format("%s: %s", k, v) )
95d00ea81131488769296fa5765ed745cbf45207trawick r:puts("unknown HTTP method " .. r.method)
f08574f1098defdf1dc7e7f18a1e3664ee157150rederpjThis handler function just prints out the uri or form encoded
f08574f1098defdf1dc7e7f18a1e3664ee157150rederpjarguments to a plaintext page.
f08574f1098defdf1dc7e7f18a1e3664ee157150rederpjThis means (and in fact encourages) that you can have multiple
f08574f1098defdf1dc7e7f18a1e3664ee157150rederpjhandlers (or hooks, or filters) in the same script.
30990c446eca5b0d16d42171a6b30da9456ff6b4trawick<p>Hook functions are how modules (and Lua scripts) participate in the
30990c446eca5b0d16d42171a6b30da9456ff6b4trawickprocessing of requests. Each type of hook exposed by the server exists for
0fd9de72e2a1be5a6134ee70703324be80d816b7trawicka specific purposes such as mapping requests to the filesystem,
0fd9de72e2a1be5a6134ee70703324be80d816b7trawickperforming access control, or setting mimetypes. General purpose hooks
0fd9de72e2a1be5a6134ee70703324be80d816b7trawickthat simply run at handy times in the request lifecycle exist as well.</p>
2213cc395cb461faf7bfeb187ebb61d97cd457efjerenkrantz<p>Hook functions are passed the request object as their only argument.
f36d2c405b5a9bcc22c67577995560e7d1b616c0aaronThey can return any value, depending on the hook, but most commonly
2213cc395cb461faf7bfeb187ebb61d97cd457efjerenkrantzthey'll return OK, DONE, or DECLINED, which you can write in lua as
854c7bc4128fa2ad9fdfe0fc307d5ef30bcb5bb9wrowe<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
854c7bc4128fa2ad9fdfe0fc307d5ef30bcb5bb9wrowe-- example hook that rewrites the URI to a filesystem path.
854c7bc4128fa2ad9fdfe0fc307d5ef30bcb5bb9wrowerequire 'apache2'
854c7bc4128fa2ad9fdfe0fc307d5ef30bcb5bb9wrowefunction translate_name(r)
854c7bc4128fa2ad9fdfe0fc307d5ef30bcb5bb9wrowe if r.uri == "/translate-name" then
854c7bc4128fa2ad9fdfe0fc307d5ef30bcb5bb9wrowe -- we don't care about this URL, give another module a chance
75f8e1cae5ca3a16a7400cdddf604815ab06b5a8rederpj--[[ example hook that rewrites one URI to another URI. It returns a
75f8e1cae5ca3a16a7400cdddf604815ab06b5a8rederpj apache2.DECLINED to give other URL mappers a chance to work on the
75f8e1cae5ca3a16a7400cdddf604815ab06b5a8rederpj substitution, including the core translate_name hook which maps based
7f481efe04fdc4da7a447c14be62c155cbe00ddbbrianp on the DocumentRoot.
7f481efe04fdc4da7a447c14be62c155cbe00ddbbrianp Note: It is currently undefined as to whether this runs before or after
9ed34e5219ab3506ccfd2ca58751ce4c81b263a8rederpjrequire 'apache2'
23b36269d124e7a6aaa5221891f7ae2ef3eeb158jerenkrantzfunction translate_name(r)
23b36269d124e7a6aaa5221891f7ae2ef3eeb158jerenkrantz if r.uri == "/translate-name" then
e65b56dc229f063425fac589002e34c8246ad878trawick<section id="datastructures"><title>Data Structures</title>
ae3d212043d50288748fe9fdf0aa1a3e8f2ff3a6wrowe <p>The request_rec is mapped in as a userdata. It has a metatable
ae3d212043d50288748fe9fdf0aa1a3e8f2ff3a6wrowe which lets you do useful things with it. For the most part it
ae3d212043d50288748fe9fdf0aa1a3e8f2ff3a6wrowe has the same fields as the request_rec struct (see httpd.h
ae3d212043d50288748fe9fdf0aa1a3e8f2ff3a6wrowe until we get better docs here) many of which are writeable as
ae3d212043d50288748fe9fdf0aa1a3e8f2ff3a6wrowe well as readable. (The table fields' content can be changed, but the
766c20b0366e1d0e359e0d9a834669e19a4db3d9trawick fields themselves cannot be set to different tables.)</p>
8dc5aa056a586ffa920a6ecd5c31048702371ea6brianp <p>The request_rec has (at least) the following methods:</p>
7e31ef4870c7ef94838585004405e8854fefcc51ianh r:addoutputfilter(name|function) -- add an output filter
7e31ef4870c7ef94838585004405e8854fefcc51ianh </example>
bd496a3a7752a55c849e62ed00cacc492d4f6d3erederpj r:parseargs() -- returns a lua table containing the request's
bd496a3a7752a55c849e62ed00cacc492d4f6d3erederpj query string arguments
a8c401eadf77822e851f19c7740e7ec6dca03daastoddard r:parsebody() -- parse the request body as a POST and return
a8c401eadf77822e851f19c7740e7ec6dca03daastoddard a lua table
791781f2ccc1f1f1bc1b1643861d3da23edfd147jerenkrantz r:puts("hello", " world", "!") -- print to response body
02e8590d904653a95eca31bdf8e60866642bb592slive r:write("a single string") -- print to response body
b7838ae85a698af19d90ba4ebe03e10bdc149eacjerenkrantz<section id="logging"><title>Logging Functions</title>
435d2db95b905b0d16d35410e18ff77dc39688aabrianp -- examples of logging messages<br />
435d2db95b905b0d16d35410e18ff77dc39688aabrianp r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
1a7728c0205d607d5d87c6b6bf1b8837a9785a99ianh r:debug("This is a debug log message")<br />
a574815e2c6db68b9d8139db89921ededf033decianh r:info("This is an info log message")<br />
a574815e2c6db68b9d8139db89921ededf033decianh r:notice("This is an notice log message")<br />
964f539e766a3301b3e2f767baeffddcf9f6092bjerenkrantz r:warn("This is an warn log message")<br />
964f539e766a3301b3e2f767baeffddcf9f6092bjerenkrantz r:err("This is an err log message")<br />
964f539e766a3301b3e2f767baeffddcf9f6092bjerenkrantz r:alert("This is an alert log message")<br />
5e538c6ced13aa2f7c358e1a44f651d31dd5fab8brianp r:crit("This is an crit log message")<br />
5e538c6ced13aa2f7c358e1a44f651d31dd5fab8brianp r:emerg("This is an emerg log message")<br />
02c49e1f35a4d1a171df2d319e76af0c5163dc4dmartin<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
6deb8bcfb8511ac38243a8274fc589842841b398ianh <dd>internal constant OK. Handlers should return this if they've
6deb8bcfb8511ac38243a8274fc589842841b398ianh handled the request.</dd>
49bbbd1939208be54a3eb00b95e61d90d180a606ianh <dd>internal constant DECLINED. Handlers should return this if
49bbbd1939208be54a3eb00b95e61d90d180a606ianh they are not going to handle the request.</dd>
bc6600a6207e5d15b895294e370e4e3320a803d8stoddard <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
bc6600a6207e5d15b895294e370e4e3320a803d8stoddard <dd>internal constants used by <module>mod_proxy</module></dd>
bc6600a6207e5d15b895294e370e4e3320a803d8stoddard<p>(Other HTTP status codes are not yet implemented.)</p>
7a23067e782dd5612d4d4b539906e1733b664df7jwoolley<directivesynopsis>
5c214a63f9722864ac4983995da11353779515dbrederpj<description>Specify the base path for resolving relative paths for mod_lua directives</description>
5c214a63f9722864ac4983995da11353779515dbrederpj<contextlist><context>server config</context><context>virtual host</context>
9f20717d827f2113a23dfa45539813171cf626eaianh<context>directory</context><context>.htaccess</context>
9f20717d827f2113a23dfa45539813171cf626eaianh</contextlist>
a0db2f093595083300ad3438314f90921405ccf9wrowe <p>Specify the base path which will be used to evaluate all
a0db2f093595083300ad3438314f90921405ccf9wrowe relative paths within mod_lua. If not specified they
c66798efb2184ecf904cd8471acd17e65688b1caianh will be resolved relative to the current working directory,
c66798efb2184ecf904cd8471acd17e65688b1caianh which may not always work well for a server.</p>
fb59f85aab19883025f619727948b8088232cc4brederpj</directivesynopsis>
fb59f85aab19883025f619727948b8088232cc4brederpj<directivesynopsis>
1a1cf0ee9229ee29e5750b25dd94dbb9b04072cfianh<description>One of once, request, conn, server -- default is once</description>
1a1cf0ee9229ee29e5750b25dd94dbb9b04072cfianh<syntax>LuaScope once|request|conn|server [max|min max]</syntax>
61afed048a4d67ed923d52e5c865c0f10a8e9e73trawick<contextlist><context>server config</context><context>virtual host</context>
0bbb249eafe9ef9508821f0ef58e7440625ecd62trawick<context>directory</context><context>.htaccess</context>
0bbb249eafe9ef9508821f0ef58e7440625ecd62trawick</contextlist>
7a23067e782dd5612d4d4b539906e1733b664df7jwoolley <p>Specify the lifecycle scope of the Lua interpreter which will
7a23067e782dd5612d4d4b539906e1733b664df7jwoolley be used by handlers in this "Directory." The default is "once"</p>
6032a7c97a25c52f4bdd78ce23f2010e52c9e81arederpj <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
ba2e14e474516f1c75a96b4f6d1a9dec332175efianh <dt>request:</dt> <dd>use the interpreter to handle anything based on
ec69fc6e323eb1f3112966e06e9e37be608d052cianh the same file within this request, which is also
f0791c5bdfd36969d292a4092df076aa6d1c34ccwrowe request scoped.</dd>
f0791c5bdfd36969d292a4092df076aa6d1c34ccwrowe <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
749011213737e8d0cd6ca78d5eb532ec6f6b9fdfianh <dt>server:</dt> <dd>This one is different than others because the
749011213737e8d0cd6ca78d5eb532ec6f6b9fdfianh server scope is quite long lived, and multiple threads
749011213737e8d0cd6ca78d5eb532ec6f6b9fdfianh will have the same server_rec. To accommodate this
ec69fc6e323eb1f3112966e06e9e37be608d052cianh server scoped interpreter are stored in an apr
ec69fc6e323eb1f3112966e06e9e37be608d052cianh resource list. The min and max arguments are intended
e7bf4d6f15d04e86e20002e65f60d7fbf80e5974stoddard to specify the pool size, but are unused at this time.</dd>
de42d3dfd83a4cc62f0dd6b79ee5cbcfa69fd503brianp</directivesynopsis>
de42d3dfd83a4cc62f0dd6b79ee5cbcfa69fd503brianp<directivesynopsis>
8ab933f1df663f95c27e2ce5772127d4f3a10e0bstriker<description>Map a path to a lua handler</description>
a8dda281113c5038945423320d8c9b42e3d1ddb1jwoolley<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
50e60f30bdc074fbc887f0b98f4d570457ac97c9brianp<contextlist><context>server config</context><context>virtual host</context>
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe<context>directory</context><context>.htaccess</context>
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe</contextlist>
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe <p>This directive matches a uri pattern to invoke a specific
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe handler function in a specific file. It uses PCRE regular
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe expressions to match the uri, and supports interpolating
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe match groups into both the file path and the function name
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe be careful writing your regular expressions to avoid security
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe issues.</p>
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe handler function handle_show on the lua vm after
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe loading that file.</p>
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe <p>This would invoke the "handle" function, which
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe is the default if no specific function name is
39dde7f4cd79d701cc14e5beac8ea528bc58d038wrowe provided.</p>
268ac122b1fd6fa948b30bdf0d8c0d80e75d68dawrowe</directivesynopsis>
268ac122b1fd6fa948b30bdf0d8c0d80e75d68dawrowe<directivesynopsis>
268ac122b1fd6fa948b30bdf0d8c0d80e75d68dawrowe<description>Add a directory to lua's package.path</description>
6ba861fd6c705eaeb1f9bb97df86ddea6895e263minfrin<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
6ba861fd6c705eaeb1f9bb97df86ddea6895e263minfrin<contextlist><context>server config</context><context>virtual host</context>
6ba861fd6c705eaeb1f9bb97df86ddea6895e263minfrin<context>directory</context><context>.htaccess</context>
268ac122b1fd6fa948b30bdf0d8c0d80e75d68dawrowe</contextlist>
b78ed256f4b99e72836d36fd68d4e7a26dbe032cianh <usage><p>Add a path to lua's module search path. Follows the same
b78ed256f4b99e72836d36fd68d4e7a26dbe032cianh conventions as lua. This just munges the package.path in the
698670444b30b79e808155739f98c39bec35f72awrowe lua vms.</p>
57bea0f0559e31536af3b7b5859d3681ee29a34cwrowe</directivesynopsis>
94e2b2d12fa269af16fa63a6270d3336d9f126f2trawick<directivesynopsis>
94e2b2d12fa269af16fa63a6270d3336d9f126f2trawick<description>Add a directory to lua's package.cpath</description>
94e2b2d12fa269af16fa63a6270d3336d9f126f2trawick<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
35313c8d7368125c3e95d3118238d2be9a613000trawick<contextlist><context>server config</context><context>virtual host</context>
35313c8d7368125c3e95d3118238d2be9a613000trawick<context>directory</context><context>.htaccess</context>
35313c8d7368125c3e95d3118238d2be9a613000trawick</contextlist>
55da18d54a0ba74dc51aecba5b0daf71a2ed10a7trawick <p>Add a path to lua's shared library search path. Follows the same
55da18d54a0ba74dc51aecba5b0daf71a2ed10a7trawick conventions as lua. This just munges the package.cpath in the
c51f2b89da23e3371959a74808dee1792d96f5c1wsanchez lua vms.</p>
c51f2b89da23e3371959a74808dee1792d96f5c1wsanchez</directivesynopsis>
79c9b0ac498d97336874edba0daf9f544ad14671trawick<directivesynopsis>
79c9b0ac498d97336874edba0daf9f544ad14671trawick<description>Configure the compiled code cache.</description>
5a7d934619b2be92e18be5dd3366f4ac6ddeab43trawick<contextlist><context>server config</context><context>virtual host</context>
5a7d934619b2be92e18be5dd3366f4ac6ddeab43trawick<context>directory</context><context>.htaccess</context>
5a7d934619b2be92e18be5dd3366f4ac6ddeab43trawick</contextlist>
5a70e5b66eb7758d0e64e070211f699fc83fca70wrowe Specify the behavior of the in-memory code cache. The default
5a70e5b66eb7758d0e64e070211f699fc83fca70wrowe is stat, which stats the top level script (not any included
84eeb0ab12215fc22577a9a0a9589cea2a445712trawick ones) each time that file is needed, and reloads it if the
84eeb0ab12215fc22577a9a0a9589cea2a445712trawick modified time indicates it is newer than the one it has
1d3fbd2d9f03c0826977d940a2081401edf522d4jerenkrantz already loaded. The other values cause it to keep the file
1d3fbd2d9f03c0826977d940a2081401edf522d4jerenkrantz cached forever (don't stat and replace) or to never cache the
e4bb84f3c11f282d3ba66f64940b1b8e13f85e7aslive <p>In general stat or forever is good for production, and stat or never
e4bb84f3c11f282d3ba66f64940b1b8e13f85e7aslive for development.</p>
e4bb84f3c11f282d3ba66f64940b1b8e13f85e7aslive LuaCodeCache stat<br />
e4bb84f3c11f282d3ba66f64940b1b8e13f85e7aslive LuaCodeCache forever<br />
e4bb84f3c11f282d3ba66f64940b1b8e13f85e7aslive LuaCodeCache never<br />
756b54396a86db555817bb52149d91b60d00e35fwrowe</directivesynopsis>
756b54396a86db555817bb52149d91b60d00e35fwrowe<directivesynopsis>
b4251d1fbef86f96e01c68f8de086e0dbb8bcb74trawick<description>Provide a hook for the translate name phase of request processing</description>
b4251d1fbef86f96e01c68f8de086e0dbb8bcb74trawick<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</syntax>
b4251d1fbef86f96e01c68f8de086e0dbb8bcb74trawick<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
24efed0910118b762a4eb84830875d4714b8d315ianh<contextlist><context>server config</context><context>virtual host</context>
50e60f30bdc074fbc887f0b98f4d570457ac97c9brianp</contextlist>
bdbafc44d060509e86f0cc56ff4d19579438f846striker Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
bdbafc44d060509e86f0cc56ff4d19579438f846striker request processing. The hook function receives a single
fbd0c3dbae333ba4a7225dad2d090419ad894e4ctrawick argument, the request_rec, and should return a status code,
bdbafc44d060509e86f0cc56ff4d19579438f846striker which is either an HTTP error code, or the constants defined
bdbafc44d060509e86f0cc56ff4d19579438f846striker in the apache2 module: apache2.OK, apache2.DECLINED, or
6d0ec39a3ef89ce485f23008efa399b7b35bf1fdjwoolley <p>For those new to hooks, basically each hook will be invoked
6d0ec39a3ef89ce485f23008efa399b7b35bf1fdjwoolley until one of them returns apache2.OK. If your hook doesn't
6d0ec39a3ef89ce485f23008efa399b7b35bf1fdjwoolley want to do the translation it should just return
0fdf8c342123fde84405b885fb1720ebc652e10djerenkrantz apache2.DECLINED. If the request should stop processing, then
6b87b6eee6a43f40ef6bead9ef3173979b4cd76crbbLuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
bfd2cedbf2918fcb95daa9f850ecdf5e24765c22jerenkrantzrequire "apache2"
bfd2cedbf2918fcb95daa9f850ecdf5e24765c22jerenkrantzfunction silly_mapper(r)
bfd2cedbf2918fcb95daa9f850ecdf5e24765c22jerenkrantz if r.uri == "/" then
41338e6ead3fa8d60ad3841d069f4b47e71d9177wrowe <note><title>Context</title><p>This directive is not valid in <directive
41338e6ead3fa8d60ad3841d069f4b47e71d9177wrowe type="section" module="core">Directory</directive>, <directive
41338e6ead3fa8d60ad3841d069f4b47e71d9177wrowe type="section" module="core">Files</directive>, or htaccess
92b0ffb9cbc04b3d9c7ce6becadc0c3d88dea2d9wrowe <note><title>Ordering</title><p>The optional arguments "early" or "late"
961ff00a8f1fe79a8ac8b18617b40a404e28cb35brianp control when this script runs relative to other modules.</p></note>
92b0ffb9cbc04b3d9c7ce6becadc0c3d88dea2d9wrowe</directivesynopsis>
6a82dfd37385024d0e94e71edd2f46b609796cfdwrowe<directivesynopsis>
6a82dfd37385024d0e94e71edd2f46b609796cfdwrowe<description>Provide a hook for the fixups phase of request
6a82dfd37385024d0e94e71edd2f46b609796cfdwroweprocessing</description>
6a82dfd37385024d0e94e71edd2f46b609796cfdwrowe<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
6a82dfd37385024d0e94e71edd2f46b609796cfdwrowe<contextlist><context>server config</context><context>virtual host</context>
6a82dfd37385024d0e94e71edd2f46b609796cfdwrowe<context>directory</context><context>.htaccess</context>
c43fd8f8f90a7549bffe1e581eedbd087db1163estoddard</contextlist>
854cc4d3451547c2359c27870a3c354ad385a49bianh Just like LuaHookTranslateName, but executed at the fixups phase
02ec77ed8e15b4b601de98a322e4bd8d7d3e1ec2trawick</directivesynopsis>
02ec77ed8e15b4b601de98a322e4bd8d7d3e1ec2trawick<directivesynopsis>
49ada1eac7c4cae429ba193273b7f40f355d9c7ejwoolley<description>Provide a hook for the map_to_storage phase of request processing</description>
49ada1eac7c4cae429ba193273b7f40f355d9c7ejwoolley<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
88425bd3442321915195ac9dfa9a80ffcd968fa4brianp<contextlist><context>server config</context><context>virtual host</context>
88425bd3442321915195ac9dfa9a80ffcd968fa4brianp<context>directory</context><context>.htaccess</context>
88425bd3442321915195ac9dfa9a80ffcd968fa4brianp</contextlist>
a8dda281113c5038945423320d8c9b42e3d1ddb1jwoolley</directivesynopsis>
a8dda281113c5038945423320d8c9b42e3d1ddb1jwoolley<directivesynopsis>
37b8494ffaeb4ee9a9a2f9917d334078c16d4212jwoolley<description>Provide a hook for the check_user_id phase of request processing</description>
bf3d1782a29630335a1df535eb395355ab1cd154jwoolley<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</syntax>
bf3d1782a29630335a1df535eb395355ab1cd154jwoolley<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
37b8494ffaeb4ee9a9a2f9917d334078c16d4212jwoolley<contextlist><context>server config</context><context>virtual host</context>
da16bea08c6ff10ceb8d250ff23e8e81a372cef8jwoolley<context>directory</context><context>.htaccess</context>
da16bea08c6ff10ceb8d250ff23e8e81a372cef8jwoolley</contextlist>
99f692732327e0c200fd639105dbf9940bd229f1rbb <note><title>Ordering</title><p>The optional arguments "early" or "late"
80f73246cc14f02d50bfac5306c079464c2dd1c6rbb control when this script runs relative to other modules.</p></note>
80f73246cc14f02d50bfac5306c079464c2dd1c6rbb</directivesynopsis>
80f73246cc14f02d50bfac5306c079464c2dd1c6rbb<directivesynopsis>
dcdc78fce34f06533df4829abbc726f7fbf207fejwoolley<description>Provide a hook for the type_checker phase of request processing</description>
dcdc78fce34f06533df4829abbc726f7fbf207fejwoolley<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
d4a93d608a28bf331625544a2896fa20bef4a2b4rbb<contextlist><context>server config</context><context>virtual host</context>
d4a93d608a28bf331625544a2896fa20bef4a2b4rbb</contextlist>
36fcd3d96b9bf9a2d4af424e64584b5dede3e3e6brianp</directivesynopsis>
36fcd3d96b9bf9a2d4af424e64584b5dede3e3e6brianp<directivesynopsis>
4b34d6a5b70303010612df6c87da3ee91ae86078rbb<description>Provide a hook for the auth_checker phase of request processing</description>
4b34d6a5b70303010612df6c87da3ee91ae86078rbb<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>
4b34d6a5b70303010612df6c87da3ee91ae86078rbb<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
4b34d6a5b70303010612df6c87da3ee91ae86078rbb<contextlist><context>server config</context><context>virtual host</context>
4b34d6a5b70303010612df6c87da3ee91ae86078rbb</contextlist>
84bdb86d57d2a2f828b17e77ac2379fed551c2adtrawick<p>Invoke a lua function in the auth_checker phase of processing
84bdb86d57d2a2f828b17e77ac2379fed551c2adtrawicka request. This can be used to implement arbitrary authentication
46603605c2edcc1cc84fa45634e19a395134078atrawickand authorization checking. A very simple example:
46603605c2edcc1cc84fa45634e19a395134078atrawickrequire 'apache2'
86826d685f83170ca07d56550db9f0c2922a916btrawick-- fake authcheck hook
86826d685f83170ca07d56550db9f0c2922a916btrawick-- If request has no auth info, set the response header and
86826d685f83170ca07d56550db9f0c2922a916btrawick-- return a 401 to ask the browser for basic auth info.
86826d685f83170ca07d56550db9f0c2922a916btrawick-- If request has auth info, don't actually look at it, just
86826d685f83170ca07d56550db9f0c2922a916btrawick-- pretend we got userid 'foo' and validated it.
4f412c60e9c2af999619d11b236068a0e0e94944trawick-- Then check if the userid is 'foo' and accept the request.
4f412c60e9c2af999619d11b236068a0e0e94944trawickfunction authcheck_hook(r)
4f6effa17a5084085c9104b0bb97c2ba1622cfa6jerenkrantz -- look for auth info
4f6effa17a5084085c9104b0bb97c2ba1622cfa6jerenkrantz auth = r.headers_in['Authorization']
4f6effa17a5084085c9104b0bb97c2ba1622cfa6jerenkrantz if auth ~= nil then
4f6effa17a5084085c9104b0bb97c2ba1622cfa6jerenkrantz -- fake the user
a946a7e607c21cf6068e7380d7e81cc2bf027913trawick if r.user == nil then
a946a7e607c21cf6068e7380d7e81cc2bf027913trawick r:debug("authcheck: user is nil, returning 401")
da16bea08c6ff10ceb8d250ff23e8e81a372cef8jwoolley r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
c88a70518d7d0b5bccb22a68d446c2d6589790dcjwoolley elseif r.user == "foo" then
e59e4b703b7e19c4b35030e4baac8a96a8d4b504dougm r:debug('user foo: OK')
e59e4b703b7e19c4b35030e4baac8a96a8d4b504dougm r:debug("authcheck: user='" .. r.user .. "'")
e59e4b703b7e19c4b35030e4baac8a96a8d4b504dougm r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
5717c6b0b97a065a84fba32cebeee959a5fe4f15dougm <note><title>Ordering</title><p>The optional arguments "early" or "late"
835836eaf9e2a23192a262307b08f626e50e2180trawick control when this script runs relative to other modules.</p></note>
835836eaf9e2a23192a262307b08f626e50e2180trawick</directivesynopsis>
81dddb023f9dd43b350f782972c1f75a88a2d93ftrawick<directivesynopsis>
9b9e0eca165f5f464e357bb2a9b8bbfc9621067cwrowe<description>Provide a hook for the access_checker phase of request processing</description>
9b9e0eca165f5f464e357bb2a9b8bbfc9621067cwrowe<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>
9b9e0eca165f5f464e357bb2a9b8bbfc9621067cwrowe<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
9b9e0eca165f5f464e357bb2a9b8bbfc9621067cwrowe<contextlist><context>server config</context><context>virtual host</context>
9b9e0eca165f5f464e357bb2a9b8bbfc9621067cwrowe<context>directory</context><context>.htaccess</context>
9b9e0eca165f5f464e357bb2a9b8bbfc9621067cwrowe</contextlist>
b26781e595625911fc8fc8215133ad2285ed75d8jim<p>Add your hook to the access_checker phase. An access checker
5117466ef123b1efbc2feba168f37069ef6f230bianhhook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
5117466ef123b1efbc2feba168f37069ef6f230bianh <note><title>Ordering</title><p>The optional arguments "early" or "late"
5117466ef123b1efbc2feba168f37069ef6f230bianh control when this script runs relative to other modules.</p></note>
9c39f8fb982df4dbce5304e49385568e6d35bfa8trawick</directivesynopsis>
9c39f8fb982df4dbce5304e49385568e6d35bfa8trawick<directivesynopsis>
bdd4aa13a97de79596cd19708f1516e8fa92700ewrowe<description>Provide a hook for the insert_filter phase of request processing</description>
bdd4aa13a97de79596cd19708f1516e8fa92700ewrowe<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
bdd4aa13a97de79596cd19708f1516e8fa92700ewrowe<contextlist><context>server config</context><context>virtual host</context>
bdd4aa13a97de79596cd19708f1516e8fa92700ewrowe<context>directory</context><context>.htaccess</context>
1d50c90ddb7e3d144ec8a2bd848ca1e7bbf8e534bnicholes</contextlist>
1d50c90ddb7e3d144ec8a2bd848ca1e7bbf8e534bnicholes</directivesynopsis>
24e361af20a3107dc934b4895911ce6bcce0603ejwoolley<directivesynopsis>
24e361af20a3107dc934b4895911ce6bcce0603ejwoolley<description>Provide a hook for the quick handler of request processing</description>
4657f9b12af4b123b80e15c73fa03c190e47a8bftrawick<contextlist><context>server config</context><context>virtual host</context>
4657f9b12af4b123b80e15c73fa03c190e47a8bftrawick<context>directory</context><context>.htaccess</context>
4657f9b12af4b123b80e15c73fa03c190e47a8bftrawick</contextlist>
c36bac9a918f59b2dbf5dcd7d67b50c1da04c89drbb <note><title>Context</title><p>This directive is not valid in <directive
c36bac9a918f59b2dbf5dcd7d67b50c1da04c89drbb type="section" module="core">Directory</directive>, <directive
c36bac9a918f59b2dbf5dcd7d67b50c1da04c89drbb type="section" module="core">Files</directive>, or htaccess
ad668861e40da485f2eea24dc4c1f9940e470698rbb</directivesynopsis>
ad668861e40da485f2eea24dc4c1f9940e470698rbb</modulesynopsis>