lua.html.en revision 205f749042ed530040a4f0080dbcb47ceae8a374
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
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>
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 thread
4aa603e6448b99f9371397d439795c91a93637eandLuaScope server 5 40</pre>
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:
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>
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.
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.
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.
4aa603e6448b99f9371397d439795c91a93637eand<pre class="prettyprint lang-config">LuaHookTranslateName /path/too/foo.lua mass_vhost</pre>
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.
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
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:
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>
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>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh<h2><a name="loadbalancing" id="loadbalancing">Example 5: A rudimentary load balancer</a></h2>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh This is an example of how you can create a load balancing mechanism.
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh In this example, we will be setting/getting the number of requests served
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh 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>
25f8d56998acb95d39c62c489d72b92d8d29b765humbedooh 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();