httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rbo...@apache.org
Subject svn commit: r1673855 [25/37] - /httpd/httpd/branches/2.4.x/docs/manual/mod/
Date Wed, 15 Apr 2015 16:35:22 GMT
Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_lua.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/mod_lua.html.en?rev=1673855&r1=1673854&r2=1673855&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_lua.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_lua.html.en Wed Apr 15 16:35:10 2015
@@ -95,279 +95,906 @@ trust, as it can be abused to change the
 <li><img alt="" src="../images/down.gif" /> <a href="#databases">Database connectivity</a></li>
 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
-
-<p>The basic module loading directive is</p>
+<div class="directive-section"><h2><a name="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a> <a name="luaauthzprovider" id="luaauthzprovider">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
+</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.3 and later</td></tr>
+</table>
+<p>After a lua function has been registered as authorization provider, it can be used
+with the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive:</p>
 
-<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>
+<pre class="prettyprint lang-config">LuaRoot "/usr/local/apache2/lua"
+LuaAuthzProvider foo authz.lua authz_check_foo
+&lt;Location "/"&gt;
+  Require foo johndoe
+&lt;/Location&gt;</pre>
 
+<pre class="prettyprint lang-lua">require "apache2"
+function authz_check_foo(r, who)
+    if r.user ~= who then return apache2.AUTHZ_DENIED
+    return apache2.AUTHZ_GRANTED
+end</pre>
 
-<p>
-<code>mod_lua</code> provides a handler named <code>lua-script</code>,
-which can be used with a <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> or
-<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive:</p>
 
