mirror of
https://github.com/apache/httpd.git
synced 2025-11-02 06:53:27 +03:00
0e6795f3e1
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@936789 13f79535-47bb-0310-9956-ffa450edef68
357 lines
12 KiB
XML
357 lines
12 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_lua.xml.meta">
|
|
|
|
<name>mod_lua</name>
|
|
|
|
<description>Provides Lua hooks into various portions of the httpd
|
|
request processing</description>
|
|
<status>experimental</status>
|
|
<sourcefile>mod_lua.c</sourcefile>
|
|
<identifier>lua_module</identifier>
|
|
<compatibility>2.4 and later</compatibility>
|
|
|
|
<summary>
|
|
<p>Someone needs to write this.</p>
|
|
|
|
</summary>
|
|
|
|
<section id="basicconf"><title>Basic Configuration</title>
|
|
|
|
The basic module loading directive is
|
|
|
|
<example>
|
|
LoadModule apreq_module modules/mod_apreq2.so<br />
|
|
LoadModule wombat_module modules/mod_wombat.so
|
|
</example>
|
|
|
|
<p>
|
|
<code>mod_lua</code> provides a handler named <code>lua-script</code>,
|
|
which can be used with an <code>AddHandler</code> directive:</p>
|
|
|
|
<example>
|
|
AddHandler lua-script .lua
|
|
</example>
|
|
|
|
<p>
|
|
This will cause any <code>.lua</code> file to be evaluated by
|
|
<code>mod_lua</code>.
|
|
</p>
|
|
</section>
|
|
|
|
<section id="writinghandlers"><title>Writing Handlers</title>
|
|
|
|
<p><code>mod_lua</code> always looks to invoke a function for the handler, rather than
|
|
just evaluating a script body CGI style. A handler function looks
|
|
something like this:</p>
|
|
|
|
<example><title>example.lua</title><pre>
|
|
require "string"
|
|
|
|
function handle_something(r)
|
|
r.content_type = "text/plain"
|
|
r:puts("Hello Lua World!\n")
|
|
|
|
if r.method == 'GET' then
|
|
for k, v in pairs( r:parseargs() ) do
|
|
r:puts( string.format("%s: %s", k, v) )
|
|
end
|
|
elseif r.method == 'POST' then
|
|
for k, v in pairs( r:parsebody() ) do
|
|
r:puts( string.format("%s: %s", k, v) )
|
|
end
|
|
else
|
|
r:puts("unknown HTTP method " .. r.method)
|
|
end
|
|
end
|
|
</pre></example>
|
|
|
|
<p>
|
|
This handler function just prints out the uri or form encoded
|
|
arguments to a plaintext page.
|
|
</p>
|
|
|
|
<p>
|
|
This means (and in fact encourages) that you can have multiple
|
|
handlers (or hooks, or filters) in the same script.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section id="datastructures"><title>Data Structures</title>
|
|
|
|
<dl>
|
|
<dt>request_rec</dt>
|
|
<dd>
|
|
<p>The request_rec is mapped in as a userdata. It has a metatable
|
|
which lets you do useful things with it. For the most part it
|
|
has the same fields as the request_rec struct (see httpd.h
|
|
until we get better docs here) many of which are writeable as
|
|
well as readable, and has (at least) the following methods:</p>
|
|
|
|
<example>
|
|
r:puts("hello", " world", "!") -- print to response body
|
|
</example>
|
|
</dd>
|
|
</dl>
|
|
|
|
</section>
|
|
|
|
<section id="logging"><title>Logging Functions</title>
|
|
|
|
<example>
|
|
r:debug("This is a debug log message")<br />
|
|
r:info("This is an info log message")<br />
|
|
r:notice("This is an notice log message")<br />
|
|
r:warn("This is an warn log message")<br />
|
|
r:err("This is an err log message")<br />
|
|
r:alert("This is an alert log message")<br />
|
|
r:crit("This is an crit log message")<br />
|
|
r:emerg("This is an emerg log message")<br />
|
|
</example>
|
|
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaRoot</name>
|
|
<description>Specify the base path for resolving relative paths for mod_lua directives</description>
|
|
<syntax>LuaRoot /path/to/a/directory</syntax>
|
|
|
|
<usage>
|
|
<p>Specify the base path which will be used to evaluate all
|
|
relative paths within mod_wombat. If not specified they
|
|
will be resolved relative to the current working directory,
|
|
which may not always work well for a server.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaScope</name>
|
|
<description>One of once, request, conn, server -- default is once</description>
|
|
<syntax>LuaScope once|request|conn|server [max|min max]</syntax>
|
|
|
|
<usage>
|
|
<p>Specify the lifecycle scope of the Lua interpreter which will
|
|
be used by handlers in this "Directory." The default is "once"</p>
|
|
|
|
<dl>
|
|
<dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
|
|
|
|
<dt>request:</dt> <dd>use the interpreter to handle anything based on
|
|
the same file within this request, which is also
|
|
request scoped.</dd>
|
|
|
|
<dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
|
|
|
|
<dt>server:</dt> <dd>This one is different than others because the
|
|
server scope is quite long lived, and multiple threads
|
|
will have the same server_rec. To accommodate this
|
|
server scoped interpreter are stored in an apr
|
|
resource list. The min and max arguments are intended
|
|
to specify the pool size, but are unused at this time.</dd>
|
|
</dl>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaMapHandler</name>
|
|
<description>Map a path to a lua handler</description>
|
|
<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
|
|
<usage>
|
|
<p>This directive matches a uri pattern to invoke a specific
|
|
handler function in a specific file. It uses PCRE regular
|
|
expressions to match the uri, and supports interpolating
|
|
match groups into both the file path and the function name
|
|
be careful writing your regular expressions to avoid security
|
|
issues.</p>
|
|
<example><title>Examples:</title>
|
|
LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
|
|
</example>
|
|
<p>This would match uri's such as /photos/show?id=9
|
|
to the file /scripts/photos.lua and invoke the
|
|
handler function handle_show on the lua vm after
|
|
loading that file.</p>
|
|
|
|
<example>
|
|
LuaMapHandler /bingo /scripts/wombat.lua
|
|
</example>
|
|
<p>This would invoke the "handle" function, which
|
|
is the default if no specific function name is
|
|
provided.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaPackagePath</name>
|
|
<description>Add a directory to lua's package.path</description>
|
|
<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
|
|
<usage><p>Add a path to lua's module search path. Follows the same
|
|
conventions as lua. This just munges the package.path in the
|
|
lua vms.</p>
|
|
|
|
<example><title>Examples:</title>
|
|
LuaPackagePath /scripts/lib/?.lua<br />
|
|
LuaPackagePath /scripts/lib/?/init.lua
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaPackageCPath</name>
|
|
<description>Add a directory to lua's package.cpath</description>
|
|
<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
|
|
|
|
<usage>
|
|
<p>Add a path to lua's shared library search path. Follows the same
|
|
conventions as lua. This just munges the package.cpath in the
|
|
lua vms.</p>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaCodeCache</name>
|
|
<description>Configure the compiled code cache.</description>
|
|
<syntax>LuaCodeCache stat|forever|never</syntax>
|
|
|
|
<usage><p>
|
|
Specify the behavior of the in-memory code cache. The default
|
|
is stat, which stats the top level script (not any included
|
|
ones) each time that file is needed, and reloads it if the
|
|
modified time indicates it is newer than the one it has
|
|
already loaded. The other values cause it to keep the file
|
|
cached forever (don't stat and replace) or to never cache the
|
|
file.</p>
|
|
|
|
<p>In general stat or forever is good production and stat or never
|
|
for deveopment.</p>
|
|
|
|
<example><title>Examples:</title>
|
|
LuaCodeCache stat<br />
|
|
LuaCodeCache forever<br />
|
|
LuaCodeCache never<br />
|
|
</example>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<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</syntax>
|
|
|
|
<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>
|
|
|
|
<example>
|
|
LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper<br />
|
|
<br />
|
|
-- /scripts/conf/hooks.lua --<br />
|
|
function silly_mapper(r)<br />
|
|
if r.uri == "/" then<br />
|
|
r.file = "/var/www/home.lua"<br />
|
|
return apache2.OK<br />
|
|
else<br />
|
|
return apache2.DECLINED<br />
|
|
end<br />
|
|
end<br />
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookFixups</name>
|
|
<description>Provide a hook for the fixups phase of request
|
|
processing</description>
|
|
<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
|
|
Just like LuaHookTranslateName, but executed at the fixups phase
|
|
</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>
|
|
<usage><p>...</p></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</syntax>
|
|
<usage><p>...</p></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>
|
|
<usage><p>...</p></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookAuthChecker</name>
|
|
<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
|
|
<usage><p>...</p></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookAccessChecker</name>
|
|
<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name</syntax>
|
|
<usage><p>...</p></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookAuthChecker</name>
|
|
<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
|
|
<usage><p>...</p></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookInsertFilter</name>
|
|
<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
|
|
<usage><p>Not Yet Implemented</p></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaQuickHandler</name>
|
|
<description>Provide a hook for the quick handler of request processing</description>
|
|
<syntax></syntax>
|
|
<usage><p>...</p></usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|
|
|