mod_lua.xml revision b09343eab0cfb21abbd0f11c484282d1d0fdd12b
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<p>This module allows the server to be extended with scripts written in the
889dc1728817c1c56d0c8d894c768614e346d86ecovenerLua programming language. The extension points (hooks) available with
889dc1728817c1c56d0c8d894c768614e346d86ecovener<module>mod_lua</module> include many of the hooks available to
889dc1728817c1c56d0c8d894c768614e346d86ecovenernatively compiled Apache HTTP Server modules, such as mapping requests to
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimfiles, generating dynamic responses, access control, authentication, and
889dc1728817c1c56d0c8d894c768614e346d86ecovenerauthorization</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<p>More information on the Lua programming language can be found at the
889dc1728817c1c56d0c8d894c768614e346d86ecovener<a href="http://www.lua.org/">the Lua website</a>.</p>
8548ace6aa09b4d3e463254b53865fb38fbbbc78poirier<note><code>mod_lua</code> is still in experimental state.
8548ace6aa09b4d3e463254b53865fb38fbbbc78poirierUntil it is declared stable, usage and behavior may change
8ad875ad9725307fd052e36abc2938f89f56902csfat any time, even between stable releases of the 2.4.x series.
8ad875ad9725307fd052e36abc2938f89f56902csfBe sure to check the CHANGES file before upgrading.</note>
fb51a6b789d85113d0976148685b0063c294220drbowen<p>This module holds a great deal of power over httpd, which is both a
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenstrength and a potential security risk. It is <strong>not</strong> recommended
fb51a6b789d85113d0976148685b0063c294220drbowenthat you use this module on a server that is shared with users you do not
3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowentrust, as it can be abused to change the internal workings of httpd.</p>
fb51a6b789d85113d0976148685b0063c294220drbowen<section id="basicconf"><title>Basic Configuration</title>
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen</highlight>
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<code>mod_lua</code> provides a handler named <code>lua-script</code>,
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierwhich can be used with an <code>AddHandler</code> directive:</p>
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenAddHandler lua-script .lua
92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>
92e5d4326ae44f79da5cb049470daba604506846poirierThis will cause <code>mod_lua</code> to handle requests for files
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<p>For more flexibility, see <directive>LuaMapHandler</directive>.
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<section id="writinghandlers"><title>Writing Handlers</title>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<p> In the Apache HTTP Server API, the handler is a specific kind of hook
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenresponsible for generating the response. Examples of modules that include a
880f77d700bc15c83bb541a053cd56e89cbfb8bchumbedoohhandler are <module>mod_proxy</module>, <module>mod_cgi</module>,
92e5d4326ae44f79da5cb049470daba604506846poirier<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
92e5d4326ae44f79da5cb049470daba604506846poirierjust evaluating a script body CGI style. A handler function looks
92e5d4326ae44f79da5cb049470daba604506846poiriersomething like this:</p>
cf7d90693f7579700c4f7e663adb83196f903df1covener-- example handler
cf7d90693f7579700c4f7e663adb83196f903df1covenerrequire "string"
92e5d4326ae44f79da5cb049470daba604506846poirier This is the default method name for Lua handlers, see the optional
92e5d4326ae44f79da5cb049470daba604506846poirier function-name in the LuaMapHandler directive to choose a different
92e5d4326ae44f79da5cb049470daba604506846poirier entry point.
8a0b66c25933ca8581954e6600c5b4f1e97dc738humbedoohfunction handle(r)
92e5d4326ae44f79da5cb049470daba604506846poirier r:puts("Hello Lua World!\n")
92e5d4326ae44f79da5cb049470daba604506846poirier if r.method == 'GET' then
92e5d4326ae44f79da5cb049470daba604506846poirier for k, v in pairs( r:parseargs() ) do
e1fcc3befbb69aab09018a6b8fe15d8816a16076humbedooh r:puts( string.format("%s: %s\n", k, v) )
92e5d4326ae44f79da5cb049470daba604506846poirier elseif r.method == 'POST' then
880f77d700bc15c83bb541a053cd56e89cbfb8bchumbedooh for k, v in pairs( r:parsebody() ) do
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:puts( string.format("%s: %s\n", k, v) )
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:puts("Unsupported HTTP method " .. r.method)
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</highlight>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenThis handler function just prints out the uri or form encoded
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowenarguments to a plaintext page.
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfThis means (and in fact encourages) that you can have multiple
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfhandlers (or hooks, or filters) in the same script.
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<p><module>mod_authz_core</module> provides a high-level interface to
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfauthorization that is much easier to use than using into the relevant
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfhooks directly. The first argument to the
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<directive module="mod_authz_core">Require</directive> directive gives
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfthe name of the responsible authorization provider. For any
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<directive module="mod_authz_core">Require</directive> line,
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<module>mod_authz_core</module> will call the authorization provider
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfof the given name, passing the rest of the line as parameters. The
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfprovider will then check authorization and pass the result as return
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<p>The authz provider is normally called before authentication. If it needs to
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfknow the authenticated user name (or if the user will be authenticated at
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfall), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfThis will cause authentication to proceed and the authz provider to be
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfcalled a second time.</p>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<p>The following authz provider function takes two arguments, one ip
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfaddress and one user name. It will allow access from the given ip address
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfwithout authentication, or if the authenticated user matches the second
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfargument:</p>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfrequire 'apache2'
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sffunction authz_check_foo(r, ip, user)
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf if r.useragent_ip == ip then
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf elseif r.user == nil then
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf elseif r.user == user then
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf</highlight>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<p>The following configuration registers this function as provider
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf<code>foo</code> and configures it for URL <code>/</code>:</p>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfLuaAuthzProvider foo authz_provider.lua authz_check_foo
92e5d4326ae44f79da5cb049470daba604506846poirier<Location />
92e5d4326ae44f79da5cb049470daba604506846poirier Require foo 10.1.2.3 john_doe
889dc1728817c1c56d0c8d894c768614e346d86ecovener</Location>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim</highlight>
889dc1728817c1c56d0c8d894c768614e346d86ecovener<section id="writinghooks"><title>Writing Hooks</title>
92e5d4326ae44f79da5cb049470daba604506846poirier<p>Hook functions are how modules (and Lua scripts) participate in the
92e5d4326ae44f79da5cb049470daba604506846poirierprocessing of requests. Each type of hook exposed by the server exists for
92e5d4326ae44f79da5cb049470daba604506846poiriera specific purpose, such as mapping requests to the filesystem,
92e5d4326ae44f79da5cb049470daba604506846poirierperforming access control, or setting mimetypes:</p>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <td><directive module="mod_lua">LuaQuickHandler</directive></td>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <td>This is the first hook that will be called after a request has
bb57315f942d09c744543fe41e453bd0181fd93ecovener been mapped to a host or virtual host</td>
880f77d700bc15c83bb541a053cd56e89cbfb8bchumbedooh <td><directive module="mod_lua">LuaHookTranslateName</directive></td>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <td>This phase translates the requested URI into a filename on the
880f77d700bc15c83bb541a053cd56e89cbfb8bchumbedooh system. Modules such as <module>mod_alias</module> and
880f77d700bc15c83bb541a053cd56e89cbfb8bchumbedooh <module>mod_rewrite</module> operate in this phase.</td>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td><directive module="mod_lua">LuaHookMapToStorage</directive></td>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <td>This phase maps files to their physical, cached or external/proxied storage.
bb57315f942d09c744543fe41e453bd0181fd93ecovener It can be used by proxy or caching modules</td>
92e5d4326ae44f79da5cb049470daba604506846poirier <td><directive module="mod_lua">LuaHookAccessChecker</directive></td>
92e5d4326ae44f79da5cb049470daba604506846poirier <td>This phase checks whether a client has access to a resource. This
92e5d4326ae44f79da5cb049470daba604506846poirier phase is run before the user is authenticated, so beware.
92e5d4326ae44f79da5cb049470daba604506846poirier <td><directive module="mod_lua">LuaHookCheckUserID</directive></td>
92e5d4326ae44f79da5cb049470daba604506846poirier <td>This phase it used to check the negotiated user ID</td>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td><directive module="mod_lua">LuaHookAuthChecker</directive> or
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <directive module="mod_lua">LuaAuthzProvider</directive></td>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>This phase authorizes a user based on the negotiated credentials, such as
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen user ID, client certificate etc.
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td><directive module="mod_lua">LuaHookTypeChecker</directive></td>
92e5d4326ae44f79da5cb049470daba604506846poirier <td>This phase checks the requested file and assigns a content type and
92e5d4326ae44f79da5cb049470daba604506846poirier a handler to it</td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td><directive module="mod_lua">LuaHookFixups</directive></td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This is the final "fix anything" phase before the content handlers
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier are run. Any last-minute changes to the request should be made here.</td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>fx. <code>.lua</code> files or through <directive module="mod_lua">LuaMapHandler</directive></td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>This is where the content is handled. Files are read, parsed, some are run,
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier and the result is sent to the client</td>
fc57cc74ee4e73618f74a7a62ea6ac77546666dacovener <td>Once a request has been handled, it enters several logging phases,
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier which logs the request in either the error or access log</td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<p>Hook functions are passed the request object as their only argument
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier(except for LuaAuthzProvider, which also gets passed the arguments from
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierthe Require directive).
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierThey can return any value, depending on the hook, but most commonly
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierthey'll return OK, DONE, or DECLINED, which you can write in lua as
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<code>apache2.OK</code>, <code>apache2.DONE</code>, or
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier-- example hook that rewrites the URI to a filesystem path.
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierrequire 'apache2'
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierfunction translate_name(r)
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier if r.uri == "/translate-name" then
f5b3f41700a107b9df2b3c5a1cc3e5ea775fd8fesf -- we don't care about this URL, give another module a chance
f5b3f41700a107b9df2b3c5a1cc3e5ea775fd8fesf</highlight>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier--[[ example hook that rewrites one URI to another URI. It returns a
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier apache2.DECLINED to give other URL mappers a chance to work on the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier substitution, including the core translate_name hook which maps based
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier on the DocumentRoot.
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier Note: Use the early/late flags in the directive to make it run before
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier or after mod_alias.
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierrequire 'apache2'
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierfunction translate_name(r)
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier if r.uri == "/translate-name" then
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener</highlight>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<section id="datastructures"><title>Data Structures</title>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>The request_rec is mapped in as a userdata. It has a metatable
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier which lets you do useful things with it. For the most part it
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier has the same fields as the request_rec struct, many of which are writeable as
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier well as readable. (The table fields' content can be changed, but the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier fields themselves cannot be set to different tables.)</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>The AllowOverride options applied to the current request.</td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>If an authentication check was made, this is set to the type
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>The query string arguments extracted from the request
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <td>Set to true if this is an HTTP/0.9 style request
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener (e.g. <code>GET /foo</code> (with no headers) )</td>
8230057b2a5c382433ec1d7a9d1e3f1bb1daa87acovener <td>The realm name used for authorization (if applicable).</td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>The server banner, f.x. <code>Apache HTTP Server/2.4.3 openssl/0.9.8c</code></td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>The basic auth password sent with this request, if any</td>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>The content encoding of the current request</td>
f5b3f41700a107b9df2b3c5a1cc3e5ea775fd8fesf <td>The content type of the current request, as determined in the
f5b3f41700a107b9df2b3c5a1cc3e5ea775fd8fesf type_check phase (f.x. <code>image/gif</code> or <code>text/html</code>)</td>
2537429a9c5d4388773bb77437e04e5f779bb176humbedooh <td>MIME header environment for the response, printed even on errors and
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier persist across internal redirects</td>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen changed in the translate-name or map-to-storage phases of a request to allow the
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen default handler (or script handlers) to serve a different file than what was requested.</td>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <td>The name of the <a href="/handler.html">handler</a> that should serve this request, f.x.
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <code>lua-script</code> if it is to be served by mod_lua. This is typically set by the
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <directive module="mod_mime">AddHandler</directive> or <directive module="core">SetHandler</directive>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen directives, but could also be set via mod_lua to allow another handler to serve up a specific request
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen that would otherwise not be served by it.
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <td>MIME header environment from the request. This contains headers such as <code>Host,
7152f5d04e3782c5e93016ae2ccd960f8538b83bcovener <td>The host name, as set by the <code>Host:</code> header or by a full URI.</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>Whether or not this request is done via HTTPS</td>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>Whether this request is the initial request or a sub-request</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>The size limit of the request body for this request, or 0 if no limit.</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>The ID to identify request in access and error log.</td>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>The request method, f.x. <code>GET</code> or <code>POST</code>.</td>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>A list of notes that can be passed on from one module to another.</td>
c994f52ac80f9664d2940e5ccd9e77466572013frbowen <td>The Options directive applied to the current request.</td>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>The protocol used, f.x. <code>HTTP/1.1</code></td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>Denotes whether this is a proxy request or not. This value is generally set in
fb51a6b789d85113d0976148685b0063c294220drbowen the post_read_request/translate_name phase of a request.</td>
fb926c8c319705c9fe42d55a6ad13d9b0972cb72humbedooh <td>The contents of the <code>Range:</code> header.</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>The number of bytes remaining to be read from the request body.</td>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>Whether some authorization is/was required for this request.</td>
6265962c731aed3af3aa7242b35852f3f181d437humbedooh <td>The environment variables set for this request.</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>The time the server was (re)started, in seconds since the epoch (Jan 1st, 1970)</td>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic <td>The (current) HTTP return code for this request, f.x. <code>200</code> or <code>404</code>.</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>The request string as sent by the client, f.x. <code>GET /foo/bar HTTP/1.1</code>.</td>
fb51a6b789d85113d0976148685b0063c294220drbowen <td>If an authentication check has been made, this is set to the name of the authenticated user.</td>
6265962c731aed3af3aa7242b35852f3f181d437humbedooh<section id="functions"><title>Built in functions</title>
6265962c731aed3af3aa7242b35852f3f181d437humbedooh<p>The request_rec object has (at least) the following methods:</p>
c994f52ac80f9664d2940e5ccd9e77466572013frbowenr:flush() -- flushes the output buffer:
c994f52ac80f9664d2940e5ccd9e77466572013frbowenwhile we_have_stuff_to_send do
fb51a6b789d85113d0976148685b0063c294220drbowen r:puts("Bla bla bla\n") -- print something to client
fb51a6b789d85113d0976148685b0063c294220drbowen r:flush() -- flush the buffer (send to client)
fb51a6b789d85113d0976148685b0063c294220drbowen r:sleep(0.5) -- fake processing time and repeat
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:addoutputfilter(name|function) -- add an output filter:
99e316bc4b9b2b5754165939ac14b6d16132cce1igalicr:addoutputfilter("fooFilter") -- add the fooFilter to the output stream
247c1db2eb82d5c836df7bafc7380887890e11a2rjung</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimif use_sendfile_thing then
fb51a6b789d85113d0976148685b0063c294220drbowen</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:parseargs() -- returns a Lua table containing the request's query string arguments:
fb51a6b789d85113d0976148685b0063c294220drbowenlocal GET = r:parseargs()
fb51a6b789d85113d0976148685b0063c294220drbowenr:puts("Your name is: " .. GET['name'] or "Unknown")
fb51a6b789d85113d0976148685b0063c294220drbowen</highlight>
6265962c731aed3af3aa7242b35852f3f181d437humbedoohr:parsebody([sizeLimit]) -- parse the request body as a POST and return a lua table.
92e5d4326ae44f79da5cb049470daba604506846poirier -- An optional number may be passed to specify the maximum number
92e5d4326ae44f79da5cb049470daba604506846poirier -- of bytes to parse. Default is 8192 bytes:
92e5d4326ae44f79da5cb049470daba604506846poirierlocal POST = r:parsebody(1024*1024)
880f77d700bc15c83bb541a053cd56e89cbfb8bchumbedoohr:puts("Your name is: " .. POST['name'] or "Unknown")
92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>
92e5d4326ae44f79da5cb049470daba604506846poirierr:puts("hello", " world", "!") -- print to response body, self explanatory
76c23dcc502f814f6b988038d600719db07d28becovener</highlight>
92e5d4326ae44f79da5cb049470daba604506846poirierr:write("a single string") -- print to response body, self explanatory
92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result
457256c49209d6e56bfe63b411688ad9cb2a8429covener</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
457256c49209d6e56bfe63b411688ad9cb2a8429covenerlocal encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=
457256c49209d6e56bfe63b411688ad9cb2a8429covener</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:base64_decode(string) -- Decodes a Base64-encoded string:
fb51a6b789d85113d0976148685b0063c294220drbowenlocal decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
99e316bc4b9b2b5754165939ac14b6d16132cce1igaliclocal hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</highlight>
3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowenr:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowenlocal hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19
3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowen</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:escape(string) -- URL-Escapes a string:
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowenlocal url = "http://foo.bar/1 2 3 & 4 + 5"
fb51a6b789d85113d0976148685b0063c294220drbowenlocal escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</highlight>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalicr:unescape(string) -- Unescapes an URL-escaped string:
fb51a6b789d85113d0976148685b0063c294220drbowenlocal url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
fb51a6b789d85113d0976148685b0063c294220drbowenlocal unescaped = r:escape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5'
fb51a6b789d85113d0976148685b0063c294220drbowen</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
99e316bc4b9b2b5754165939ac14b6d16132cce1igaliclocal mpm = r.mpm_query(14)
99e316bc4b9b2b5754165939ac14b6d16132cce1igalicif mpm == 1 then
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic r:puts("This server uses the Event MPM")
457256c49209d6e56bfe63b411688ad9cb2a8429covener</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:expr(string) -- Evaluates an <a href="/expr.html">expr</a> string.
fb51a6b789d85113d0976148685b0063c294220drbowenif r:expr("%{HTTP_HOST} =~ /^www/") then
fb51a6b789d85113d0976148685b0063c294220drbowen r:puts("This host name starts with www")
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen</highlight>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalicr:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
99e316bc4b9b2b5754165939ac14b6d16132cce1igaliclocal process = r:scoreboard_process(1)
fb51a6b789d85113d0976148685b0063c294220drbowenr:puts("Server 1 has PID " .. process.pid)
fb51a6b789d85113d0976148685b0063c294220drbowen</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
457256c49209d6e56bfe63b411688ad9cb2a8429covenerlocal thread = r:scoreboard_worker(1, 1)
99e316bc4b9b2b5754165939ac14b6d16132cce1igalicr:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</highlight>
247c1db2eb82d5c836df7bafc7380887890e11a2rjungr:started() -- Returns the time of the last server (re)start
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</highlight>
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr:clock() -- Returns the current time with microsecond precision
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</highlight>
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr:requestbody(filename) -- Reads and returns the request body of a request.
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier -- If 'filename' is specified, it instead saves the
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier -- contents to that file:
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierlocal input = r:requestbody()
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr:puts("You sent the following request body to me:\n")
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr:puts(input)
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</highlight>
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</highlight>
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr.module_info(module_name) -- Queries the server for information about a module
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier for k, v in pairs(mod.commands) do
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier</highlight>
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierr:loaded_modules() -- Returns a list of modules loaded by httpd:
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirierfor k, module in pairs(r:loaded_modules()) do
768c8bcc0d91d1c3c04b0f80c309d31c6182fbf8poirier r:puts("I have loaded module " .. module .. "\n")
457256c49209d6e56bfe63b411688ad9cb2a8429covener</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
fb51a6b789d85113d0976148685b0063c294220drbowen -- relative to the appropriate run-time directory.
fb51a6b789d85113d0976148685b0063c294220drbowen</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:server_info() -- Returns a table containing server information, such as
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic -- the name of the httpd executable file, mpm used etc.
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</highlight>
247c1db2eb82d5c836df7bafc7380887890e11a2rjungr:set_document_root(file_path) -- Sets the document root for the request to file_path
92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covener<highlight language="lua">
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:add_version_component(component_string) - - Adds a component to the server banner.
92e5d4326ae44f79da5cb049470daba604506846poirier</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request
9cd56c73a0fd508522ba2f6bc6c9839c478c61c3rbowen</highlight>
99e316bc4b9b2b5754165939ac14b6d16132cce1igalicr:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependant way
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic</highlight>
fb51a6b789d85113d0976148685b0063c294220drbowenr:escape_logitem(string) -- Escapes a string for logging
fb51a6b789d85113d0976148685b0063c294220drbowen</highlight>
ae600ca541efc686b34f8b1f21bd3d0741d37674covenerr:strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
ae600ca541efc686b34f8b1f21bd3d0741d37674covener -- fx. whether 'www.example.com' matches '*.example.com':
ae600ca541efc686b34f8b1f21bd3d0741d37674covenerlocal match = r:strcmp_match("foobar.com", "foo*.com")
ae600ca541efc686b34f8b1f21bd3d0741d37674covenerif match then
ae600ca541efc686b34f8b1f21bd3d0741d37674covener r:puts("foobar.com matches foo*.com")
448a4db8228c5b9f6c1d3693e7a6b07b8b2b0c5erjung</highlight>
ae600ca541efc686b34f8b1f21bd3d0741d37674covenerr:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.
ae600ca541efc686b34f8b1f21bd3d0741d37674covener</highlight>
ae600ca541efc686b34f8b1f21bd3d0741d37674covenerr:make_etag() -- Constructs and returns the etag for the current request.
ae600ca541efc686b34f8b1f21bd3d0741d37674covener</highlight>
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowenr:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen -- if 'clear' is true, available headers will be sent and cleared.
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen</highlight>
448a4db8228c5b9f6c1d3693e7a6b07b8b2b0c5erjungr:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
99e316bc4b9b2b5754165939ac14b6d16132cce1igalic -- This works much like the ErrorDocument directive:
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr:custom_response(404, "Baleted!")
457256c49209d6e56bfe63b411688ad9cb2a8429covener</highlight>
457256c49209d6e56bfe63b411688ad9cb2a8429covenerr.exists_config_define(string) -- Checks whether a configuration definition exists or not:
6b4cd1f143d5d7244d2476d1e28456212faddb72rbowen r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf</highlight>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfr:state_query(string) -- Queries the server for state information
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf</highlight>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfr:stat(filename) -- Runs stat() on a file, and returns a table with file information:
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfif info then
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf r:puts("This file exists and was last modified at: " .. info.modified)
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf</highlight>
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfr:regex(string, pattern, [flags]) -- Runs a regular expression match on a string, returning captures if matched:
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sflocal matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sfif matches then
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sf-- Example ignoring case sensitivity:
e20c6ecbd465cd7dabb44acea6afafc7925f3a03sflocal matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
<dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
<dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>
coroutine.yield([optional header to be prepended to the content])
coroutine.yield(output) -- Return our new content to the filter chain
coroutine.yield([optional footer to be appended to the content])
<p>The example below shows how to acquire a database handle and return information from a table:</p>
r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
<description>Specify the base path for resolving relative paths for mod_lua directives</description>
states are pooled, allowing f.x. 1000 threads to share only 100 Lua states,
LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
conventions as lua. This just munges the package.path in the
conventions as lua. This just munges the package.cpath in the
until one of them returns apache2.OK. If your hook doesn't
apache2.DECLINED. If the request should stop processing, then
if r.uri == "/" then
return apache2.OK
return apache2.DECLINED
local input = io.open(filename, "r")
if r.filename:match("%.png$") then -- Only match PNG files
local file = cached_files[r.filename] -- Check cache entries
file = read_file(r.filename) -- Read file into cache
r.status = 200
r:info(("Sent %s to client from cache"):format(r.filename))
return apache2.DONE -- skip default handler for PNG files
return apache2.DECLINED -- If we had nothing to do, let others serve this.
r.handler = "gifWizard" -- tell the gifWizard module to handle this
return apache2.OK
return apache2.DECLINED
auth = r.headers_in['Authorization']
r.user = 'foo'
if r.user == nil then
r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
elseif r.user == "foo" then
r:debug("authcheck: user='" .. r.user .. "'")
r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
return apache2.OK
LuaAuthzProvider foo authz.lua authz_check_foo
return apache2.AUTHZ_GRANTED
coroutine.yield() -- Yield and wait for buckets
local output = string.upper(bucket) -- Convert all POST data to uppercase
coroutine.yield(output) -- Send converted data down the chain
coroutine.yield("&filterSignature=1234") -- Append signature at the end
coroutine.yield() -- wait for buckets
coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Prepend some data to the output,
coroutine.yield(output) -- Send converted data down the chain
coroutine.yield() -- wait for buckets