1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>mod_lua - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
14 <div id="page-header">
15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
16 <p class="apache">Apache HTTP Server Version 2.5</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
20 <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>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_lua</h1>
24 <p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a></p>
26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides Lua hooks into various portions of the httpd
27 request processing</td></tr>
28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>lua_module</td></tr>
30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_lua.c</td></tr>
31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>2.3 and later</td></tr></table>
34 <p>This module allows the server to be extended with scripts written in the
35 Lua programming language. The extension points (hooks) available with
36 <code class="module"><a href="../mod/mod_lua.html">mod_lua</a></code> include many of the hooks available to
37 natively compiled Apache HTTP Server modules, such as mapping requests to
38 files, generating dynamic responses, access control, authentication, and
41 <p>More information on the Lua programming language can be found at the
42 <a href="http://www.lua.org/">the Lua website</a>.</p>
44 <div class="note"><code>mod_lua</code> is still in experimental state.
45 Until it is declared stable, usage and behavior may change
46 at any time, even between stable releases of the 2.4.x series.
47 Be sure to check the CHANGES file before upgrading.</div>
50 <div id="quickview"><h3 class="directives">Directives</h3>
52 <li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li>
53 <li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li>
54 <li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li>
55 <li><img alt="" src="../images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li>
56 <li><img alt="" src="../images/down.gif" /> <a href="#luahookfixups">LuaHookFixups</a></li>
57 <li><img alt="" src="../images/down.gif" /> <a href="#luahookinsertfilter">LuaHookInsertFilter</a></li>
58 <li><img alt="" src="../images/down.gif" /> <a href="#luahookmaptostorage">LuaHookMapToStorage</a></li>
59 <li><img alt="" src="../images/down.gif" /> <a href="#luahooktranslatename">LuaHookTranslateName</a></li>
60 <li><img alt="" src="../images/down.gif" /> <a href="#luahooktypechecker">LuaHookTypeChecker</a></li>
61 <li><img alt="" src="../images/down.gif" /> <a href="#luainherit">LuaInherit</a></li>
62 <li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li>
63 <li><img alt="" src="../images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li>
64 <li><img alt="" src="../images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li>
65 <li><img alt="" src="../images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li>
66 <li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li>
67 <li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li>
71 <li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Basic Configuration</a></li>
72 <li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Writing Handlers</a></li>
73 <li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Writing Hooks</a></li>
74 <li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Data Structures</a></li>
75 <li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging Functions</a></li>
76 <li><img alt="" src="../images/down.gif" /> <a href="#apache2">apache2 Package</a></li>
78 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
80 <h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
82 <p>The basic module loading directive is</p>
84 <div class="example"><p><code>
85 LoadModule lua_module modules/mod_lua.so
89 <code>mod_lua</code> provides a handler named <code>lua-script</code>,
90 which can be used with an <code>AddHandler</code> directive:</p>
92 <div class="example"><p><code>
93 AddHandler lua-script .lua
97 This will cause <code>mod_lua</code> to handle requests for files
98 ending in <code>.lua</code> by invoking that file's
99 <code>handle</code> function.
102 <p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
105 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
106 <div class="section">
107 <h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
108 <p> In the Apache HTTP Server API, the handler is a specific kind of hook
109 responsible for generating the response. Examples of modules that include a
110 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>,
111 and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p>
113 <p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
114 just evaluating a script body CGI style. A handler function looks
115 something like this:</p>
117 <div class="example"><h3>example.lua</h3><pre>
123 This is the default method name for Lua handlers, see the optional
124 function-name in the LuaMapHandler directive to choose a different
128 r.content_type = "text/plain"
129 r:puts("Hello Lua World!\n")
131 if r.method == 'GET' then
132 for k, v in pairs( r:parseargs() ) do
133 r:puts( string.format("%s: %s", k, v) )
135 elseif r.method == 'POST' then
136 for k, v in pairs( r:parsebody() ) do
137 r:puts( string.format("%s: %s", k, v) )
140 r:puts("unknown HTTP method " .. r.method)
146 This handler function just prints out the uri or form encoded
147 arguments to a plaintext page.
151 This means (and in fact encourages) that you can have multiple
152 handlers (or hooks, or filters) in the same script.
155 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
156 <div class="section">
157 <h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
159 <p>Hook functions are how modules (and Lua scripts) participate in the
160 processing of requests. Each type of hook exposed by the server exists for
161 a specific purposes such as mapping requests to the filesystem,
162 performing access control, or setting mimetypes. General purpose hooks
163 that simply run at handy times in the request lifecycle exist as well.</p>
165 <p>Hook functions are passed the request object as their only argument.
166 They can return any value, depending on the hook, but most commonly
167 they'll return OK, DONE, or DECLINED, which you can write in lua as
168 <code>apache2.OK</code>, <code>apache2.DONE</code>, or
169 <code>apache2.DECLINED</code>, or else an HTTP status code.</p>
171 <div class="example"><h3>translate_name.lua</h3><pre>
172 -- example hook that rewrites the URI to a filesystem path.
176 function translate_name(r)
177 if r.uri == "/translate-name" then
178 r.filename = r.document_root .. "/find_me.txt"
181 -- we don't care about this URL, give another module a chance
182 return apache2.DECLINED
186 <div class="example"><h3>translate_name2.lua</h3><pre>
187 --[[ example hook that rewrites one URI to another URI. It returns a
188 apache2.DECLINED to give other URL mappers a chance to work on the
189 substitution, including the core translate_name hook which maps based
192 Note: It is currently undefined as to whether this runs before or after
198 function translate_name(r)
199 if r.uri == "/translate-name" then
200 r.uri = "/find_me.txt"
201 return apache2.DECLINED
203 return apache2.DECLINED
206 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
207 <div class="section">
208 <h2><a name="datastructures" id="datastructures">Data Structures</a></h2>
213 <p>The request_rec is mapped in as a userdata. It has a metatable
214 which lets you do useful things with it. For the most part it
215 has the same fields as the request_rec struct (see httpd.h
216 until we get better docs here) many of which are writeable as
217 well as readable. (The table fields' content can be changed, but the
218 fields themselves cannot be set to different tables.)</p>
220 <table class="bordered">
223 <th><strong>Name</strong></th>
224 <th><strong>Lua type</strong></th>
225 <th><strong>Writable</strong></th>
228 <td><code>ap_auth_type</code></td>
233 <td><code>args</code></td>
238 <td><code>assbackwards</code></td>
244 <td><code>canonical_filename</code></td>
249 <td><code>content_encoding</code></td>
254 <td><code>content_type</code></td>
260 <td><code>document_root</code></td>
265 <td><code>err_headers_out</code></td>
270 <td><code>filename</code></td>
275 <td><code>handler</code></td>
281 <td><code>headers_in</code></td>
286 <td><code>headers_out</code></td>
291 <td><code>hostname</code></td>
296 <td><code>method</code></td>
301 <td><code>notes</code></td>
306 <td><code>path_info</code></td>
311 <td><code>protocol</code></td>
316 <td><code>proxyreq</code></td>
321 <td><code>range</code></td>
326 <td><code>subprocess_env</code></td>
331 <td><code>status</code></td>
336 <td><code>the_request</code></td>
341 <td><code>unparsed_uri</code></td>
346 <td><code>uri</code></td>
351 <td><code>user</code></td>
357 <p>The request_rec has (at least) the following methods:</p>
359 <div class="example"><p><code>
360 r:addoutputfilter(name|function) -- add an output filter
363 <div class="example"><p><code>
364 r:parseargs() -- returns a lua table containing the request's
365 query string arguments
368 <div class="example"><p><code>
369 r:parsebody() -- parse the request body as a POST and return
373 <div class="example"><p><code>
374 r:puts("hello", " world", "!") -- print to response body
377 <div class="example"><p><code>
378 r:write("a single string") -- print to response body
383 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
384 <div class="section">
385 <h2><a name="logging" id="logging">Logging Functions</a></h2>
387 <div class="example"><p><code>
388 -- examples of logging messages<br />
389 r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
390 r:debug("This is a debug log message")<br />
391 r:info("This is an info log message")<br />
392 r:notice("This is an notice log message")<br />
393 r:warn("This is an warn log message")<br />
394 r:err("This is an err log message")<br />
395 r:alert("This is an alert log message")<br />
396 r:crit("This is an crit log message")<br />
397 r:emerg("This is an emerg log message")<br />
400 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
401 <div class="section">
402 <h2><a name="apache2" id="apache2">apache2 Package</a></h2>
403 <p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
406 <dd>internal constant OK. Handlers should return this if they've
407 handled the request.</dd>
408 <dt>apache2.DECLINED</dt>
409 <dd>internal constant DECLINED. Handlers should return this if
410 they are not going to handle the request.</dd>
411 <dt>apache2.DONE</dt>
412 <dd>internal constant DONE.</dd>
413 <dt>apache2.version</dt>
414 <dd>Apache HTTP server version string</dd>
415 <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
416 <dd>HTTP status code</dd>
417 <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
418 <dd>internal constants used by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd>
420 <p>(Other HTTP status codes are not yet implemented.)</p>
422 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
423 <div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2>
424 <table class="directive">
425 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr>
426 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
427 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr>
428 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
429 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
430 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
431 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
433 Specify the behavior of the in-memory code cache. The default
434 is stat, which stats the top level script (not any included
435 ones) each time that file is needed, and reloads it if the
436 modified time indicates it is newer than the one it has
437 already loaded. The other values cause it to keep the file
438 cached forever (don't stat and replace) or to never cache the
441 <p>In general stat or forever is good for production, and stat or never
444 <div class="example"><h3>Examples:</h3><p><code>
445 LuaCodeCache stat<br />
446 LuaCodeCache forever<br />
447 LuaCodeCache never<br />
452 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
453 <div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2>
454 <table class="directive">
455 <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>
456 <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>
457 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
458 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
459 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
460 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
461 <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>
463 <p>Add your hook to the access_checker phase. An access checker
464 hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
465 <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
466 control when this script runs relative to other modules.</p></div>
469 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
470 <div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2>
471 <table class="directive">
472 <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>
473 <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>
474 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
475 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
476 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
477 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
478 <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>
480 <p>Invoke a lua function in the auth_checker phase of processing
481 a request. This can be used to implement arbitrary authentication
482 and authorization checking. A very simple example:
484 <div class="example"><pre>
487 -- fake authcheck hook
488 -- If request has no auth info, set the response header and
489 -- return a 401 to ask the browser for basic auth info.
490 -- If request has auth info, don't actually look at it, just
491 -- pretend we got userid 'foo' and validated it.
492 -- Then check if the userid is 'foo' and accept the request.
493 function authcheck_hook(r)
495 -- look for auth info
496 auth = r.headers_in['Authorization']
502 if r.user == nil then
503 r:debug("authcheck: user is nil, returning 401")
504 r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
506 elseif r.user == "foo" then
507 r:debug('user foo: OK')
509 r:debug("authcheck: user='" .. r.user .. "'")
510 r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
516 <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
517 control when this script runs relative to other modules.</p></div>
520 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
521 <div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2>
522 <table class="directive">
523 <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>
524 <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>
525 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
526 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
527 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
528 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
529 <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>
531 <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
532 control when this script runs relative to other modules.</p></div>
535 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
536 <div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2>
537 <table class="directive">
538 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of request
540 <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>
541 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
542 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
543 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
544 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
547 Just like LuaHookTranslateName, but executed at the fixups phase
551 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
552 <div class="directive-section"><h2><a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2>
553 <table class="directive">
554 <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>
555 <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>
556 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
557 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
558 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
559 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
560 </table><p>Not Yet Implemented</p>
562 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
563 <div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
564 <table class="directive">
565 <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>
566 <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>
567 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
568 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
569 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
570 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
573 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
574 <div class="directive-section"><h2><a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2>
575 <table class="directive">
576 <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>
577 <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>
578 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
579 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
580 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
581 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
582 <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>
584 Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
585 request processing. The hook function receives a single
586 argument, the request_rec, and should return a status code,
587 which is either an HTTP error code, or the constants defined
588 in the apache2 module: apache2.OK, apache2.DECLINED, or
591 <p>For those new to hooks, basically each hook will be invoked
592 until one of them returns apache2.OK. If your hook doesn't
593 want to do the translation it should just return
594 apache2.DECLINED. If the request should stop processing, then
595 return apache2.DONE.</p>
599 <div class="example"><pre>
601 LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
603 -- /scripts/conf/hooks.lua --
605 function silly_mapper(r)
607 r.filename = "/var/www/home.lua"
610 return apache2.DECLINED
615 <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
618 <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
619 control when this script runs relative to other modules.</p></div>
623 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
624 <div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2>
625 <table class="directive">
626 <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>
627 <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>
628 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
629 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
630 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
631 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
634 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
635 <div class="directive-section"><h2><a name="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2>
636 <table class="directive">
637 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr>
638 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
639 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</code></td></tr>
640 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
641 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
642 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
643 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
644 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.0 and later</td></tr>
645 </table><p>By default, if LuaHook* directives are used in overlapping
646 Directory or Location configuration sections, the scripts defined in the
647 more specific section are run <em>after</em> those defined in the more
648 generic section (LuaInherit parent-first). You can reverse this order, or
649 make the parent context not apply at all.</p>
651 <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
652 directives from parent configuration sections.</p>
654 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
655 <div class="directive-section"><h2><a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2>
656 <table class="directive">
657 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr>
658 <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>
659 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
660 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
661 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
662 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
664 <p>This directive matches a uri pattern to invoke a specific
665 handler function in a specific file. It uses PCRE regular
666 expressions to match the uri, and supports interpolating
667 match groups into both the file path and the function name
668 be careful writing your regular expressions to avoid security
670 <div class="example"><h3>Examples:</h3><p><code>
671 LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
673 <p>This would match uri's such as /photos/show?id=9
674 to the file /scripts/photos.lua and invoke the
675 handler function handle_show on the lua vm after
676 loading that file.</p>
678 <div class="example"><p><code>
679 LuaMapHandler /bingo /scripts/wombat.lua
681 <p>This would invoke the "handle" function, which
682 is the default if no specific function name is
686 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
687 <div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
688 <table class="directive">
689 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr>
690 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</code></td></tr>
691 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
692 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
693 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
694 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
696 <p>Add a path to lua's shared library search path. Follows the same
697 conventions as lua. This just munges the package.cpath in the
702 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
703 <div class="directive-section"><h2><a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2>
704 <table class="directive">
705 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr>
706 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</code></td></tr>
707 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
708 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
709 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
710 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
711 </table><p>Add a path to lua's module search path. Follows the same
712 conventions as lua. This just munges the package.path in the
715 <div class="example"><h3>Examples:</h3><p><code>
716 LuaPackagePath /scripts/lib/?.lua<br />
717 LuaPackagePath /scripts/lib/?/init.lua
721 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
722 <div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2>
723 <table class="directive">
724 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr>
725 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code /></td></tr>
726 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
727 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
728 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
729 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
731 <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
735 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
736 <div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2>
737 <table class="directive">
738 <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>
739 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</code></td></tr>
740 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
741 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
742 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
743 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
745 <p>Specify the base path which will be used to evaluate all
746 relative paths within mod_lua. If not specified they
747 will be resolved relative to the current working directory,
748 which may not always work well for a server.</p>
751 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
752 <div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2>
753 <table class="directive">
754 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, server -- default is once</td></tr>
755 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|server [max|min max]</code></td></tr>
756 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr>
757 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
758 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
759 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
760 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
762 <p>Specify the lifecycle scope of the Lua interpreter which will
763 be used by handlers in this "Directory." The default is "once"</p>
766 <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
768 <dt>request:</dt> <dd>use the interpreter to handle anything based on
769 the same file within this request, which is also
772 <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
774 <dt>server:</dt> <dd>This one is different than others because the
775 server scope is quite long lived, and multiple threads
776 will have the same server_rec. To accommodate this
777 server scoped interpreter are stored in an apr
778 resource list. The min and max arguments are intended
779 to specify the pool size, but are unused at this time.</dd>
784 <div class="bottomlang">
785 <p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a></p>
786 </div><div id="footer">
787 <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>
788 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>