mirror of
https://github.com/apache/httpd.git
synced 2025-11-03 17:53:20 +03:00
671803f375
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1524242 13f79535-47bb-0310-9956-ffa450edef68
2056 lines
89 KiB
XML
2056 lines
89 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/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/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<61>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<EFBFBD>Identifier:</a></th><td>lua_module</td></tr>
|
||
<tr><th><a href="module-dict.html#SourceFile">Source<EFBFBD>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 class="warning"><h3>Warning</h3>
|
||
<p>This module holds a great deal of power over httpd, which is both a
|
||
strength and a potential security risk. It is <strong>not</strong> recommended
|
||
that you use this module on a server that is shared with users you do not
|
||
trust, as it can be abused to change the internal workings of httpd.</p>
|
||
</div>
|
||
|
||
</div>
|
||
<div id="quickview"><h3 class="directives">Directives</h3>
|
||
<ul id="toc">
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li>
|
||
<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="#luahooklog">LuaHookLog</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="#luainputfilter">LuaInputFilter</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#luaoutputfilter">LuaOutputFilter</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="#writingauthzproviders">Writing Authorization Providers</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="#functions">Built in functions</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>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modifying contents with Lua filters</a></li>
|
||
<li><img alt="" src="../images/down.gif" /> <a href="#databases">Database connectivity</a></li>
|
||
</ul><ul class="seealso"><li><a href="#comments_section">Comments</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><br />
|
||
-- 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"
|
||
|
||
if r.method == 'GET' then
|
||
r:puts("Hello Lua World!\n")
|
||
for k, v in pairs( r:parseargs() ) do
|
||
r:puts( string.format("%s: %s\n", k, v) )
|
||
end
|
||
elseif r.method == 'POST' then
|
||
r:puts("Hello Lua World!\n")
|
||
for k, v in pairs( r:parsebody() ) do
|
||
r:puts( string.format("%s: %s\n", k, v) )
|
||
end
|
||
elseif r.method == 'PUT' then
|
||
-- use our own Error contents
|
||
r:puts("Unsupported HTTP method " .. r.method)
|
||
r.status = 405
|
||
return apache2.ok
|
||
else
|
||
-- use the ErrorDocument
|
||
return 501
|
||
end
|
||
return apache2.OK
|
||
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="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2>
|
||
|
||
|
||
<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to
|
||
authorization that is much easier to use than using into the relevant
|
||
hooks directly. The first argument to the
|
||
<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive gives
|
||
the name of the responsible authorization provider. For any
|
||
<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> line,
|
||
<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider
|
||
of the given name, passing the rest of the line as parameters. The
|
||
provider will then check authorization and pass the result as return
|
||
value.</p>
|
||
|
||
<p>The authz provider is normally called before authentication. If it needs to
|
||
know the authenticated user name (or if the user will be authenticated at
|
||
all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
|
||
This will cause authentication to proceed and the authz provider to be
|
||
called a second time.</p>
|
||
|
||
<p>The following authz provider function takes two arguments, one ip
|
||
address and one user name. It will allow access from the given ip address
|
||
without authentication, or if the authenticated user matches the second
|
||
argument:</p>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
<strong>authz_provider.lua</strong><br />
|
||
|
||
require 'apache2'
|
||
|
||
function authz_check_foo(r, ip, user)
|
||
if r.useragent_ip == ip then
|
||
return apache2.AUTHZ_GRANTED
|
||
elseif r.user == nil then
|
||
return apache2.AUTHZ_DENIED_NO_USER
|
||
elseif r.user == user then
|
||
return apache2.AUTHZ_GRANTED
|
||
else
|
||
return apache2.AUTHZ_DENIED
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
|
||
<p>The following configuration registers this function as provider
|
||
<code>foo</code> and configures it for URL <code>/</code>:</p>
|
||
<pre class="prettyprint lang-config">
|
||
LuaAuthzProvider foo authz_provider.lua authz_check_foo
|
||
<Location />
|
||
Require foo 10.1.2.3 john_doe
|
||
</Location>
|
||
</pre>
|
||
|
||
|
||
</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 purpose, such as mapping requests to the file system,
|
||
performing access control, or setting mime types:</p>
|
||
|
||
<table class="bordered"><tr class="header">
|
||
<th>Hook phase</th>
|
||
<th>mod_lua directive</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td>Quick handler</td>
|
||
<td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
|
||
<td>This is the first hook that will be called after a request has
|
||
been mapped to a host or virtual host</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td>Translate name</td>
|
||
<td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
|
||
<td>This phase translates the requested URI into a filename on the
|
||
system. Modules such as <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
|
||
<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operate in this phase.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Map to storage</td>
|
||
<td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
|
||
<td>This phase maps files to their physical, cached or external/proxied storage.
|
||
It can be used by proxy or caching modules</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td>Check Access</td>
|
||
<td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
|
||
<td>This phase checks whether a client has access to a resource. This
|
||
phase is run before the user is authenticated, so beware.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Check User ID</td>
|
||
<td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
|
||
<td>This phase it used to check the negotiated user ID</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td>Check Authorization</td>
|
||
<td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> or
|
||
<code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
|
||
<td>This phase authorizes a user based on the negotiated credentials, such as
|
||
user ID, client certificate etc.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Check Type</td>
|
||
<td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
|
||
<td>This phase checks the requested file and assigns a content type and
|
||
a handler to it</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td>Fixups</td>
|
||
<td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
|
||
<td>This is the final "fix anything" phase before the content handlers
|
||
are run. Any last-minute changes to the request should be made here.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Content handler</td>
|
||
<td>fx. <code>.lua</code> files or through <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
|
||
<td>This is where the content is handled. Files are read, parsed, some are run,
|
||
and the result is sent to the client</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td>Logging</td>
|
||
<td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
|
||
<td>Once a request has been handled, it enters several logging phases,
|
||
which logs the request in either the error or access log. Mod_lua
|
||
is able to hook into the start of this and control logging output.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p>Hook functions are passed the request object as their only argument
|
||
(except for LuaAuthzProvider, which also gets passed the arguments from
|
||
the Require directive).
|
||
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><br />
|
||
-- 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><br />
|
||
--[[ 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: Use the early/late flags in the directive to make it run 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, many of which are writable 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 class="header">
|
||
<th><strong>Name</strong></th>
|
||
<th><strong>Lua type</strong></th>
|
||
<th><strong>Writable</strong></th>
|
||
<th><strong>Description</strong></th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>allowoverrides</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The AllowOverride options applied to the current request.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>ap_auth_type</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>If an authentication check was made, this is set to the type
|
||
of authentication (f.x. <code>basic</code>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>args</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>The query string arguments extracted from the request
|
||
(f.x. <code>foo=bar&name=johnsmith</code>)</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>assbackwards</code></td>
|
||
<td>boolean</td>
|
||
<td>no</td>
|
||
<td>Set to true if this is an HTTP/0.9 style request
|
||
(e.g. <code>GET /foo</code> (with no headers) )</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>auth_name</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The realm name used for authorization (if applicable).</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>banner</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The server banner, f.x. <code>Apache HTTP Server/2.4.3 openssl/0.9.8c</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>basic_auth_pw</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The basic auth password sent with this request, if any</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>canonical_filename</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The canonical filename of the request</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>content_encoding</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The content encoding of the current request</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>content_type</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>The content type of the current request, as determined in the
|
||
type_check phase (f.x. <code>image/gif</code> or <code>text/html</code>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>context_prefix</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td />
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>context_document_root</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td />
|
||
</tr>
|
||
<tr>
|
||
<td><code>document_root</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The document root of the host</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>err_headers_out</code></td>
|
||
<td>table</td>
|
||
<td>no</td>
|
||
<td>MIME header environment for the response, printed even on errors and
|
||
persist across internal redirects</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>filename</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be
|
||
changed in the translate-name or map-to-storage phases of a request to allow the
|
||
default handler (or script handlers) to serve a different file than what was requested.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>handler</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>The name of the <a href="../handler.html">handler</a> that should serve this request, f.x.
|
||
<code>lua-script</code> if it is to be served by mod_lua. This is typically set by the
|
||
<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> or <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code>
|
||
directives, but could also be set via mod_lua to allow another handler to serve up a specific request
|
||
that would otherwise not be served by it.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>headers_in</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
<td>MIME header environment from the request. This contains headers such as <code>Host,
|
||
User-Agent, Referer</code> and so on.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>headers_out</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
<td>MIME header environment for the response.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>hostname</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The host name, as set by the <code>Host:</code> header or by a full URI.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>is_https</code></td>
|
||
<td>boolean</td>
|
||
<td>no</td>
|
||
<td>Whether or not this request is done via HTTPS</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>is_initial_req</code></td>
|
||
<td>boolean</td>
|
||
<td>no</td>
|
||
<td>Whether this request is the initial request or a sub-request</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>limit_req_body</code></td>
|
||
<td>number</td>
|
||
<td>no</td>
|
||
<td>The size limit of the request body for this request, or 0 if no limit.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>log_id</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The ID to identify request in access and error log.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>method</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The request method, f.x. <code>GET</code> or <code>POST</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>notes</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
<td>A list of notes that can be passed on from one module to another.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>options</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The Options directive applied to the current request.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>path_info</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The PATH_INFO extracted from this request.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>port</code></td>
|
||
<td>number</td>
|
||
<td>no</td>
|
||
<td>The server port used by the request.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>protocol</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The protocol used, f.x. <code>HTTP/1.1</code></td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>proxyreq</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>Denotes whether this is a proxy request or not. This value is generally set in
|
||
the post_read_request/translate_name phase of a request.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>range</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The contents of the <code>Range:</code> header.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>remaining</code></td>
|
||
<td>number</td>
|
||
<td>no</td>
|
||
<td>The number of bytes remaining to be read from the request body.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>server_built</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The time the server executable was built.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>server_name</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The server name for this request.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>some_auth_required</code></td>
|
||
<td>boolean</td>
|
||
<td>no</td>
|
||
<td>Whether some authorization is/was required for this request.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>subprocess_env</code></td>
|
||
<td>table</td>
|
||
<td>yes</td>
|
||
<td>The environment variables set for this request.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>started</code></td>
|
||
<td>number</td>
|
||
<td>no</td>
|
||
<td>The time the server was (re)started, in seconds since the epoch (Jan 1st, 1970)</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>status</code></td>
|
||
<td>number</td>
|
||
<td>yes</td>
|
||
<td>The (current) HTTP return code for this request, f.x. <code>200</code> or <code>404</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>the_request</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The request string as sent by the client, f.x. <code>GET /foo/bar HTTP/1.1</code>.</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>unparsed_uri</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The unparsed URI of the request</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>uri</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>The URI after it has been parsed by httpd</td>
|
||
</tr>
|
||
<tr class="odd">
|
||
<td><code>user</code></td>
|
||
<td>string</td>
|
||
<td>yes</td>
|
||
<td>If an authentication check has been made, this is set to the name of the authenticated user.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>useragent_ip</code></td>
|
||
<td>string</td>
|
||
<td>no</td>
|
||
<td>The IP of the user agent making the request</td>
|
||
</tr>
|
||
</table>
|
||
</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="functions" id="functions">Built in functions</a></h2>
|
||
|
||
<p>The request_rec object has (at least) the following methods:</p>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:flush() -- flushes the output buffer.
|
||
-- Returns true if the flush was successful, false otherwise.
|
||
|
||
while we_have_stuff_to_send do
|
||
r:puts("Bla bla bla\n") -- print something to client
|
||
r:flush() -- flush the buffer (send to client)
|
||
r.usleep(500000) -- fake processing time for 0.5 sec. and repeat
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:addoutputfilter(name|function) -- add an output filter:
|
||
|
||
r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
|
||
|
||
if use_sendfile_thing then
|
||
r:sendfile("/var/www/large_file.img")
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:parseargs() -- returns two tables; one standard key/value table for regular GET data,
|
||
-- and one for multi-value data (fx. foo=1&foo=2&foo=3):
|
||
|
||
local GET, GETMULTI = r:parseargs()
|
||
r:puts("Your name is: " .. GET['name'] or "Unknown")
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
|
||
-- just like r:parseargs().
|
||
-- An optional number may be passed to specify the maximum number
|
||
-- of bytes to parse. Default is 8192 bytes:
|
||
|
||
local POST, POSTMULTI = r:parsebody(1024*1024)
|
||
r:puts("Your name is: " .. POST['name'] or "Unknown")
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:puts("hello", " world", "!") -- print to response body, self explanatory
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:write("a single string") -- print to response body, self explanatory
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
|
||
|
||
local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:base64_decode(string) -- Decodes a Base64-encoded string:
|
||
|
||
local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
|
||
|
||
local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
|
||
|
||
local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:escape(string) -- URL-Escapes a string:
|
||
|
||
local url = "http://foo.bar/1 2 3 & 4 + 5"
|
||
local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:unescape(string) -- Unescapes an URL-escaped string:
|
||
|
||
local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
|
||
local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5'
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:construct_url(string) -- Constructs an URL from an URI
|
||
|
||
local url = r:construct_url(r.uri)
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
|
||
|
||
local mpm = r.mpm_query(14)
|
||
if mpm == 1 then
|
||
r:puts("This server uses the Event MPM")
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
|
||
|
||
if r:expr("%{HTTP_HOST} =~ /^www/") then
|
||
r:puts("This host name starts with www")
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
|
||
|
||
local process = r:scoreboard_process(1)
|
||
r:puts("Server 1 has PID " .. process.pid)
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
|
||
|
||
local thread = r:scoreboard_worker(1, 1)
|
||
r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")
|
||
</pre>
|
||
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:clock() -- Returns the current time with microsecond precision
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:requestbody(filename) -- Reads and returns the request body of a request.
|
||
-- If 'filename' is specified, it instead saves the
|
||
-- contents to that file:
|
||
|
||
local input = r:requestbody()
|
||
r:puts("You sent the following request body to me:\n")
|
||
r:puts(input)
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r.module_info(module_name) -- Queries the server for information about a module
|
||
|
||
local mod = r.module_info("mod_lua.c")
|
||
if mod then
|
||
for k, v in pairs(mod.commands) do
|
||
r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:loaded_modules() -- Returns a list of modules loaded by httpd:
|
||
|
||
for k, module in pairs(r:loaded_modules()) do
|
||
r:puts("I have loaded module " .. module .. "\n")
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
|
||
-- relative to the appropriate run-time directory.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:server_info() -- Returns a table containing server information, such as
|
||
-- the name of the httpd executable file, mpm used etc.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:set_document_root(file_path) -- Sets the document root for the request to file_path
|
||
</pre>
|
||
|
||
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:escape_logitem(string) -- Escapes a string for logging
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r.strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
|
||
-- fx. whether 'www.example.com' matches '*.example.com':
|
||
|
||
local match = r.strcmp_match("foobar.com", "foo*.com")
|
||
if match then
|
||
r:puts("foobar.com matches foo*.com")
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:make_etag() -- Constructs and returns the etag for the current request.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
|
||
-- if 'clear' is true, available headers will be sent and cleared.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
|
||
-- This works much like the ErrorDocument directive:
|
||
|
||
r:custom_response(404, "Baleted!")
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r.exists_config_define(string) -- Checks whether a configuration definition exists or not:
|
||
|
||
if r.exists_config_define("FOO") then
|
||
r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:state_query(string) -- Queries the server for state information
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:stat(filename [,wanted]) -- Runs stat() on a file, and returns a table with file information:
|
||
|
||
local info = r:stat("/var/www/foo.txt")
|
||
if info then
|
||
r:puts("This file exists and was last modified at: " .. info.modified)
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:regex(string, pattern [,flags]) -- Runs a regular expression match on a string, returning captures if matched:
|
||
|
||
local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
|
||
if matches then
|
||
r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
|
||
end
|
||
|
||
-- Example ignoring case sensitivity:
|
||
local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
|
||
|
||
-- Flags can be a bitwise combination of:
|
||
-- 0x01: Ignore case
|
||
-- 0x02: Multiline search
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
|
||
-- See '<a href="#databases">Database connectivity</a>' for details.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:ivm_set("key", value) -- Set an Inter-VM variable to hold a specific value.
|
||
-- These values persist even though the VM is gone or not being used,
|
||
-- and so should only be used if MaxConnectionsPerChild is > 0
|
||
-- Values can be numbers, strings and booleans, and are stored on a
|
||
-- per process basis (so they won't do much good with a prefork mpm)
|
||
|
||
r:ivm_get("key") -- Fetches a variable set by ivm_set. Returns the contents of the variable
|
||
-- if it exists or nil if no such variable exists.
|
||
|
||
-- An example getter/setter that saves a global variable outside the VM:
|
||
function handle(r)
|
||
-- First VM to call this will get no value, and will have to create it
|
||
local foo = r:ivm_get("cached_data")
|
||
if not foo then
|
||
foo = do_some_calcs() -- fake some return value
|
||
r:ivm_set("cached_data", foo) -- set it globally
|
||
end
|
||
r:puts("Cached data is: ", foo)
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:htpassword(string [,algorithm [,cost]]) -- Creates a password hash from a string.
|
||
-- algorithm: 0 = APMD5 (default), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
|
||
-- cost: only valid with BCRYPT algorithm (default = 5).
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode paramter.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode paramter.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:rmdir(dir) -- Removes a directory.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:get_direntries(dir) -- Returns a table with all directory entries.
|
||
|
||
function handle(r)
|
||
local dir = r.context_document_root
|
||
for _, f in ipairs(r:get_direntries(dir)) do
|
||
local info = r:stat(dir .. "/" .. f)
|
||
if info then
|
||
local mtime = os.date(fmt, info.mtime / 1000000)
|
||
local ftype = (info.filetype == 2) and "[dir] " or "[file]"
|
||
r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
|
||
end
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:getcookie(key) -- Gets a HTTP cookie
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:setcookie(key, value, secure, expires) -- Sets a HTTP cookie, for instance:
|
||
r:setcookie("foo", "bar and stuff", false, os.time() + 86400)
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:wsupgrade() -- Upgrades a connection to WebSockets if possible (and requested):
|
||
if r:wsupgrade() then -- if we can upgrade:
|
||
r:wswrite("Welcome to websockets!") -- write something to the client
|
||
r:wsclose() -- goodbye!
|
||
end
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:wsread() -- Reads a WebSocket frame from a WebSocket upgraded connection (see above):
|
||
|
||
local line, isFinal = r:wsread() -- isFinal denotes whether this is the final frame.
|
||
-- If it isn't, then more frames can be read
|
||
r:wswrite("You wrote: " .. line)
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:wswrite(line) -- Writes a frame to a WebSocket client:
|
||
r:wswrite("Hello, world!")
|
||
</pre>
|
||
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
r:wsclose() -- Closes a WebSocket request and terminates it for httpd:
|
||
|
||
if r:wsupgrade() then
|
||
r:wswrite("Write something: ")
|
||
local line = r:wsread() or "nothing"
|
||
r:wswrite("You wrote: " .. line);
|
||
r:wswrite("Goodbye!")
|
||
r:wsclose()
|
||
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="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 a notice log message")<br />
|
||
r:warn("This is a 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 a 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>
|
||
<dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>
|
||
<dd>internal constants used by <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</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="section">
|
||
<h2><a name="modifying_buckets" id="modifying_buckets">Modifying contents with Lua filters</a></h2>
|
||
|
||
<p>
|
||
Filter functions implemented via <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code>
|
||
or <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> are designed as
|
||
three-stage non-blocking functions using coroutines to suspend and resume a
|
||
function as buckets are sent down the filter chain. The core structure of
|
||
such a function is:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
function filter(r)
|
||
-- Our first yield is to signal that we are ready to receive buckets.
|
||
-- Before this yield, we can set up our environment, check for conditions,
|
||
-- and, if we deem it necessary, decline filtering a request alltogether:
|
||
if something_bad then
|
||
return -- This would skip this filter.
|
||
end
|
||
-- Regardless of whether we have data to prepend, a yield MUST be called here.
|
||
-- Note that only output filters can prepend data. Input filters must use the
|
||
-- final stage to append data to the content.
|
||
coroutine.yield([optional header to be prepended to the content])
|
||
|
||
-- After we have yielded, buckets will be sent to us, one by one, and we can
|
||
-- do whatever we want with them and then pass on the result.
|
||
-- Buckets are stored in the global variable 'bucket', so we create a loop
|
||
-- that checks if 'bucket' is not nil:
|
||
while bucket ~= nil do
|
||
local output = mangle(bucket) -- Do some stuff to the content
|
||
coroutine.yield(output) -- Return our new content to the filter chain
|
||
end
|
||
|
||
-- Once the buckets are gone, 'bucket' is set to nil, which will exit the
|
||
-- loop and land us here. Anything extra we want to append to the content
|
||
-- can be done by doing a final yield here. Both input and output filters
|
||
-- can append data to the content in this phase.
|
||
coroutine.yield([optional footer to be appended to the content])
|
||
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="databases" id="databases">Database connectivity</a></h2>
|
||
|
||
<p>
|
||
Mod_lua implements a simple database feature for querying and running commands
|
||
on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle)
|
||
as well as mod_dbd.
|
||
</p>
|
||
<p>The example below shows how to acquire a database handle and return information from a table:</p>
|
||
<pre class="prettyprint lang-lua">
|
||
function handle(r)
|
||
-- Acquire a database handle
|
||
local database, err = r:dbacquire("mysql", "server=localhost,user=root,dbname=mydb")
|
||
if not err then
|
||
-- Select some information from it
|
||
local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
|
||
if not err then
|
||
local rows = results(0) -- fetch all rows synchronously
|
||
for k, row in pairs(rows) do
|
||
r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
|
||
end
|
||
else
|
||
r:puts("Database query error: " .. err)
|
||
end
|
||
database:close()
|
||
else
|
||
r:puts("Could not connect to the database: " .. err)
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
<p>
|
||
To utilize <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, specify <code>mod_dbd</code>
|
||
as the database type, or leave the field blank:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
local database = r:dbacquire("mod_dbd")
|
||
</pre>
|
||
|
||
<h3><a name="database_object" id="database_object">Database object and contained functions</a></h3>
|
||
|
||
<p>The database object returned by <code>dbacquire</code> has the following methods:</p>
|
||
<p><strong>Normal select and query from a database:</strong></p>
|
||
<pre class="prettyprint lang-lua">
|
||
-- Run a statement and return the number of rows affected:
|
||
local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
|
||
|
||
-- Run a statement and return a result set that can be used synchronously or async:
|
||
local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")
|
||
</pre>
|
||
|
||
<p><strong>Using prepared statements (recommended):</strong></p>
|
||
<pre class="prettyprint lang-lua">
|
||
-- Create and run a prepared statement:
|
||
local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
|
||
if not errmsg then
|
||
local result, errmsg = statement:query(20) -- run the statement with age > 20
|
||
end
|
||
|
||
-- Fetch a prepared statement from a DBDPrepareSQL directive:
|
||
local statement, errmsg = database:prepared(r, "someTag")
|
||
if not errmsg then
|
||
local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
|
||
end
|
||
|
||
</pre>
|
||
|
||
<p><strong>Escaping values, closing databases etc:</strong></p>
|
||
<pre class="prettyprint lang-lua">
|
||
-- Escape a value for use in a statement:
|
||
local escaped = database:escape(r, [["'|blabla]])
|
||
|
||
-- Close a database connection and free up handles:
|
||
database:close()
|
||
|
||
-- Check whether a database connection is up and running:
|
||
local connected = database:active()
|
||
</pre>
|
||
|
||
|
||
<h3><a name="result_sets" id="result_sets">Working with result sets</a></h3>
|
||
|
||
<p>The result set returned by <code>db:select</code> or by the prepared statement functions
|
||
created through <code>db:prepare</code> can be used to
|
||
fetch rows synchronously or asynchronously, depending on the row number specified:<br />
|
||
<code>result(0)</code> fetches all rows in a synchronous manner, returning a table of rows.<br />
|
||
<code>result(-1)</code> fetches the next available row in the set, asynchronously.<br />
|
||
<code>result(N)</code> fetches row number <code>N</code>, asynchronously:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
-- fetch a result set using a regular query:
|
||
local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
|
||
|
||
local rows = result(0) -- Fetch ALL rows synchronously
|
||
local row = result(-1) -- Fetch the next available row, asynchronously
|
||
local row = result(1234) -- Fetch row number 1234, asynchronously
|
||
</pre>
|
||
|
||
<p>One can construct a function that returns an iterative function to iterate over all rows
|
||
in a synchronous or asynchronous way, depending on the async argument:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
function rows(resultset, async)
|
||
local a = 0
|
||
local function getnext()
|
||
a = a + 1
|
||
local row = resultset(-1)
|
||
return row and a or nil, row
|
||
end
|
||
if not async then
|
||
return pairs(resultset(0))
|
||
else
|
||
return getnext, self
|
||
end
|
||
end
|
||
|
||
local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u")
|
||
if not err then
|
||
-- fetch rows asynchronously:
|
||
local result, err = statement:select(20)
|
||
if not err then
|
||
for index, row in rows(result, true) do
|
||
....
|
||
end
|
||
end
|
||
|
||
-- fetch rows synchronously:
|
||
local result, err = statement:select(20)
|
||
if not err then
|
||
for index, row in rows(result, false) do
|
||
....
|
||
end
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
|
||
<h3><a name="closing_databases" id="closing_databases">Closing a database connection</a></h3>
|
||
|
||
|
||
<p>Database handles should be closed using <code>database:close()</code> when they are no longer
|
||
needed. If you do not close them manually, they will eventually be garbage collected and
|
||
closed by mod_lua, but you may end up having too many unused connections to the database
|
||
if you leave the closing up to mod_lua. Essentially, the following two measures are
|
||
the same:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
-- Method 1: Manually close a handle
|
||
local database = r:dbacquire("mod_dbd")
|
||
database:close() -- All done
|
||
|
||
-- Method 2: Letting the garbage collector close it
|
||
local database = r:dbacquire("mod_dbd")
|
||
database = nil -- throw away the reference
|
||
collectgarbage() -- close the handle via GC
|
||
</pre>
|
||
|
||
|
||
<h3><a name="database_caveat" id="database_caveat">Precautions when working with databases</a></h3>
|
||
|
||
<p>Although the standard <code>query</code> and <code>run</code> functions are freely
|
||
available, it is recommended that you use prepared statements whenever possible, to
|
||
both optimize performance (if your db handle lives on for a long time) and to minimize
|
||
the risk of SQL injection attacks. <code>run</code> and <code>query</code> should only
|
||
be used when there are no variables inserted into a statement (a static statement).
|
||
When using dynamic statements, use <code>db:prepare</code> or <code>db:prepared</code>.
|
||
</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="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a> <a name="luaauthzprovider" id="luaauthzprovider">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
|
||
</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</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.3 and later</td></tr>
|
||
</table>
|
||
<p>After a lua function has been registered as authorization provider, it can be used
|
||
with the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive:</p>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
LuaRoot /usr/local/apache2/lua
|
||
LuaAuthzProvider foo authz.lua authz_check_foo
|
||
<Location />
|
||
Require foo johndoe
|
||
</Location>
|
||
</pre>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
require "apache2"
|
||
function authz_check_foo(r, who)
|
||
if r.user ~= who then return apache2.AUTHZ_DENIED
|
||
return apache2.AUTHZ_GRANTED
|
||
end
|
||
</pre>
|
||
|
||
|
||
|
||
|
||
</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 a 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="LuaHookLog" id="LuaHookLog">LuaHookLog</a> <a name="luahooklog" id="luahooklog">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access log phase of a request
|
||
processing</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookLog /path/to/lua/script.lua log_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 simple logging hook allows you to run a function when httpd enters the
|
||
logging phase of a request. With it, you can append data to your own logs,
|
||
manipulate data before the regular log is written, or prevent a log entry
|
||
from being created. To prevent the usual logging from happening, simply return
|
||
<code>apache2.DONE</code> in your logging handler, otherwise return
|
||
<code>apache2.OK</code> to tell httpd to log as normal.
|
||
</p>
|
||
<p>Example:</p>
|
||
<pre class="prettyprint lang-config">
|
||
LuaHookLog /path/to/script.lua logger
|
||
</pre>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
-- /path/to/script.lua --
|
||
function logger(r)
|
||
-- flip a coin:
|
||
-- If 1, then we write to our own Lua log and tell httpd not to log
|
||
-- in the main log.
|
||
-- If 2, then we just sanitize the output a bit and tell httpd to
|
||
-- log the sanitized bits.
|
||
|
||
if math.random(1,2) == 1 then
|
||
-- Log stuff ourselves and don't log in the regular log
|
||
local f = io.open("/foo/secret.log", "a")
|
||
if f then
|
||
f:write("Something secret happened at " .. r.uri .. "\n")
|
||
f:close()
|
||
end
|
||
return apache2.DONE -- Tell httpd not to use the regular logging functions
|
||
else
|
||
r.uri = r.uri:gsub("somesecretstuff", "") -- sanitize the URI
|
||
return apache2.OK -- tell httpd to log it.
|
||
end
|
||
end
|
||
</pre>
|
||
|
||
|
||
</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>Like <code class="directive">LuaHookTranslateName</code> but executed at the
|
||
map-to-storage phase of a request. Modules like mod_cache run at this phase,
|
||
which makes for an interesting example on what to do here:</p>
|
||
<pre class="prettyprint lang-config">
|
||
LuaHookMapToStorage /path/to/lua/script.lua check_cache
|
||
</pre>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
require"apache2"
|
||
cached_files = {}
|
||
|
||
function read_file(filename)
|
||
local input = io.open(filename, "r")
|
||
if input then
|
||
local data = input:read("*a")
|
||
cached_files[filename] = data
|
||
file = cached_files[filename]
|
||
input:close()
|
||
end
|
||
return cached_files[filename]
|
||
end
|
||
|
||
function check_cache(r)
|
||
if r.filename:match("%.png$") then -- Only match PNG files
|
||
local file = cached_files[r.filename] -- Check cache entries
|
||
if not file then
|
||
file = read_file(r.filename) -- Read file into cache
|
||
end
|
||
if file then -- If file exists, write it out
|
||
r.status = 200
|
||
r:write(file)
|
||
r:info(("Sent %s to client from cache"):format(r.filename))
|
||
return apache2.DONE -- skip default handler for PNG files
|
||
end
|
||
end
|
||
return apache2.DECLINED -- If we had nothing to do, let others serve this.
|
||
end
|
||
</pre>
|
||
|
||
|
||
|
||
</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</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>
|
||
This directive provides a hook for the type_checker phase of the request processing.
|
||
This phase is where requests are assigned a content type and a handler, and thus can
|
||
be used to modify the type and handler based on input:
|
||
</p>
|
||
<pre class="prettyprint lang-config">
|
||
LuaHookTypeChecker /path/to/lua/script.lua type_checker
|
||
</pre>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
function type_checker(r)
|
||
if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
|
||
r.content_type = "image/gif" -- assign it the image/gif type
|
||
r.handler = "gifWizard" -- tell the gifWizard module to handle this
|
||
r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested
|
||
return apache2.OK
|
||
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="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="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a> <a name="luainputfilter" id="luainputfilter">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content input filtering</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</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.5.0 and later</td></tr>
|
||
</table>
|
||
<p>Provides a means of adding a Lua function as an input filter.
|
||
As with output filters, input filters work as coroutines,
|
||
first yielding before buffers are sent, then yielding whenever
|
||
a bucket needs to be passed down the chain, and finally (optionally)
|
||
yielding anything that needs to be appended to the input data. The
|
||
global variable <code>bucket</code> holds the buckets as they are passed
|
||
onto the Lua script:
|
||
</p>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
LuaInputFilter myInputFilter /www/filter.lua input_filter
|
||
<FilesMatch "\.lua>
|
||
SetInputFilter myInputFilter
|
||
</FilesMatch>
|
||
</pre>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
--[[
|
||
Example input filter that converts all POST data to uppercase.
|
||
]]--
|
||
function input_filter(r)
|
||
print("luaInputFilter called") -- debug print
|
||
coroutine.yield() -- Yield and wait for buckets
|
||
while bucket do -- For each bucket, do...
|
||
local output = string.upper(bucket) -- Convert all POST data to uppercase
|
||
coroutine.yield(output) -- Send converted data down the chain
|
||
end
|
||
-- No more buckets available.
|
||
coroutine.yield("&filterSignature=1234") -- Append signature at the end
|
||
end
|
||
</pre>
|
||
|
||
<p>
|
||
The input filter supports denying/skipping a filter if it is deemed unwanted:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
function input_filter(r)
|
||
if not good then
|
||
return -- Simply deny filtering, passing on the original content instead
|
||
end
|
||
coroutine.yield() -- wait for buckets
|
||
... -- insert filter stuff here
|
||
end
|
||
</pre>
|
||
|
||
<p>
|
||
See "<a href="#modifying_buckets">Modifying contents with Lua
|
||
filters</a>" for more information.
|
||
</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="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a> <a name="luaoutputfilter" id="luaoutputfilter">Directive</a></h2>
|
||
<table class="directive">
|
||
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content output filtering</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</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.5.0 and later</td></tr>
|
||
</table>
|
||
<p>Provides a means of adding a Lua function as an output filter.
|
||
As with input filters, output filters work as coroutines,
|
||
first yielding before buffers are sent, then yielding whenever
|
||
a bucket needs to be passed down the chain, and finally (optionally)
|
||
yielding anything that needs to be appended to the input data. The
|
||
global variable <code>bucket</code> holds the buckets as they are passed
|
||
onto the Lua script:
|
||
</p>
|
||
|
||
<pre class="prettyprint lang-config">
|
||
LuaOutputFilter myOutputFilter /www/filter.lua output_filter
|
||
<FilesMatch "\.lua>
|
||
SetOutputFilter myOutputFilter
|
||
</FilesMatch>
|
||
</pre>
|
||
|
||
<pre class="prettyprint lang-lua">
|
||
--[[
|
||
Example output filter that escapes all HTML entities in the output
|
||
]]--
|
||
function output_filter(r)
|
||
coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Prepend some data to the output,
|
||
-- yield and wait for buckets.
|
||
while bucket do -- For each bucket, do...
|
||
local output = r:escape_html(bucket) -- Escape all output
|
||
coroutine.yield(output) -- Send converted data down the chain
|
||
end
|
||
-- No more buckets available.
|
||
end
|
||
</pre>
|
||
|
||
<p>
|
||
As with the input filter, the output filter supports denying/skipping a filter
|
||
if it is deemed unwanted:
|
||
</p>
|
||
<pre class="prettyprint lang-lua">
|
||
function output_filter(r)
|
||
if not r.content_type:match("text/html") then
|
||
return -- Simply deny filtering, passing on the original content instead
|
||
end
|
||
coroutine.yield() -- wait for buckets
|
||
... -- insert filter stuff here
|
||
end
|
||
</pre>
|
||
|
||
<div class="note"><h3>Lua filters with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3>
|
||
<p> When a Lua filter is used as the underlying provider via the
|
||
<code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code> directive, filtering
|
||
will only work when the <var>filter-name</var> is identical to the <var>provider-name</var>.
|
||
</p> </div>
|
||
|
||
<p>
|
||
See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more
|
||
information.
|
||
</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>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr>
|
||
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</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 phase is run immediately after the request has been mapped to a virtal host,
|
||
and can be used to either do some request processing before the other phases kick
|
||
in, or to serve a request without the need to translate, map to storage et cetera.
|
||
As this phase is run before anything else, directives such as <code class="directive"><a href="../mod/core.html#location"><Location></a></code> or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> are void in this phase, just as
|
||
URIs have not been properly parsed yet.
|
||
</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, thread -- default is once</td></tr>
|
||
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread|server [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 life cycle 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>thread:</dt> <dd>Use the interpreter for the lifetime of the thread
|
||
handling the request (only available with threaded MPMs).</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 Lua states are stored in an apr
|
||
resource list. The <code>min</code> and <code>max</code> arguments
|
||
specify the minimum and maximum number of Lua states to keep in the
|
||
pool.</dd>
|
||
</dl>
|
||
<p>
|
||
Generally speaking, the <code>thread</code> and <code>server</code> scopes
|
||
execute roughly 2-3 times faster than the rest, because they don't have to
|
||
spawn new Lua states on every request (especially with the event MPM, as
|
||
even keepalive requests will use a new thread for each request). If you are
|
||
satisfied that your scripts will not have problems reusing a state, then
|
||
the <code>thread</code> or <code>server</code> scopes should be used for
|
||
maximum performance. While the <code>thread</code> scope will provide the
|
||
fastest responses, the <code>server</code> scope will use less memory, as
|
||
states are pooled, allowing f.x. 1000 threads to share only 100 Lua states,
|
||
thus using only 10% of the memory required by the <code>thread</code> scope.
|
||
</p>
|
||
|
||
</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<61>ais"> fr </a></p>
|
||
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
|
||
<script type="text/javascript"><!--//--><![CDATA[//><!--
|
||
var comments_shortname = 'httpd';
|
||
var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_lua.html';
|
||
(function(w, d) {
|
||
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
|
||
d.write('<div id="comments_thread"><\/div>');
|
||
var s = d.createElement('script');
|
||
s.type = 'text/javascript';
|
||
s.async = true;
|
||
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
|
||
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
|
||
}
|
||
else {
|
||
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
|
||
}
|
||
})(window, document);
|
||
//--><!]]></script></div><div id="footer">
|
||
<p class="apache">Copyright 2013 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/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/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> |