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
51 <section id="basicconf"><title>Basic Configuration</title>
53 <p>The basic module loading directive is</p>
56 LoadModule lua_module modules/mod_lua.so
60 <code>mod_lua</code> provides a handler named <code>lua-script</code>,
61 which can be used with an <code>AddHandler</code> directive:</p>
64 AddHandler lua-script .lua
68 This will cause <code>mod_lua</code> to handle requests for files
69 ending in <code>.lua</code> by invoking that file's
70 <code>handle</code> function.
73 <p>For more flexibility, see <directive>LuaMapHandler</directive>.
78 <section id="writinghandlers"><title>Writing Handlers</title>
79 <p> In the Apache HTTP Server API, the handler is a specific kind of hook
80 responsible for generating the response. Examples of modules that include a
81 handler are <module>mod_proxy</module>, <module>mod_cgi</module>,
82 and <module>mod_status</module>.</p>
84 <p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
85 just evaluating a script body CGI style. A handler function looks
86 something like this:</p>
88 <example><title>example.lua</title><pre>
94 This is the default method name for Lua handlers, see the optional
95 function-name in the LuaMapHandler directive to choose a different
99 r.content_type = "text/plain"
100 r:puts("Hello Lua World!\n")
102 if r.method == 'GET' then
103 for k, v in pairs( r:parseargs() ) do
104 r:puts( string.format("%s: %s", k, v) )
106 elseif r.method == 'POST' then
107 for k, v in pairs( r:parsebody() ) do
108 r:puts( string.format("%s: %s", k, v) )
111 r:puts("unknown HTTP method " .. r.method)
117 This handler function just prints out the uri or form encoded
118 arguments to a plaintext page.
122 This means (and in fact encourages) that you can have multiple
123 handlers (or hooks, or filters) in the same script.
128 <section id="writinghooks"><title>Writing Hooks</title>
130 <p>Hook functions are how modules (and Lua scripts) participate in the
131 processing of requests. Each type of hook exposed by the server exists for
132 a specific purposes such as mapping requests to the filesystem,
133 performing access control, or setting mimetypes. General purpose hooks
134 that simply run at handy times in the request lifecycle exist as well.</p>
136 <p>Hook functions are passed the request object as their only argument.
137 They can return any value, depending on the hook, but most commonly
138 they'll return OK, DONE, or DECLINED, which you can write in lua as
139 <code>apache2.OK</code>, <code>apache2.DONE</code>, or
140 <code>apache2.DECLINED</code>, or else an HTTP status code.</p>
142 <example><title>translate_name.lua</title><pre>
143 -- example hook that rewrites the URI to a filesystem path.
147 function translate_name(r)
148 if r.uri == "/translate-name" then
149 r.filename = r.document_root .. "/find_me.txt"
152 -- we don't care about this URL, give another module a chance
153 return apache2.DECLINED
157 <example><title>translate_name2.lua</title><pre>
158 --[[ example hook that rewrites one URI to another URI. It returns a
159 apache2.DECLINED to give other URL mappers a chance to work on the
160 substitution, including the core translate_name hook which maps based
163 Note: It is currently undefined as to whether this runs before or after
169 function translate_name(r)
170 if r.uri == "/translate-name" then
171 r.uri = "/find_me.txt"
172 return apache2.DECLINED
174 return apache2.DECLINED
179 <section id="datastructures"><title>Data Structures</title>
184 <p>The request_rec is mapped in as a userdata. It has a metatable
185 which lets you do useful things with it. For the most part it
186 has the same fields as the request_rec struct (see httpd.h
187 until we get better docs here) many of which are writeable as
188 well as readable. (The table fields' content can be changed, but the
189 fields themselves cannot be set to different tables.)</p>
194 <th><strong>Name</strong></th>
195 <th><strong>Lua type</strong></th>
196 <th><strong>Writable</strong></th>
199 <td><code>ap_auth_type</code></td>
204 <td><code>args</code></td>
209 <td><code>assbackwards</code></td>
215 <td><code>canonical_filename</code></td>
220 <td><code>content_encoding</code></td>
225 <td><code>content_type</code></td>
231 <td><code>document_root</code></td>
236 <td><code>err_headers_out</code></td>
241 <td><code>filename</code></td>
246 <td><code>headers_in</code></td>
251 <td><code>headers_out</code></td>
256 <td><code>hostname</code></td>
261 <td><code>method</code></td>
266 <td><code>notes</code></td>
271 <td><code>path_info</code></td>
276 <td><code>protocol</code></td>
281 <td><code>range</code></td>
286 <td><code>subprocess_env</code></td>
291 <td><code>status</code></td>
296 <td><code>the_request</code></td>
301 <td><code>unparsed_uri</code></td>
306 <td><code>uri</code></td>
311 <td><code>user</code></td>
317 <p>The request_rec has (at least) the following methods:</p>
320 r:addoutputfilter(name|function) -- add an output filter
324 r:parseargs() -- returns a lua table containing the request's
325 query string arguments
329 r:parsebody() -- parse the request body as a POST and return
334 r:puts("hello", " world", "!") -- print to response body
338 r:write("a single string") -- print to response body
345 <section id="logging"><title>Logging Functions</title>
348 -- examples of logging messages<br />
349 r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
350 r:debug("This is a debug log message")<br />
351 r:info("This is an info log message")<br />
352 r:notice("This is an notice log message")<br />
353 r:warn("This is an warn log message")<br />
354 r:err("This is an err log message")<br />
355 r:alert("This is an alert log message")<br />
356 r:crit("This is an crit log message")<br />
357 r:emerg("This is an emerg log message")<br />
362 <section id="apache2"><title>apache2 Package</title>
363 <p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
366 <dd>internal constant OK. Handlers should return this if they've
367 handled the request.</dd>
368 <dt>apache2.DECLINED</dt>
369 <dd>internal constant DECLINED. Handlers should return this if
370 they are not going to handle the request.</dd>
371 <dt>apache2.DONE</dt>
372 <dd>internal constant DONE.</dd>
373 <dt>apache2.version</dt>
374 <dd>Apache HTTP server version string</dd>
375 <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
376 <dd>HTTP status code</dd>
378 <p>(Other HTTP status codes are not yet implemented.)</p>
383 <description>Specify the base path for resolving relative paths for mod_lua directives</description>
384 <syntax>LuaRoot /path/to/a/directory</syntax>
385 <contextlist><context>server config</context><context>virtual host</context>
386 <context>directory</context><context>.htaccess</context>
388 <override>All</override>
391 <p>Specify the base path which will be used to evaluate all
392 relative paths within mod_lua. If not specified they
393 will be resolved relative to the current working directory,
394 which may not always work well for a server.</p>
399 <name>LuaScope</name>
400 <description>One of once, request, conn, server -- default is once</description>
401 <syntax>LuaScope once|request|conn|server [max|min max]</syntax>
402 <default>LuaScope once</default>
403 <contextlist><context>server config</context><context>virtual host</context>
404 <context>directory</context><context>.htaccess</context>
406 <override>All</override>
409 <p>Specify the lifecycle scope of the Lua interpreter which will
410 be used by handlers in this "Directory." The default is "once"</p>
413 <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
415 <dt>request:</dt> <dd>use the interpreter to handle anything based on
416 the same file within this request, which is also
419 <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
421 <dt>server:</dt> <dd>This one is different than others because the
422 server scope is quite long lived, and multiple threads
423 will have the same server_rec. To accommodate this
424 server scoped interpreter are stored in an apr
425 resource list. The min and max arguments are intended
426 to specify the pool size, but are unused at this time.</dd>
432 <name>LuaMapHandler</name>
433 <description>Map a path to a lua handler</description>
434 <syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
435 <contextlist><context>server config</context><context>virtual host</context>
436 <context>directory</context><context>.htaccess</context>
438 <override>All</override>
440 <p>This directive matches a uri pattern to invoke a specific
441 handler function in a specific file. It uses PCRE regular
442 expressions to match the uri, and supports interpolating
443 match groups into both the file path and the function name
444 be careful writing your regular expressions to avoid security
446 <example><title>Examples:</title>
447 LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
449 <p>This would match uri's such as /photos/show?id=9
450 to the file /scripts/photos.lua and invoke the
451 handler function handle_show on the lua vm after
452 loading that file.</p>
455 LuaMapHandler /bingo /scripts/wombat.lua
457 <p>This would invoke the "handle" function, which
458 is the default if no specific function name is
464 <name>LuaPackagePath</name>
465 <description>Add a directory to lua's package.path</description>
466 <syntax>LuaPackagePath /path/to/include/?.lua</syntax>
467 <contextlist><context>server config</context><context>virtual host</context>
468 <context>directory</context><context>.htaccess</context>
470 <override>All</override>
471 <usage><p>Add a path to lua's module search path. Follows the same
472 conventions as lua. This just munges the package.path in the
475 <example><title>Examples:</title>
476 LuaPackagePath /scripts/lib/?.lua<br />
477 LuaPackagePath /scripts/lib/?/init.lua
483 <name>LuaPackageCPath</name>
484 <description>Add a directory to lua's package.cpath</description>
485 <syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
486 <contextlist><context>server config</context><context>virtual host</context>
487 <context>directory</context><context>.htaccess</context>
489 <override>All</override>
492 <p>Add a path to lua's shared library search path. Follows the same
493 conventions as lua. This just munges the package.cpath in the
500 <name>LuaCodeCache</name>
501 <description>Configure the compiled code cache.</description>
502 <syntax>LuaCodeCache stat|forever|never</syntax>
503 <default>LuaCodeCache stat</default>
504 <contextlist><context>server config</context><context>virtual host</context>
505 <context>directory</context><context>.htaccess</context>
507 <override>All</override>
510 Specify the behavior of the in-memory code cache. The default
511 is stat, which stats the top level script (not any included
512 ones) each time that file is needed, and reloads it if the
513 modified time indicates it is newer than the one it has
514 already loaded. The other values cause it to keep the file
515 cached forever (don't stat and replace) or to never cache the
518 <p>In general stat or forever is good for production, and stat or never
521 <example><title>Examples:</title>
522 LuaCodeCache stat<br />
523 LuaCodeCache forever<br />
524 LuaCodeCache never<br />
531 <name>LuaHookTranslateName</name>
532 <description>Provide a hook for the translate name phase of request processing</description>
533 <syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name</syntax>
534 <contextlist><context>server config</context><context>virtual host</context>
535 <context>directory</context><context>.htaccess</context>
537 <override>All</override>
540 Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
541 request processing. The hook function receives a single
542 argument, the request_rec, and should return a status code,
543 which is either an HTTP error code, or the constants defined
544 in the apache2 module: apache2.OK, apache2.DECLINED, or
547 <p>For those new to hooks, basically each hook will be invoked
548 until one of them returns apache2.OK. If your hook doesn't
549 want to do the translation it should just return
550 apache2.DECLINED. If the request should stop processing, then
551 return apache2.DONE.</p>
557 LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
559 -- /scripts/conf/hooks.lua --
561 function silly_mapper(r)
563 r.filename = "/var/www/home.lua"
566 return apache2.DECLINED
574 <name>LuaHookFixups</name>
575 <description>Provide a hook for the fixups phase of request
576 processing</description>
577 <syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
578 <contextlist><context>server config</context><context>virtual host</context>
579 <context>directory</context><context>.htaccess</context>
581 <override>All</override>
584 Just like LuaHookTranslateName, but executed at the fixups phase
590 <name>LuaHookMapToStorage</name>
591 <description>Provide a hook for the map_to_storage phase of request processing</description>
592 <syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
593 <contextlist><context>server config</context><context>virtual host</context>
594 <context>directory</context><context>.htaccess</context>
596 <override>All</override>
597 <usage><p>...</p></usage>
601 <name>LuaHookCheckUserID</name>
602 <description>Provide a hook for the check_user_id phase of request processing</description>
603 <syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name</syntax>
604 <contextlist><context>server config</context><context>virtual host</context>
605 <context>directory</context><context>.htaccess</context>
607 <override>All</override>
608 <usage><p>...</p></usage>
612 <name>LuaHookTypeChecker</name>
613 <description>Provide a hook for the type_checker phase of request processing</description>
614 <syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
615 <contextlist><context>server config</context><context>virtual host</context>
616 <context>directory</context><context>.htaccess</context>
618 <override>All</override>
619 <usage><p>...</p></usage>
623 <name>LuaHookAuthChecker</name>
624 <description>Provide a hook for the auth_checker phase of request processing</description>
625 <syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
626 <contextlist><context>server config</context><context>virtual host</context>
627 <context>directory</context><context>.htaccess</context>
629 <override>All</override>
631 <p>Invoke a lua function in the auth_checker phase of processing
632 a request. This can be used to implement arbitrary authentication
633 and authorization checking. A very simple example:
638 -- fake authcheck hook
639 -- If request has no auth info, set the response header and
640 -- return a 401 to ask the browser for basic auth info.
641 -- If request has auth info, don't actually look at it, just
642 -- pretend we got userid 'foo' and validated it.
643 -- Then check if the userid is 'foo' and accept the request.
644 function authcheck_hook(r)
646 -- look for auth info
647 auth = r.headers_in['Authorization']
653 if r.user == nil then
654 r:debug("authcheck: user is nil, returning 401")
655 r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
657 elseif r.user == "foo" then
658 r:debug('user foo: OK')
660 r:debug("authcheck: user='" .. r.user .. "'")
661 r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
671 <name>LuaHookAccessChecker</name>
672 <description>Provide a hook for the access_checker phase of request processing</description>
673 <syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name</syntax>
674 <contextlist><context>server config</context><context>virtual host</context>
675 <context>directory</context><context>.htaccess</context>
677 <override>All</override>
679 <p>Add your hook to the access_checker phase. An access checker
680 hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
685 <name>LuaHookInsertFilter</name>
686 <description>Provide a hook for the insert_filter phase of request processing</description>
687 <syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
688 <contextlist><context>server config</context><context>virtual host</context>
689 <context>directory</context><context>.htaccess</context>
691 <override>All</override>
692 <usage><p>Not Yet Implemented</p></usage>
696 <name>LuaQuickHandler</name>
697 <description>Provide a hook for the quick handler of request processing</description>
699 <contextlist><context>server config</context><context>virtual host</context>
700 <context>directory</context><context>.htaccess</context>
702 <override>All</override>
703 <usage><p>...</p></usage>