-<pre class="prettyprint lang-config">&lt;Files "*.lua"&gt;
-    SetHandler lua-script
-&lt;/Files&gt;</pre>
 
 
-<p>
-This will cause <code>mod_lua</code> to handle requests for files
-ending in <code>.lua</code> by invoking that file's
-<code>handle</code> function.
-</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>
+    Specify the behavior of the in-memory code cache. The default
+    is stat, which stats the top level script (not any included
+    ones) each time that file is needed, and reloads it if the
+    modified time indicates it is newer than the one it has
+    already loaded. The other values cause it to keep the file
+    cached forever (don't stat and replace) or to never cache the
+    file.</p>
 
-<p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
-</p>
+    <p>In general stat or forever is good for production, and stat or never
+    for development.</p>
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
-<p> In the Apache HTTP Server API, the handler is a specific kind of hook
-responsible for generating the response.  Examples of modules that include a
-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>,
-and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p>
+    <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaCodeCache stat
+LuaCodeCache forever
+LuaCodeCache never</pre>
+</div>
 
-<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
-just evaluating a script body CGI style. A handler function looks
-something like this:</p>
 
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<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>
+</table>
+<p>Add your hook to the access_checker phase.  An access checker
+hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
+   <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" 
+   control when this script runs relative to other modules.</p></div>
 
-<pre class="prettyprint lang-lua">
-<strong>example.lua</strong><br />
--- example handler
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<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>
+</table>
+<p>Invoke a lua function in the auth_checker phase of processing
+a request.  This can be used to implement arbitrary authentication
+and authorization checking.  A very simple example:
+</p>
+<pre class="prettyprint lang-lua">require 'apache2'
 
-require "string"
+-- fake authcheck hook
+-- If request has no auth info, set the response header and
+-- return a 401 to ask the browser for basic auth info.
+-- If request has auth info, don't actually look at it, just
+-- pretend we got userid 'foo' and validated it.
+-- Then check if the userid is 'foo' and accept the request.
+function authcheck_hook(r)
 
---[[
-     This is the default method name for Lua handlers, see the optional
-     function-name in the LuaMapHandler directive to choose a different
-     entry point.
---]]
-function handle(r)
-    r.content_type = "text/plain"
+   -- look for auth info
+   auth = r.headers_in['Authorization']
+   if auth ~= nil then
+     -- fake the user
+     r.user = 'foo'
+   end
 
-    if r.method == 'GET' then
-        r:puts("Hello Lua World!\n")
-        for k, v in pairs( r:parseargs() ) do
-            r:puts( string.format("%s: %s\n", k, v) )
-        end
-    elseif r.method == 'POST' then
-        r:puts("Hello Lua World!\n")
-        for k, v in pairs( r:parsebody() ) do
-            r:puts( string.format("%s: %s\n", k, v) )
-        end
-    elseif r.method == 'PUT' then
--- use our own Error contents
-        r:puts("Unsupported HTTP method " .. r.method)
-        r.status = 405
-        return apache2.ok
-    else
--- use the ErrorDocument
-        return 501
-    end
-    return apache2.OK
+   if r.user == nil then
+      r:debug("authcheck: user is nil, returning 401")
+      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
+      return 401
+   elseif r.user == "foo" then
+      r:debug('user foo: OK')
+   else
+      r:debug("authcheck: user='" .. r.user .. "'")
+      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
+      return 401
+   end
+   return apache2.OK
 end</pre>
 
+   <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" 
+   control when this script runs relative to other modules.</p></div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<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>
+</table><p>...</p>
+   <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" 
+   control when this script runs relative to other modules.</p></div>
 
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of a request
+processing</td></tr>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
 <p>
-This handler function just prints out the uri or form encoded
-arguments to a plaintext page.
+    Just like LuaHookTranslateName, but executed at the fixups phase
 </p>
 
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>Not Yet Implemented</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookLog" id="LuaHookLog">LuaHookLog</a> <a name="luahooklog" id="luahooklog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access log phase of a request
+processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookLog  /path/to/lua/script.lua log_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
 <p>
-This means (and in fact encourages) that you can have multiple
-handlers (or hooks, or filters) in the same script.
+    This simple logging hook allows you to run a function when httpd enters the 
+    logging phase of a request. With it, you can append data to your own logs, 
+    manipulate data before the regular log is written, or prevent a log entry 
+    from being created. To prevent the usual logging from happening, simply return
+    <code>apache2.DONE</code> in your logging handler, otherwise return 
+    <code>apache2.OK</code> to tell httpd to log as normal.
 </p>
+<p>Example:</p>
+<pre class="prettyprint lang-config">LuaHookLog "/path/to/script.lua" logger</pre>
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2>
+<pre class="prettyprint lang-lua">-- /path/to/script.lua --
+function logger(r)
+    -- flip a coin:
+    -- If 1, then we write to our own Lua log and tell httpd not to log
+    -- in the main log.
+    -- If 2, then we just sanitize the output a bit and tell httpd to 
+    -- log the sanitized bits.
 
+    if math.random(1,2) == 1 then
+        -- Log stuff ourselves and don't log in the regular log
+        local f = io.open("/foo/secret.log", "a")
+        if f then
+            f:write("Something secret happened at " .. r.uri .. "\n")
+            f:close()
+        end
+        return apache2.DONE -- Tell httpd not to use the regular logging functions
+    else
+        r.uri = r.uri:gsub("somesecretstuff", "") -- sanitize the URI
+        return apache2.OK -- tell httpd to log it.
+    end
+end</pre>
 
-<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to
-authorization that is much easier to use than using into the relevant
-hooks directly. The first argument to the
-<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive gives
-the name of the responsible authorization provider. For any
-<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> line,
-<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider
-of the given name, passing the rest of the line as parameters. The
-provider will then check authorization and pass the result as return
-value.</p>
-
-<p>The authz provider is normally called before authentication. If it needs to
-know the authenticated user name (or if the user will be authenticated at
-all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
-This will cause authentication to proceed and the authz provider to be
-called a second time.</p>
 
-<p>The following authz provider function takes two arguments, one ip
-address and one user name. It will allow access from the given ip address
-without authentication, or if the authenticated user matches the second
-argument:</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+    <p>Like <code class="directive">LuaHookTranslateName</code> but executed at the 
+    map-to-storage phase of a request. Modules like mod_cache run at this phase,
+    which makes for an interesting example on what to do here:</p>
+    <pre class="prettyprint lang-config">LuaHookMapToStorage "/path/to/lua/script.lua" check_cache</pre>
 
-<pre class="prettyprint lang-lua">
-<strong>authz_provider.lua</strong><br />
+    <pre class="prettyprint lang-lua">require"apache2"
+cached_files = {}
 
-require 'apache2'
+function read_file(filename) 
+    local input = io.open(filename, "r")
+    if input then
+        local data = input:read("*a")
+        cached_files[filename] = data
+        file = cached_files[filename]
+        input:close()
+    end
+    return cached_files[filename]
+end
 
-function authz_check_foo(r, ip, user)
-    if r.useragent_ip == ip then
-        return apache2.AUTHZ_GRANTED
-    elseif r.user == nil then
-        return apache2.AUTHZ_DENIED_NO_USER
-    elseif r.user == user then
-        return apache2.AUTHZ_GRANTED
-    else
-        return apache2.AUTHZ_DENIED
+function check_cache(r)
+    if r.filename:match("%.png$") then -- Only match PNG files
+        local file = cached_files[r.filename] -- Check cache entries
+        if not file then
+            file = read_file(r.filename)  -- Read file into cache
+        end
+        if file then -- If file exists, write it out
+            r.status = 200
+            r:write(file)
+            r:info(("Sent %s to client from cache"):format(r.filename))
+            return apache2.DONE -- skip default handler for PNG files
+        end
     end
+    return apache2.DECLINED -- If we had nothing to do, let others serve this.
 end</pre>
 
 
-<p>The following configuration registers this function as provider
-<code>foo</code> and configures it for URL <code>/</code>:</p>
-<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
-&lt;Location "/"&gt;
-  Require foo 10.1.2.3 john_doe
-&lt;/Location&gt;</pre>
-
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
-
-<p>Hook functions are how modules (and Lua scripts) participate in the
-processing of requests. Each type of hook exposed by the server exists for
-a specific purpose, such as mapping requests to the file system,
-performing access control, or setting mime types:</p>
-
-<table class="bordered"><tr class="header">
-        <th>Hook phase</th>
-        <th>mod_lua directive</th>
-        <th>Description</th>
-    </tr>
-<tr>
-        <td>Quick handler</td>
-        <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
-        <td>This is the first hook that will be called after a request has 
-            been mapped to a host or virtual host</td>
-    </tr>
-<tr class="odd">
-        <td>Translate name</td>
-        <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
-        <td>This phase translates the requested URI into a filename on the 
-            system. Modules such as <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
-            <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operate in this phase.</td>
-    </tr>
-<tr>
-        <td>Map to storage</td>
-        <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
-        <td>This phase maps files to their physical, cached or external/proxied storage. 
-            It can be used by proxy or caching modules</td>
-    </tr>
-<tr class="odd">
-        <td>Check Access</td>
-        <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
-        <td>This phase checks whether a client has access to a resource. This 
-            phase is run before the user is authenticated, so beware.
-        </td>
-    </tr>
-<tr>
-        <td>Check User ID</td>
-        <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
-        <td>This phase it used to check the negotiated user ID</td>
-    </tr>
-<tr class="odd">
-        <td>Check Authorization</td>
-        <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> or 
-            <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
-        <td>This phase authorizes a user based on the negotiated credentials, such as 
-            user ID, client certificate etc.
-        </td>
-    </tr>
-<tr>
-        <td>Check Type</td>
-        <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
-        <td>This phase checks the requested file and assigns a content type and 
-            a handler to it</td>
-    </tr>
-<tr class="odd">
-        <td>Fixups</td>
-        <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
-        <td>This is the final "fix anything" phase before the content handlers 
-            are run. Any last-minute changes to the request should be made here.</td>
-    </tr>
-<tr>
-        <td>Content handler</td>
-        <td>fx. <code>.lua</code> files or through <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
-        <td>This is where the content is handled. Files are read, parsed, some are run, 
-            and the result is sent to the client</td>
-    </tr>
-<tr class="odd">
-        <td>Logging</td>
-        <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
-        <td>Once a request has been handled, it enters several logging phases, 
-            which logs the request in either the error or access log. Mod_lua
-            is able to hook into the start of this and control logging output.</td>
-    </tr>
-</table>
+    
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<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>
+</table><p>
+    Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
+    request processing. The hook function receives a single
+    argument, the request_rec, and should return a status code,
+    which is either an HTTP error code, or the constants defined
+    in the apache2 module: apache2.OK, apache2.DECLINED, or
+    apache2.DONE. </p>
 
-<p>Hook functions are passed the request object as their only argument 
-(except for LuaAuthzProvider, which also gets passed the arguments from 
-the Require directive).
-They can return any value, depending on the hook, but most commonly
-they'll return OK, DONE, or DECLINED, which you can write in Lua as
-<code>apache2.OK</code>, <code>apache2.DONE</code>, or
-<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
+    <p>For those new to hooks, basically each hook will be invoked
+    until one of them returns apache2.OK. If your hook doesn't
+    want to do the translation it should just return
+    apache2.DECLINED. If the request should stop processing, then
+    return apache2.DONE.</p>
 
+    <p>Example:</p>
 
-<pre class="prettyprint lang-lua">
-<strong>translate_name.lua</strong><br />
--- example hook that rewrites the URI to a filesystem path.
+<pre class="prettyprint lang-config"># httpd.conf
+LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper</pre>
 
-require 'apache2'
 
-function translate_name(r)
-    if r.uri == "/translate-name" then
-        r.filename = r.document_root .. "/find_me.txt"
+<pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua --
+require "apache2"
+function silly_mapper(r)
+    if r.uri == "/" then
+        r.filename = "/var/www/home.lua"
         return apache2.OK
+    else
+        return apache2.DECLINED
     end
-    -- we don't care about this URL, give another module a chance
-    return apache2.DECLINED
 end</pre>
 
 
+   <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>, <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code>, or htaccess
+   context.</p></div>
 
-<pre class="prettyprint lang-lua">
-<strong>translate_name2.lua</strong><br />
---[[ example hook that rewrites one URI to another URI. It returns a
-     apache2.DECLINED to give other URL mappers a chance to work on the
-     substitution, including the core translate_name hook which maps based
-     on the DocumentRoot.
+   <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" 
+   control when this script runs relative to other modules.</p></div>
 
-     Note: Use the early/late flags in the directive to make it run before
-           or after mod_alias.
---]]
 
-require 'apache2'
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2>
+<table class="directive">
+<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>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>
+    This directive provides a hook for the type_checker phase of the request processing. 
+    This phase is where requests are assigned a content type and a handler, and thus can 
+    be used to modify the type and handler based on input:
+    </p>
+    <pre class="prettyprint lang-config">LuaHookTypeChecker "/path/to/lua/script.lua" type_checker</pre>
+
+    <pre class="prettyprint lang-lua">    function type_checker(r)
+        if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
+            r.content_type = "image/gif" -- assign it the image/gif type
+            r.handler = "gifWizard"      -- tell the gifWizard module to handle this
+            r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested
+            return apache2.OK
+        end
 
-function translate_name(r)
-    if r.uri == "/translate-name" then
-        r.uri = "/find_me.txt"
         return apache2.DECLINED
-    end
-    return apache2.DECLINED
-end</pre>
+    end</pre>
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="datastructures" id="datastructures">Data Structures</a></h2>
 
-<dl>
-<dt>request_rec</dt>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.0 and later</td></tr>
+</table><p>By default, if LuaHook* directives are used in overlapping
+    Directory or Location configuration sections, the scripts defined in the
+    more specific section are run <em>after</em> those defined in the more
+    generic section (LuaInherit parent-first).  You can reverse this order, or
+    make the parent context not apply at all.</p>
+    
+    <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
+    directives from parent configuration sections.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a> <a name="luainputfilter" id="luainputfilter">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content input filtering</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
+</table>
+<p>Provides a means of adding a Lua function as an input filter. 
+As with output filters, input filters work as coroutines, 
+first yielding before buffers are sent, then yielding whenever 
+a bucket needs to be passed down the chain, and finally (optionally) 
+yielding anything that needs to be appended to the input data. The 
+global variable <code>bucket</code> holds the buckets as they are passed 
+onto the Lua script:
+</p>
+
+<pre class="prettyprint lang-config">LuaInputFilter myInputFilter "/www/filter.lua" input_filter
+&lt;Files "*.lua"&gt;
+  SetInputFilter myInputFilter
+&lt;/Files&gt;</pre>
+
+<pre class="prettyprint lang-lua">--[[
+    Example input filter that converts all POST data to uppercase.
+]]--
+function input_filter(r)
+    print("luaInputFilter called") -- debug print
+    coroutine.yield() -- Yield and wait for buckets
+    while bucket do -- For each bucket, do...
+        local output = string.upper(bucket) -- Convert all POST data to uppercase
+        coroutine.yield(output) -- Send converted data down the chain
+    end
+    -- No more buckets available.
+    coroutine.yield("&amp;filterSignature=1234") -- Append signature at the end
+end</pre>
+
+<p>
+The input filter supports denying/skipping a filter if it is deemed unwanted:
+</p>
+<pre class="prettyprint lang-lua">function input_filter(r)
+    if not good then
+        return -- Simply deny filtering, passing on the original content instead
+    end
+    coroutine.yield() -- wait for buckets
+    ... -- insert filter stuff here
+end</pre>
+
+<p>
+See "<a href="#modifying_buckets">Modifying contents with Lua 
+filters</a>" for more information.
+</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr>
+<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>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+    <p>This directive matches a uri pattern to invoke a specific
+    handler function in a specific file. It uses PCRE regular
+    expressions to match the uri, and supports interpolating
+    match groups into both the file path and the function name. 
+    Be careful writing your regular expressions to avoid security
+    issues.</p>
+   <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"</pre>
+</div>
+        <p>This would match uri's such as /photos/show?id=9
+        to the file /scripts/photos.lua and invoke the
+        handler function handle_show on the lua vm after
+        loading that file.</p>
+
+<pre class="prettyprint lang-config">LuaMapHandler "/bingo" "/scripts/wombat.lua"</pre>
+
+        <p>This would invoke the "handle" function, which
+        is the default if no specific function name is
+        provided.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a> <a name="luaoutputfilter" id="luaoutputfilter">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content output filtering</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
+</table>
+<p>Provides a means of adding a Lua function as an output filter. 
+As with input filters, output filters work as coroutines, 
+first yielding before buffers are sent, then yielding whenever 
+a bucket needs to be passed down the chain, and finally (optionally) 
+yielding anything that needs to be appended to the input data. The 
+global variable <code>bucket</code> holds the buckets as they are passed 
+onto the Lua script:
+</p>
+
+<pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter
+&lt;Files "*.lua"&gt;
+  SetOutputFilter myOutputFilter
+&lt;/Files&gt;</pre>
+
+<pre class="prettyprint lang-lua">--[[
+    Example output filter that escapes all HTML entities in the output
+]]--
+function output_filter(r)
+    coroutine.yield("(Handled by myOutputFilter)&lt;br/&gt;\n") -- Prepend some data to the output,
+                                                          -- yield and wait for buckets.
+    while bucket do -- For each bucket, do...
+        local output = r:escape_html(bucket) -- Escape all output
+        coroutine.yield(output) -- Send converted data down the chain
+    end
+    -- No more buckets available.
+end</pre>
+
+<p>
+As with the input filter, the output filter supports denying/skipping a filter 
+if it is deemed unwanted:
+</p>
+<pre class="prettyprint lang-lua">function output_filter(r)
+    if not r.content_type:match("text/html") then
+        return -- Simply deny filtering, passing on the original content instead
+    end
+    coroutine.yield() -- wait for buckets
+    ... -- insert filter stuff here
+end</pre>
+
+<div class="note"><h3>Lua filters with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3>
+<p> When a Lua filter is used as the underlying provider via the 
+<code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code> directive, filtering 
+will only work when the <var>filter-name</var> is identical to the <var>provider-name</var>.
+</p> </div>
+
+<p>
+See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more 
+information.
+</p>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+    <p>Add a path to lua's shared library search path. Follows the same
+    conventions as lua. This just munges the package.cpath in the
+    lua vms.</p>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>Add a path to lua's module search path. Follows the same
+    conventions as lua. This just munges the package.path in the
+    lua vms.</p>
+
+    <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaPackagePath "/scripts/lib/?.lua"
+LuaPackagePath "/scripts/lib/?/init.lua"</pre>
+</div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+    <p>
+    This phase is run immediately after the request has been mapped to a virtal host, 
+    and can be used to either do some request processing before the other phases kick 
+    in, or to serve a request without the need to translate, map to storage et cetera. 
+    As this phase is run before anything else, directives such as <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> or <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> are void in this phase, just as 
+    URIs have not been properly parsed yet.
+    </p>
+   <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>, <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code>, or htaccess
+   context.</p></div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2>
+<table class="directive">
+<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>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+    <p>Specify the base path which will be used to evaluate all
+    relative paths within mod_lua. If not specified they
+    will be resolved relative to the current working directory,
+    which may not always work well for a server.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, thread -- default is once</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread|server [min] [max]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+    <p>Specify the life cycle scope of the Lua interpreter which will
+    be used by handlers in this "Directory." The default is "once"</p>
+
+   <dl>
+    <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
+
+    <dt>request:</dt> <dd>use the interpreter to handle anything based on
+             the same file within this request, which is also
+             request scoped.</dd>
+
+    <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
+
+    <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread 
+            handling the request (only available with threaded MPMs).</dd>
+
+    <dt>server:</dt>  <dd>This one is different than others because the
+            server scope is quite long lived, and multiple threads
+            will have the same server_rec. To accommodate this,
+            server scoped Lua states are stored in an apr
+            resource list. The <code>min</code> and <code>max</code> arguments 
+            specify the minimum and maximum number of Lua states to keep in the 
+            pool.</dd>
+   </dl>
+    <p>
+    Generally speaking, the <code>thread</code> and <code>server</code> scopes 
+    execute roughly 2-3 times faster than the rest, because they don't have to 
+    spawn new Lua states on every request (especially with the event MPM, as 
+    even keepalive requests will use a new thread for each request). If you are 
+    satisfied that your scripts will not have problems reusing a state, then 
+    the <code>thread</code> or <code>server</code> scopes should be used for 
+    maximum performance. While the <code>thread</code> scope will provide the 
+    fastest responses, the <code>server</code> scope will use less memory, as 
+    states are pooled, allowing f.x. 1000 threads to share only 100 Lua states, 
+    thus using only 10% of the memory required by the <code>thread</code> scope.
+    </p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
+
+<p>The basic module loading directive is</p>
+
+<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>
+
+
+<p>
+<code>mod_lua</code> provides a handler named <code>lua-script</code>,
+which can be used with a <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> or
+<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive:</p>
+
+<pre class="prettyprint lang-config">&lt;Files "*.lua"&gt;
+    SetHandler lua-script
+&lt;/Files&gt;</pre>
+
+
+<p>
+This will cause <code>mod_lua</code> to handle requests for files
+ending in <code>.lua</code> by invoking that file's
+<code>handle</code> function.
+</p>
+
+<p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
+<p> In the Apache HTTP Server API, the handler is a specific kind of hook
+responsible for generating the response.  Examples of modules that include a
+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>,
+and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p>
+
+<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
+just evaluating a script body CGI style. A handler function looks
+something like this:</p>
+
+
+<pre class="prettyprint lang-lua">
+<strong>example.lua</strong><br />
+-- example handler
+
+require "string"
+
+--[[
+     This is the default method name for Lua handlers, see the optional
+     function-name in the LuaMapHandler directive to choose a different
+     entry point.
+--]]
+function handle(r)
+    r.content_type = "text/plain"
+
+    if r.method == 'GET' then
+        r:puts("Hello Lua World!\n")
+        for k, v in pairs( r:parseargs() ) do
+            r:puts( string.format("%s: %s\n", k, v) )
+        end
+    elseif r.method == 'POST' then
+        r:puts("Hello Lua World!\n")
+        for k, v in pairs( r:parsebody() ) do
+            r:puts( string.format("%s: %s\n", k, v) )
+        end
+    elseif r.method == 'PUT' then
+-- use our own Error contents
+        r:puts("Unsupported HTTP method " .. r.method)
+        r.status = 405
+        return apache2.ok
+    else
+-- use the ErrorDocument
+        return 501
+    end
+    return apache2.OK
+end</pre>
+
+
+<p>
+This handler function just prints out the uri or form encoded
+arguments to a plaintext page.
+</p>
+
+<p>
+This means (and in fact encourages) that you can have multiple
+handlers (or hooks, or filters) in the same script.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2>
+
+
+<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to
+authorization that is much easier to use than using into the relevant
+hooks directly. The first argument to the
+<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive gives
+the name of the responsible authorization provider. For any
+<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> line,
+<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider
+of the given name, passing the rest of the line as parameters. The
+provider will then check authorization and pass the result as return
+value.</p>
+
+<p>The authz provider is normally called before authentication. If it needs to
+know the authenticated user name (or if the user will be authenticated at
+all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
+This will cause authentication to proceed and the authz provider to be
+called a second time.</p>
+
+<p>The following authz provider function takes two arguments, one ip
+address and one user name. It will allow access from the given ip address
+without authentication, or if the authenticated user matches the second
+argument:</p>
+
+<pre class="prettyprint lang-lua">
+<strong>authz_provider.lua</strong><br />
+
+require 'apache2'
+
+function authz_check_foo(r, ip, user)
+    if r.useragent_ip == ip then
+        return apache2.AUTHZ_GRANTED
+    elseif r.user == nil then
+        return apache2.AUTHZ_DENIED_NO_USER
+    elseif r.user == user then
+        return apache2.AUTHZ_GRANTED
+    else
+        return apache2.AUTHZ_DENIED
+    end
+end</pre>
+
+
+<p>The following configuration registers this function as provider
+<code>foo</code> and configures it for URL <code>/</code>:</p>
+<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
+&lt;Location "/"&gt;
+  Require foo 10.1.2.3 john_doe
+&lt;/Location&gt;</pre>
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
+
+<p>Hook functions are how modules (and Lua scripts) participate in the
+processing of requests. Each type of hook exposed by the server exists for
+a specific purpose, such as mapping requests to the file system,
+performing access control, or setting mime types:</p>
+
+<table class="bordered"><tr class="header">
+        <th>Hook phase</th>
+        <th>mod_lua directive</th>
+        <th>Description</th>
+    </tr>
+<tr>
+        <td>Quick handler</td>
+        <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
+        <td>This is the first hook that will be called after a request has 
+            been mapped to a host or virtual host</td>
+    </tr>
+<tr class="odd">
+        <td>Translate name</td>
+        <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
+        <td>This phase translates the requested URI into a filename on the 
+            system. Modules such as <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
+            <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operate in this phase.</td>
+    </tr>
+<tr>
+        <td>Map to storage</td>
+        <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
+        <td>This phase maps files to their physical, cached or external/proxied storage. 
+            It can be used by proxy or caching modules</td>
+    </tr>
+<tr class="odd">
+        <td>Check Access</td>
+        <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
+        <td>This phase checks whether a client has access to a resource. This 
+            phase is run before the user is authenticated, so beware.
+        </td>
+    </tr>
+<tr>
+        <td>Check User ID</td>
+        <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
+        <td>This phase it used to check the negotiated user ID</td>
+    </tr>
+<tr class="odd">
+        <td>Check Authorization</td>
+        <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> or 
+            <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
+        <td>This phase authorizes a user based on the negotiated credentials, such as 
+            user ID, client certificate etc.
+        </td>
+    </tr>
+<tr>
+        <td>Check Type</td>
+        <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
+        <td>This phase checks the requested file and assigns a content type and 
+            a handler to it</td>
+    </tr>
+<tr class="odd">
+        <td>Fixups</td>
+        <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
+        <td>This is the final "fix anything" phase before the content handlers 
+            are run. Any last-minute changes to the request should be made here.</td>
+    </tr>
+<tr>
+        <td>Content handler</td>
+        <td>fx. <code>.lua</code> files or through <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
+        <td>This is where the content is handled. Files are read, parsed, some are run, 
+            and the result is sent to the client</td>
+    </tr>
+<tr class="odd">
+        <td>Logging</td>
+        <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
+        <td>Once a request has been handled, it enters several logging phases, 
+            which logs the request in either the error or access log. Mod_lua
+            is able to hook into the start of this and control logging output.</td>
+    </tr>
+</table>
+
+<p>Hook functions are passed the request object as their only argument 
+(except for LuaAuthzProvider, which also gets passed the arguments from 
+the Require directive).
+They can return any value, depending on the hook, but most commonly
+they'll return OK, DONE, or DECLINED, which you can write in Lua as
+<code>apache2.OK</code>, <code>apache2.DONE</code>, or
+<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
+
+
+<pre class="prettyprint lang-lua">
+<strong>translate_name.lua</strong><br />
+-- example hook that rewrites the URI to a filesystem path.
+
+require 'apache2'
+
+function translate_name(r)
+    if r.uri == "/translate-name" then
+        r.filename = r.document_root .. "/find_me.txt"
+        return apache2.OK
+    end
+    -- we don't care about this URL, give another module a chance
+    return apache2.DECLINED
+end</pre>
+
+
+
+<pre class="prettyprint lang-lua">
+<strong>translate_name2.lua</strong><br />
+--[[ example hook that rewrites one URI to another URI. It returns a
+     apache2.DECLINED to give other URL mappers a chance to work on the
+     substitution, including the core translate_name hook which maps based
+     on the DocumentRoot.
+
+     Note: Use the early/late flags in the directive to make it run before
+           or after mod_alias.
+--]]
+
+require 'apache2'
+
+function translate_name(r)
+    if r.uri == "/translate-name" then
+        r.uri = "/find_me.txt"
+        return apache2.DECLINED
+    end
+    return apache2.DECLINED
+end</pre>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="datastructures" id="datastructures">Data Structures</a></h2>
+
+<dl>
+<dt>request_rec</dt>
         <dd>
         <p>The request_rec is mapped in as a userdata. It has a metatable
         which lets you do useful things with it. For the most part it
@@ -650,1215 +1277,588 @@ end</pre>
 <tr>
           <td><code>useragent_ip</code></td>
           <td>string</td>
-          <td>no</td>
-          <td>The IP of the user agent making the request</td>
-        </tr>
-</table>
-           </dd>
-    </dl>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="functions" id="functions">Built in functions</a></h2>
-
-<p>The request_rec object has (at least) the following methods:</p>
-
-<pre class="prettyprint lang-lua">r:flush()   -- flushes the output buffer.
-            -- Returns true if the flush was successful, false otherwise.
-
-while we_have_stuff_to_send do
-    r:puts("Bla bla bla\n") -- print something to client
-    r:flush() -- flush the buffer (send to client)
-    r.usleep(500000) -- fake processing time for 0.5 sec. and repeat
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- add an output filter:
-
-r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream</pre>
-
-
-<pre class="prettyprint lang-lua">r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
-
-if use_sendfile_thing then
-    r:sendfile("/var/www/large_file.img")
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:parseargs() -- returns two tables; one standard key/value table for regular GET data, 
-              -- and one for multi-value data (fx. foo=1&amp;foo=2&amp;foo=3):
-
-local GET, GETMULTI = r:parseargs()
-r:puts("Your name is: " .. GET['name'] or "Unknown")</pre>
-
-
-<pre class="prettyprint lang-lua">r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
-                         -- just like r:parseargs().
-                         -- An optional number may be passed to specify the maximum number 
-                         -- of bytes to parse. Default is 8192 bytes:
-                 
-local POST, POSTMULTI = r:parsebody(1024*1024)
-r:puts("Your name is: " .. POST['name'] or "Unknown")</pre>
-
-
-<pre class="prettyprint lang-lua">r:puts("hello", " world", "!") -- print to response body, self explanatory</pre>
-
-
-<pre class="prettyprint lang-lua">r:write("a single string") -- print to response body, self explanatory</pre>
-
-
-<pre class="prettyprint lang-lua">r:escape_html("&lt;html&gt;test&lt;/html&gt;") -- Escapes HTML code and returns the escaped result</pre>
-
-
-<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
-
-local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>
-
-
-<pre class="prettyprint lang-lua">r:base64_decode(string) -- Decodes a Base64-encoded string:
-
-local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>
-
-
-<pre class="prettyprint lang-lua">r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
-
-local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>
-
-
-<pre class="prettyprint lang-lua">r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
-
-local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>
-
-
-<pre class="prettyprint lang-lua">r:escape(string) -- URL-Escapes a string:
-
-local url = "http://foo.bar/1 2 3 &amp; 4 + 5"
-local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>
-
-
-<pre class="prettyprint lang-lua">r:unescape(string) -- Unescapes an URL-escaped string:
-
-local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
-local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 &amp; 4 + 5'</pre>
-
-
-<pre class="prettyprint lang-lua">r:construct_url(string) -- Constructs an URL from an URI
-
-local url = r:construct_url(r.uri)</pre>
-
-
-<pre class="prettyprint lang-lua">r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
-
-local mpm = r.mpm_query(14)
-if mpm == 1 then
-    r:puts("This server uses the Event MPM")
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
-
-if r:expr("%{HTTP_HOST} =~ /^www/") then
-    r:puts("This host name starts with www")
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
-
-local process = r:scoreboard_process(1)
-r:puts("Server 1 has PID " .. process.pid)</pre>
-
-
-<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
-
-local thread = r:scoreboard_worker(1, 1)
-r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")</pre>
-
-
-
-<pre class="prettyprint lang-lua">r:clock() -- Returns the current time with microsecond precision</pre>
-
-
-<pre class="prettyprint lang-lua">r:requestbody(filename) -- Reads and returns the request body of a request.
-                -- If 'filename' is specified, it instead saves the
-                -- contents to that file:
-                
-local input = r:requestbody()
-r:puts("You sent the following request body to me:\n")
-r:puts(input)</pre>
-
-
-<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter</pre>
-
-
-<pre class="prettyprint lang-lua">r.module_info(module_name) -- Queries the server for information about a module
-
-local mod = r.module_info("mod_lua.c")
-if mod then
-    for k, v in pairs(mod.commands) do
-       r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
-    end
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:loaded_modules() -- Returns a list of modules loaded by httpd:
-
-for k, module in pairs(r:loaded_modules()) do
-    r:puts("I have loaded module " .. module .. "\n")
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file") 
-                         -- relative to the appropriate run-time directory.</pre>
-
-
-<pre class="prettyprint lang-lua">r:server_info() -- Returns a table containing server information, such as 
-                -- the name of the httpd executable file, mpm used etc.</pre>
-
-
-<pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Sets the document root for the request to file_path</pre>
-
-
-
-
-<pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request</pre>
-
-
-<pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way</pre>
-
-
-<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Escapes a string for logging</pre>
-
-
-<pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
-                        -- fx. whether 'www.example.com' matches '*.example.com':
-                        
-local match = r.strcmp_match("foobar.com", "foo*.com")
-if match then 
-    r:puts("foobar.com matches foo*.com")
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.</pre>
-
-
-<pre class="prettyprint lang-lua">r:make_etag() -- Constructs and returns the etag for the current request.</pre>
-
-
-<pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
-                       -- if 'clear' is true, available headers will be sent and cleared.</pre>
-
-
-<pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
-                               -- This works much like the ErrorDocument directive:
-                               
-r:custom_response(404, "Baleted!")</pre>
-
-
-<pre class="prettyprint lang-lua">r.exists_config_define(string) -- Checks whether a configuration definition exists or not:
-
-if r.exists_config_define("FOO") then
-    r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
-end</pre>
-
-
-<pre class="prettyprint lang-lua">r:state_query(string) -- Queries the server for state information</pre>
+          <td>no</td>
+          <td>The IP of the user agent making the request</td>
+        </tr>
+</table>
+           </dd>
+    </dl>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="functions" id="functions">Built in functions</a></h2>
 
+<p>The request_rec object has (at least) the following methods:</p>
 
-<pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Runs stat() on a file, and returns a table with file information:
+<pre class="prettyprint lang-lua">r:flush()   -- flushes the output buffer.
+            -- Returns true if the flush was successful, false otherwise.
 
-local info = r:stat("/var/www/foo.txt")
-if info then
-    r:puts("This file exists and was last modified at: " .. info.modified)
+while we_have_stuff_to_send do
+    r:puts("Bla bla bla\n") -- print something to client
+    r:flush() -- flush the buffer (send to client)
+    r.usleep(500000) -- fake processing time for 0.5 sec. and repeat
 end</pre>
 
 
-<pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Runs a regular expression match on a string, returning captures if matched:
+<pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- add an output filter:
 
-local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
-if matches then
-    r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
-end
+r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream</pre>
 
--- Example ignoring case sensitivity:
-local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
 
--- Flags can be a bitwise combination of:
--- 0x01: Ignore case
--- 0x02: Multiline search</pre>
+<pre class="prettyprint lang-lua">r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
 
+if use_sendfile_thing then
+    r:sendfile("/var/www/large_file.img")
+end</pre>
 
-<pre class="prettyprint lang-lua">r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.</pre>
 
+<pre class="prettyprint lang-lua">r:parseargs() -- returns two tables; one standard key/value table for regular GET data, 
+              -- and one for multi-value data (fx. foo=1&amp;foo=2&amp;foo=3):
 
-<pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
-                        -- See '<a href="#databases">Database connectivity</a>' for details.</pre>
+local GET, GETMULTI = r:parseargs()
+r:puts("Your name is: " .. GET['name'] or "Unknown")</pre>
 
 
-<pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Set an Inter-VM variable to hold a specific value.
-                        -- These values persist even though the VM is gone or not being used,
-                        -- and so should only be used if MaxConnectionsPerChild is &gt; 0
-                        -- Values can be numbers, strings and booleans, and are stored on a 
-                        -- per process basis (so they won't do much good with a prefork mpm)
-                        
-r:ivm_get("key")        -- Fetches a variable set by ivm_set. Returns the contents of the variable
-                        -- if it exists or nil if no such variable exists.
-                        
--- An example getter/setter that saves a global variable outside the VM:
-function handle(r)
-    -- First VM to call this will get no value, and will have to create it
-    local foo = r:ivm_get("cached_data")
-    if not foo then
-        foo = do_some_calcs() -- fake some return value
-        r:ivm_set("cached_data", foo) -- set it globally
-    end
-    r:puts("Cached data is: ", foo)
-end</pre>
+<pre class="prettyprint lang-lua">r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
+                         -- just like r:parseargs().
+                         -- An optional number may be passed to specify the maximum number 
+                         -- of bytes to parse. Default is 8192 bytes:
+                 
+local POST, POSTMULTI = r:parsebody(1024*1024)
+r:puts("Your name is: " .. POST['name'] or "Unknown")</pre>
 
 
-<pre class="prettyprint lang-lua">r:htpassword(string [,algorithm [,cost]]) -- Creates a password hash from a string.
-                                          -- algorithm: 0 = APMD5 (default), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
-                                          -- cost: only valid with BCRYPT algorithm (default = 5).</pre>
+<pre class="prettyprint lang-lua">r:puts("hello", " world", "!") -- print to response body, self explanatory</pre>
 
 
-<pre class="prettyprint lang-lua">r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode paramter.</pre>
+<pre class="prettyprint lang-lua">r:write("a single string") -- print to response body, self explanatory</pre>
 
 
-<pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode paramter.</pre>
+<pre class="prettyprint lang-lua">r:escape_html("&lt;html&gt;test&lt;/html&gt;") -- Escapes HTML code and returns the escaped result</pre>
 
 
-<pre class="prettyprint lang-lua">r:rmdir(dir) -- Removes a directory.</pre>
+<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
 
+local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>
 
-<pre class="prettyprint lang-lua">r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.</pre>
 
+<pre class="prettyprint lang-lua">r:base64_decode(string) -- Decodes a Base64-encoded string:
 
-<pre class="prettyprint lang-lua">r:get_direntries(dir) -- Returns a table with all directory entries.
+local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>
 
-function handle(r)
-  local dir = r.context_document_root
-  for _, f in ipairs(r:get_direntries(dir)) do
-    local info = r:stat(dir .. "/" .. f)
-    if info then
-      local mtime = os.date(fmt, info.mtime / 1000000)
-      local ftype = (info.filetype == 2) and "[dir] " or "[file]"
-      r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
-    end
-  end
-end</pre>
 
+<pre class="prettyprint lang-lua">r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
 
-<pre class="prettyprint lang-lua">r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.</pre>
+local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>
 
 
-<pre class="prettyprint lang-lua">r:getcookie(key) -- Gets a HTTP cookie</pre>
+<pre class="prettyprint lang-lua">r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
 
+local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>
 
-<pre class="prettyprint lang-lua">r:setcookie{
-  key = [key],
-  value = [value],
-  expires = [expiry],
-  secure = [boolean],
-  httponly = [boolean],
-  path = [path],
-  domain = [domain]
-} -- Sets a HTTP cookie, for instance:
 
-r:setcookie{
-  key = "cookie1",
-  value = "HDHfa9eyffh396rt",
-  expires = os.time() + 86400,
-  secure = true
-}</pre>
+<pre class="prettyprint lang-lua">r:escape(string) -- URL-Escapes a string:
 
+local url = "http://foo.bar/1 2 3 &amp; 4 + 5"
+local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>
 
-<pre class="prettyprint lang-lua">r:wsupgrade() -- Upgrades a connection to WebSockets if possible (and requested):
-if r:wsupgrade() then -- if we can upgrade:
-    r:wswrite("Welcome to websockets!") -- write something to the client
-    r:wsclose()  -- goodbye!
-end</pre>
 
+<pre class="prettyprint lang-lua">r:unescape(string) -- Unescapes an URL-escaped string:
 
-<pre class="prettyprint lang-lua">r:wsread() -- Reads a WebSocket frame from a WebSocket upgraded connection (see above):
+local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
+local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 &amp; 4 + 5'</pre>
 
-local line, isFinal = r:wsread() -- isFinal denotes whether this is the final frame.
-                                 -- If it isn't, then more frames can be read
-r:wswrite("You wrote: " .. line)</pre>
 
+<pre class="prettyprint lang-lua">r:construct_url(string) -- Constructs an URL from an URI
 
-<pre class="prettyprint lang-lua">r:wswrite(line) -- Writes a frame to a WebSocket client:
-r:wswrite("Hello, world!")</pre>
+local url = r:construct_url(r.uri)</pre>
 
 
-<pre class="prettyprint lang-lua">r:wsclose() -- Closes a WebSocket request and terminates it for httpd:
+<pre class="prettyprint lang-lua">r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
 
-if r:wsupgrade() then
-    r:wswrite("Write something: ")
-    local line = r:wsread() or "nothing"
-    r:wswrite("You wrote: " .. line);
-    r:wswrite("Goodbye!")
-    r:wsclose()
+local mpm = r.mpm_query(14)
+if mpm == 1 then
+    r:puts("This server uses the Event MPM")
 end</pre>
 
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="logging" id="logging">Logging Functions</a></h2>
-
-<pre class="prettyprint lang-lua">        -- examples of logging messages<br />
-        r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
-        r:debug("This is a debug log message")<br />
-        r:info("This is an info log message")<br />
-        r:notice("This is a notice log message")<br />
-        r:warn("This is a warn log message")<br />
-        r:err("This is an err log message")<br />
-        r:alert("This is an alert log message")<br />
-        r:crit("This is a crit log message")<br />
-        r:emerg("This is an emerg log message")<br />
-</pre>
-
+<pre class="prettyprint lang-lua">r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="apache2" id="apache2">apache2 Package</a></h2>
-<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
-<dl>
-  <dt>apache2.OK</dt>
-  <dd>internal constant OK.  Handlers should return this if they've
-  handled the request.</dd>
-  <dt>apache2.DECLINED</dt>
-  <dd>internal constant DECLINED.  Handlers should return this if
-  they are not going to handle the request.</dd>
-  <dt>apache2.DONE</dt>
-  <dd>internal constant DONE.</dd>
-  <dt>apache2.version</dt>
-  <dd>Apache HTTP server version string</dd>
-  <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
-  <dd>HTTP status code</dd>
-  <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
-  <dd>internal constants used by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd>
-  <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>
-  <dd>internal constants used by <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></dd>
+if r:expr("%{HTTP_HOST} =~ /^www/") then
+    r:puts("This host name starts with www")
+end</pre>
 
-</dl>
-<p>(Other HTTP status codes are not yet implemented.)</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="modifying_buckets" id="modifying_buckets">Modifying contents with Lua filters</a></h2>
-    
-    <p>
-    Filter functions implemented via <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code> 
-    or <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> are designed as 
-    three-stage non-blocking functions using coroutines to suspend and resume a 
-    function as buckets are sent down the filter chain. The core structure of 
-    such a function is:
-    </p>
-    <pre class="prettyprint lang-lua">function filter(r)
-    -- Our first yield is to signal that we are ready to receive buckets.
-    -- Before this yield, we can set up our environment, check for conditions,
-    -- and, if we deem it necessary, decline filtering a request alltogether:
-    if something_bad then
-        return -- This would skip this filter.
-    end
-    -- Regardless of whether we have data to prepend, a yield MUST be called here.
-    -- Note that only output filters can prepend data. Input filters must use the 
-    -- final stage to append data to the content.
-    coroutine.yield([optional header to be prepended to the content])
-    
-    -- After we have yielded, buckets will be sent to us, one by one, and we can 
-    -- do whatever we want with them and then pass on the result.
-    -- Buckets are stored in the global variable 'bucket', so we create a loop
-    -- that checks if 'bucket' is not nil:
-    while bucket ~= nil do
-        local output = mangle(bucket) -- Do some stuff to the content
-        coroutine.yield(output) -- Return our new content to the filter chain
-    end
 
-    -- Once the buckets are gone, 'bucket' is set to nil, which will exit the 
-    -- loop and land us here. Anything extra we want to append to the content
-    -- can be done by doing a final yield here. Both input and output filters 
-    -- can append data to the content in this phase.
-    coroutine.yield([optional footer to be appended to the content])
-end</pre>
+<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="databases" id="databases">Database connectivity</a></h2>
-    
-    <p>
-    Mod_lua implements a simple database feature for querying and running commands
-    on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle)
-    as well as mod_dbd.
-    </p>
-    <p>The example below shows how to acquire a database handle and return information from a table:</p>
-    <pre class="prettyprint lang-lua">function handle(r)
-    -- Acquire a database handle
-    local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
-    if not err then
-        -- Select some information from it
-        local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
-        if not err then
-            local rows = results(0) -- fetch all rows synchronously
-            for k, row in pairs(rows) do
-                r:puts( string.format("Name: %s, Age: %s&lt;br/&gt;", row[1], row[2]) )
-            end
-        else
-            r:puts("Database query error: " .. err)
-        end
-        database:close()
-    else
-        r:puts("Could not connect to the database: " .. err)
-    end
-end</pre>
+local process = r:scoreboard_process(1)
+r:puts("Server 1 has PID " .. process.pid)</pre>
 
-    <p>
-    To utilize <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, specify <code>mod_dbd</code>
-    as the database type, or leave the field blank:
-    </p>
-    <pre class="prettyprint lang-lua">local database = r:dbacquire("mod_dbd")</pre>
 
-    <h3><a name="database_object" id="database_object">Database object and contained functions</a></h3>
-        
-        <p>The database object returned by <code>dbacquire</code> has the following methods:</p>
-        <p><strong>Normal select and query from a database:</strong></p>
-    <pre class="prettyprint lang-lua">-- Run a statement and return the number of rows affected:
-local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
+<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
 
--- Run a statement and return a result set that can be used synchronously or async:
-local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")</pre>
+local thread = r:scoreboard_worker(1, 1)
+r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")</pre>
 
-        <p><strong>Using prepared statements (recommended):</strong></p>
-    <pre class="prettyprint lang-lua">-- Create and run a prepared statement:
-local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` &gt; %u")
-if not errmsg then
-    local result, errmsg = statement:query(20) -- run the statement with age &gt; 20
-end
 
--- Fetch a prepared statement from a DBDPrepareSQL directive:
-local statement, errmsg = database:prepared(r, "someTag")
-if not errmsg then
-    local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
-end</pre>
 
-        <p><strong>Escaping values, closing databases etc:</strong></p>
-    <pre class="prettyprint lang-lua">-- Escape a value for use in a statement:
-local escaped = database:escape(r, [["'|blabla]])
+<pre class="prettyprint lang-lua">r:clock() -- Returns the current time with microsecond precision</pre>
 
--- Close a database connection and free up handles:
-database:close()
 
--- Check whether a database connection is up and running:
-local connected = database:active()</pre>
+<pre class="prettyprint lang-lua">r:requestbody(filename) -- Reads and returns the request body of a request.
+                -- If 'filename' is specified, it instead saves the
+                -- contents to that file:
+                
+local input = r:requestbody()
+r:puts("You sent the following request body to me:\n")
+r:puts(input)</pre>
 
-    
-    <h3><a name="result_sets" id="result_sets">Working with result sets</a></h3>
-    
-    <p>The result set returned by <code>db:select</code> or by the prepared statement functions 
-    created through <code>db:prepare</code> can be used to
-    fetch rows synchronously or asynchronously, depending on the row number specified:<br />
-    <code>result(0)</code> fetches all rows in a synchronous manner, returning a table of rows.<br />
-    <code>result(-1)</code> fetches the next available row in the set, asynchronously.<br />
-    <code>result(N)</code> fetches row number <code>N</code>, asynchronously:
-    </p>
-    <pre class="prettyprint lang-lua">-- fetch a result set using a regular query:
-local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
 
-local rows = result(0) -- Fetch ALL rows synchronously
-local row = result(-1) -- Fetch the next available row, asynchronously
-local row = result(1234) -- Fetch row number 1234, asynchronously
-local row = result(-1, true) -- Fetch the next available row, using row names as key indexes.</pre>
+<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter</pre>
 
-    <p>One can construct a function that returns an iterative function to iterate over all rows 
-    in a synchronous or asynchronous way, depending on the async argument:
-    </p>
-    <pre class="prettyprint lang-lua">function rows(resultset, async)
-    local a = 0
-    local function getnext()
-        a = a + 1
-        local row = resultset(-1)
-        return row and a or nil, row
-    end
-    if not async then
-        return pairs(resultset(0))
-    else
-        return getnext, self
-    end
-end
 
-local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` &gt; %u")
-if not err then
-     -- fetch rows asynchronously:
-    local result, err = statement:select(20)
-    if not err then
-        for index, row in rows(result, true) do
-            ....
-        end
-    end
+<pre class="prettyprint lang-lua">r.module_info(module_name) -- Queries the server for information about a module
 
-     -- fetch rows synchronously:
-    local result, err = statement:select(20)
-    if not err then
-        for index, row in rows(result, false) do
-            ....
-        end
+local mod = r.module_info("mod_lua.c")
+if mod then
+    for k, v in pairs(mod.commands) do
+       r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
     end
 end</pre>
 
-    
-    <h3><a name="closing_databases" id="closing_databases">Closing a database connection</a></h3>
-        
 
-    <p>Database handles should be closed using <code>database:close()</code> when they are no longer
-    needed. If you do not close them manually, they will eventually be garbage collected and 
-    closed by mod_lua, but you may end up having too many unused connections to the database 
-    if you leave the closing up to mod_lua. Essentially, the following two measures are
-    the same:
-    </p>
-    <pre class="prettyprint lang-lua">-- Method 1: Manually close a handle
-local database = r:dbacquire("mod_dbd")
-database:close() -- All done
+<pre class="prettyprint lang-lua">r:loaded_modules() -- Returns a list of modules loaded by httpd:
 
--- Method 2: Letting the garbage collector close it

[... 997 lines stripped ...]


Mime
View raw message