mod_lua.html.en revision b1962de8ac685112689b70f4a31f7c8b392aa634
2c786597c67139f4536078aee9c5ef08378908c2nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2c786597c67139f4536078aee9c5ef08378908c2nd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
2c786597c67139f4536078aee9c5ef08378908c2nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
2c786597c67139f4536078aee9c5ef08378908c2nd This file is generated from xml source: DO NOT EDIT
2c786597c67139f4536078aee9c5ef08378908c2nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
2c786597c67139f4536078aee9c5ef08378908c2nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
2c786597c67139f4536078aee9c5ef08378908c2nd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
2c786597c67139f4536078aee9c5ef08378908c2nd<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" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.js" type="text/javascript">
2c786597c67139f4536078aee9c5ef08378908c2nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
2c786597c67139f4536078aee9c5ef08378908c2nd<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<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>
2c786597c67139f4536078aee9c5ef08378908c2nd<p><span>Available Languages: </span><a href="/en/mod/mod_lua.html" title="English"> en </a> |
2c786597c67139f4536078aee9c5ef08378908c2nd<a href="/fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
2c786597c67139f4536078aee9c5ef08378908c2nd<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides Lua hooks into various portions of the httpd
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>lua_module</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_lua.c</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>2.3 and later</td></tr></table>
2c786597c67139f4536078aee9c5ef08378908c2nd<p>This module allows the server to be extended with scripts written in the
2c786597c67139f4536078aee9c5ef08378908c2ndLua programming language. The extension points (hooks) available with
2c786597c67139f4536078aee9c5ef08378908c2nd<code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> include many of the hooks available to
2c786597c67139f4536078aee9c5ef08378908c2ndnatively compiled Apache HTTP Server modules, such as mapping requests to
2c786597c67139f4536078aee9c5ef08378908c2ndfiles, generating dynamic responses, access control, authentication, and
6e78b54cb721beced83b8b775ee142ae9fbfaa38ndauthorization</p>
2c786597c67139f4536078aee9c5ef08378908c2nd<p>More information on the Lua programming language can be found at the
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="note"><code>mod_lua</code> is still in experimental state.
2c786597c67139f4536078aee9c5ef08378908c2ndUntil it is declared stable, usage and behavior may change
2c786597c67139f4536078aee9c5ef08378908c2ndat any time, even between stable releases of the 2.4.x series.
6c4ef4a72d9897e53365b94103f4bd819fd0d3acndBe sure to check the CHANGES file before upgrading.</div>
2c786597c67139f4536078aee9c5ef08378908c2nd<p>This module holds a great deal of power over httpd, which is both a
2c786597c67139f4536078aee9c5ef08378908c2ndstrength and a potential security risk. It is <strong>not</strong> recommended
2c786597c67139f4536078aee9c5ef08378908c2ndthat you use this module on a server that is shared with users you do not
2c786597c67139f4536078aee9c5ef08378908c2ndtrust, as it can be abused to change the internal workings of httpd.</p>
2c786597c67139f4536078aee9c5ef08378908c2nd<div id="quickview"><h3 class="directives">Directives</h3>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahookfixups">LuaHookFixups</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahookinsertfilter">LuaHookInsertFilter</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahookmaptostorage">LuaHookMapToStorage</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahooktranslatename">LuaHookTranslateName</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luahooktypechecker">LuaHookTypeChecker</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luainherit">LuaInherit</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luaroot">LuaRoot</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#luascope">LuaScope</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#basicconf">Basic Configuration</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#writinghandlers">Writing Handlers</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#writingauthzproviders">Writing Authorization Providers</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#writinghooks">Writing Hooks</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#datastructures">Data Structures</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#logging">Logging Functions</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd<li><img alt="" src="/images/down.gif" /> <a href="#apache2">apache2 Package</a></li>
2c786597c67139f4536078aee9c5ef08378908c2nd</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<code>mod_lua</code> provides a handler named <code>lua-script</code>,
2c786597c67139f4536078aee9c5ef08378908c2ndwhich can be used with an <code>AddHandler</code> directive:</p>
2c786597c67139f4536078aee9c5ef08378908c2ndAddHandler lua-script .lua
2c786597c67139f4536078aee9c5ef08378908c2ndThis will cause <code>mod_lua</code> to handle requests for files
1723928efa40774afc394d9e6b2b974c1f49330dnd<p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
2c786597c67139f4536078aee9c5ef08378908c2nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<p> In the Apache HTTP Server API, the handler is a specific kind of hook
2c786597c67139f4536078aee9c5ef08378908c2ndresponsible for generating the response. Examples of modules that include a
2c786597c67139f4536078aee9c5ef08378908c2ndhandler 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>,
2c786597c67139f4536078aee9c5ef08378908c2ndand <code class="module"><a href="/mod/mod_status.html">mod_status</a></code>.</p>
2c786597c67139f4536078aee9c5ef08378908c2nd<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
2c786597c67139f4536078aee9c5ef08378908c2ndjust evaluating a script body CGI style. A handler function looks
2c786597c67139f4536078aee9c5ef08378908c2ndsomething like this:</p>
2c786597c67139f4536078aee9c5ef08378908c2nd-- example handler
2c786597c67139f4536078aee9c5ef08378908c2ndrequire "string"
2c786597c67139f4536078aee9c5ef08378908c2nd This is the default method name for Lua handlers, see the optional
2c786597c67139f4536078aee9c5ef08378908c2nd function-name in the LuaMapHandler directive to choose a different
2c786597c67139f4536078aee9c5ef08378908c2nd entry point.
2c786597c67139f4536078aee9c5ef08378908c2ndfunction handle(r)
2c786597c67139f4536078aee9c5ef08378908c2nd r:puts("Hello Lua World!\n")
2c786597c67139f4536078aee9c5ef08378908c2nd if r.method == 'GET' then
2c786597c67139f4536078aee9c5ef08378908c2nd for k, v in pairs( r:parseargs() ) do
2c786597c67139f4536078aee9c5ef08378908c2nd r:puts( string.format("%s: %s\n", k, v) )
2c786597c67139f4536078aee9c5ef08378908c2nd elseif r.method == 'POST' then
2c786597c67139f4536078aee9c5ef08378908c2nd for k, v in pairs( r:parsebody() ) do
2c786597c67139f4536078aee9c5ef08378908c2nd r:puts( string.format("%s: %s\n", k, v) )
2c786597c67139f4536078aee9c5ef08378908c2nd r:puts("Unsupported HTTP method " .. r.method)
2c786597c67139f4536078aee9c5ef08378908c2ndThis handler function just prints out the uri or form encoded
acf65805923cf80834c39689cc0e2a8e7201c186sfarguments to a plaintext page.
acf65805923cf80834c39689cc0e2a8e7201c186sfThis means (and in fact encourages) that you can have multiple
2c786597c67139f4536078aee9c5ef08378908c2ndhandlers (or hooks, or filters) in the same script.
acf65805923cf80834c39689cc0e2a8e7201c186sf</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
acf65805923cf80834c39689cc0e2a8e7201c186sf<h2><a name="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<p><code class="module"><a href="/mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to
acf65805923cf80834c39689cc0e2a8e7201c186sfauthorization that is much easier to use than using into the relevant
2c786597c67139f4536078aee9c5ef08378908c2ndhooks directly. The first argument to the
acf65805923cf80834c39689cc0e2a8e7201c186sf<code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> directive gives
2c786597c67139f4536078aee9c5ef08378908c2ndthe name of the responsible authorization provider. For any
acf65805923cf80834c39689cc0e2a8e7201c186sf<code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> line,
acf65805923cf80834c39689cc0e2a8e7201c186sf<code class="module"><a href="/mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider
acf65805923cf80834c39689cc0e2a8e7201c186sfof the given name, passing the rest of the line as parameters. The
acf65805923cf80834c39689cc0e2a8e7201c186sfprovider will then check authorization and pass the result as return
acf65805923cf80834c39689cc0e2a8e7201c186sf<p>The authz provider is normally called before authentication. If it needs to
acf65805923cf80834c39689cc0e2a8e7201c186sfknow the authenticated user name (or if the user will be authenticated at
acf65805923cf80834c39689cc0e2a8e7201c186sfall), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
acf65805923cf80834c39689cc0e2a8e7201c186sfThis will cause authentication to proceed and the authz provider to be
acf65805923cf80834c39689cc0e2a8e7201c186sfcalled a second time.</p>
acf65805923cf80834c39689cc0e2a8e7201c186sf<p>The following authz provider function takes two arguments, one ip
acf65805923cf80834c39689cc0e2a8e7201c186sfaddress and one user name. It will allow access from the given ip address
acf65805923cf80834c39689cc0e2a8e7201c186sfwithout authentication, or if the authenticated user matches the second
acf65805923cf80834c39689cc0e2a8e7201c186sfargument:</p>
acf65805923cf80834c39689cc0e2a8e7201c186sfrequire 'apache2'
acf65805923cf80834c39689cc0e2a8e7201c186sffunction authz_check_foo(r, ip, user)
acf65805923cf80834c39689cc0e2a8e7201c186sf if r.useragent_ip == ip then
acf65805923cf80834c39689cc0e2a8e7201c186sf elseif r.user == nil then
2c786597c67139f4536078aee9c5ef08378908c2nd elseif r.user == user then
acf65805923cf80834c39689cc0e2a8e7201c186sf<p>The following configuration registers this function as provider
2c786597c67139f4536078aee9c5ef08378908c2nd<code>foo</code> and configures it for URL <code>/</code>:</p>
2c786597c67139f4536078aee9c5ef08378908c2ndLuaAuthzProvider foo authz_provider.lua authz_check_foo
acf65805923cf80834c39689cc0e2a8e7201c186sf<Location />
acf65805923cf80834c39689cc0e2a8e7201c186sf Require foo 10.1.2.3 john_doe
2c786597c67139f4536078aee9c5ef08378908c2nd</Location>
acf65805923cf80834c39689cc0e2a8e7201c186sf</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
acf65805923cf80834c39689cc0e2a8e7201c186sf<p>Hook functions are how modules (and Lua scripts) participate in the
2c786597c67139f4536078aee9c5ef08378908c2ndprocessing of requests. Each type of hook exposed by the server exists for
acf65805923cf80834c39689cc0e2a8e7201c186sfa specific purposes such as mapping requests to the filesystem,
acf65805923cf80834c39689cc0e2a8e7201c186sfperforming access control, or setting mimetypes. General purpose hooks
acf65805923cf80834c39689cc0e2a8e7201c186sfthat simply run at handy times in the request lifecycle exist as well.</p>
acf65805923cf80834c39689cc0e2a8e7201c186sf<p>Hook functions are passed the request object as their only argument.
acf65805923cf80834c39689cc0e2a8e7201c186sfThey can return any value, depending on the hook, but most commonly
acf65805923cf80834c39689cc0e2a8e7201c186sfthey'll return OK, DONE, or DECLINED, which you can write in lua as
2c786597c67139f4536078aee9c5ef08378908c2nd<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
65a611af7093423efb91e5794b8887a527d4cf63trawick-- example hook that rewrites the URI to a filesystem path.
acf65805923cf80834c39689cc0e2a8e7201c186sfrequire 'apache2'
2c786597c67139f4536078aee9c5ef08378908c2ndfunction translate_name(r)
acf65805923cf80834c39689cc0e2a8e7201c186sf if r.uri == "/translate-name" then
acf65805923cf80834c39689cc0e2a8e7201c186sf -- we don't care about this URL, give another module a chance
2c786597c67139f4536078aee9c5ef08378908c2nd--[[ example hook that rewrites one URI to another URI. It returns a
2c786597c67139f4536078aee9c5ef08378908c2nd apache2.DECLINED to give other URL mappers a chance to work on the
acf65805923cf80834c39689cc0e2a8e7201c186sf substitution, including the core translate_name hook which maps based
acf65805923cf80834c39689cc0e2a8e7201c186sf on the DocumentRoot.
acf65805923cf80834c39689cc0e2a8e7201c186sf Note: It is currently undefined as to whether this runs before or after
acf65805923cf80834c39689cc0e2a8e7201c186sf mod_alias.
acf65805923cf80834c39689cc0e2a8e7201c186sfrequire 'apache2'
2c786597c67139f4536078aee9c5ef08378908c2ndfunction translate_name(r)
acf65805923cf80834c39689cc0e2a8e7201c186sf if r.uri == "/translate-name" then
acf65805923cf80834c39689cc0e2a8e7201c186sf</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
acf65805923cf80834c39689cc0e2a8e7201c186sf<h2><a name="datastructures" id="datastructures">Data Structures</a></h2>
acf65805923cf80834c39689cc0e2a8e7201c186sf <p>The request_rec is mapped in as a userdata. It has a metatable
2c786597c67139f4536078aee9c5ef08378908c2nd which lets you do useful things with it. For the most part it
acf65805923cf80834c39689cc0e2a8e7201c186sf has the same fields as the request_rec struct (see httpd.h
acf65805923cf80834c39689cc0e2a8e7201c186sf until we get better docs here) many of which are writeable as
2c786597c67139f4536078aee9c5ef08378908c2nd well as readable. (The table fields' content can be changed, but the
acf65805923cf80834c39689cc0e2a8e7201c186sf fields themselves cannot be set to different tables.)</p>
2c786597c67139f4536078aee9c5ef08378908c2nd <p>The request_rec has (at least) the following methods:</p>
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:addoutputfilter(name|function) -- add an output filter
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:parseargs() -- returns a Lua table containing the request's query string arguments
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:parsebody() -- parse any POST data in the request and return it as a Lua table
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:puts("hello", " world", "!") -- print to response body
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:write("a single string") -- print to response body
2c786597c67139f4536078aee9c5ef08378908c2nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<h2><a name="logging" id="logging">Logging Functions</a></h2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick -- examples of logging messages<br />
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:debug("This is a debug log message")<br />
2c786597c67139f4536078aee9c5ef08378908c2nd r:info("This is an info log message")<br />
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:notice("This is an notice log message")<br />
2c786597c67139f4536078aee9c5ef08378908c2nd r:warn("This is an warn log message")<br />
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:err("This is an err log message")<br />
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:alert("This is an alert log message")<br />
c1621f589e6e26efc55db89e59c9f445580856cctrawick r:crit("This is an crit log message")<br />
2c786597c67139f4536078aee9c5ef08378908c2nd r:emerg("This is an emerg log message")<br />
01d52afd5ea497df24826737569291294d5dfa04rbowen</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<h2><a name="apache2" id="apache2">apache2 Package</a></h2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <dd>internal constant OK. Handlers should return this if they've
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar handled the request.</dd>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <dd>internal constant DECLINED. Handlers should return this if
c1621f589e6e26efc55db89e59c9f445580856cctrawick they are not going to handle the request.</dd>
2c786597c67139f4536078aee9c5ef08378908c2nd <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <dd>internal constants used by <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code></dd>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="directive-section"><h2><a name="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a> <a name="luaauthzprovider" id="luaauthzprovider">Directive</a></h2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<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>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<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>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.5.0 and later</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<p>After a lua function has been registered as authorization provider, it can be used
c1621f589e6e26efc55db89e59c9f445580856cctrawickwith the <code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> directive:</p>
2c786597c67139f4536078aee9c5ef08378908c2ndLuaAuthzProvider foo authz.lua authz_check_foo
c1621f589e6e26efc55db89e59c9f445580856cctrawick<Location />
2c786597c67139f4536078aee9c5ef08378908c2nd Require foo johndoe
c1621f589e6e26efc55db89e59c9f445580856cctrawick</Location>
c1621f589e6e26efc55db89e59c9f445580856cctrawickrequire "apache2"
c1621f589e6e26efc55db89e59c9f445580856cctrawickfunction authz_check_foo(r, who)
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick Specify the behavior of the in-memory code cache. The default
2c786597c67139f4536078aee9c5ef08378908c2nd is stat, which stats the top level script (not any included
c1621f589e6e26efc55db89e59c9f445580856cctrawick ones) each time that file is needed, and reloads it if the
c1621f589e6e26efc55db89e59c9f445580856cctrawick modified time indicates it is newer than the one it has
c1621f589e6e26efc55db89e59c9f445580856cctrawick already loaded. The other values cause it to keep the file
c1621f589e6e26efc55db89e59c9f445580856cctrawick cached forever (don't stat and replace) or to never cache the
2c786597c67139f4536078aee9c5ef08378908c2nd <p>In general stat or forever is good for production, and stat or never
c1621f589e6e26efc55db89e59c9f445580856cctrawick for development.</p>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
c1621f589e6e26efc55db89e59c9f445580856cctrawickLuaCodeCache stat
c1621f589e6e26efc55db89e59c9f445580856cctrawickLuaCodeCache forever
c1621f589e6e26efc55db89e59c9f445580856cctrawickLuaCodeCache never
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<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>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<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>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<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>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<p>Add your hook to the access_checker phase. An access checker
2c786597c67139f4536078aee9c5ef08378908c2ndhook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
2c786597c67139f4536078aee9c5ef08378908c2nd control when this script runs relative to other modules.</p></div>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<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>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<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>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
c1621f589e6e26efc55db89e59c9f445580856cctrawick<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1723928efa40774afc394d9e6b2b974c1f49330dnd<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>
1723928efa40774afc394d9e6b2b974c1f49330dnd<p>Invoke a lua function in the auth_checker phase of processing
1723928efa40774afc394d9e6b2b974c1f49330dnda request. This can be used to implement arbitrary authentication
2c786597c67139f4536078aee9c5ef08378908c2ndand authorization checking. A very simple example:
2c786597c67139f4536078aee9c5ef08378908c2ndrequire 'apache2'
1723928efa40774afc394d9e6b2b974c1f49330dnd-- fake authcheck hook
2c786597c67139f4536078aee9c5ef08378908c2nd-- If request has no auth info, set the response header and
1723928efa40774afc394d9e6b2b974c1f49330dnd-- return a 401 to ask the browser for basic auth info.
1723928efa40774afc394d9e6b2b974c1f49330dnd-- If request has auth info, don't actually look at it, just
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen-- pretend we got userid 'foo' and validated it.
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen-- Then check if the userid is 'foo' and accept the request.
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenfunction authcheck_hook(r)
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen -- look for auth info
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen auth = r.headers_in['Authorization']
2c786597c67139f4536078aee9c5ef08378908c2nd if auth ~= nil then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen -- fake the user
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if r.user == nil then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen r:debug("authcheck: user is nil, returning 401")
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen elseif r.user == "foo" then
2c786597c67139f4536078aee9c5ef08378908c2nd r:debug('user foo: OK')
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen r:debug("authcheck: user='" .. r.user .. "'")
63befe0983261d711e62457b380e24ecc3b7b79etrawick r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen control when this script runs relative to other modules.</p></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
2c786597c67139f4536078aee9c5ef08378908c2nd <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen control when this script runs relative to other modules.</p></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of a request
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen Just like LuaHookTranslateName, but executed at the fixups phase
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
2c786597c67139f4536078aee9c5ef08378908c2nd<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
2c786597c67139f4536078aee9c5ef08378908c2nd<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <p>Like <code class="directive">LuaHookTranslateName</code> but executed at the
2c786597c67139f4536078aee9c5ef08378908c2nd map-to-storage phase of a request. Modules like mod_cache run at this phase,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen which makes for an interesting example on what to do here:</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenrequire"apache2"
2c786597c67139f4536078aee9c5ef08378908c2ndcached_files = {}
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenfunction read_file(filename)
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen local input = io.open(filename, "r")
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if input then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen local data = input:read("*a")
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen cached_files[filename] = data
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen file = cached_files[filename]
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen input:close()
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen return cached_files[filename]
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenfunction check_cache(r)
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if r.filename:match("%.png$") then -- Only match PNG files
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen local file = cached_files[r.filename] -- Check cache entries
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if not file then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen file = read_file(r.filename) -- Read file into cache
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if file then -- If file exists, write it out
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen r:write(file)
2c786597c67139f4536078aee9c5ef08378908c2nd r:info(("Sent %s to client from cache"):format(r.filename))
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen return apache2.DONE -- skip default handler for PNG files
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen return apache2.DECLINED -- If we had nothing to do, let others serve this.
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
01d52afd5ea497df24826737569291294d5dfa04rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen request processing. The hook function receives a single
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen argument, the request_rec, and should return a status code,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen which is either an HTTP error code, or the constants defined
2c786597c67139f4536078aee9c5ef08378908c2nd <p>For those new to hooks, basically each hook will be invoked
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen until one of them returns apache2.OK. If your hook doesn't
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen want to do the translation it should just return
2c786597c67139f4536078aee9c5ef08378908c2nd apache2.DECLINED. If the request should stop processing, then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenrequire "apache2"
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenfunction silly_mapper(r)
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if r.uri == "/" then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <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
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
2c786597c67139f4536078aee9c5ef08378908c2nd control when this script runs relative to other modules.</p></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen This directive provides a hook for the type_checker phase of the request processing.
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen This phase is where requests are assigned a content type and a handler, and thus can
2c786597c67139f4536078aee9c5ef08378908c2nd be used to modify the type and handler based on input:
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen LuaHookTypeChecker /path/to/lua/script.lua type_checker
2c786597c67139f4536078aee9c5ef08378908c2nd function type_checker(r)
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
2c786597c67139f4536078aee9c5ef08378908c2nd r.content_type = "image/gif" -- assign it the image/gif type
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen r.handler = "gifWizard" -- tell the gifWizard module to handle this
2c786597c67139f4536078aee9c5ef08378908c2nd r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="directive-section"><h2><a name="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.0 and later</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen</table><p>By default, if LuaHook* directives are used in overlapping
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen Directory or Location configuration sections, the scripts defined in the
2c786597c67139f4536078aee9c5ef08378908c2nd more specific section are run <em>after</em> those defined in the more
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen generic section (LuaInherit parent-first). You can reverse this order, or
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen make the parent context not apply at all.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen directives from parent configuration sections.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
01d52afd5ea497df24826737569291294d5dfa04rbowen<div class="directive-section"><h2><a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <p>This directive matches a uri pattern to invoke a specific
2c786597c67139f4536078aee9c5ef08378908c2nd handler function in a specific file. It uses PCRE regular
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen expressions to match the uri, and supports interpolating
2c786597c67139f4536078aee9c5ef08378908c2nd match groups into both the file path and the function name
2c786597c67139f4536078aee9c5ef08378908c2nd be careful writing your regular expressions to avoid security
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen issues.</p>
2c786597c67139f4536078aee9c5ef08378908c2nd <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
2c786597c67139f4536078aee9c5ef08378908c2nd handler function handle_show on the lua vm after
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen loading that file.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <p>This would invoke the "handle" function, which
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen is the default if no specific function name is
2c786597c67139f4536078aee9c5ef08378908c2nd provided.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <p>Add a path to lua's shared library search path. Follows the same
2c786597c67139f4536078aee9c5ef08378908c2nd conventions as lua. This just munges the package.cpath in the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen lua vms.</p>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen</table><p>Add a path to lua's module search path. Follows the same
2c786597c67139f4536078aee9c5ef08378908c2nd conventions as lua. This just munges the package.path in the
2c786597c67139f4536078aee9c5ef08378908c2nd lua vms.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
2c786597c67139f4536078aee9c5ef08378908c2nd<div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <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
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <p>Specify the base path which will be used to evaluate all
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen relative paths within mod_lua. If not specified they
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen will be resolved relative to the current working directory,
2c786597c67139f4536078aee9c5ef08378908c2nd which may not always work well for a server.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn -- default is once</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread</code></td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
2c786597c67139f4536078aee9c5ef08378908c2nd <p>Specify the lifecycle scope of the Lua interpreter which will
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen be used by handlers in this "Directory." The default is "once"</p>
2c786597c67139f4536078aee9c5ef08378908c2nd <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
2c786597c67139f4536078aee9c5ef08378908c2nd <dt>request:</dt> <dd>use the interpreter to handle anything based on
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen the same file within this request, which is also
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen request scoped.</dd>
2c786597c67139f4536078aee9c5ef08378908c2nd <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen handling the request (only available with threaded MPMs).</dd>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<p><span>Available Languages: </span><a href="/en/mod/mod_lua.html" title="English"> en </a> |
2c786597c67139f4536078aee9c5ef08378908c2nd<a href="/fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen</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>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenvar comments_shortname = 'httpd';
2c786597c67139f4536078aee9c5ef08378908c2ndvar comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_lua.html';
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen(function(w, d) {
2c786597c67139f4536078aee9c5ef08378908c2nd if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen d.write('<div id="comments_thread"><\/div>');
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen var s = d.createElement('script');
2c786597c67139f4536078aee9c5ef08378908c2nd s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen})(window, document);
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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[//><!--
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenif (typeof(prettyPrint) !== 'undefined') {
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen prettyPrint();