mirror of
https://github.com/apache/httpd.git
synced 2025-05-30 01:07:09 +03:00
cadc3c17dd
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1331553 13f79535-47bb-0310-9956-ffa450edef68
820 lines
40 KiB
XML
820 lines
40 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
|
||
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
This file is generated from xml source: DO NOT EDIT
|
||
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
-->
|
||
<title>mod_lua - Apache HTTP Server</title>
|
||
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
|
||
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
|
||
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
|
||
<script src="../style/scripts/prettify.js" type="text/javascript">
|
||
</script>
|
||
|
||
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
|
||
<body>
|
||
<div id="page-header">
|
||
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
|
||
<p class="apache">Apache HTTP Server Version 2.5</p>
|
||
<img alt="" src="../images/feather.gif" /></div>
|
||
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
|
||
<div id="path">
|
||
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
|
||
<div id="page-content">
|
||
<div id="preamble"><h1>Apache Module mod_lua</h1>
|
||
<div class="toplang">
|
||
<p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a> |
|
||
<a href="../fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
|
||
</div>
|
||
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides Lua hooks into various portions of the httpd
|
||
request processing</td></tr>
|
||
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>lua_module</td></tr>
|
||
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_lua.c</td></tr>
|
||
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>2.3 and later</td></tr></table>
|
||
<h3>Summary</h3>
|
||
|
||
<p>This module allows the server to be extended with scripts written in the
|
||
Lua programming language. The extension points (hooks) available with
|
||
<code class="module"><a href="../mod/mod_lua.html">mod_lua</a></code> include many of the hooks available to
|
||
natively compiled Apache HTTP Server modules, such as mapping requests to
|
||
files, generating dynamic responses, access control, authentication, and
|
||
authorization</p>
|
||
|
||
<p>More information on the Lua programming language can be found at the
|
||
<a href="http://www.lua.org/">the Lua website</a>.</p>
|
||
|
||
<div class="note"><code>mod_lua</code> is still in experimental state.
|
||
Until it is declared stable, usage and behavior may change
|
||
at any time, even between stable releases of the 2.4.x series.
|
||
Be sure to check the CHANGES file before upgrading.</div>
|
||
|
||
</div>
|
||
<div id="quickview"><h3 class="directives">Directives</h3>
|
||
<ul id="toc">
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahookfixups">LuaHookFixups</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahookinsertfilter">LuaHookInsertFilter</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahookmaptostorage">LuaHookMapToStorage</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahooktranslatename">LuaHookTranslateName</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luahooktypechecker">LuaHookTypeChecker</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luainherit">LuaInherit</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li>
|
||
</ul>
|
||
<h3>Topics</h3>
|
||
<ul id="topics">
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Basic Configuration</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Writing Handlers</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Writing Hooks</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Data Structures</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging Functions</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#apache2">apache2 Package</a></li>
|
||
</ul></div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="section">
|
||
<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
|
||
|
||
<p>The basic module loading directive is</p>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
LoadModule lua_module modules/mod_lua.so
|
||
</pre>
|
||
|
||
|
||
<p>
|
||
<code>mod_lua</code> provides a handler named <code>lua-script</code>,
|
||
which can be used with an <code>AddHandler</code> directive:</p>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
AddHandler lua-script .lua
|
||
</pre>
|
||
|
||
|
||
<p>
|
||
This will cause <code>mod_lua</code> to handle requests for files
|
||
ending in <code>.lua</code> by invoking that file's
|
||
<code>handle</code> function.
|
||
</p>
|
||
|
||
<p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
|
||
</p>
|
||
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="section">
|
||
<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
|
||
<p> In the Apache HTTP Server API, the handler is a specific kind of hook
|
||
responsible for generating the response. Examples of modules that include a
|
||
handler are <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>,
|
||
and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p>
|
||
|
||
<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
|
||
just evaluating a script body CGI style. A handler function looks
|
||
something like this:</p>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
<strong>example.lua</strong>
|
||
-- example handler
|
||
|
||
require "string"
|
||
|
||
--[[
|
||
This is the default method name for Lua handlers, see the optional
|
||
function-name in the LuaMapHandler directive to choose a different
|
||
entry point.
|
||
--]]
|
||
function handle(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>
|
||
|
||
|
||
<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>
|
||
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="section">
|
||
<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
|
||
|
||
<p>Hook functions are how modules (and Lua scripts) participate in the
|
||
processing of requests. Each type of hook exposed by the server exists for
|
||
a specific purposes such as mapping requests to the filesystem,
|
||
performing access control, or setting mimetypes. General purpose hooks
|
||
that simply run at handy times in the request lifecycle exist as well.</p>
|
||
|
||
<p>Hook functions are passed the request object as their only argument.
|
||
They can return any value, depending on the hook, but most commonly
|
||
they'll return OK, DONE, or DECLINED, which you can write in lua as
|
||
<code>apache2.OK</code>, <code>apache2.DONE</code>, or
|
||
<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
<strong>translate_name.lua</strong>
|
||
-- example hook that rewrites the URI to a filesystem path.
|
||
|
||
require 'apache2'
|
||
|
||
function translate_name(r)
|
||
if r.uri == "/translate-name" then
|
||
r.filename = r.document_root .. "/find_me.txt"
|
||
return apache2.OK
|
||
end
|
||
-- we don't care about this URL, give another module a chance
|
||
return apache2.DECLINED
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
<strong>translate_name2.lua</strong>
|
||
--[[ example hook that rewrites one URI to another URI. It returns a
|
||
apache2.DECLINED to give other URL mappers a chance to work on the
|
||
substitution, including the core translate_name hook which maps based
|
||
on the DocumentRoot.
|
||
|
||
Note: It is currently undefined as to whether this runs before or after
|
||
mod_alias.
|
||
--]]
|
||
|
||
require 'apache2'
|
||
|
||
function translate_name(r)
|
||
if r.uri == "/translate-name" then
|
||
r.uri = "/find_me.txt"
|
||
return apache2.DECLINED
|
||
end
|
||
return apache2.DECLINED
|
||
end
|
||
</pre>
|
||
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="section">
|
||
<h2><a name="datastructures" id="datastructures">Data Structures</a></h2>
|
||
|
||
<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. (The table fields' content can be changed, but the
|
||
fields themselves cannot be set to different tables.)</p>
|
||
|
||
<table class="bordered">
|
||
|
||
<tr>
|
||
<th><strong>Name</strong></th>
|
||
<th><strong>Lua type</strong></th>
|
||
<th><strong>Writable</strong></th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>ap_auth_type</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>args</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>assbackwards</code></td>
|
||
<td>boolean</td>
|
||
<td>no</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>canonical_filename</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>content_encoding</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>content_type</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>document_root</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>err_headers_out</code></td>
|
||
<td>table</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>filename</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>handler</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>headers_in</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>headers_out</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>hostname</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>method</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>notes</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>path_info</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>protocol</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>proxyreq</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>range</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>subprocess_env</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>status</code></td>
|
||
<td>number</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>the_request</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>unparsed_uri</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>uri</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>user</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p>The request_rec has (at least) the following methods:</p>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:addoutputfilter(name|function) -- add an output filter
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:parseargs() -- returns a lua table containing the request's query string arguments
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:parsebody() -- parse the request body as a POST and return a lua table
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:puts("hello", " world", "!") -- print to response body
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:write("a single string") -- print to response body
|
||
</pre>
|
||
|
||
</dd>
|
||
</dl>
|
||
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="section">
|
||
<h2><a name="logging" id="logging">Logging Functions</a></h2>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
-- examples of logging messages<br />
|
||
r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
|
||
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 />
|
||
</pre>
|
||
|
||
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="section">
|
||
<h2><a name="apache2" id="apache2">apache2 Package</a></h2>
|
||
<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
|
||
<dl>
|
||
<dt>apache2.OK</dt>
|
||
<dd>internal constant OK. Handlers should return this if they've
|
||
handled the request.</dd>
|
||
<dt>apache2.DECLINED</dt>
|
||
<dd>internal constant DECLINED. Handlers should return this if
|
||
they are not going to handle the request.</dd>
|
||
<dt>apache2.DONE</dt>
|
||
<dd>internal constant DONE.</dd>
|
||
<dt>apache2.version</dt>
|
||
<dd>Apache HTTP server version string</dd>
|
||
<dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
|
||
<dd>HTTP status code</dd>
|
||
<dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
|
||
<dd>internal constants used by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd>
|
||
</dl>
|
||
<p>(Other HTTP status codes are not yet implemented.)</p>
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table><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 for production, and stat or never
|
||
for development.</p>
|
||
|
||
<div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
|
||
LuaCodeCache stat
|
||
LuaCodeCache forever
|
||
LuaCodeCache never
|
||
</pre>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access_checker phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
|
||
</table>
|
||
<p>Add your hook to the access_checker phase. An access checker
|
||
hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
|
||
<div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
|
||
control when this script runs relative to other modules.</p></div>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the auth_checker phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
|
||
</table>
|
||
<p>Invoke a lua function in the auth_checker phase of processing
|
||
a request. This can be used to implement arbitrary authentication
|
||
and authorization checking. A very simple example:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
require 'apache2'
|
||
|
||
-- fake authcheck hook
|
||
-- If request has no auth info, set the response header and
|
||
-- return a 401 to ask the browser for basic auth info.
|
||
-- If request has auth info, don't actually look at it, just
|
||
-- pretend we got userid 'foo' and validated it.
|
||
-- Then check if the userid is 'foo' and accept the request.
|
||
function authcheck_hook(r)
|
||
|
||
-- look for auth info
|
||
auth = r.headers_in['Authorization']
|
||
if auth ~= nil then
|
||
-- fake the user
|
||
r.user = 'foo'
|
||
end
|
||
|
||
if r.user == nil then
|
||
r:debug("authcheck: user is nil, returning 401")
|
||
r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
|
||
return 401
|
||
elseif r.user == "foo" then
|
||
r:debug('user foo: OK')
|
||
else
|
||
r:debug("authcheck: user='" .. r.user .. "'")
|
||
r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
|
||
return 401
|
||
end
|
||
return apache2.OK
|
||
end
|
||
</pre>
|
||
|
||
<div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
|
||
control when this script runs relative to other modules.</p></div>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the check_user_id phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
|
||
</table><p>...</p>
|
||
<div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
|
||
control when this script runs relative to other modules.</p></div>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of request
|
||
processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookFixups /path/to/lua/script.lua hook_function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table>
|
||
<p>
|
||
Just like LuaHookTranslateName, but executed at the fixups phase
|
||
</p>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the insert_filter phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table><p>Not Yet Implemented</p>
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the map_to_storage phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table><p>...</p>
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the translate name phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
|
||
</table><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>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
# httpd.conf
|
||
LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
-- /scripts/conf/hooks.lua --
|
||
require "apache2"
|
||
function silly_mapper(r)
|
||
if r.uri == "/" then
|
||
r.filename = "/var/www/home.lua"
|
||
return apache2.OK
|
||
else
|
||
return apache2.DECLINED
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
|
||
<div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
|
||
context.</p></div>
|
||
|
||
<div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
|
||
control when this script runs relative to other modules.</p></div>
|
||
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the type_checker phase of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table><p>...</p>
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.0 and later</td></tr>
|
||
</table><p>By default, if LuaHook* directives are used in overlapping
|
||
Directory or Location configuration sections, the scripts defined in the
|
||
more specific section are run <em>after</em> those defined in the more
|
||
generic section (LuaInherit parent-first). You can reverse this order, or
|
||
make the parent context not apply at all.</p>
|
||
|
||
<p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
|
||
directives from parent configuration sections.</p>
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table>
|
||
<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>
|
||
<div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
|
||
LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
|
||
</pre>
|
||
</div>
|
||
<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>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
LuaMapHandler /bingo /scripts/wombat.lua
|
||
</pre>
|
||
|
||
<p>This would invoke the "handle" function, which
|
||
is the default if no specific function name is
|
||
provided.</p>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table>
|
||
<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>
|
||
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table><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>
|
||
|
||
<div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
|
||
LuaPackagePath /scripts/lib/?.lua
|
||
LuaPackagePath /scripts/lib/?/init.lua
|
||
</pre>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code /></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table><p>...</p>
|
||
<div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
|
||
context.</p></div>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the base path for resolving relative paths for mod_lua directives</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table>
|
||
<p>Specify the base path which will be used to evaluate all
|
||
relative paths within mod_lua. If not specified they
|
||
will be resolved relative to the current working directory,
|
||
which may not always work well for a server.</p>
|
||
|
||
</div>
|
||
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
||
<div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, server -- default is once</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|server [max|min max]</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
|
||
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
|
||
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
|
||
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
|
||
</table>
|
||
<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>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="bottomlang">
|
||
<p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a> |
|
||
<a href="../fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
|
||
</div><div id="footer">
|
||
<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
|
||
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
|
||
if (typeof(prettyPrint) !== undefined) {
|
||
prettyPrint();
|
||
}
|
||
//--><!]]></script>
|
||
</body></html> |