lua.html.en revision d374d0c14a2cf6582e3c9825a9b0acba0d7c736a
c6b6876815d20010b548909998c894a527adc139humbedooh<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
c6b6876815d20010b548909998c894a527adc139humbedooh<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
c6b6876815d20010b548909998c894a527adc139humbedooh XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
c6b6876815d20010b548909998c894a527adc139humbedooh This file is generated from xml source: DO NOT EDIT
c6b6876815d20010b548909998c894a527adc139humbedooh XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
c6b6876815d20010b548909998c894a527adc139humbedooh<title>Creating hooks and scripts with mod_lua - Apache HTTP Server</title>
c6b6876815d20010b548909998c894a527adc139humbedooh<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
c6b6876815d20010b548909998c894a527adc139humbedooh<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
c6b6876815d20010b548909998c894a527adc139humbedooh<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
c6b6876815d20010b548909998c894a527adc139humbedooh<script src="/style/scripts/prettify.js" type="text/javascript">
c6b6876815d20010b548909998c894a527adc139humbedooh<link href="/images/favicon.ico" rel="shortcut icon" /></head>
c6b6876815d20010b548909998c894a527adc139humbedooh<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
c6b6876815d20010b548909998c894a527adc139humbedooh<p class="apache">Apache HTTP Server Version 2.5</p>
c6b6876815d20010b548909998c894a527adc139humbedooh<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Developer</a></div><div id="page-content"><div id="preamble"><h1>Creating hooks and scripts with mod_lua</h1>
c6b6876815d20010b548909998c894a527adc139humbedooh<p><span>Available Languages: </span><a href="/en/developer/lua.html" title="English"> en </a></p>
c6b6876815d20010b548909998c894a527adc139humbedooh<p>This document expands on the <code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> documentation and explores
c6b6876815d20010b548909998c894a527adc139humbedooh additional ways of using mod_lua for writing hooks and scripts.</p>
c6b6876815d20010b548909998c894a527adc139humbedooh<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh<li><img alt="" src="/images/down.gif" /> <a href="#enabling">Optimizing mod_lua for production servers</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#basic_remap">Example 1: A basic remapping module</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#mass_vhost">Example 2: Mass virtual hosting</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#basic_auth">Example 3: A basic authorization hook</a></li>
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#authz">Example 4: Authorization using LuaAuthzProvider</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#map_handler">Example 5: Overlays using LuaMapHandler</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#mod_status_lua">Example 6: Basic Lua scripts</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#String_manipulation">HTTPd bindings: String manipulation</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#Request_handling">HTTPd bindings: Request handling</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#Parser_functions">HTTPd bindings: Parser functions</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#Server_settings">HTTPd bindings: Server settings</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#Database_connectivity">HTTPd bindings: Database connectivity</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#Miscellaneous">HTTPd bindings: Miscellaneous</a></li>
c6b6876815d20010b548909998c894a527adc139humbedooh</ul><h3>See also</h3><ul class="seealso"><li><a href="/mod/mod_lua.html">mod_lua</a></li><li><a href="modguide.html">Developing modules for Apache 2.4</a></li><li><a href="request.html">Request Processing in Apache 2.4</a></li><li><a href="hooks.html">Apache 2.x Hook Functions</a></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="introduction" id="introduction">Introduction</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="what" id="what">What is mod_lua</a></h3>
c6b6876815d20010b548909998c894a527adc139humbedoohStuff about what <code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> is goes here.
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="contents" id="contents">What we will be discussing in this document</a></h3>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohThis document will discuss several cases where <code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> can be used
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohto either ease up a phase of the request processing or create more transparency in
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohthe logic behind a decision made in a phase.
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="prerequisites" id="prerequisites">Prerequisites</a></h3>
c6b6876815d20010b548909998c894a527adc139humbedoohFirst and foremost, you are expected to have a basic knowledge of how the Lua
c6b6876815d20010b548909998c894a527adc139humbedoohprogramming language works. In most cases, we will try to be as pedagogical
c6b6876815d20010b548909998c894a527adc139humbedoohas possible and link to documents describing the functions used in the
c6b6876815d20010b548909998c894a527adc139humbedoohexamples, but there are also many cases where it is necessary to either
c6b6876815d20010b548909998c894a527adc139humbedoohjust assume that "it works" or do some digging yourself into what the hows
c6b6876815d20010b548909998c894a527adc139humbedoohand whys of various function calls.
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh<h2><a name="enabling" id="enabling">Optimizing mod_lua for production servers</a></h2>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohSetting the right <code class="directive"><a href="/mod/mod_lua.html#luascope">LuaScope</a></code> setting
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohfor your Lua scripts can be essential to your server's
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohperformance. By default, the scope is set to <code>once</code>, which means
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohthat every call to a Lua script will spawn a new Lua state that handles that
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohscript and is destroyed immediately after. This option keeps the memory
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohfootprint of mod_lua low, but also affects the processing speed of a request.
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohIf you have the memory to spare, you can set the scope to <code>thread</code>,
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohwhich will make mod_lua spawn a Lua state that lasts the entirity of a thread's
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohlifetime, speeding up request processing by 2-3 times. Since mod_lua will create
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooha state for each script, this may be an expensive move, memory-wise, so to
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohcompromise between speed and memory usage, you can choose the <code>server</code>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohoption to create a pool of Lua states to be used. Each request for a Lua script or
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooha hook function will then acquire a state from the pool and release it back when it's
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohdone using it, allowing you to still gain a significant performance increase, while
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohkeeping your memory footprint low. Some examples of possible settings are:
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohLuaScope once
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohLuaScope thread
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohLuaScope server 5 40
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohAs a general rule of thumb: If your server has none to low usage, use <code>once</code>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohor <code>request</code>, if your server has low to medium usage, use the <code>server</code>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohpool, and if it has high usage, use the <code>thread</code> setting. As your server's
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohload increases, so will the number of states being actively used, and having your scope
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohset to <code>once/request/conn</code> will stop being beneficial to your memory footprint.
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh<strong>Note:</strong> The <code>min</code> and <code>max</code> settings for the
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh<code>server</code> scope denotes the minimum and maximum states to keep in a pool per
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohserver <em>process</em>, so keep this below your <code>ThreadsPerChild</code> limit.
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohBy default, <code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> stats each Lua script to determine whether a reload
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh(and thus, a re-interpretation and re-compilation) of a script is required. This is managed
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohthrough the <code class="directive"><a href="/mod/mod_lua.html#luacodecache">LuaCodeCache</a></code> directive. If you are running
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohyour scripts on a production server, and you do not need to update them regularly, it may be
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohadvantageous to set this directive to the <code>forever</code> value, which will cause mod_lua
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohto skip the stat process and always reuse the compiled byte-code from the first access to the
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohscript, thus speeding up the processing. For Lua hooks, this can prove to increase peformance,
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohwhile for scripts handled by the <code>lua-script</code> handler, the increase in performance
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohmay be negligible, as files httpd will stat the files regardless.
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohFor maximum performance, it is generally recommended that any initialization of libraries,
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohconstants and master tables be kept outside the handle's scope:
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh--[[ This is good practice ]]--
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohrequire "string"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohrequire "someLibrary"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohlocal masterTable = {}
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohlocal constant = "Foo bar baz"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohfunction handle(r)
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh--[[ This is bad practice ]]--
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohrequire "string"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohfunction handle(r)
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh require "someLibrary"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh local masterTable = {}
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh local constant = "Foo bar baz"
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="basic_remap" id="basic_remap">Example 1: A basic remapping module</a></h2>
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh These first examples show how mod_lua can be used to rewrite URIs in the same
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh way that one could do using <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> or
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>, but with more clarity
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh on how the decision-making takes place, as well as allowing for more complex
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh decisions than would otherwise be allowed with said directives.
c6b6876815d20010b548909998c894a527adc139humbedooh Simple remap example.
c6b6876815d20010b548909998c894a527adc139humbedooh This example will rewrite /foo/test.bar to the physical file
c6b6876815d20010b548909998c894a527adc139humbedooh /internal/test, somewhat like how mod_alias works.
c6b6876815d20010b548909998c894a527adc139humbedoohfunction remap(r)
c6b6876815d20010b548909998c894a527adc139humbedooh -- Test if the URI matches our criteria
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh local barFile = r.uri:match("/foo/([a-zA-Z0-9]+)%.bar")
c6b6876815d20010b548909998c894a527adc139humbedooh if barFile then
c6b6876815d20010b548909998c894a527adc139humbedooh r.filename = "/internal/" .. barFile
c6b6876815d20010b548909998c894a527adc139humbedooh Advanced remap example.
c6b6876815d20010b548909998c894a527adc139humbedooh This example will evaluate some conditions, and based on that,
c6b6876815d20010b548909998c894a527adc139humbedooh remap a file to one of two destinations, using a rewrite map.
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh This is similar to mixing AliasMatch and ProxyPass, but
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh without them clashing in any way. Assuming we are on example.com, then:
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh http://example.com/photos/test.png will be rewritten as /uploads/www/test.png
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh http://example.com/ext/foo.html will be proxied to http://www.external.com/foo.html
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh URIs that do not match, will be served by their respective default handlers
c6b6876815d20010b548909998c894a527adc139humbedoohlocal map = {
c6b6876815d20010b548909998c894a527adc139humbedooh source = [[^/photos/(.+)\.png$]],
c6b6876815d20010b548909998c894a527adc139humbedooh proxy = false
c6b6876815d20010b548909998c894a527adc139humbedooh externals = {
c6b6876815d20010b548909998c894a527adc139humbedooh source = [[^/ext/(.*)$]],
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh destination = [[http://www.external.com/$1]],
c6b6876815d20010b548909998c894a527adc139humbedooh proxy = true
c6b6876815d20010b548909998c894a527adc139humbedoohfunction interpolateString(s,v)
c6b6876815d20010b548909998c894a527adc139humbedooh return s:gsub("%$(%d+)", function(a) return v[tonumber(a)] end)
c6b6876815d20010b548909998c894a527adc139humbedoohfunction remap(r)
c6b6876815d20010b548909998c894a527adc139humbedooh -- browse through the rewrite map
c6b6876815d20010b548909998c894a527adc139humbedooh for key, entry in pairs(map) do
c6b6876815d20010b548909998c894a527adc139humbedooh -- Match source regex against URI
c6b6876815d20010b548909998c894a527adc139humbedooh local match = apache2.regex(r, entry.source, r.uri) then
c6b6876815d20010b548909998c894a527adc139humbedooh if match and match[0] then
c6b6876815d20010b548909998c894a527adc139humbedooh r.filename = interpolateString(entry.destination, match)
c6b6876815d20010b548909998c894a527adc139humbedooh -- Is this a proxied remap?
c6b6876815d20010b548909998c894a527adc139humbedooh r.handler = "proxy-server" -- tell mod_proxy to handle this
c6b6876815d20010b548909998c894a527adc139humbedooh r.proxyreq = apache2.PROXYREQ_REVERSE -- We'll want to do a reverse proxy
c6b6876815d20010b548909998c894a527adc139humbedooh r.filename = "proxy:" .. r.filename -- Add the proxy scheme to the destination
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="mass_vhost" id="mass_vhost">Example 2: Mass virtual hosting</a></h2>
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh As with simple and advanced rewriting, you can use mod_lua for dynamically
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh assigning a hostname to a specific document root, much like
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> does, but with more control over what goes
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh where. This could be as simple as a table holding the information about which
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh host goes into which folder, or more advanced, using a database holding the
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh document roots of each hostname.
c6b6876815d20010b548909998c894a527adc139humbedooh Simple mass vhost script
c6b6876815d20010b548909998c894a527adc139humbedooh This example will check a map for a virtual host and rewrite filename and
c6b6876815d20010b548909998c894a527adc139humbedooh document root accordingly.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal vhosts = {
c6b6876815d20010b548909998c894a527adc139humbedooh { domain = "example.com", home = "/www/example.com" },
c6b6876815d20010b548909998c894a527adc139humbedooh { domain = "example.org", home = "/nfs/ext1/example.org" }
c6b6876815d20010b548909998c894a527adc139humbedoohfunction mass_vhost(r)
c6b6876815d20010b548909998c894a527adc139humbedooh -- Match against our hostname
c6b6876815d20010b548909998c894a527adc139humbedooh for key, entry in pairs(vhosts) do
c6b6876815d20010b548909998c894a527adc139humbedooh -- match against either host or *.host:
c6b6876815d20010b548909998c894a527adc139humbedooh if apache2.strcmp_match(r.hostname, entry.domain) or
c6b6876815d20010b548909998c894a527adc139humbedooh apache2.strcmp_match(r.hostname, "*." .. entry.domain) then
c6b6876815d20010b548909998c894a527adc139humbedooh -- If it matches, rewrite filename and set document root
c6b6876815d20010b548909998c894a527adc139humbedooh local filename = r.filename:sub(r.document_root:len()+1)
c6b6876815d20010b548909998c894a527adc139humbedooh Advanced mass virtual hosting
c6b6876815d20010b548909998c894a527adc139humbedooh This example will query a database for vhost entries and save them for
c6b6876815d20010b548909998c894a527adc139humbedooh 60 seconds before checking for updates. For best performance, such scripts
c6b6876815d20010b548909998c894a527adc139humbedooh should generally be run with LuaScope set to 'thread' or 'server'
c6b6876815d20010b548909998c894a527adc139humbedoohlocal cached_vhosts = {}
c6b6876815d20010b548909998c894a527adc139humbedoohlocal timeout = 60
c6b6876815d20010b548909998c894a527adc139humbedooh-- Function for querying the database for saved vhost entries
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedoohfunction query_vhosts(r)
c6b6876815d20010b548909998c894a527adc139humbedooh if not cached_vhosts[host] or (cached_vhosts[host] and cached_vhosts[host].updated < os.time() - timeout) then
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh local db,err = ap.dbopen(r,"mod_dbd")
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh local _host = db:escape(r,host)
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh local res, err = db:query(r, ("SELECT `destination` FROM `vhosts` WHERE `hostname` = '%s' LIMIT 1"):format(_host) )
c6b6876815d20010b548909998c894a527adc139humbedooh if res and #res == 1 then
c6b6876815d20010b548909998c894a527adc139humbedooh cached_vhosts[host] = { updated = os.time(), destination = res[1][1] }
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh cached_vhosts[host] = { updated = os.time(), destination = nil } -- don't re-query whenever there's no result, wait a while.
c6b6876815d20010b548909998c894a527adc139humbedooh if cached_vhosts[host] then
c6b6876815d20010b548909998c894a527adc139humbedooh return cached_vhosts[host].destination
c6b6876815d20010b548909998c894a527adc139humbedoohfunction mass_vhost(r)
c6b6876815d20010b548909998c894a527adc139humbedooh -- Check whether the hostname is in our database
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh local destination = query_vhosts(r)
c6b6876815d20010b548909998c894a527adc139humbedooh if destination then
c6b6876815d20010b548909998c894a527adc139humbedooh -- If found, rewrite and change document root
c6b6876815d20010b548909998c894a527adc139humbedooh local filename = r.filename:sub(r.document_root:len()+1)
c6b6876815d20010b548909998c894a527adc139humbedooh r.filename = destination .. filename
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="basic_auth" id="basic_auth">Example 3: A basic authorization hook</a></h2>
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh With the authorization hooks, you can add custom auth phases to your request
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh processing, allowing you to either add new requirements that were not previously
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh supported by httpd, or tweaking existing ones to accommodate your needs.
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh A simple authentication hook that checks a table containing usernames and
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh passwords of two accounts.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal accounts = {
c6b6876815d20010b548909998c894a527adc139humbedooh bob = 'somePassword',
c6b6876815d20010b548909998c894a527adc139humbedooh jane = 'Iloveponies'
c6b6876815d20010b548909998c894a527adc139humbedooh-- Function for parsing the Authorization header into a username and a password
c6b6876815d20010b548909998c894a527adc139humbedoohfunction parse_auth(str)
c6b6876815d20010b548909998c894a527adc139humbedooh local user,pass = nil, nil
c6b6876815d20010b548909998c894a527adc139humbedooh if str and str:len() > 0 then
c6b6876815d20010b548909998c894a527adc139humbedooh str = apache2.base64_decode(auth):sub(7));
c6b6876815d20010b548909998c894a527adc139humbedooh user, pass = auth:match("([^:]+)%:([^:]+)")
c6b6876815d20010b548909998c894a527adc139humbedooh return user, pass
c6b6876815d20010b548909998c894a527adc139humbedooh-- The authentication hook
c6b6876815d20010b548909998c894a527adc139humbedoohfunction check_auth(r)
c6b6876815d20010b548909998c894a527adc139humbedooh local user, pass = parse_auth(r.headers_in['Authorization'])
c6b6876815d20010b548909998c894a527adc139humbedooh local authenticated = false
c6b6876815d20010b548909998c894a527adc139humbedooh if user and pass then
c6b6876815d20010b548909998c894a527adc139humbedooh if accounts[user] and accounts[user] == pass then
c6b6876815d20010b548909998c894a527adc139humbedooh authenticated = true
c6b6876815d20010b548909998c894a527adc139humbedooh r.headers_out["WWW-Authenticate"] = 'Basic realm="Super secret zone"'
c6b6876815d20010b548909998c894a527adc139humbedooh if not authenticated then
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh An advanced authentication checker with a database backend,
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh caching account entries for 1 minute
c6b6876815d20010b548909998c894a527adc139humbedoohlocal timeout = 60 -- Set account info to be refreshed every minute
c6b6876815d20010b548909998c894a527adc139humbedoohlocal accounts = {}
c6b6876815d20010b548909998c894a527adc139humbedooh-- Function for parsing the Authorization header into a username and a password
c6b6876815d20010b548909998c894a527adc139humbedoohfunction parse_auth(str)
c6b6876815d20010b548909998c894a527adc139humbedooh local user,pass = nil, nil
c6b6876815d20010b548909998c894a527adc139humbedooh if str and str:len() > 0 then
c6b6876815d20010b548909998c894a527adc139humbedooh str = apache2.base64_decode(auth):sub(7));
c6b6876815d20010b548909998c894a527adc139humbedooh user, pass = auth:match("([^:]+)%:([^:]+)")
c6b6876815d20010b548909998c894a527adc139humbedooh return user, pass
c6b6876815d20010b548909998c894a527adc139humbedooh-- Function for querying the database for the account's password (stored as a salted SHA-1 hash)
c6b6876815d20010b548909998c894a527adc139humbedoohfunction fetch_password(user)
c6b6876815d20010b548909998c894a527adc139humbedooh if not accounts[user] or (accounts[user] and accounts[user].updated < os.time() - timeout) then
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh local db = apache2.dbopen(r, "mod_dbd")
c6b6876815d20010b548909998c894a527adc139humbedooh local usr = db:escape(user)
c6b6876815d20010b548909998c894a527adc139humbedooh local res, err = db:query( ("SELECT `password` FROM `accounts` WHERE `user` = '%s' LIMIT 1"):format(usr) )
c6b6876815d20010b548909998c894a527adc139humbedooh if res and #res == 1 then
c6b6876815d20010b548909998c894a527adc139humbedooh accounts[user] = { updated = os.time(), password = res[1][1] }
c6b6876815d20010b548909998c894a527adc139humbedooh accounts[user] = nil
c6b6876815d20010b548909998c894a527adc139humbedooh if accounts[user] then
c6b6876815d20010b548909998c894a527adc139humbedooh return accounts[user].password
c6b6876815d20010b548909998c894a527adc139humbedooh-- The authentication hook
c6b6876815d20010b548909998c894a527adc139humbedoohfunction check_auth(r)
c6b6876815d20010b548909998c894a527adc139humbedooh local user, pass = parse_auth(r.headers_in['Authorization'])
c6b6876815d20010b548909998c894a527adc139humbedooh local authenticated = false
c6b6876815d20010b548909998c894a527adc139humbedooh if user and pass then
c6b6876815d20010b548909998c894a527adc139humbedooh pass = apache2.sha1("addSomeSalt" .. pass)
c6b6876815d20010b548909998c894a527adc139humbedooh local stored_pass = fetch_password(user)
c6b6876815d20010b548909998c894a527adc139humbedooh if stored_pass and pass == stored_pass then
c6b6876815d20010b548909998c894a527adc139humbedooh authenticated = true
c6b6876815d20010b548909998c894a527adc139humbedooh r.headers_out["WWW-Authenticate"] = 'Basic realm="Super secret zone"'
c6b6876815d20010b548909998c894a527adc139humbedooh if not authenticated then
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh<h2><a name="authz" id="authz">Example 4: Authorization using LuaAuthzProvider</a></h2>
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh If you require even more advanced control over your authorization phases,
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh you can add custom authz providers to help you manage your server. The
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh example below shows you how you can split a single htpasswd file into
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh groups with different permissions:
c6b6876815d20010b548909998c894a527adc139humbedoohLuaAuthzProvider rights /path/to/lua/script.lua rights_handler
c6b6876815d20010b548909998c894a527adc139humbedooh Require rights member
c6b6876815d20010b548909998c894a527adc139humbedooh</Directory>
c6b6876815d20010b548909998c894a527adc139humbedooh Require rights admin
c6b6876815d20010b548909998c894a527adc139humbedooh</Directory>
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh This script has two user groups; members and admins, and whichever
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh is refered to by the "Require rights" directive is checked to see
7bf171806d862d85c9e913b87aacccb31403be9bhumbedooh if the authenticated user belongs to this group.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal members = { "rbowen", "humbedooh", "igalic", "covener" }
c6b6876815d20010b548909998c894a527adc139humbedoohlocal admins = { "humbedooh" }
c6b6876815d20010b548909998c894a527adc139humbedoohfunction rights_handler(r, what)
c6b6876815d20010b548909998c894a527adc139humbedooh if r.user == nil then
c6b6876815d20010b548909998c894a527adc139humbedooh if what == "member" then
c6b6876815d20010b548909998c894a527adc139humbedooh for k, v in pairs(members) do
c6b6876815d20010b548909998c894a527adc139humbedooh if r.user == v then
c6b6876815d20010b548909998c894a527adc139humbedooh elseif what == "admin" then
c6b6876815d20010b548909998c894a527adc139humbedooh for k, v in pairs(admins) do
c6b6876815d20010b548909998c894a527adc139humbedooh if r.user == v then
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="map_handler" id="map_handler">Example 5: Overlays using LuaMapHandler</a></h2>
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedoohLuaMapHandler ^/portal/([a-z]+)/ /path/to/lua/script.lua handle_$1
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="mod_status_lua" id="mod_status_lua">Example 6: Basic Lua scripts</a></h2>
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedoohAlso coming soon
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="String_manipulation" id="String_manipulation">HTTPd bindings: String manipulation</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.base64_encode">apache2.base64_encode</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.base64_decode">apache2.base64_decode</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.escapehtml">apache2.escapehtml</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.os_escape_path">apache2.os_escape_path</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.escape_logitem">apache2.escape_logitem</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.base64_decode" id="apache2.base64_decode">apache2.base64_decode(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohDecodes a base64-encoded string
c6b6876815d20010b548909998c894a527adc139humbedoohThe base64-decoded string.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal str = "This is a test"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal encoded = apache2.base64_encode(str)
c6b6876815d20010b548909998c894a527adc139humbedoohlocal decoded = apache2.base64_decode(encoded)
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.base64_encode" id="apache2.base64_encode">apache2.base64_encode(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohEncodes a string using the base64 encoding scheme.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal str = "This is a test"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal encoded = apache2.base64_encode(str)
c6b6876815d20010b548909998c894a527adc139humbedoohlocal decoded = apache2.base64_decode(encoded)
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.escape" id="apache2.escape">apache2.escape(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohurl-escapes a string
c6b6876815d20010b548909998c894a527adc139humbedoohThe URL-escaped string.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal str = "This is a test"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal escaped = apache2.escape(str)
c6b6876815d20010b548909998c894a527adc139humbedoohprint(escaped) -- prints "This+is+a+test"
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.escape_logitem" id="apache2.escape_logitem">apache2.escape_logitem(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> path</em>
c6b6876815d20010b548909998c894a527adc139humbedoohEscape a string for logging
c6b6876815d20010b548909998c894a527adc139humbedoohThe converted string
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.escapehtml" id="apache2.escapehtml">apache2.escapehtml(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> html</em>, boolean<em> toasc</em>
c6b6876815d20010b548909998c894a527adc139humbedoohEscapes HTML entities.
c6b6876815d20010b548909998c894a527adc139humbedooh<td>Whether to escape all non-ASCI characters as &#nnn;</td>
c6b6876815d20010b548909998c894a527adc139humbedoohThe escaped HTML code.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal html = "<b>Testing!</b>"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal escaped = apache2.escapehtml(html)
c6b6876815d20010b548909998c894a527adc139humbedoohr:puts(escaped) -- prints "&lt;b&gt;Testing!&lt;/b&gt;"
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.md5" id="apache2.md5">apache2.md5(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohComputes an MD5 digest sum based on a string (binary safe)
c6b6876815d20010b548909998c894a527adc139humbedoohThe MD5 digest sum of the data provided
c6b6876815d20010b548909998c894a527adc139humbedoohlocal text = "The quick brown fox jumps over the lazy dog"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal md5 = apache2.md51(text)
c6b6876815d20010b548909998c894a527adc139humbedoohr:puts(md5) -- prints out "9e107d9d372bb6826bd81d3542a419d6"
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.os_escape_path" id="apache2.os_escape_path">apache2.os_escape_path(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> path</em>, boolean<em> partial</em>
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedoohconvert an OS path to a URL in an OS dependent way.
c6b6876815d20010b548909998c894a527adc139humbedooh<td>partial if set, assume that the path will be appended to something with a '/' in it (and thus does not prefix "./")</td>
c6b6876815d20010b548909998c894a527adc139humbedoohThe converted URL
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.sha1" id="apache2.sha1">apache2.sha1(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohComputes an SHA-1 digest sum based on a string (binary safe)
c6b6876815d20010b548909998c894a527adc139humbedoohThe SHA-1 digest sum of the data provided
c6b6876815d20010b548909998c894a527adc139humbedoohlocal text = "The quick brown fox jumps over the lazy dog"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal sha1 = apache2.sha1(text)
c6b6876815d20010b548909998c894a527adc139humbedoohr:puts(sha1) -- prints out "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.unescape" id="apache2.unescape">apache2.unescape(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohunescapes an URL-escaped string
c6b6876815d20010b548909998c894a527adc139humbedoohThe URL-unescaped string
c6b6876815d20010b548909998c894a527adc139humbedoohlocal str = "This+is+a+test"
c6b6876815d20010b548909998c894a527adc139humbedoohlocal unescaped = apache2.unescape(str)
c6b6876815d20010b548909998c894a527adc139humbedoohprint(unescaped) -- prints "This is a test"
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="Request_handling" id="Request_handling">HTTPd bindings: Request handling</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.requestbody">apache2.requestbody</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.add_input_filter">apache2.add_input_filter</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.get_basic_auth_pw">apache2.get_basic_auth_pw</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.set_document_root">apache2.set_document_root</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.set_context_prefix">apache2.set_context_prefix</a>
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh<a href="#apache2.get_server_name_for_url">apache2.get_server_name_for_url</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.set_keepalive">apache2.set_keepalive</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.send_interim_response">apache2.send_interim_response</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.add_input_filter" id="apache2.add_input_filter">apache2.add_input_filter(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> filter</em>
c6b6876815d20010b548909998c894a527adc139humbedoohAdds an input filter to the request
c6b6876815d20010b548909998c894a527adc139humbedoohapache2.add_input_filter(r, "SPAM_FILTER") -- Check input for spam..?
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.get_basic_auth_pw" id="apache2.get_basic_auth_pw">apache2.get_basic_auth_pw(
c6b6876815d20010b548909998c894a527adc139humbedoohReturns the password from a basic authorization request or nil if none was supplied
c6b6876815d20010b548909998c894a527adc139humbedoohThe password from a basic authorization request or nil if none was supplied
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh<h3><a name="apache2.get_server_name_for_url" id="apache2.get_server_name_for_url">apache2.get_server_name_for_url(
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedoohGet the current server name from the request for the purposes of using in a URL.
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedoohIf the server name is an IPv6 literal address, it will be returned in URL format (e.g., "[fe80::1]").
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.make_etag" id="apache2.make_etag">apache2.make_etag(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, boolean<em> force_weak</em>
c6b6876815d20010b548909998c894a527adc139humbedoohConstructs an entity tag from the resource information. If it's a real file, build in some of the file characteristics.
c6b6876815d20010b548909998c894a527adc139humbedooh<td>force_weak Force the entity tag to be weak - it could be modified again in as short an interval.</td>
c6b6876815d20010b548909998c894a527adc139humbedoohThe entity tag
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.requestbody" id="apache2.requestbody">apache2.requestbody(
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh request_rec<em> r</em>, number<em> size</em>, string<em> filename</em>
c6b6876815d20010b548909998c894a527adc139humbedoohReads the request body. If a filename is specified, the request body will be written to that file and the number of bytes written returned, otherwise, the full request body will be returned as a string.
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh<td>The maximum size allowed, or 0/nil for unlimited size</td>
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh<td>The file to save the output to, or nil to return it as a string</td>
c6b6876815d20010b548909998c894a527adc139humbedoohThe number of bytes written if a filename was specified, otherwise it returns the entire request body as a string.
c6b6876815d20010b548909998c894a527adc139humbedoohif tonumber(r.headers_in['Content-Length'] or 0) < 10000 then
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh local smallfile = apache2.requestbody(r, 10000) -- fetch a small file into memory
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("I saved the uploaded file in memory")
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh local read = apache2.requestbody(r, 0, "/path/to/tmp")
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("I saved the uploaded file in a temp directory. Total bytes written was: ", read)
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.send_interim_response" id="apache2.send_interim_response">apache2.send_interim_response(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, boolean<em> send_headers</em>
c6b6876815d20010b548909998c894a527adc139humbedoohSends an interim (HTTP 1xx) response immediately.
c6b6876815d20010b548909998c894a527adc139humbedooh<td>send_headers Whether to send&clear headers in r->headers_out</td>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.set_context_prefix" id="apache2.set_context_prefix">apache2.set_context_prefix(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> prefix</em>, string<em> document</em>
c6b6876815d20010b548909998c894a527adc139humbedoohSet context_prefix and context_document_root for a request.
c6b6876815d20010b548909998c894a527adc139humbedooh<td>The corresponding directory on disk, without trailing slash</td>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.set_document_root" id="apache2.set_document_root">apache2.set_document_root(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> root</em>
c6b6876815d20010b548909998c894a527adc139humbedoohSets the document root of the request.
c6b6876815d20010b548909998c894a527adc139humbedooh-- Suppose our real document root is /var/bar, then...
c6b6876815d20010b548909998c894a527adc139humbedooh apache2.set_document_root(r, "/www/foo") -- change document root on the fly
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.set_keepalive" id="apache2.set_keepalive">apache2.set_keepalive(
c6b6876815d20010b548909998c894a527adc139humbedoohSets the keepalive status for this request
c6b6876815d20010b548909998c894a527adc139humbedoohTrue if keepalive can be set, false otherwise
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="Parser_functions" id="Parser_functions">HTTPd bindings: Parser functions</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.strcmp_match">apache2.strcmp_match</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.expr" id="apache2.expr">apache2.expr(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> expression</em>
c6b6876815d20010b548909998c894a527adc139humbedoohEvaluates an ap_expr (think <If ...>) expression and returns true if the expression is true, false otherwise. A second value containing an error string is returned if the expression is invalid.
c6b6876815d20010b548909998c894a527adc139humbedoohTrue if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string.
c6b6876815d20010b548909998c894a527adc139humbedoohif apache2.expr("%{REQUEST_URI} =~ /force-gzip") then
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedooh r:addoutputfilter("DEFLATE")
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.regex" id="apache2.regex">apache2.regex(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> expression</em>, string<em> source</em>
c6b6876815d20010b548909998c894a527adc139humbedoohEvaluates a regular expression and, if it matches the source string, captures the variables and returns the matches as a table. On error, it returns nil.
c6b6876815d20010b548909998c894a527adc139humbedoohTrue if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal matches = apache2.regex(r, [[(\S+) kitty]], "Hello kitty")
c6b6876815d20010b548909998c894a527adc139humbedoohif matches and matches[1] then
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("You said ", matches[1], " to kitty")
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.strcmp_match" id="apache2.strcmp_match">apache2.strcmp_match(
c6b6876815d20010b548909998c894a527adc139humbedooh string<em> str</em>, string<em> expexted</em>, boolean<em> ignoreCase</em>
c6b6876815d20010b548909998c894a527adc139humbedoohDetermines if a string matches a pattern containing the wildcards '?' or '*'
c6b6876815d20010b548909998c894a527adc139humbedoohTrue if the two strings match, false otherwise.
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("It matches!")
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="Server_settings" id="Server_settings">HTTPd bindings: Server settings</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.add_version_component">apache2.add_version_component</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.scoreboard_process">apache2.scoreboard_process</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.scoreboard_worker">apache2.scoreboard_worker</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.module_info">apache2.module_info</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.loaded_modules">apache2.loaded_modules</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.runtime_dir_relative">apache2.runtime_dir_relative</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.server_info">apache2.server_info</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.state_query">apache2.state_query</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.custom_response">apache2.custom_response</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<a href="#apache2.exists_config_define">apache2.exists_config_define</a>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.add_version_component" id="apache2.add_version_component">apache2.add_version_component(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> component</em>
c6b6876815d20010b548909998c894a527adc139humbedoohAdds a component to the server description and banner strings
c6b6876815d20010b548909998c894a527adc139humbedoohif not apache2.banner():match("FooModule") then -- Make sure we haven't added it already
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.custom_response" id="apache2.custom_response">apache2.custom_response(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, number<em> status</em>, string<em> string</em>
c6b6876815d20010b548909998c894a527adc139humbedoohInstall a custom response handler for a given status
c6b6876815d20010b548909998c894a527adc139humbedooh<td>The status for which the custom response should be used</td>
c6b6876815d20010b548909998c894a527adc139humbedooh<td>The custom response. This can be a static string, a file or a URL</td>
c6b6876815d20010b548909998c894a527adc139humbedoohapache2.custom_response(r, 404, "Not found!!")
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.exists_config_define" id="apache2.exists_config_define">apache2.exists_config_define(
c6b6876815d20010b548909998c894a527adc139humbedoohChecks for a definition from the server command line
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("This server was started with -DFOO")
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.loaded_modules" id="apache2.loaded_modules">apache2.loaded_modules(
c6b6876815d20010b548909998c894a527adc139humbedoohReturns a table containing the name (c filename) of all loaded modules
c6b6876815d20010b548909998c894a527adc139humbedoohA table containing the name (c filename) of all loaded modules
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.module_info" id="apache2.module_info">apache2.module_info(
c6b6876815d20010b548909998c894a527adc139humbedooh string<em> c</em>, string<em> file</em>
c6b6876815d20010b548909998c894a527adc139humbedoohReturns information about a specific module (if loaded)
c6b6876815d20010b548909998c894a527adc139humbedoohThe various commands available to this module as a table, or nil if the module wasn't found.
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.mpm_query" id="apache2.mpm_query">apache2.mpm_query(
c6b6876815d20010b548909998c894a527adc139humbedoohQueries the MPM for a specific value
c6b6876815d20010b548909998c894a527adc139humbedoohThe queried value
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.runtime_dir_relative" id="apache2.runtime_dir_relative">apache2.runtime_dir_relative(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> file</em>
c6b6876815d20010b548909998c894a527adc139humbedoohReturns the path of a file relative to the default runtime directory
c6b6876815d20010b548909998c894a527adc139humbedoohThe path of a file relative to the default runtime directory
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.scoreboard_process" id="apache2.scoreboard_process">apache2.scoreboard_process(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, number<em> child</em>
c6b6876815d20010b548909998c894a527adc139humbedoohReturns the scoreboard for a server daemon as a table
c6b6876815d20010b548909998c894a527adc139humbedoohThe scoreboard for a server daemon as a table
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.scoreboard_worker" id="apache2.scoreboard_worker">apache2.scoreboard_worker(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, number<em> child</em>, number<em> thread</em>
c6b6876815d20010b548909998c894a527adc139humbedoohReturns the scoreboard for a single thread as a table
c6b6876815d20010b548909998c894a527adc139humbedoohThe scoreboard for a single thread as a table
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.server_info" id="apache2.server_info">apache2.server_info(
c6b6876815d20010b548909998c894a527adc139humbedoohReturns a table with information about the server program
c6b6876815d20010b548909998c894a527adc139humbedoohA table with information about the server program
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.state_query" id="apache2.state_query">apache2.state_query(
c6b6876815d20010b548909998c894a527adc139humbedoohQuery the server for some state information
c6b6876815d20010b548909998c894a527adc139humbedoohr:puts("This is generation no. " .. gen .. " of the top-level parent")
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.terminate" id="apache2.terminate">apache2.terminate(
c6b6876815d20010b548909998c894a527adc139humbedoohKills off a server process. This has no other use than to show how dangerous mod_lua can be ;)
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="Database_connectivity" id="Database_connectivity">HTTPd bindings: Database connectivity</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.dbopen" id="apache2.dbopen">apache2.dbopen(
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> dbtype</em>, string<em> conn_string</em>
4c92e4b7cda4dc894b561e202bc682ebaac0ea48humbedoohOpens up a new database connection. See the DB functions for mod_pLua for more info on this.
c6b6876815d20010b548909998c894a527adc139humbedoohThe database connection as a table with functions, or nil if the connection failed. If a connection failed, a second argument (string) with the error code is returned.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal db, error = apache2.dbopen(r, "mod_dbd")
c6b6876815d20010b548909998c894a527adc139humbedoohif error then
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("DB error: ", error)
c6b6876815d20010b548909998c894a527adc139humbedooh -- DB stuff here
c6b6876815d20010b548909998c894a527adc139humbedoohCloses a database connection
c6b6876815d20010b548909998c894a527adc139humbedoohlocal db = apache2.dbopen(r, "mod_dbd") -- open a db connection
c6b6876815d20010b548909998c894a527adc139humbedoohdb:close() -- close it down
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> query</em>
c6b6876815d20010b548909998c894a527adc139humbedoohExecutes a statement that doesn't return a result set
c6b6876815d20010b548909998c894a527adc139humbedoohIf the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal db = apache2.dbopen(r, "mod_dbd")
c6b6876815d20010b548909998c894a527adc139humbedoohlocal affected = db:do("DELETE FROM `table` WHERE 1")
c6b6876815d20010b548909998c894a527adc139humbedoohif affected then
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts("Affected ", affected, " rows")
c6b6876815d20010b548909998c894a527adc139humbedooh request_rec<em> r</em>, string<em> query</em>
c6b6876815d20010b548909998c894a527adc139humbedoohQueries the database for information using the specified statement.
c6b6876815d20010b548909998c894a527adc139humbedoohIf the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message.
c6b6876815d20010b548909998c894a527adc139humbedoohlocal db = apache2.dbopen(r, "mod_dbd")
c6b6876815d20010b548909998c894a527adc139humbedoohlocal result, error = db:query("SELECT * FROM `table` WHERE 1")
c6b6876815d20010b548909998c894a527adc139humbedoohif result then
c6b6876815d20010b548909998c894a527adc139humbedooh for key, value in pairs(result)
c6b6876815d20010b548909998c894a527adc139humbedooh r:puts( ("row %s: %s\n"):format(key, table.concat(value, ", ")) )
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c6b6876815d20010b548909998c894a527adc139humbedooh<h2><a name="Miscellaneous" id="Miscellaneous">HTTPd bindings: Miscellaneous</a></h2>
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.clock" id="apache2.clock">apache2.clock(
c6b6876815d20010b548909998c894a527adc139humbedoohReturns the current time in microseconds.
c6b6876815d20010b548909998c894a527adc139humbedoohThe current time in microseconds.
c6b6876815d20010b548909998c894a527adc139humbedooh<h3><a name="apache2.sleep" id="apache2.sleep">apache2.sleep(
c6b6876815d20010b548909998c894a527adc139humbedoohSleeps for a while. Floating point values can be used to sleep for less than a second.
c6b6876815d20010b548909998c894a527adc139humbedoohr:puts("this is ")
c6b6876815d20010b548909998c894a527adc139humbedoohapache2.sleep(0.25) -- sleep for a quarter second.
c6b6876815d20010b548909998c894a527adc139humbedoohr:puts("delayed")
c6b6876815d20010b548909998c894a527adc139humbedooh<p><span>Available Languages: </span><a href="/en/developer/lua.html" title="English"> en </a></p>
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
c6b6876815d20010b548909998c894a527adc139humbedooh<script type="text/javascript"><!--//--><![CDATA[//><!--
c6b6876815d20010b548909998c894a527adc139humbedoohvar comments_shortname = 'httpd';
c6b6876815d20010b548909998c894a527adc139humbedoohvar comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/lua.html';
c6b6876815d20010b548909998c894a527adc139humbedooh(function(w, d) {
c6b6876815d20010b548909998c894a527adc139humbedooh if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
c6b6876815d20010b548909998c894a527adc139humbedooh d.write('<div id="comments_thread"><\/div>');
c6b6876815d20010b548909998c894a527adc139humbedooh var s = d.createElement('script');
c6b6876815d20010b548909998c894a527adc139humbedooh s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
c6b6876815d20010b548909998c894a527adc139humbedooh (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
c6b6876815d20010b548909998c894a527adc139humbedooh d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
c6b6876815d20010b548909998c894a527adc139humbedooh})(window, document);
c6b6876815d20010b548909998c894a527adc139humbedooh<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
c6b6876815d20010b548909998c894a527adc139humbedooh<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
c6b6876815d20010b548909998c894a527adc139humbedoohif (typeof(prettyPrint) !== 'undefined') {
c6b6876815d20010b548909998c894a527adc139humbedooh prettyPrint();