2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_lua.xml.meta">
27 <description>Provides Lua hooks into various portions of the httpd
28 request processing</description>
29 <status>Experimental</status>
30 <sourcefile>mod_lua.c</sourcefile>
31 <identifier>lua_module</identifier>
32 <compatibility>2.3 and later</compatibility>
35 <p>This module allows the server to be extended with scripts written in the
36 Lua programming language. The extension points (hooks) available with
37 <module>mod_lua</module> include many of the hooks available to
38 natively compiled Apache HTTP Server modules, such as mapping requests to
39 files, generating dynamic responses, access control, authentication, and
42 <p>More information on the Lua programming language can be found at the
43 <a href="http://www.lua.org/">the Lua website</a>.</p>
45 <note><code>mod_lua</code> is still in experimental state.
46 Until it is declared stable, usage and behavior may change
47 at any time, even between stable releases of the 2.4.x series.
48 Be sure to check the CHANGES file before upgrading.</note>
52 <section id="basicconf"><title>Basic Configuration</title>
54 <p>The basic module loading directive is</p>
57 LoadModule lua_module modules/mod_lua.so
61 <code>mod_lua</code> provides a handler named <code>lua-script</code>,
62 which can be used with an <code>AddHandler</code> directive:</p>
65 AddHandler lua-script .lua
69 This will cause <code>mod_lua</code> to handle requests for files
70 ending in <code>.lua</code> by invoking that file's
71 <code>handle</code> function.
74 <p>For more flexibility, see <directive>LuaMapHandler</directive>.
79 <section id="writinghandlers"><title>Writing Handlers</title>
80 <p> In the Apache HTTP Server API, the handler is a specific kind of hook
81 responsible for generating the response. Examples of modules that include a
82 handler are <module>mod_proxy</module>, <module>mod_cgi</module>,
83 and <module>mod_status</module>.</p>
85 <p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
86 just evaluating a script body CGI style. A handler function looks
87 something like this:</p>
89 <example><title>example.lua</title><pre>
95 This is the default method name for Lua handlers, see the optional
96 function-name in the LuaMapHandler directive to choose a different
100 r.content_type = "text/plain"
101 r:puts("Hello Lua World!\n")
103 if r.method == 'GET' then
104 for k, v in pairs( r:parseargs() ) do
105 r:puts( string.format("%s: %s", k, v) )
107 elseif r.method == 'POST' then
108 for k, v in pairs( r:parsebody() ) do
109 r:puts( string.format("%s: %s", k, v) )
112 r:puts("unknown HTTP method " .. r.method)
118 This handler function just prints out the uri or form encoded
119 arguments to a plaintext page.
123 This means (and in fact encourages) that you can have multiple
124 handlers (or hooks, or filters) in the same script.
129 <section id="writinghooks"><title>Writing Hooks</title>
131 <p>Hook functions are how modules (and Lua scripts) participate in the
132 processing of requests. Each type of hook exposed by the server exists for
133 a specific purposes such as mapping requests to the filesystem,
134 performing access control, or setting mimetypes. General purpose hooks
135 that simply run at handy times in the request lifecycle exist as well.</p>
137 <p>Hook functions are passed the request object as their only argument.
138 They can return any value, depending on the hook, but most commonly
139 they'll return OK, DONE, or DECLINED, which you can write in lua as
140 <code>apache2.OK</code>, <code>apache2.DONE</code>, or
141 <code>apache2.DECLINED</code>, or else an HTTP status code.</p>
143 <example><title>translate_name.lua</title><pre>
144 -- example hook that rewrites the URI to a filesystem path.
148 function translate_name(r)
149 if r.uri == "/translate-name" then
150 r.filename = r.document_root .. "/find_me.txt"
153 -- we don't care about this URL, give another module a chance
154 return apache2.DECLINED
158 <example><title>translate_name2.lua</title><pre>
159 --[[ example hook that rewrites one URI to another URI. It returns a
160 apache2.DECLINED to give other URL mappers a chance to work on the
161 substitution, including the core translate_name hook which maps based
164 Note: It is currently undefined as to whether this runs before or after
170 function translate_name(r)
171 if r.uri == "/translate-name" then
172 r.uri = "/find_me.txt"
173 return apache2.DECLINED
175 return apache2.DECLINED
180 <section id="datastructures"><title>Data Structures</title>
185 <p>The request_rec is mapped in as a userdata. It has a metatable
186 which lets you do useful things with it. For the most part it
187 has the same fields as the request_rec struct (see httpd.h
188 until we get better docs here) many of which are writeable as
189 well as readable. (The table fields' content can be changed, but the
190 fields themselves cannot be set to different tables.)</p>
195 <th><strong>Name</strong></th>
196 <th><strong>Lua type</strong></th>
197 <th><strong>Writable</strong></th>
200 <td><code>ap_auth_type</code></td>
205 <td><code>args</code></td>
210 <td><code>assbackwards</code></td>
216 <td><code>canonical_filename</code></td>
221 <td><code>content_encoding</code></td>
226 <td><code>content_type</code></td>
232 <td><code>document_root</code></td>
237 <td><code>err_headers_out</code></td>
242 <td><code>filename</code></td>
247 <td><code>handler</code></td>
253 <td><code>headers_in</code></td>
258 <td><code>headers_out</code></td>
263 <td><code>hostname</code></td>
268 <td><code>method</code></td>
273 <td><code>notes</code></td>
278 <td><code>path_info</code></td>
283 <td><code>protocol</code></td>
288 <td><code>proxyreq</code></td>
293 <td><code>range</code></td>
298 <td><code>subprocess_env</code></td>
303 <td><code>status</code></td>
308 <td><code>the_request</code></td>
313 <td><code>unparsed_uri</code></td>
318 <td><code>uri</code></td>
323 <td><code>user</code></td>
329 <p>The request_rec has (at least) the following methods:</p>
332 r:addoutputfilter(name|function) -- add an output filter
336 r:parseargs() -- returns a lua table containing the request's
337 query string arguments
341 r:parsebody() -- parse the request body as a POST and return
346 r:puts("hello", " world", "!") -- print to response body
350 r:write("a single string") -- print to response body
357 <section id="logging"><title>Logging Functions</title>
360 -- examples of logging messages<br />
361 r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
362 r:debug("This is a debug log message")<br />
363 r:info("This is an info log message")<br />
364 r:notice("This is an notice log message")<br />
365 r:warn("This is an warn log message")<br />
366 r:err("This is an err log message")<br />
367 r:alert("This is an alert log message")<br />
368 r:crit("This is an crit log message")<br />
369 r:emerg("This is an emerg log message")<br />
374 <section id="apache2"><title>apache2 Package</title>
375 <p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
378 <dd>internal constant OK. Handlers should return this if they've
379 handled the request.</dd>
380 <dt>apache2.DECLINED</dt>
381 <dd>internal constant DECLINED. Handlers should return this if
382 they are not going to handle the request.</dd>
383 <dt>apache2.DONE</dt>
384 <dd>internal constant DONE.</dd>
385 <dt>apache2.version</dt>
386 <dd>Apache HTTP server version string</dd>
387 <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
388 <dd>HTTP status code</dd>
389 <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
390 <dd>internal constants used by <module>mod_proxy</module></dd>
392 <p>(Other HTTP status codes are not yet implemented.)</p>
397 <description>Specify the base path for resolving relative paths for mod_lua directives</description>
398 <syntax>LuaRoot /path/to/a/directory</syntax>
399 <contextlist><context>server config</context><context>virtual host</context>
400 <context>directory</context><context>.htaccess</context>
402 <override>All</override>
405 <p>Specify the base path which will be used to evaluate all
406 relative paths within mod_lua. If not specified they
407 will be resolved relative to the current working directory,
408 which may not always work well for a server.</p>
413 <name>LuaScope</name>
414 <description>One of once, request, conn, server -- default is once</description>
415 <syntax>LuaScope once|request|conn|server [max|min max]</syntax>
416 <default>LuaScope once</default>
417 <contextlist><context>server config</context><context>virtual host</context>
418 <context>directory</context><context>.htaccess</context>
420 <override>All</override>
423 <p>Specify the lifecycle scope of the Lua interpreter which will
424 be used by handlers in this "Directory." The default is "once"</p>
427 <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
429 <dt>request:</dt> <dd>use the interpreter to handle anything based on
430 the same file within this request, which is also
433 <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
435 <dt>server:</dt> <dd>This one is different than others because the
436 server scope is quite long lived, and multiple threads
437 will have the same server_rec. To accommodate this
438 server scoped interpreter are stored in an apr
439 resource list. The min and max arguments are intended
440 to specify the pool size, but are unused at this time.</dd>
446 <name>LuaMapHandler</name>
447 <description>Map a path to a lua handler</description>
448 <syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
449 <contextlist><context>server config</context><context>virtual host</context>
450 <context>directory</context><context>.htaccess</context>
452 <override>All</override>
454 <p>This directive matches a uri pattern to invoke a specific
455 handler function in a specific file. It uses PCRE regular
456 expressions to match the uri, and supports interpolating
457 match groups into both the file path and the function name
458 be careful writing your regular expressions to avoid security
460 <example><title>Examples:</title>
461 LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
463 <p>This would match uri's such as /photos/show?id=9
464 to the file /scripts/photos.lua and invoke the
465 handler function handle_show on the lua vm after
466 loading that file.</p>
469 LuaMapHandler /bingo /scripts/wombat.lua
471 <p>This would invoke the "handle" function, which
472 is the default if no specific function name is
478 <name>LuaPackagePath</name>
479 <description>Add a directory to lua's package.path</description>
480 <syntax>LuaPackagePath /path/to/include/?.lua</syntax>
481 <contextlist><context>server config</context><context>virtual host</context>
482 <context>directory</context><context>.htaccess</context>
484 <override>All</override>
485 <usage><p>Add a path to lua's module search path. Follows the same
486 conventions as lua. This just munges the package.path in the
489 <example><title>Examples:</title>
490 LuaPackagePath /scripts/lib/?.lua<br />
491 LuaPackagePath /scripts/lib/?/init.lua
497 <name>LuaPackageCPath</name>
498 <description>Add a directory to lua's package.cpath</description>
499 <syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
500 <contextlist><context>server config</context><context>virtual host</context>
501 <context>directory</context><context>.htaccess</context>
503 <override>All</override>
506 <p>Add a path to lua's shared library search path. Follows the same
507 conventions as lua. This just munges the package.cpath in the
514 <name>LuaCodeCache</name>
515 <description>Configure the compiled code cache.</description>
516 <syntax>LuaCodeCache stat|forever|never</syntax>
517 <default>LuaCodeCache stat</default>
518 <contextlist><context>server config</context><context>virtual host</context>
519 <context>directory</context><context>.htaccess</context>
521 <override>All</override>
524 Specify the behavior of the in-memory code cache. The default
525 is stat, which stats the top level script (not any included
526 ones) each time that file is needed, and reloads it if the
527 modified time indicates it is newer than the one it has
528 already loaded. The other values cause it to keep the file
529 cached forever (don't stat and replace) or to never cache the
532 <p>In general stat or forever is good for production, and stat or never
535 <example><title>Examples:</title>
536 LuaCodeCache stat<br />
537 LuaCodeCache forever<br />
538 LuaCodeCache never<br />
545 <name>LuaHookTranslateName</name>
546 <description>Provide a hook for the translate name phase of request processing</description>
547 <syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</syntax>
548 <contextlist><context>server config</context><context>virtual host</context>
549 <context>directory</context>
551 <override>All</override>
552 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
555 Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
556 request processing. The hook function receives a single
557 argument, the request_rec, and should return a status code,
558 which is either an HTTP error code, or the constants defined
559 in the apache2 module: apache2.OK, apache2.DECLINED, or
562 <p>For those new to hooks, basically each hook will be invoked
563 until one of them returns apache2.OK. If your hook doesn't
564 want to do the translation it should just return
565 apache2.DECLINED. If the request should stop processing, then
566 return apache2.DONE.</p>
572 LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
574 -- /scripts/conf/hooks.lua --
576 function silly_mapper(r)
578 r.filename = "/var/www/home.lua"
581 return apache2.DECLINED
586 <note><title>Context</title><p>This directive is not valid in <directive
587 type="section" module="core">Directory</directive>, <directive
588 type="section" module="core">Files</directive>, or htaccess
591 <note><title>Ordering</title><p>The optional arguments "early" or "late"
592 control when this script runs relative to other modules.</p></note>
598 <name>LuaHookFixups</name>
599 <description>Provide a hook for the fixups phase of request
600 processing</description>
601 <syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
602 <contextlist><context>server config</context><context>virtual host</context>
603 <context>directory</context><context>.htaccess</context>
605 <override>All</override>
608 Just like LuaHookTranslateName, but executed at the fixups phase
614 <name>LuaHookMapToStorage</name>
615 <description>Provide a hook for the map_to_storage phase of request processing</description>
616 <syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
617 <contextlist><context>server config</context><context>virtual host</context>
618 <context>directory</context><context>.htaccess</context>
620 <override>All</override>
621 <usage><p>...</p></usage>
625 <name>LuaHookCheckUserID</name>
626 <description>Provide a hook for the check_user_id phase of request processing</description>
627 <syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</syntax>
628 <contextlist><context>server config</context><context>virtual host</context>
629 <context>directory</context><context>.htaccess</context>
631 <override>All</override>
632 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
634 <note><title>Ordering</title><p>The optional arguments "early" or "late"
635 control when this script runs relative to other modules.</p></note>
640 <name>LuaHookTypeChecker</name>
641 <description>Provide a hook for the type_checker phase of request processing</description>
642 <syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
643 <contextlist><context>server config</context><context>virtual host</context>
644 <context>directory</context><context>.htaccess</context>
646 <override>All</override>
647 <usage><p>...</p></usage>
651 <name>LuaHookAuthChecker</name>
652 <description>Provide a hook for the auth_checker phase of request processing</description>
653 <syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>
654 <contextlist><context>server config</context><context>virtual host</context>
655 <context>directory</context><context>.htaccess</context>
657 <override>All</override>
658 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
660 <p>Invoke a lua function in the auth_checker phase of processing
661 a request. This can be used to implement arbitrary authentication
662 and authorization checking. A very simple example:
667 -- fake authcheck hook
668 -- If request has no auth info, set the response header and
669 -- return a 401 to ask the browser for basic auth info.
670 -- If request has auth info, don't actually look at it, just
671 -- pretend we got userid 'foo' and validated it.
672 -- Then check if the userid is 'foo' and accept the request.
673 function authcheck_hook(r)
675 -- look for auth info
676 auth = r.headers_in['Authorization']
682 if r.user == nil then
683 r:debug("authcheck: user is nil, returning 401")
684 r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
686 elseif r.user == "foo" then
687 r:debug('user foo: OK')
689 r:debug("authcheck: user='" .. r.user .. "'")
690 r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
696 <note><title>Ordering</title><p>The optional arguments "early" or "late"
697 control when this script runs relative to other modules.</p></note>
702 <name>LuaHookAccessChecker</name>
703 <description>Provide a hook for the access_checker phase of request processing</description>
704 <syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>
705 <contextlist><context>server config</context><context>virtual host</context>
706 <context>directory</context><context>.htaccess</context>
708 <override>All</override>
709 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
711 <p>Add your hook to the access_checker phase. An access checker
712 hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
713 <note><title>Ordering</title><p>The optional arguments "early" or "late"
714 control when this script runs relative to other modules.</p></note>
719 <name>LuaHookInsertFilter</name>
720 <description>Provide a hook for the insert_filter phase of request processing</description>
721 <syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
722 <contextlist><context>server config</context><context>virtual host</context>
723 <context>directory</context><context>.htaccess</context>
725 <override>All</override>
726 <usage><p>Not Yet Implemented</p></usage>
730 <name>LuaInherit</name>
731 <description>Controls how parent configuration sections are merged into children</description>
732 <syntax>LuaInherit none|parent-first|parent-last</syntax>
733 <default>LuaInherit parent-first</default>
734 <contextlist><context>server config</context><context>virtual host</context>
735 <context>directory</context><context>.htaccess</context>
737 <override>All</override>
738 <compatibility>2.4.0 and later</compatibility>
739 <usage><p>By default, if LuaHook* directives are used in overlapping
740 Directory or Location configuration sections, the scripts defined in the
741 more specific section are run <em>after</em> those defined in the more
742 generic section (LuaInherit parent-first). You can reverse this order, or
743 make the parent context not apply at all.</p>
745 <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
746 directives from parent configuration sections.</p></usage>
750 <name>LuaQuickHandler</name>
751 <description>Provide a hook for the quick handler of request processing</description>
753 <contextlist><context>server config</context><context>virtual host</context>
754 <context>directory</context><context>.htaccess</context>
756 <override>All</override>
758 <note><title>Context</title><p>This directive is not valid in <directive
759 type="section" module="core">Directory</directive>, <directive
760 type="section" module="core">Files</directive>, or htaccess