<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<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" />
-<script src="../style/scripts/prettify.js" type="text/javascript">
+<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
-<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>
+<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>
<p class="apache">Apache HTTP Server Version 2.5</p>
<img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookfixups">LuaHookFixups</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookinsertfilter">LuaHookInsertFilter</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#luahooklog">LuaHookLog</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookmaptostorage">LuaHookMapToStorage</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahooktranslatename">LuaHookTranslateName</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahooktypechecker">LuaHookTypeChecker</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#writingauthzproviders">Writing Authorization Providers</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Writing Hooks</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Data Structures</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#functions">Built in functions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging Functions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#apache2">apache2 Package</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modifying contents with Lua filters</a></li>
<p>The basic module loading directive is</p>
-<pre class="prettyprint lang-config">
- LoadModule lua_module modules/mod_lua.so
-</pre>
+<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>
<p>
<code>mod_lua</code> provides a handler named <code>lua-script</code>,
-which can be used with an <code>AddHandler</code> directive:</p>
+which can be used with an <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code>
+or <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> directive:</p>
-<pre class="prettyprint lang-config">
-AddHandler lua-script .lua
-</pre>
+<pre class="prettyprint lang-config"><Files *.lua>
+ SetHandler lua-script .lua
+</Files></pre>
<p>
--]]
function handle(r)
r.content_type = "text/plain"
- r:puts("Hello Lua World!\n")
if r.method == 'GET' then
+ r:puts("Hello Lua World!\n")
for k, v in pairs( r:parseargs() ) do
r:puts( string.format("%s: %s\n", k, v) )
end
elseif r.method == 'POST' then
+ r:puts("Hello Lua World!\n")
for k, v in pairs( r:parsebody() ) do
r:puts( string.format("%s: %s\n", k, v) )
end
- else
+ elseif r.method == 'PUT' then
+-- use our own Error contents
r:puts("Unsupported HTTP method " .. r.method)
+ r.status = 405
+ return apache2.ok
+ else
+-- use the ErrorDocument
+ return 501
end
-end
-</pre>
+ return apache2.OK
+end</pre>
<p>
else
return apache2.AUTHZ_DENIED
end
-end
-</pre>
+end</pre>
<p>The following configuration registers this function as provider
<code>foo</code> and configures it for URL <code>/</code>:</p>
-<pre class="prettyprint lang-config">
-LuaAuthzProvider foo authz_provider.lua authz_check_foo
+<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
<Location />
Require foo 10.1.2.3 john_doe
-</Location>
-</pre>
+</Location></pre>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<p>Hook functions are how modules (and Lua scripts) participate in the
processing of requests. Each type of hook exposed by the server exists for
-a specific purpose, such as mapping requests to the filesystem,
-performing access control, or setting mimetypes:</p>
+a specific purpose, such as mapping requests to the file system,
+performing access control, or setting mime types:</p>
<table class="bordered"><tr class="header">
<th>Hook phase</th>
</tr>
<tr class="odd">
<td>Logging</td>
- <td>(none)</td>
+ <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
<td>Once a request has been handled, it enters several logging phases,
- which logs the request in either the error or access log</td>
+ which logs the request in either the error or access log. Mod_lua
+ is able to hook into the start of this and control logging output.</td>
</tr>
</table>
(except for LuaAuthzProvider, which also gets passed the arguments from
the Require directive).
They can return any value, depending on the hook, but most commonly
-they'll return OK, DONE, or DECLINED, which you can write in lua as
+they'll return OK, DONE, or DECLINED, which you can write in Lua as
<code>apache2.OK</code>, <code>apache2.DONE</code>, or
<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
end
-- we don't care about this URL, give another module a chance
return apache2.DECLINED
-end
-</pre>
+end</pre>
return apache2.DECLINED
end
return apache2.DECLINED
-end
-</pre>
+end</pre>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<dd>
<p>The request_rec is mapped in as a userdata. It has a metatable
which lets you do useful things with it. For the most part it
- has the same fields as the request_rec struct, many of which are writeable as
+ has the same fields as the request_rec struct, many of which are writable as
well as readable. (The table fields' content can be changed, but the
fields themselves cannot be set to different tables.)</p>
<td>The IP of the user agent making the request</td>
</tr>
</table>
+ </dd>
+ </dl>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="functions" id="functions">Built in functions</a></h2>
+
+<p>The request_rec object has (at least) the following methods:</p>
+
+<pre class="prettyprint lang-lua">r:flush() -- flushes the output buffer.
+ -- Returns true if the flush was successful, false otherwise.
- <p>The request_rec has (at least) the following methods:</p>
+while we_have_stuff_to_send do
+ r:puts("Bla bla bla\n") -- print something to client
+ r:flush() -- flush the buffer (send to client)
+ r.usleep(500000) -- fake processing time for 0.5 sec. and repeat
+end</pre>
- <pre class="prettyprint lang-lua">
- r:flush() -- flushes the output buffer
- </pre>
+<pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- add an output filter:
- <pre class="prettyprint lang-lua">
- r:addoutputfilter(name|function) -- add an output filter
- </pre>
+r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream</pre>
- <pre class="prettyprint lang-lua">
- r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform
- </pre>
+<pre class="prettyprint lang-lua">r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
+if use_sendfile_thing then
+ r:sendfile("/var/www/large_file.img")
+end</pre>
- <pre class="prettyprint lang-lua">
- r:parseargs() -- returns a Lua table containing the request's query string arguments
- </pre>
+<pre class="prettyprint lang-lua">r:parseargs() -- returns two tables; one standard key/value table for regular GET data,
+ -- and one for multi-value data (fx. foo=1&foo=2&foo=3):
- <pre class="prettyprint lang-lua">
- r:parsebody([sizeLimit]) -- parse the request body as a POST and return a lua table.
+local GET, GETMULTI = r:parseargs()
+r:puts("Your name is: " .. GET['name'] or "Unknown")</pre>
+
+
+<pre class="prettyprint lang-lua">r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
+ -- just like r:parseargs().
-- An optional number may be passed to specify the maximum number
- -- of bytes to parse. Default is 8192 bytes.
- </pre>
+ -- of bytes to parse. Default is 8192 bytes:
+
+local POST, POSTMULTI = r:parsebody(1024*1024)
+r:puts("Your name is: " .. POST['name'] or "Unknown")</pre>
- <pre class="prettyprint lang-lua">
- r:puts("hello", " world", "!") -- print to response body
- </pre>
+<pre class="prettyprint lang-lua">r:puts("hello", " world", "!") -- print to response body, self explanatory</pre>
- <pre class="prettyprint lang-lua">
- r:write("a single string") -- print to response body
- </pre>
+<pre class="prettyprint lang-lua">r:write("a single string") -- print to response body, self explanatory</pre>
- <pre class="prettyprint lang-lua">
- r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result
- </pre>
+<pre class="prettyprint lang-lua">r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result</pre>
- <pre class="prettyprint lang-lua">
- r:base64_encode(string) -- Encodes a string using the Base64 encoding standard
- </pre>
+<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
+local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>
- <pre class="prettyprint lang-lua">
- r:base64_decode(string) -- Decodes a Base64-encoded string
- </pre>
+<pre class="prettyprint lang-lua">r:base64_decode(string) -- Decodes a Base64-encoded string:
- <pre class="prettyprint lang-lua">
- r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe)
- </pre>
+local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>
- <pre class="prettyprint lang-lua">
- r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe)
- </pre>
+<pre class="prettyprint lang-lua">r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
+local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>
- <pre class="prettyprint lang-lua">
- r:escape(string) -- URL-Escapes a string
- </pre>
+<pre class="prettyprint lang-lua">r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
- <pre class="prettyprint lang-lua">
- r:unescape(string) -- Unescapes an URL-escaped string
- </pre>
+local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>
- <pre class="prettyprint lang-lua">
- r:banner() -- Returns the current server banner
- </pre>
+<pre class="prettyprint lang-lua">r:escape(string) -- URL-Escapes a string:
+local url = "http://foo.bar/1 2 3 & 4 + 5"
+local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>
- <pre class="prettyprint lang-lua">
- r:port() -- Returns the current server port used for the request
- </pre>
+<pre class="prettyprint lang-lua">r:unescape(string) -- Unescapes an URL-escaped string:
- <pre class="prettyprint lang-lua">
- r:mpm_query(number) -- Queries the server for MPM information using ap_mpm_query
- </pre>
+local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
+local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5'</pre>
- <pre class="prettyprint lang-lua">
- r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
- </pre>
+<pre class="prettyprint lang-lua">r:construct_url(string) -- Constructs an URL from an URI
+local url = r:construct_url(r.uri)</pre>
- <pre class="prettyprint lang-lua">
- r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>
- </pre>
+<pre class="prettyprint lang-lua">r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
- <pre class="prettyprint lang-lua">
- r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>
- </pre>
+local mpm = r.mpm_query(14)
+if mpm == 1 then
+ r:puts("This server uses the Event MPM")
+end</pre>
- <pre class="prettyprint lang-lua">
- r:started() -- Returns the time of the last server (re)start
- </pre>
+<pre class="prettyprint lang-lua">r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
+if r:expr("%{HTTP_HOST} =~ /^www/") then
+ r:puts("This host name starts with www")
+end</pre>
- <pre class="prettyprint lang-lua">
- r:clock() -- Returns the current time with microsecond precision
- </pre>
+<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
- <pre class="prettyprint lang-lua">
-r:requestbody(filename) -- Reads and returns the request body of a request.
- -- If 'filename' is specified, it instead saves the
- -- contents to that file.
- </pre>
+local process = r:scoreboard_process(1)
+r:puts("Server 1 has PID " .. process.pid)</pre>
- <pre class="prettyprint lang-lua">
- r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter
- </pre>
+<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
+local thread = r:scoreboard_worker(1, 1)
+r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")</pre>
- <pre class="prettyprint lang-lua">
- r:module_info(module_name) -- Queries the server for information about a module
- </pre>
- <pre class="prettyprint lang-lua">
- r:loaded_modules() -- Returns a list of modules loaded by httpd
- </pre>
+<pre class="prettyprint lang-lua">r:clock() -- Returns the current time with microsecond precision</pre>
- <pre class="prettyprint lang-lua">
-r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
- -- relative to the appropriate run-time directory.
- </pre>
+<pre class="prettyprint lang-lua">r:requestbody(filename) -- Reads and returns the request body of a request.
+ -- If 'filename' is specified, it instead saves the
+ -- contents to that file:
+
+local input = r:requestbody()
+r:puts("You sent the following request body to me:\n")
+r:puts(input)</pre>
- <pre class="prettyprint lang-lua">
- r:server_info() -- Returns a table containing server information, such as
- -- the name of the httpd executable file, mpm used etc.
- </pre>
+<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter</pre>
- <pre class="prettyprint lang-lua">
- r:set_document_root(file_path) -- Sets the document root for the request to file_path
- </pre>
+<pre class="prettyprint lang-lua">r.module_info(module_name) -- Queries the server for information about a module
+local mod = r.module_info("mod_lua.c")
+if mod then
+ for k, v in pairs(mod.commands) do
+ r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
+ end
+end</pre>
- <pre class="prettyprint lang-lua">
- r:add_version_component(component_string) -- Adds a component to the server banner.
- </pre>
+<pre class="prettyprint lang-lua">r:loaded_modules() -- Returns a list of modules loaded by httpd:
- <pre class="prettyprint lang-lua">
- r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request
- </pre>
+for k, module in pairs(r:loaded_modules()) do
+ r:puts("I have loaded module " .. module .. "\n")
+end</pre>
- <pre class="prettyprint lang-lua">
- r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependant way
- </pre>
+<pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
+ -- relative to the appropriate run-time directory.</pre>
- <pre class="prettyprint lang-lua">
- r:escape_logitem(string) -- Escapes a string for logging
- </pre>
+<pre class="prettyprint lang-lua">r:server_info() -- Returns a table containing server information, such as
+ -- the name of the httpd executable file, mpm used etc.</pre>
- <pre class="prettyprint lang-lua">
-r:strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (GLOBs).
- -- fx. whether 'www.example.com' matches '*.example.com'
- </pre>
+<pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Sets the document root for the request to file_path</pre>
- <pre class="prettyprint lang-lua">
- r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.
- </pre>
- <pre class="prettyprint lang-lua">
- r:make_etag() -- Constructs and returns the etag for the current request.
- </pre>
+<pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request</pre>
- <pre class="prettyprint lang-lua">
-r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
- -- if 'clear' is true, available headers will be sent and cleared.
- </pre>
+<pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way</pre>
- <pre class="prettyprint lang-lua">
-r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
- -- This works much like the ErrorDocument directive.
- </pre>
+<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Escapes a string for logging</pre>
- <pre class="prettyprint lang-lua">
- r:exists_config_define(string) -- Checks whether a configuration definition exists or not.
- </pre>
+<pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
+ -- fx. whether 'www.example.com' matches '*.example.com':
+
+local match = r.strcmp_match("foobar.com", "foo*.com")
+if match then
+ r:puts("foobar.com matches foo*.com")
+end</pre>
- <pre class="prettyprint lang-lua">
- r:state_query(string) -- Queries the server for state information
- </pre>
+<pre class="prettyprint lang-lua">r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.</pre>
- <pre class="prettyprint lang-lua">
- r:stat(filename) -- Runs stat() on a file, and returns a table with file information
- </pre>
+<pre class="prettyprint lang-lua">r:make_etag() -- Constructs and returns the etag for the current request.</pre>
- <pre class="prettyprint lang-lua">
- r:regex(string, pattern) -- Runs a regular expression match on a string, returning captures if matched.
- </pre>
+<pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
+ -- if 'clear' is true, available headers will be sent and cleared.</pre>
- <pre class="prettyprint lang-lua">
- r:sleep(number_of_seconds) -- Puts the script to sleep for a given number of seconds.
- </pre>
+<pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
+ -- This works much like the ErrorDocument directive:
+
+r:custom_response(404, "Baleted!")</pre>
- <pre class="prettyprint lang-lua">
-r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
- -- See '<a href="#databases">Database connectivity</a>' for details.
- </pre>
+<pre class="prettyprint lang-lua">r.exists_config_define(string) -- Checks whether a configuration definition exists or not:
+
+if r.exists_config_define("FOO") then
+ r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:state_query(string) -- Queries the server for state information</pre>
+
+
+<pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Runs stat() on a file, and returns a table with file information:
+
+local info = r:stat("/var/www/foo.txt")
+if info then
+ r:puts("This file exists and was last modified at: " .. info.modified)
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Runs a regular expression match on a string, returning captures if matched:
+
+local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
+if matches then
+ r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
+end
+
+-- Example ignoring case sensitivity:
+local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
+
+-- Flags can be a bitwise combination of:
+-- 0x01: Ignore case
+-- 0x02: Multiline search</pre>
+
+
+<pre class="prettyprint lang-lua">r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.</pre>
+
+
+<pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
+ -- See '<a href="#databases">Database connectivity</a>' for details.</pre>
+
+
+<pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Set an Inter-VM variable to hold a specific value.
+ -- These values persist even though the VM is gone or not being used,
+ -- and so should only be used if MaxConnectionsPerChild is > 0
+ -- Values can be numbers, strings and booleans, and are stored on a
+ -- per process basis (so they won't do much good with a prefork mpm)
+
+r:ivm_get("key") -- Fetches a variable set by ivm_set. Returns the contents of the variable
+ -- if it exists or nil if no such variable exists.
+
+-- An example getter/setter that saves a global variable outside the VM:
+function handle(r)
+ -- First VM to call this will get no value, and will have to create it
+ local foo = r:ivm_get("cached_data")
+ if not foo then
+ foo = do_some_calcs() -- fake some return value
+ r:ivm_set("cached_data", foo) -- set it globally
+ end
+ r:puts("Cached data is: ", foo)
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:htpassword(string [,algorithm [,cost]]) -- Creates a password hash from a string.
+ -- algorithm: 0 = APMD5 (default), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
+ -- cost: only valid with BCRYPT algorithm (default = 5).</pre>
+
+
+<pre class="prettyprint lang-lua">r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode paramter.</pre>
+
+
+<pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode paramter.</pre>
+
+
+<pre class="prettyprint lang-lua">r:rmdir(dir) -- Removes a directory.</pre>
+
+
+<pre class="prettyprint lang-lua">r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.</pre>
+
+
+<pre class="prettyprint lang-lua">r:get_direntries(dir) -- Returns a table with all directory entries.
+
+function handle(r)
+ local dir = r.context_document_root
+ for _, f in ipairs(r:get_direntries(dir)) do
+ local info = r:stat(dir .. "/" .. f)
+ if info then
+ local mtime = os.date(fmt, info.mtime / 1000000)
+ local ftype = (info.filetype == 2) and "[dir] " or "[file]"
+ r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
+ end
+ end
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.</pre>
+
+
+<pre class="prettyprint lang-lua">r:getcookie(key) -- Gets a HTTP cookie</pre>
+
+
+<pre class="prettyprint lang-lua">r:setcookie{
+ key = [key],
+ value = [value],
+ expires = [expiry],
+ secure = [boolean],
+ httponly = [boolean],
+ path = [path],
+ domain = [domain]
+} -- Sets a HTTP cookie, for instance:
+
+r:setcookie{
+ key = "cookie1",
+ value = "HDHfa9eyffh396rt",
+ expires = os.time() + 86400,
+ secure = true
+}</pre>
+
+
+<pre class="prettyprint lang-lua">r:wsupgrade() -- Upgrades a connection to WebSockets if possible (and requested):
+if r:wsupgrade() then -- if we can upgrade:
+ r:wswrite("Welcome to websockets!") -- write something to the client
+ r:wsclose() -- goodbye!
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:wsread() -- Reads a WebSocket frame from a WebSocket upgraded connection (see above):
+
+local line, isFinal = r:wsread() -- isFinal denotes whether this is the final frame.
+ -- If it isn't, then more frames can be read
+r:wswrite("You wrote: " .. line)</pre>
+
+
+<pre class="prettyprint lang-lua">r:wswrite(line) -- Writes a frame to a WebSocket client:
+r:wswrite("Hello, world!")</pre>
+
+
+<pre class="prettyprint lang-lua">r:wsclose() -- Closes a WebSocket request and terminates it for httpd:
+
+if r:wsupgrade() then
+ r:wswrite("Write something: ")
+ local line = r:wsread() or "nothing"
+ r:wswrite("You wrote: " .. line);
+ r:wswrite("Goodbye!")
+ r:wsclose()
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:wspeek() -- Checks if any data is ready to be read
+
+-- Sleep while nothing is being sent to us...
+while r:wspeek() == false do
+ r.usleep(50000)
+end
+-- We have data ready!
+local line = r:wsread()</pre>
- </dd>
- </dl>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="logging" id="logging">Logging Functions</a></h2>
-<pre class="prettyprint lang-lua">
- -- examples of logging messages<br />
+<pre class="prettyprint lang-lua"> -- examples of logging messages<br />
r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
r:debug("This is a debug log message")<br />
r:info("This is an info log message")<br />
function as buckets are sent down the filter chain. The core structure of
such a function is:
</p>
- <pre class="prettyprint lang-lua">
-function filter(r)
+ <pre class="prettyprint lang-lua">function filter(r)
-- Our first yield is to signal that we are ready to receive buckets.
-- Before this yield, we can set up our environment, check for conditions,
-- and, if we deem it necessary, decline filtering a request alltogether:
-- can be done by doing a final yield here. Both input and output filters
-- can append data to the content in this phase.
coroutine.yield([optional footer to be appended to the content])
-end
- </pre>
+end</pre>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle)
as well as mod_dbd.
</p>
- <p>Connecting and firing off queries is as easy as:</p>
- <pre class="prettyprint lang-lua">
-function handler(r)
- local database, err = r:dbacquire("mysql", "server=localhost&user=root&database=mydb")
+ <p>The example below shows how to acquire a database handle and return information from a table:</p>
+ <pre class="prettyprint lang-lua">function handle(r)
+ -- Acquire a database handle
+ local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
if not err then
+ -- Select some information from it
local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
if not err then
local rows = results(0) -- fetch all rows synchronously
else
r:puts("Could not connect to the database: " .. err)
end
-end
- </pre>
+end</pre>
<p>
- To utilize <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, simply specify <code>mod_dbd</code>
+ To utilize <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, specify <code>mod_dbd</code>
as the database type, or leave the field blank:
</p>
- <pre class="prettyprint lang-lua">
- local database = r:dbacquire("mod_dbd")
- </pre>
+ <pre class="prettyprint lang-lua">local database = r:dbacquire("mod_dbd")</pre>
<h3><a name="database_object" id="database_object">Database object and contained functions</a></h3>
<p>The database object returned by <code>dbacquire</code> has the following methods:</p>
<p><strong>Normal select and query from a database:</strong></p>
- <pre class="prettyprint lang-lua">
--- Run a statement and return the number of rows affected:
+ <pre class="prettyprint lang-lua">-- Run a statement and return the number of rows affected:
local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
-- Run a statement and return a result set that can be used synchronously or async:
-local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")
- </pre>
+local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")</pre>
<p><strong>Using prepared statements (recommended):</strong></p>
- <pre class="prettyprint lang-lua">
--- Create and run a prepared statement:
+ <pre class="prettyprint lang-lua">-- Create and run a prepared statement:
local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
if not errmsg then
- local result, errmsg = statement:query(20) -- run the statement with age >20
+ local result, errmsg = statement:query(20) -- run the statement with age > 20
end
-- Fetch a prepared statement from a DBDPrepareSQL directive:
local statement, errmsg = database:prepared(r, "someTag")
if not errmsg then
local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
-end
-
-</pre>
+end</pre>
<p><strong>Escaping values, closing databases etc:</strong></p>
- <pre class="prettyprint lang-lua">
--- Escape a value for use in a statement:
+ <pre class="prettyprint lang-lua">-- Escape a value for use in a statement:
local escaped = database:escape(r, [["'|blabla]])
-- Close a database connection and free up handles:
database:close()
-- Check whether a database connection is up and running:
-local connected = database:active()
- </pre>
+local connected = database:active()</pre>
<h3><a name="result_sets" id="result_sets">Working with result sets</a></h3>
- <p>The result set returned by <code>db:query</code> or by the prepared statement functions
+ <p>The result set returned by <code>db:select</code> or by the prepared statement functions
created through <code>db:prepare</code> can be used to
fetch rows synchronously or asynchronously, depending on the row number specified:<br />
<code>result(0)</code> fetches all rows in a synchronous manner, returning a table of rows.<br />
<code>result(-1)</code> fetches the next available row in the set, asynchronously.<br />
<code>result(N)</code> fetches row number <code>N</code>, asynchronously:
</p>
- <pre class="prettyprint lang-lua">
--- fetch a result set using a regular query:
+ <pre class="prettyprint lang-lua">-- fetch a result set using a regular query:
local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
local rows = result(0) -- Fetch ALL rows synchronously
local row = result(-1) -- Fetch the next available row, asynchronously
local row = result(1234) -- Fetch row number 1234, asynchronously
- </pre>
+local row = result(-1, true) -- Fetch the next available row, using row names as key indexes.</pre>
<p>One can construct a function that returns an iterative function to iterate over all rows
in a synchronous or asynchronous way, depending on the async argument:
</p>
- <pre class="prettyprint lang-lua">
-function rows(resultset, async)
+ <pre class="prettyprint lang-lua">function rows(resultset, async)
local a = 0
local function getnext()
a = a + 1
....
end
end
-end
- </pre>
+end</pre>
<h3><a name="closing_databases" id="closing_databases">Closing a database connection</a></h3>
if you leave the closing up to mod_lua. Essentially, the following two measures are
the same:
</p>
- <pre class="prettyprint lang-lua">
--- Method 1: Manually close a handle
+ <pre class="prettyprint lang-lua">-- Method 1: Manually close a handle
local database = r:dbacquire("mod_dbd")
database:close() -- All done
-- Method 2: Letting the garbage collector close it
local database = r:dbacquire("mod_dbd")
database = nil -- throw away the reference
-collectgarbage() -- close the handle via GC
-</pre>
+collectgarbage() -- close the handle via GC</pre>
<h3><a name="database_caveat" id="database_caveat">Precautions when working with databases</a></h3>
<p>After a lua function has been registered as authorization provider, it can be used
with the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive:</p>
-<pre class="prettyprint lang-config">
-LuaRoot /usr/local/apache2/lua
+<pre class="prettyprint lang-config">LuaRoot /usr/local/apache2/lua
LuaAuthzProvider foo authz.lua authz_check_foo
<Location />
Require foo johndoe
-</Location>
-</pre>
+</Location></pre>
-<pre class="prettyprint lang-lua">
-require "apache2"
+<pre class="prettyprint lang-lua">require "apache2"
function authz_check_foo(r, who)
if r.user ~= who then return apache2.AUTHZ_DENIED
return apache2.AUTHZ_GRANTED
-end
-</pre>
+end</pre>
<p>In general stat or forever is good for production, and stat or never
for development.</p>
- <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
-LuaCodeCache stat
+ <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaCodeCache stat
LuaCodeCache forever
-LuaCodeCache never
- </pre>
+LuaCodeCache never</pre>
</div>
a request. This can be used to implement arbitrary authentication
and authorization checking. A very simple example:
</p>
-<pre class="prettyprint lang-lua">
-require 'apache2'
+<pre class="prettyprint lang-lua">require 'apache2'
-- fake authcheck hook
-- If request has no auth info, set the response header and
return 401
end
return apache2.OK
-end
-</pre>
+end</pre>
<div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
control when this script runs relative to other modules.</p></div>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
</table><p>Not Yet Implemented</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookLog" id="LuaHookLog">LuaHookLog</a> <a name="luahooklog" id="luahooklog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access log phase of a request
+processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookLog /path/to/lua/script.lua log_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+<p>
+ This simple logging hook allows you to run a function when httpd enters the
+ logging phase of a request. With it, you can append data to your own logs,
+ manipulate data before the regular log is written, or prevent a log entry
+ from being created. To prevent the usual logging from happening, simply return
+ <code>apache2.DONE</code> in your logging handler, otherwise return
+ <code>apache2.OK</code> to tell httpd to log as normal.
+</p>
+<p>Example:</p>
+<pre class="prettyprint lang-config">LuaHookLog /path/to/script.lua logger</pre>
+
+<pre class="prettyprint lang-lua">-- /path/to/script.lua --
+function logger(r)
+ -- flip a coin:
+ -- If 1, then we write to our own Lua log and tell httpd not to log
+ -- in the main log.
+ -- If 2, then we just sanitize the output a bit and tell httpd to
+ -- log the sanitized bits.
+
+ if math.random(1,2) == 1 then
+ -- Log stuff ourselves and don't log in the regular log
+ local f = io.open("/foo/secret.log", "a")
+ if f then
+ f:write("Something secret happened at " .. r.uri .. "\n")
+ f:close()
+ end
+ return apache2.DONE -- Tell httpd not to use the regular logging functions
+ else
+ r.uri = r.uri:gsub("somesecretstuff", "") -- sanitize the URI
+ return apache2.OK -- tell httpd to log it.
+ end
+end</pre>
+
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
<p>Like <code class="directive">LuaHookTranslateName</code> but executed at the
map-to-storage phase of a request. Modules like mod_cache run at this phase,
which makes for an interesting example on what to do here:</p>
- <pre class="prettyprint lang-config">
- LuaHookMapToStorage /path/to/lua/script.lua check_cache
- </pre>
+ <pre class="prettyprint lang-config">LuaHookMapToStorage /path/to/lua/script.lua check_cache</pre>
- <pre class="prettyprint lang-lua">
-require"apache2"
+ <pre class="prettyprint lang-lua">require"apache2"
cached_files = {}
function read_file(filename)
end
end
return apache2.DECLINED -- If we had nothing to do, let others serve this.
-end
- </pre>
+end</pre>
<p>Example:</p>
-<pre class="prettyprint lang-config">
-# httpd.conf
-LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
-</pre>
+<pre class="prettyprint lang-config"># httpd.conf
+LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper</pre>
-<pre class="prettyprint lang-lua">
--- /scripts/conf/hooks.lua --
+<pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua --
require "apache2"
function silly_mapper(r)
if r.uri == "/" then
else
return apache2.DECLINED
end
-end
-</pre>
+end</pre>
<div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
This phase is where requests are assigned a content type and a handler, and thus can
be used to modify the type and handler based on input:
</p>
- <pre class="prettyprint lang-config">
- LuaHookTypeChecker /path/to/lua/script.lua type_checker
- </pre>
+ <pre class="prettyprint lang-config">LuaHookTypeChecker /path/to/lua/script.lua type_checker</pre>
- <pre class="prettyprint lang-lua">
- function type_checker(r)
+ <pre class="prettyprint lang-lua"> function type_checker(r)
if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
r.content_type = "image/gif" -- assign it the image/gif type
r.handler = "gifWizard" -- tell the gifWizard module to handle this
end
return apache2.DECLINED
- end
- </pre>
+ end</pre>
</div>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.5.0 and later</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
</table>
<p>Provides a means of adding a Lua function as an input filter.
As with output filters, input filters work as coroutines,
onto the Lua script:
</p>
-<pre class="prettyprint lang-config">
-LuaInputFilter myInputFilter /www/filter.lua input_filter
-<FilesMatch "\.lua>
+<pre class="prettyprint lang-config">LuaInputFilter myInputFilter /www/filter.lua input_filter
+<Files *.lua>
SetInputFilter myInputFilter
-</FilesMatch>
-</pre>
+</Files></pre>
-<pre class="prettyprint lang-lua">
---[[
+<pre class="prettyprint lang-lua">--[[
Example input filter that converts all POST data to uppercase.
]]--
function input_filter(r)
end
-- No more buckets available.
coroutine.yield("&filterSignature=1234") -- Append signature at the end
-end
-</pre>
+end</pre>
<p>
The input filter supports denying/skipping a filter if it is deemed unwanted:
</p>
-<pre class="prettyprint lang-lua">
-function input_filter(r)
+<pre class="prettyprint lang-lua">function input_filter(r)
if not good then
return -- Simply deny filtering, passing on the original content instead
end
coroutine.yield() -- wait for buckets
... -- insert filter stuff here
-end
-</pre>
+end</pre>
<p>
See "<a href="#modifying_buckets">Modifying contents with Lua
match groups into both the file path and the function name.
Be careful writing your regular expressions to avoid security
issues.</p>
- <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
- LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
- </pre>
+ <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2</pre>
</div>
<p>This would match uri's such as /photos/show?id=9
to the file /scripts/photos.lua and invoke the
handler function handle_show on the lua vm after
loading that file.</p>
-<pre class="prettyprint lang-config">
- LuaMapHandler /bingo /scripts/wombat.lua
-</pre>
+<pre class="prettyprint lang-config">LuaMapHandler /bingo /scripts/wombat.lua</pre>
<p>This would invoke the "handle" function, which
is the default if no specific function name is
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.5.0 and later</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
</table>
<p>Provides a means of adding a Lua function as an output filter.
As with input filters, output filters work as coroutines,
onto the Lua script:
</p>
-<pre class="prettyprint lang-config">
-LuaOutputFilter myOutputFilter /www/filter.lua output_filter
-<FilesMatch "\.lua>
+<pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter /www/filter.lua output_filter
+<Files *.lua>
SetOutputFilter myOutputFilter
-</FilesMatch>
-</pre>
+</Files></pre>
-<pre class="prettyprint lang-lua">
---[[
+<pre class="prettyprint lang-lua">--[[
Example output filter that escapes all HTML entities in the output
]]--
function output_filter(r)
coroutine.yield(output) -- Send converted data down the chain
end
-- No more buckets available.
-end
-</pre>
+end</pre>
<p>
As with the input filter, the output filter supports denying/skipping a filter
if it is deemed unwanted:
</p>
-<pre class="prettyprint lang-lua">
-function output_filter(r)
+<pre class="prettyprint lang-lua">function output_filter(r)
if not r.content_type:match("text/html") then
return -- Simply deny filtering, passing on the original content instead
end
coroutine.yield() -- wait for buckets
... -- insert filter stuff here
-end
-</pre>
+end</pre>
+
+<div class="note"><h3>Lua filters with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3>
+<p> When a Lua filter is used as the underlying provider via the
+<code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code> directive, filtering
+will only work when the <var>filter-name</var> is identical to the <var>provider-name</var>.
+</p> </div>
<p>
See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more
information.
</p>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
conventions as lua. This just munges the package.path in the
lua vms.</p>
- <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">
-LuaPackagePath /scripts/lib/?.lua
-LuaPackagePath /scripts/lib/?/init.lua
- </pre>
+ <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaPackagePath /scripts/lib/?.lua
+LuaPackagePath /scripts/lib/?/init.lua</pre>
</div>
</div>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
</table>
- <p>Specify the lifecycle scope of the Lua interpreter which will
+ <p>Specify the life cycle scope of the Lua interpreter which will
be used by handlers in this "Directory." The default is "once"</p>
<dl>
}
})(window, document);
//--><!]]></script></div><div id="footer">
-<p class="apache">Copyright 201
2 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>
-<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"><!--//--><
projects / apache / blobdiff