c6b6876815d20010b548909998c894a527adc139humbedooh<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
c6b6876815d20010b548909998c894a527adc139humbedooh XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
c6b6876815d20010b548909998c894a527adc139humbedooh This file is generated from xml source: DO NOT EDIT
c6b6876815d20010b548909998c894a527adc139humbedooh XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>Creating hooks and scripts with mod_lua - Apache HTTP Server Version 2.5</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" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.min.js" type="text/javascript">
c6b6876815d20010b548909998c894a527adc139humbedooh<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.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>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#loadbalancing">Example 5: A rudimentary load balancer</a></li>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh<li><img alt="" src="/images/down.gif" /> <a href="#map_handler">Example 6: 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</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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarThis document will discuss several cases where <code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> can be used
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarto 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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarFirst and foremost, you are expected to have a basic knowledge of how the Lua
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarprogramming language works. In most cases, we will try to be as pedagogical
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coaras possible and link to documents describing the functions used in the
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarexamples, but there are also many cases where it is necessary to either
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarjust assume that "it works" or do some digging yourself into what the hows
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarand 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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarSetting the right <code class="directive"><a href="/mod/mod_lua.html#luascope">LuaScope</a></code> setting
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarfor your Lua scripts can be essential to your server's
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarperformance. By default, the scope is set to <code>once</code>, which means
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarthat every call to a Lua script will spawn a new Lua state that handles that
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarscript and is destroyed immediately after. This option keeps the memory
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarfootprint of mod_lua low, but also affects the processing speed of a request.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarIf you have the memory to spare, you can set the scope to <code>thread</code>,
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarwhich will make mod_lua spawn a Lua state that lasts the entirity of a thread's
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarlifetime, speeding up request processing by 2-3 times. Since mod_lua will create
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coara state for each script, this may be an expensive move, memory-wise, so to
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarcompromise between speed and memory usage, you can choose the <code>server</code>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coaroption to create a pool of Lua states to be used. Each request for a Lua script or
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coara hook function will then acquire a state from the pool and release it back when it's
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coardone using it, allowing you to still gain a significant performance increase, while
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohkeeping your memory footprint low. Some examples of possible settings are:
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohLuaScope thread
4aa603e6448b99f9371397d439795c91a93637eandLuaScope server 5 40</pre>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarAs a general rule of thumb: If your server has none to low usage, use <code>once</code>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coaror <code>request</code>, if your server has low to medium usage, use the <code>server</code>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarpool, and if it has high usage, use the <code>thread</code> setting. As your server's
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarload 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.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<strong>Note:</strong> The <code>min</code> and <code>max</code> settings for the
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<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.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarBy default, <code class="module"><a href="/mod/mod_lua.html">mod_lua</a></code> stats each Lua script to determine whether a reload
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar(and thus, a re-interpretation and re-compilation) of a script is required. This is managed
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarthrough the <code class="directive"><a href="/mod/mod_lua.html#luacodecache">LuaCodeCache</a></code> directive. If you are running
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coaryour scripts on a production server, and you do not need to update them regularly, it may be
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coaradvantageous to set this directive to the <code>forever</code> value, which will cause mod_lua
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarto skip the stat process and always reuse the compiled byte-code from the first access to the
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarscript, thus speeding up the processing. For Lua hooks, this can prove to increase peformance,
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarwhile 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.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarFor maximum performance, it is generally recommended that any initialization of libraries,
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohconstants and master tables be kept outside the handle's scope:
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-lua">--[[ This is good practice ]]--
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohrequire "string"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohrequire "someLibrary"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohlocal masterTable = {}
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohlocal constant = "Foo bar baz"
7bf171806d862d85c9e913b87aacccb31403be9bhumbedoohfunction handle(r)
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-lua">--[[ 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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar These first examples show how mod_lua can be used to rewrite URIs in the same
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar way that one could do using <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> or
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>, but with more clarity
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar on how the decision-making takes place, as well as allowing for more complex
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh decisions than would otherwise be allowed with said directives.
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaHookTranslateName /path/too/foo.lua remap</pre>
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.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar This example will evaluate some conditions, and based on that,
c6b6876815d20010b548909998c894a527adc139humbedooh remap a file to one of two destinations, using a rewrite map.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar 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 = {
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar photos = {
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar 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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar As with simple and advanced rewriting, you can use mod_lua for dynamically
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar assigning a hostname to a specific document root, much like
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> does, but with more control over what goes
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar where. This could be as simple as a table holding the information about which
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar host goes into which folder, or more advanced, using a database holding the
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh document roots of each hostname.
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaHookTranslateName /path/too/foo.lua mass_vhost</pre>
c6b6876815d20010b548909998c894a527adc139humbedooh Simple mass vhost script
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar 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.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar 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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar With the authorization hooks, you can add custom auth phases to your request
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar processing, allowing you to either add new requirements that were not previously
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar supported by httpd, or tweaking existing ones to accommodate your needs.
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaHookAuthChecker /path/too/foo.lua check_auth</pre>
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
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar 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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar If you require even more advanced control over your authorization phases,
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar you can add custom authz providers to help you manage your server. The
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar example below shows you how you can split a single htpasswd file into
d374d0c14a2cf6582e3c9825a9b0acba0d7c736ahumbedooh groups with different permissions:
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaAuthzProvider rights /path/to/lua/script.lua rights_handler
c6b6876815d20010b548909998c894a527adc139humbedooh Require rights member
c6b6876815d20010b548909998c894a527adc139humbedooh</Directory>
c6b6876815d20010b548909998c894a527adc139humbedooh Require rights admin
4aa603e6448b99f9371397d439795c91a93637eand</Directory></pre>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar 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>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh<h2><a name="loadbalancing" id="loadbalancing">Example 5: A rudimentary load balancer</a></h2>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar This is an example of how you can create a load balancing mechanism.
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar In this example, we will be setting/getting the number of requests served
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar by each backend using IVM variables, and preferring the backend with least
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh requests served in total:
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaHookTranslateName /path/to/script.lua proxy_handler</pre>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar This script uses a basic IVM table to determine where to
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh send the request.
25f8d56998acb95d39c62c489d72b92d8d29b765humbedoohlocal backends = {
25f8d56998acb95d39c62c489d72b92d8d29b765humbedoohfunction pick_backend(r)
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh local chosen_backend = 1 -- default to backend1
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh local lowest_count = nil
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh for i = 1, #backends, 1 do -- Loop through all backends
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh local count = r:ivm_get("proxy_request_count_" .. i)
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh if not count then -- If this backend hasn't been used at all, prefer it
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh chosen_backend = i
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh lowest_count = 0
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh if not lowest_count or lowest_count > count then -- If this backend has had less requests, pick it for now
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh chosen_backend = i
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh lowest_count = count
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh lowest_count = lowest_count + 1
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh r:ivm_set("proxy_request_count_" .. chosen_backend, lowest_count)
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh return chosen_backend
25f8d56998acb95d39c62c489d72b92d8d29b765humbedoohfunction proxy_handler(r)
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh local backend = pick_backend(r) -- Pick a backend based on no. of requests served
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh r.handler = "proxy-server"
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh r.filename = "proxy:" .. backends[backend] .. r.uri
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh return apache2.DECLINED -- let the proxy handler do this instead
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh<h2><a name="map_handler" id="map_handler">Example 6: Overlays using LuaMapHandler</a></h2>
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaMapHandler ^/portal/([a-z]+)/ /path/to/lua/script.lua handle_$1</pre>
c6b6876815d20010b548909998c894a527adc139humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh<h2><a name="mod_status_lua" id="mod_status_lua">Example 6: Basic Lua scripts</a></h2>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedoohAlso coming soon
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);
205f749042ed530040a4f0080dbcb47ceae8a374rjung<p class="apache">Copyright 2015 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>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.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();