mod_lua.xml revision 1abe2f0d024bcb5d099cef68af06781da4e3270b
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen<!-- $LastChangedRevision$ -->
bdd36cfdba3ff66d25570a9ff568d69e1eb543cfTimo Sirainen Licensed to the Apache Software Foundation (ASF) under one or more
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen contributor license agreements. See the NOTICE file distributed with
8338066be35c696b59fa9aefdc07042cb0797197Timo Sirainen this work for additional information regarding copyright ownership.
f158d9a303bb15a6848ca276c9391c7ca52e452bTimo Sirainen The ASF licenses this file to You under the Apache License, Version 2.0
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen (the "License"); you may not use this file except in compliance with
e1550f6a31306246a8499f5c9ca876096cbbeae9Timo Sirainen the License. You may obtain a copy of the License at
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen Unless required by applicable law or agreed to in writing, software
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen distributed under the License is distributed on an "AS IS" BASIS,
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen See the License for the specific language governing permissions and
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen limitations under the License.
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<description>Provides Lua hooks into various portions of the httpd
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenrequest processing</description>
678d0463849ba777106eb7875f27db07a5d8e3dfTimo Sirainen<p>This module allows the server to be extended with scripts written in the
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo SirainenLua programming language. The extension points (hooks) available with
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<module>mod_lua</module> include many of the hooks available to
378603cc3f3e0bf238347e7e972383d549661272Timo Sirainennatively compiled Apache HTTP Server modules, such as mapping requests to
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainenfiles, generating dynamic responses, access control, authentication, and
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenauthorization</p>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<p>More information on the Lua programming language can be found at the
8338066be35c696b59fa9aefdc07042cb0797197Timo Sirainen<a href="http://www.lua.org/">the Lua website</a>.</p>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<note><code>mod_lua</code> is still in experimental state.
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo SirainenUntil it is declared stable, usage and behavior may change
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenat any time, even between stable releases of the 2.4.x series.
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo SirainenBe sure to check the CHANGES file before upgrading.</note>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<p>This module holds a great deal of power over httpd, which is both a
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenstrength and a potential security risk. It is <strong>not</strong> recommended
91770f85d9b2ac3e91b7aa74f57149412ae33c4cTimo Sirainenthat you use this module on a server that is shared with users you do not
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainentrust, as it can be abused to change the internal workings of httpd.</p>
224414073c72d77a09a77b4dd71500ada5690802Timo Sirainen<section id="basicconf"><title>Basic Configuration</title>
224414073c72d77a09a77b4dd71500ada5690802Timo Sirainen<code>mod_lua</code> provides a handler named <code>lua-script</code>,
224414073c72d77a09a77b4dd71500ada5690802Timo Sirainenwhich can be used with an <code>AddHandler</code> directive:</p>
f158d9a303bb15a6848ca276c9391c7ca52e452bTimo SirainenAddHandler lua-script .lua
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo SirainenThis will cause <code>mod_lua</code> to handle requests for files
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenending in <code>.lua</code> by invoking that file's
e256ae453eb7b4495b3491062bce7c66f2fb1d81Timo Sirainen<p>For more flexibility, see <directive>LuaMapHandler</directive>.
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<section id="writinghandlers"><title>Writing Handlers</title>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<p> In the Apache HTTP Server API, the handler is a specific kind of hook
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenresponsible for generating the response. Examples of modules that include a
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainenhandler are <module>mod_proxy</module>, <module>mod_cgi</module>,
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenjust evaluating a script body CGI style. A handler function looks
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainensomething like this:</p>
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen-- example handler
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenrequire "string"
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen This is the default method name for Lua handlers, see the optional
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen function-name in the LuaMapHandler directive to choose a different
3957200d949c6e96c4184db2395444d723950583Timo Sirainenfunction handle(r)
3957200d949c6e96c4184db2395444d723950583Timo Sirainen r:puts("Hello Lua World!\n")
3957200d949c6e96c4184db2395444d723950583Timo Sirainen if r.method == 'GET' then
3957200d949c6e96c4184db2395444d723950583Timo Sirainen for k, v in pairs( r:parseargs() ) do
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen r:puts( string.format("%s: %s\n", k, v) )
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen elseif r.method == 'POST' then
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen for k, v in pairs( r:parsebody() ) do
e256ae453eb7b4495b3491062bce7c66f2fb1d81Timo Sirainen r:puts( string.format("%s: %s\n", k, v) )
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen r:puts("Unsupported HTTP method " .. r.method)
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo SirainenThis handler function just prints out the uri or form encoded
b2024fa4e6ed39f9b5b6bb6c051f6d535fc0e011Timo Sirainenarguments to a plaintext page.
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo SirainenThis means (and in fact encourages) that you can have multiple
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainenhandlers (or hooks, or filters) in the same script.
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<p><module>mod_authz_core</module> provides a high-level interface to
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainenauthorization that is much easier to use than using into the relevant
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainenhooks directly. The first argument to the
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainen<directive module="mod_authz_core">Require</directive> directive gives
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainenthe name of the responsible authorization provider. For any
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainen<directive module="mod_authz_core">Require</directive> line,
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainen<module>mod_authz_core</module> will call the authorization provider
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainenof the given name, passing the rest of the line as parameters. The
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainenprovider will then check authorization and pass the result as return
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainen<p>The authz provider is normally called before authentication. If it needs to
b2024fa4e6ed39f9b5b6bb6c051f6d535fc0e011Timo Sirainenknow the authenticated user name (or if the user will be authenticated at
b2024fa4e6ed39f9b5b6bb6c051f6d535fc0e011Timo Sirainenall), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
b2024fa4e6ed39f9b5b6bb6c051f6d535fc0e011Timo SirainenThis will cause authentication to proceed and the authz provider to be
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainencalled a second time.</p>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<p>The following authz provider function takes two arguments, one ip
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenaddress and one user name. It will allow access from the given ip address
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainenwithout authentication, or if the authenticated user matches the second
b2024fa4e6ed39f9b5b6bb6c051f6d535fc0e011Timo Sirainenrequire 'apache2'
68787d48554f497e711ff66a087ab31f990a11e9Timo Sirainenfunction authz_check_foo(r, ip, user)
4074caeff651a922131d53e2d8f83585d1b07433Timo Sirainen elseif r.user == nil then
68787d48554f497e711ff66a087ab31f990a11e9Timo Sirainen elseif r.user == user then
68787d48554f497e711ff66a087ab31f990a11e9Timo Sirainen<p>The following configuration registers this function as provider
68787d48554f497e711ff66a087ab31f990a11e9Timo Sirainen<code>foo</code> and configures it for URL <code>/</code>:</p>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo SirainenLuaAuthzProvider foo authz_provider.lua authz_check_foo
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<Location />
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen Require foo 10.1.2.3 john_doe
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen</Location>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<section id="writinghooks"><title>Writing Hooks</title>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen<p>Hook functions are how modules (and Lua scripts) participate in the
678d0463849ba777106eb7875f27db07a5d8e3dfTimo Sirainenprocessing of requests. Each type of hook exposed by the server exists for
678d0463849ba777106eb7875f27db07a5d8e3dfTimo Sirainena specific purposes such as mapping requests to the filesystem,
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainenperforming access control, or setting mimetypes. General purpose hooks
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainenthat simply run at handy times in the request lifecycle exist as well.</p>
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen<p>Hook functions are passed the request object as their only argument.
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo SirainenThey can return any value, depending on the hook, but most commonly
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainenthey'll return OK, DONE, or DECLINED, which you can write in lua as
e1550f6a31306246a8499f5c9ca876096cbbeae9Timo Sirainen<code>apache2.OK</code>, <code>apache2.DONE</code>, or
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen-- example hook that rewrites the URI to a filesystem path.
a10ed8c47534b4c6b6bf2711ccfe577e720a47b4Timo Sirainenrequire 'apache2'
678d0463849ba777106eb7875f27db07a5d8e3dfTimo Sirainenfunction translate_name(r)
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen if r.uri == "/translate-name" then
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen r.filename = r.document_root .. "/find_me.txt"
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen -- we don't care about this URL, give another module a chance
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen--[[ example hook that rewrites one URI to another URI. It returns a
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen apache2.DECLINED to give other URL mappers a chance to work on the
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen substitution, including the core translate_name hook which maps based
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen on the DocumentRoot.
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen Note: Use the early/late flags in the directive to make it run before
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen or after mod_alias.
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainenrequire 'apache2'
678d0463849ba777106eb7875f27db07a5d8e3dfTimo Sirainenfunction translate_name(r)
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen if r.uri == "/translate-name" then
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen<section id="datastructures"><title>Data Structures</title>
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <p>The request_rec is mapped in as a userdata. It has a metatable
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen which lets you do useful things with it. For the most part it
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen has the same fields as the request_rec struct, many of which are writeable as
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen well as readable. (The table fields' content can be changed, but the
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen fields themselves cannot be set to different tables.)</p>
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <td>If an authentication check was made, this is set to the type
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen of authentication (f.x. <code>basic</code>)</td>
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <td>The query string arguments extracted from the request
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen (f.x. <code>foo=bar&name=johnsmith</code>)</td>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen <td>Set to true if this is an HTTP/0.9 style request
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen (e.g. <code>GET /foo</code> (with no headers) )</td>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen <td>The canonical filename of the request</td>
3957200d949c6e96c4184db2395444d723950583Timo Sirainen <td>The content encoding of the current request</td>
3957200d949c6e96c4184db2395444d723950583Timo Sirainen <td>The content type of the current request, as determined in the
3957200d949c6e96c4184db2395444d723950583Timo Sirainen type_check phase (f.x. <code>image/gif</code> or <code>text/html</code>)</td>
3957200d949c6e96c4184db2395444d723950583Timo Sirainen <td>MIME header environment for the response, printed even on errors and
3957200d949c6e96c4184db2395444d723950583Timo Sirainen persist across internal redirects</td>
6176f3618240943f3cb41cb7063ecef56b1dd7dfTimo Sirainen <td>The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be
cac19595c35d7477f7b911805da60a7f6c898bcbTimo Sirainen changed in the translate-name or map-to-storage phases of a request to allow the
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen default handler (or script handlers) to serve a different file than what was requested.</td>
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <td>The name of the <a href="/handler.html">handler</a> that should serve this request, f.x.
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <code>lua-script</code> if it is to be served by mod_lua. This is typically set by the
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <directive module="mod_mime">AddHandler</directive> or <directive module="core">SetHandler</directive>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen directives, but could also be set via mod_lua to allow another handler to serve up a specific request
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen that would otherwise not be served by it.
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen <td>MIME header environment from the request. This contains headers such as <code>Host,
f6bf269b74e128decd45b6ab01f425e5d3c13894Timo Sirainen <td>MIME header environment for the response.</td>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen <td>The host name, as set by the <code>Host:</code> header or by a full URI.</td>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen <td>Whether or not this request is done via HTTPS</td>
3957200d949c6e96c4184db2395444d723950583Timo Sirainen <td>The ID to identify request in access and error log.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The request method, f.x. <code>GET</code> or <code>POST</code>.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>A list of notes that can be passed on from one module to another.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The PATH_INFO extracted from this request.</td>
2ea9c5da50bbcb67de03c91ef4cf7778d1e57a22Timo Sirainen <td>The protocol used, f.x. <code>HTTP/1.1</code></td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>Denotes whether this is a proxy request or not. This value is generally set in
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen the post_read_request/translate_name phase of a request.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The contents of the <code>Range:</code> header.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The environment variables set for this request.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The (current) HTTP return code for this request, f.x. <code>200</code> or <code>404</code>.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The request string as sent by the client, f.x. <code>GET /foo/bar HTTP/1.1</code>.</td>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <td>The URI after it has been parsed by httpd</td>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <td>If an authentication check has been made, this is set to the name of the authenticated user.</td>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <td>The IP of the user agent making the request</td>
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen <p>The request_rec has (at least) the following methods:</p>
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:addoutputfilter(name|function) -- add an output filter
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:parseargs() -- returns a Lua table containing the request's query string arguments
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:parsebody() -- parse any POST data in the request and return it as a Lua table
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:puts("hello", " world", "!") -- print to response body
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen r:write("a single string") -- print to response body
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<section id="logging"><title>Logging Functions</title>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen -- examples of logging messages<br />
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:debug("This is a debug log message")<br />
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:info("This is an info log message")<br />
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen r:notice("This is an notice log message")<br />
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen r:warn("This is an warn log message")<br />
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen r:err("This is an err log message")<br />
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen r:alert("This is an alert log message")<br />
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen r:crit("This is an crit log message")<br />
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen r:emerg("This is an emerg log message")<br />
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen<section id="apache2"><title>apache2 Package</title>
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen <dd>internal constant OK. Handlers should return this if they've
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen handled the request.</dd>
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen <dd>internal constant DECLINED. Handlers should return this if
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen they are not going to handle the request.</dd>
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen <dd>internal constants used by <module>mod_proxy</module></dd>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<p>(Other HTTP status codes are not yet implemented.)</p>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<directivesynopsis>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<description>Specify the base path for resolving relative paths for mod_lua directives</description>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<contextlist><context>server config</context><context>virtual host</context>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<context>directory</context><context>.htaccess</context>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen</contextlist>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen <p>Specify the base path which will be used to evaluate all
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen relative paths within mod_lua. If not specified they
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen will be resolved relative to the current working directory,
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen which may not always work well for a server.</p>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen</directivesynopsis>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<directivesynopsis>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<description>One of once, request, conn -- default is once</description>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<syntax>LuaScope once|request|conn|thread</syntax>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<contextlist><context>server config</context><context>virtual host</context>
0591dbf3c6edb9ad502df0e57a0a458896e632a1Timo Sirainen<context>directory</context><context>.htaccess</context>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen</contextlist>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen <p>Specify the lifecycle scope of the Lua interpreter which will
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen be used by handlers in this "Directory." The default is "once"</p>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen <dt>request:</dt> <dd>use the interpreter to handle anything based on
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen the same file within this request, which is also
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen request scoped.</dd>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen handling the request (only available with threaded MPMs).</dd>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<!-- not implemented
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen <dt>server:</dt> <dd>This one is different than others because the
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen server scope is quite long lived, and multiple threads
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen will have the same server_rec. To accommodate this
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen server scoped interpreter are stored in an apr
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen resource list. The min and max arguments are intended
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen to specify the pool size, but are unused at this time.</dd>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen</directivesynopsis>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<directivesynopsis>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<description>Map a path to a lua handler</description>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<contextlist><context>server config</context><context>virtual host</context>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen<context>directory</context><context>.htaccess</context>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen</contextlist>
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen <p>This directive matches a uri pattern to invoke a specific
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen handler function in a specific file. It uses PCRE regular
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen expressions to match the uri, and supports interpolating
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen match groups into both the file path and the function name
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen be careful writing your regular expressions to avoid security
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen <p>This would match uri's such as /photos/show?id=9
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen to the file /scripts/photos.lua and invoke the
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen handler function handle_show on the lua vm after
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen loading that file.</p>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen <p>This would invoke the "handle" function, which
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen is the default if no specific function name is
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen provided.</p>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen</directivesynopsis>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<directivesynopsis>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<description>Add a directory to lua's package.path</description>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<contextlist><context>server config</context><context>virtual host</context>
3c296d819c54e21ce05c3d2eeeedc79be42ac593Timo Sirainen<context>directory</context><context>.htaccess</context>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen</contextlist>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen <usage><p>Add a path to lua's module search path. Follows the same
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen conventions as lua. This just munges the package.path in the
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen</directivesynopsis>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen<directivesynopsis>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<description>Add a directory to lua's package.cpath</description>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<contextlist><context>server config</context><context>virtual host</context>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<context>directory</context><context>.htaccess</context>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen</contextlist>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen <p>Add a path to lua's shared library search path. Follows the same
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen conventions as lua. This just munges the package.cpath in the
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen</directivesynopsis>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<directivesynopsis>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<description>Configure the compiled code cache.</description>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<syntax>LuaCodeCache stat|forever|never</syntax>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<context>server config</context><context>virtual host</context>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<context>directory</context><context>.htaccess</context>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen</contextlist>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen Specify the behavior of the in-memory code cache. The default
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen is stat, which stats the top level script (not any included
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen ones) each time that file is needed, and reloads it if the
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen modified time indicates it is newer than the one it has
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen already loaded. The other values cause it to keep the file
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen cached forever (don't stat and replace) or to never cache the
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen <p>In general stat or forever is good for production, and stat or never
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen for development.</p>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo SirainenLuaCodeCache stat
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo SirainenLuaCodeCache forever
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo SirainenLuaCodeCache never
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen</directivesynopsis>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<directivesynopsis>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<description>Provide a hook for the translate name phase of request processing</description>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</syntax>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<contextlist><context>server config</context><context>virtual host</context>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen</contextlist>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen request processing. The hook function receives a single
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen argument, the request_rec, and should return a status code,
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen which is either an HTTP error code, or the constants defined
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen in the apache2 module: apache2.OK, apache2.DECLINED, or
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen <p>For those new to hooks, basically each hook will be invoked
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen until one of them returns apache2.OK. If your hook doesn't
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen want to do the translation it should just return
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen apache2.DECLINED. If the request should stop processing, then
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo SirainenLuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainenrequire "apache2"
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainenfunction silly_mapper(r)
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen if r.uri == "/" then
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen <note><title>Context</title><p>This directive is not valid in <directive
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen type="section" module="core">Directory</directive>, <directive
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen type="section" module="core">Files</directive>, or htaccess
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <note><title>Ordering</title><p>The optional arguments "early" or "late"
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen control when this script runs relative to other modules.</p></note>
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen</directivesynopsis>
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen<directivesynopsis>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<description>Provide a hook for the fixups phase of a request
bde78a7bf5f9000f1ae4dc7ce6cabd012e1f8b79Pascal Volkprocessing</description>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
3957200d949c6e96c4184db2395444d723950583Timo Sirainen<contextlist><context>server config</context><context>virtual host</context>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<context>directory</context><context>.htaccess</context>
bde78a7bf5f9000f1ae4dc7ce6cabd012e1f8b79Pascal Volk</contextlist>
15ab2452b0220a115f4351ad9d7fd5ec70ae7966Timo Sirainen Just like LuaHookTranslateName, but executed at the fixups phase
5e9bb72de1209cd39fdf3e95bdb26e047cc5594eTimo Sirainen</directivesynopsis>
8b16d3b00f051401c97568697ccdbba48663759aTimo Sirainen<directivesynopsis>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<description>Provide a hook for the map_to_storage phase of request processing</description>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<contextlist><context>server config</context><context>virtual host</context>
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen<context>directory</context><context>.htaccess</context>
d3af9043837e4bf0e87a9150fedc9e94908e6f82Timo Sirainen</contextlist>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen <p>Like <directive>LuaHookTranslateName</directive> but executed at the
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen map-to-storage phase of a request. Modules like mod_cache run at this phase,
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen which makes for an interesting example on what to do here:</p>
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainen LuaHookMapToStorage /path/to/lua/script.lua check_cache
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainenrequire"apache2"
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainencached_files = {}
caa1fa99c79c568ce2e42477bc169e7024fb220bTimo Sirainenfunction read_file(filename)
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen local input = io.open(filename, "r")
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen if input then
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen local data = input:read("*a")
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen cached_files[filename] = data
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen file = cached_files[filename]
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen input:close()
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen return cached_files[filename]
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