mod_lua.xml revision 2219c51bf0756c2f6f7deb88a13baf30f141c12e
fb51a6b789d85113d0976148685b0063c294220drbowen<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
77a0265761f1bec2aaa0b4116c644f8066e349e3rbowen<!-- $LastChangedRevision$ -->
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen Licensed to the Apache Software Foundation (ASF) under one or more
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen contributor license agreements. See the NOTICE file distributed with
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen this work for additional information regarding copyright ownership.
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen The ASF licenses this file to You under the Apache License, Version 2.0
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen (the "License"); you may not use this file except in compliance with
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen the License. You may obtain a copy of the License at
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen Unless required by applicable law or agreed to in writing, software
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen distributed under the License is distributed on an "AS IS" BASIS,
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen See the License for the specific language governing permissions and
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen limitations under the License.
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<description>Provides Lua hooks into various portions of the httpd
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenrequest processing</description>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<section id="basicconf"><title>Basic Configuration</title>
8548ace6aa09b4d3e463254b53865fb38fbbbc78poirier<code>mod_lua</code> provides a handler named <code>lua-script</code>,
fb51a6b789d85113d0976148685b0063c294220drbowenwhich can be used with an <code>AddHandler</code> directive:</p>
fb51a6b789d85113d0976148685b0063c294220drbowenAddHandler lua-script .lua
2219c51bf0756c2f6f7deb88a13baf30f141c12epoirierThis will cause any <code>.lua</code> file to be evaluated by
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<section id="writinghandlers"><title>Writing Handlers</title>
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<p><code>mod_lua</code> always looks to invoke a function for the handler, rather than
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenjust evaluating a script body CGI style. A handler function looks
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowensomething like this:</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier require "string"
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier function handle_something(r)
92e5d4326ae44f79da5cb049470daba604506846poirier r:puts("Hello Lua World!\n")
92e5d4326ae44f79da5cb049470daba604506846poirier if r.method == 'GET' then
92e5d4326ae44f79da5cb049470daba604506846poirier for k, v in pairs( r:parseargs() ) do
fb51a6b789d85113d0976148685b0063c294220drbowen r:puts( string.format("%s: %s", k, v) )
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen elseif r.method == 'POST' then
889dc1728817c1c56d0c8d894c768614e346d86ecovener for k, v in pairs( r:parsebody() ) do
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim r:puts( string.format("%s: %s", k, v) )
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:puts("unknown HTTP method " .. r.method)
92e5d4326ae44f79da5cb049470daba604506846poirierThis handler function just prints out the uri or form encoded
92e5d4326ae44f79da5cb049470daba604506846poirierarguments to a plaintext page.
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimThis means (and in fact encourages) that you can have multiple
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimhandlers (or hooks, or filters) in the same script.
92e5d4326ae44f79da5cb049470daba604506846poirier<section id="datastructures"><title>Data Structures</title>
92e5d4326ae44f79da5cb049470daba604506846poirier <p>The request_rec is mapped in as a userdata. It has a metatable
92e5d4326ae44f79da5cb049470daba604506846poirier which lets you do useful things with it. For the most part it
92e5d4326ae44f79da5cb049470daba604506846poirier has the same fields as the request_rec struct (see httpd.h
92e5d4326ae44f79da5cb049470daba604506846poirier until we get better docs here) many of which are writeable as
92e5d4326ae44f79da5cb049470daba604506846poirier well as readable, and has (at least) the following methods:</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim r:puts("hello", " world", "!") -- print to response body
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<section id="logging"><title>Logging Functions</title>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:debug("This is a debug log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:info("This is an info log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:notice("This is an notice log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:warn("This is an warn log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:err("This is an err log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:alert("This is an alert log message")<br />
92e5d4326ae44f79da5cb049470daba604506846poirier r:crit("This is an crit log message")<br />
92e5d4326ae44f79da5cb049470daba604506846poirier r:emerg("This is an emerg log message")<br />
889dc1728817c1c56d0c8d894c768614e346d86ecovener<directivesynopsis>
92e5d4326ae44f79da5cb049470daba604506846poirier<description>Specify the base path for resolving relative paths for mod_lua directives</description>
92e5d4326ae44f79da5cb049470daba604506846poirier<contextlist><context>server config</context><context>virtual host</context>
92e5d4326ae44f79da5cb049470daba604506846poirier<context>directory</context><context>.htaccess</context>
92e5d4326ae44f79da5cb049470daba604506846poirier</contextlist>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <p>Specify the base path which will be used to evaluate all
bb57315f942d09c744543fe41e453bd0181fd93ecovener relative paths within mod_lua. If not specified they
bb57315f942d09c744543fe41e453bd0181fd93ecovener will be resolved relative to the current working directory,
bb57315f942d09c744543fe41e453bd0181fd93ecovener which may not always work well for a server.</p>
bb57315f942d09c744543fe41e453bd0181fd93ecovener</directivesynopsis>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<directivesynopsis>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<description>One of once, request, conn, server -- default is once</description>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<syntax>LuaScope once|request|conn|server [max|min max]</syntax>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<contextlist><context>server config</context><context>virtual host</context>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<context>directory</context><context>.htaccess</context>
bb57315f942d09c744543fe41e453bd0181fd93ecovener</contextlist>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>Specify the lifecycle scope of the Lua interpreter which will
bb57315f942d09c744543fe41e453bd0181fd93ecovener be used by handlers in this "Directory." The default is "once"</p>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
92e5d4326ae44f79da5cb049470daba604506846poirier <dt>request:</dt> <dd>use the interpreter to handle anything based on
92e5d4326ae44f79da5cb049470daba604506846poirier the same file within this request, which is also
92e5d4326ae44f79da5cb049470daba604506846poirier request scoped.</dd>
92e5d4326ae44f79da5cb049470daba604506846poirier <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
92e5d4326ae44f79da5cb049470daba604506846poirier <dt>server:</dt> <dd>This one is different than others because the
92e5d4326ae44f79da5cb049470daba604506846poirier server scope is quite long lived, and multiple threads
92e5d4326ae44f79da5cb049470daba604506846poirier will have the same server_rec. To accommodate this
92e5d4326ae44f79da5cb049470daba604506846poirier server scoped interpreter are stored in an apr
92e5d4326ae44f79da5cb049470daba604506846poirier resource list. The min and max arguments are intended
92e5d4326ae44f79da5cb049470daba604506846poirier to specify the pool size, but are unused at this time.</dd>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<description>Map a path to a lua handler</description>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<contextlist><context>server config</context><context>virtual host</context>
92e5d4326ae44f79da5cb049470daba604506846poirier<context>directory</context><context>.htaccess</context>
92e5d4326ae44f79da5cb049470daba604506846poirier</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>This directive matches a uri pattern to invoke a specific
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier handler function in a specific file. It uses PCRE regular
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier expressions to match the uri, and supports interpolating
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier match groups into both the file path and the function name
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier be careful writing your regular expressions to avoid security
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier issues.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier handler function handle_show on the lua vm after
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier loading that file.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>This would invoke the "handle" function, which
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier is the default if no specific function name is
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier provided.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Add a directory to lua's package.path</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <usage><p>Add a path to lua's module search path. Follows the same
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier conventions as lua. This just munges the package.path in the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier lua vms.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Add a directory to lua's package.cpath</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>Add a path to lua's shared library search path. Follows the same
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener conventions as lua. This just munges the package.cpath in the
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener lua vms.</p>
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Configure the compiled code cache.</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier Specify the behavior of the in-memory code cache. The default
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier is stat, which stats the top level script (not any included
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier ones) each time that file is needed, and reloads it if the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier modified time indicates it is newer than the one it has
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier already loaded. The other values cause it to keep the file
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier cached forever (don't stat and replace) or to never cache the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>In general stat or forever is good production and stat or never
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier for deveopment.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaCodeCache stat<br />
92e5d4326ae44f79da5cb049470daba604506846poirier LuaCodeCache forever<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaCodeCache never<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the translate name phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener<context>directory</context><context>.htaccess</context>
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier request processing. The hook function receives a single
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier argument, the request_rec, and should return a status code,
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier which is either an HTTP error code, or the constants defined
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier in the apache2 module: apache2.OK, apache2.DECLINED, or
8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener <p>For those new to hooks, basically each hook will be invoked
8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener until one of them returns apache2.OK. If your hook doesn't
8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener want to do the translation it should just return
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier apache2.DECLINED. If the request should stop processing, then
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier function silly_mapper(r)<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the fixups phase of request
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierprocessing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</contextlist>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim Just like LuaHookTranslateName, but executed at the fixups phase
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the map_to_storage phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<description>Provide a hook for the check_user_id phase of request processing</description>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name</syntax>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<contextlist><context>server config</context><context>virtual host</context>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<context>directory</context><context>.htaccess</context>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</contextlist>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
b60ba9fb00026d3dbca744c6c19afe63cba3a3d1covener<directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<description>Provide a hook for the type_checker phase of request processing</description>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<contextlist><context>server config</context><context>virtual host</context>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<context>directory</context><context>.htaccess</context>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</contextlist>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<directivesynopsis>
92e5d4326ae44f79da5cb049470daba604506846poirier<description>Provide a hook for the auth_checker phase of request processing</description>
92e5d4326ae44f79da5cb049470daba604506846poirier<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</contextlist>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the access_checker phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<contextlist><context>server config</context><context>virtual host</context>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<context>directory</context><context>.htaccess</context>
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener</contextlist>
92e5d4326ae44f79da5cb049470daba604506846poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
fb51a6b789d85113d0976148685b0063c294220drbowen<description>Provide a hook for the insert_filter phase of request processing</description>
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
fb51a6b789d85113d0976148685b0063c294220drbowen<contextlist><context>server config</context><context>virtual host</context>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic<context>directory</context><context>.htaccess</context>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</contextlist>
fb51a6b789d85113d0976148685b0063c294220drbowen</directivesynopsis>
fb51a6b789d85113d0976148685b0063c294220drbowen<directivesynopsis>
fb51a6b789d85113d0976148685b0063c294220drbowen<description>Provide a hook for the quick handler of request processing</description>
fb51a6b789d85113d0976148685b0063c294220drbowen<contextlist><context>server config</context><context>virtual host</context>
fb51a6b789d85113d0976148685b0063c294220drbowen<context>directory</context><context>.htaccess</context>
fb51a6b789d85113d0976148685b0063c294220drbowen</contextlist>
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</modulesynopsis>