diff options
Diffstat (limited to '')
-rw-r--r-- | docs/manual/mod/mod_lua.html | 9 | ||||
-rw-r--r-- | docs/manual/mod/mod_lua.html.en | 1922 | ||||
-rw-r--r-- | docs/manual/mod/mod_lua.html.fr.utf8 | 2079 |
3 files changed, 4010 insertions, 0 deletions
diff --git a/docs/manual/mod/mod_lua.html b/docs/manual/mod/mod_lua.html new file mode 100644 index 0000000..634a9a7 --- /dev/null +++ b/docs/manual/mod/mod_lua.html @@ -0,0 +1,9 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: mod_lua.html.en +Content-Language: en +Content-type: text/html; charset=UTF-8 + +URI: mod_lua.html.fr.utf8 +Content-Language: fr +Content-type: text/html; charset=UTF-8 diff --git a/docs/manual/mod/mod_lua.html.en b/docs/manual/mod/mod_lua.html.en new file mode 100644 index 0000000..52cdcf8 --- /dev/null +++ b/docs/manual/mod/mod_lua.html.en @@ -0,0 +1,1922 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head> +<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /> +<!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --> +<title>mod_lua - Apache HTTP Server Version 2.4</title> +<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.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="apache">Apache HTTP Server Version 2.4</p> +<img alt="" src="../images/feather.png" /></div> +<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> +<div id="path"> +<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.4</a> > <a href="./">Modules</a></div> +<div id="page-content"> +<div id="preamble"><h1>Apache Module mod_lua</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a> | +<a href="../fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> +</div> +<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides Lua hooks into various portions of the httpd +request processing</td></tr> +<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>lua_module</td></tr> +<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_lua.c</td></tr> +<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>2.3 and later</td></tr></table> +<h3>Summary</h3> + +<p>This module allows the server to be extended with scripts written in the +Lua programming language. The extension points (hooks) available with +<code class="module"><a href="../mod/mod_lua.html">mod_lua</a></code> include many of the hooks available to +natively compiled Apache HTTP Server modules, such as mapping requests to +files, generating dynamic responses, access control, authentication, and +authorization</p> + +<p>More information on the Lua programming language can be found at the +<a href="http://www.lua.org/">the Lua website</a>.</p> + +<div class="warning"><h3>Warning</h3> +<p>This module holds a great deal of power over httpd, which is both a +strength and a potential security risk. It is <strong>not</strong> recommended +that you use this module on a server that is shared with users you do not +trust, as it can be abused to change the internal workings of httpd.</p> +</div> + +</div> +<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><h3>Topics</h3> +<ul id="topics"> +<li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Basic Configuration</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Writing Handlers</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> +<li><img alt="" src="../images/down.gif" /> <a href="#databases">Database connectivity</a></li> +</ul><h3 class="directives">Directives</h3> +<ul id="toc"> +<li><img alt="" src="../images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li> +<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="#luahookpretranslate">LuaHookPreTranslate</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="#luainherit">LuaInherit</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luainputfilter">LuaInputFilter</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luaoutputfilter">LuaOutputFilter</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li> +</ul> +<h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_lua">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_lua">Report a bug</a></li></ul><h3>See also</h3> +<ul class="seealso"> +<li><a href="#comments_section">Comments</a></li></ul></div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2> + +<p>The basic module loading directive is</p> + +<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 a <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> or +<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive:</p> + +<pre class="prettyprint lang-config"><Files "*.lua"> + SetHandler lua-script +</Files></pre> + + +<p> +This will cause <code>mod_lua</code> to handle requests for files +ending in <code>.lua</code> by invoking that file's +<code>handle</code> function. +</p> + +<p>For more flexibility, see <code class="directive">LuaMapHandler</code>. +</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2> +<p> In the Apache HTTP Server API, the handler is a specific kind of hook +responsible for generating the response. Examples of modules that include a +handler are <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, +and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p> + +<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than +just evaluating a script body CGI style. A handler function looks +something like this:</p> + + +<pre class="prettyprint lang-lua"> +<strong>example.lua</strong><br /> +-- example handler + +require "string" + +--[[ + This is the default method name for Lua handlers, see the optional + function-name in the LuaMapHandler directive to choose a different + entry point. +--]] +function handle(r) + r.content_type = "text/plain" + + 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 + 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 + return apache2.OK +end</pre> + + +<p> +This handler function just prints out the uri or form encoded +arguments to a plaintext page. +</p> + +<p> +This means (and in fact encourages) that you can have multiple +handlers (or hooks, or filters) in the same script. +</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2> + + +<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to +authorization that is much easier to use than using into the relevant +hooks directly. The first argument to the +<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive gives +the name of the responsible authorization provider. For any +<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> line, +<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider +of the given name, passing the rest of the line as parameters. The +provider will then check authorization and pass the result as return +value.</p> + +<p>The authz provider is normally called before authentication. If it needs to +know the authenticated user name (or if the user will be authenticated at +all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>. +This will cause authentication to proceed and the authz provider to be +called a second time.</p> + +<p>The following authz provider function takes two arguments, one ip +address and one user name. It will allow access from the given ip address +without authentication, or if the authenticated user matches the second +argument:</p> + +<pre class="prettyprint lang-lua"> +<strong>authz_provider.lua</strong><br /> + +require 'apache2' + +function authz_check_foo(r, ip, user) + if r.useragent_ip == ip then + return apache2.AUTHZ_GRANTED + elseif r.user == nil then + return apache2.AUTHZ_DENIED_NO_USER + elseif r.user == user then + return apache2.AUTHZ_GRANTED + else + return apache2.AUTHZ_DENIED + end +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 +<Location "/"> + Require foo 10.1.2.3 john_doe +</Location></pre> + + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2> + +<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 file system, +performing access control, or setting mime types:</p> + +<table class="bordered"><tr class="header"> + <th>Hook phase</th> + <th>mod_lua directive</th> + <th>Description</th> + </tr> +<tr> + <td>Quick handler</td> + <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td> + <td>This is the first hook that will be called after a request has + been mapped to a host or virtual host</td> + </tr> +<tr class="odd"> + <td>Pre-Translate name</td> + <td><code class="directive"><a href="#luahookpretranslatename">LuaHookPreTranslateName</a></code></td> + <td>This phase translates the requested URI into a filename on the + system, before decoding occurs. Modules such as <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> + can operate in this phase.</td> + </tr> +<tr> + <td>Translate name</td> + <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td> + <td>This phase translates the requested URI into a filename on the + system. Modules such as <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and + <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operate in this phase.</td> + </tr> +<tr class="odd"> + <td>Map to storage</td> + <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td> + <td>This phase maps files to their physical, cached or external/proxied storage. + It can be used by proxy or caching modules</td> + </tr> +<tr> + <td>Check Access</td> + <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td> + <td>This phase checks whether a client has access to a resource. This + phase is run before the user is authenticated, so beware. + </td> + </tr> +<tr class="odd"> + <td>Check User ID</td> + <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td> + <td>This phase it used to check the negotiated user ID</td> + </tr> +<tr> + <td>Check Authorization</td> + <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> or + <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td> + <td>This phase authorizes a user based on the negotiated credentials, such as + user ID, client certificate etc. + </td> + </tr> +<tr class="odd"> + <td>Check Type</td> + <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td> + <td>This phase checks the requested file and assigns a content type and + a handler to it</td> + </tr> +<tr> + <td>Fixups</td> + <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td> + <td>This is the final "fix anything" phase before the content handlers + are run. Any last-minute changes to the request should be made here.</td> + </tr> +<tr class="odd"> + <td>Content handler</td> + <td>fx. <code>.lua</code> files or through <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td> + <td>This is where the content is handled. Files are read, parsed, some are run, + and the result is sent to the client</td> + </tr> +<tr> + <td>Logging</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. Mod_lua + is able to hook into the start of this and control logging output.</td> + </tr> +</table> + +<p>Hook functions are passed the request object as their only argument +(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 +<code>apache2.OK</code>, <code>apache2.DONE</code>, or +<code>apache2.DECLINED</code>, or else an HTTP status code.</p> + + +<pre class="prettyprint lang-lua"> +<strong>translate_name.lua</strong><br /> +-- example hook that rewrites the URI to a filesystem path. + +require 'apache2' + +function translate_name(r) + if r.uri == "/translate-name" then + r.filename = r.document_root .. "/find_me.txt" + return apache2.OK + end + -- we don't care about this URL, give another module a chance + return apache2.DECLINED +end</pre> + + + +<pre class="prettyprint lang-lua"> +<strong>translate_name2.lua</strong><br /> +--[[ example hook that rewrites one URI to another URI. It returns a + apache2.DECLINED to give other URL mappers a chance to work on the + substitution, including the core translate_name hook which maps based + on the DocumentRoot. + + Note: Use the early/late flags in the directive to make it run before + or after mod_alias. +--]] + +require 'apache2' + +function translate_name(r) + if r.uri == "/translate-name" then + r.uri = "/find_me.txt" + return apache2.DECLINED + end + return apache2.DECLINED +end</pre> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="datastructures" id="datastructures">Data Structures</a></h2> + +<dl> +<dt>request_rec</dt> + <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 writable as + well as readable. (The table fields' content can be changed, but the + fields themselves cannot be set to different tables.)</p> + + <table class="bordered"><tr class="header"> + <th><strong>Name</strong></th> + <th><strong>Lua type</strong></th> + <th><strong>Writable</strong></th> + <th><strong>Description</strong></th> + </tr> +<tr> + <td><code>allowoverrides</code></td> + <td>string</td> + <td>no</td> + <td>The AllowOverride options applied to the current request.</td> + </tr> +<tr class="odd"> + <td><code>ap_auth_type</code></td> + <td>string</td> + <td>no</td> + <td>If an authentication check was made, this is set to the type + of authentication (f.x. <code>basic</code>)</td> + </tr> +<tr> + <td><code>args</code></td> + <td>string</td> + <td>yes</td> + <td>The query string arguments extracted from the request + (f.x. <code>foo=bar&name=johnsmith</code>)</td> + </tr> +<tr class="odd"> + <td><code>assbackwards</code></td> + <td>boolean</td> + <td>no</td> + <td>Set to true if this is an HTTP/0.9 style request + (e.g. <code>GET /foo</code> (with no headers) )</td> + </tr> +<tr> + <td><code>auth_name</code></td> + <td>string</td> + <td>no</td> + <td>The realm name used for authorization (if applicable).</td> + </tr> +<tr class="odd"> + <td><code>banner</code></td> + <td>string</td> + <td>no</td> + <td>The server banner, f.x. <code>Apache HTTP Server/2.4.3 openssl/0.9.8c</code></td> + </tr> +<tr> + <td><code>basic_auth_pw</code></td> + <td>string</td> + <td>no</td> + <td>The basic auth password sent with this request, if any</td> + </tr> +<tr class="odd"> + <td><code>canonical_filename</code></td> + <td>string</td> + <td>no</td> + <td>The canonical filename of the request</td> + </tr> +<tr> + <td><code>content_encoding</code></td> + <td>string</td> + <td>no</td> + <td>The content encoding of the current request</td> + </tr> +<tr class="odd"> + <td><code>content_type</code></td> + <td>string</td> + <td>yes</td> + <td>The content type of the current request, as determined in the + type_check phase (f.x. <code>image/gif</code> or <code>text/html</code>)</td> + </tr> +<tr> + <td><code>context_prefix</code></td> + <td>string</td> + <td>no</td> + <td /> + </tr> +<tr class="odd"> + <td><code>context_document_root</code></td> + <td>string</td> + <td>no</td> + <td /> + </tr> +<tr> + <td><code>document_root</code></td> + <td>string</td> + <td>no</td> + <td>The document root of the host</td> + </tr> +<tr class="odd"> + <td><code>err_headers_out</code></td> + <td>table</td> + <td>no</td> + <td>MIME header environment for the response, printed even on errors and + persist across internal redirects. A read-only lua table suitable for iteration is available as r:err_headers_out_table().</td> + </tr> +<tr> + <td><code>filename</code></td> + <td>string</td> + <td>yes</td> + <td>The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be + changed in the pre-translate-name, translate-name or map-to-storage phases of a request to allow the + default handler (or script handlers) to serve a different file than what was requested.</td> + </tr> +<tr class="odd"> + <td><code>handler</code></td> + <td>string</td> + <td>yes</td> + <td>The name of the <a href="../handler.html">handler</a> that should serve this request, f.x. + <code>lua-script</code> if it is to be served by mod_lua. This is typically set by the + <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> + directives, but could also be set via mod_lua to allow another handler to serve up a specific request + that would otherwise not be served by it. + </td> + </tr> +<tr> + <td><code>headers_in</code></td> + <td>table</td> + <td>yes</td> + <td>MIME header environment from the request. This contains headers such as <code>Host, + User-Agent, Referer</code> and so on. A read-only lua table suitable for iteration is available as r:headers_in_table().</td> + </tr> +<tr class="odd"> + <td><code>headers_out</code></td> + <td>table</td> + <td>yes</td> + <td>MIME header environment for the response. A read-only lua table suitable for iteration is available as r:headers_out_table().</td> + </tr> +<tr> + <td><code>hostname</code></td> + <td>string</td> + <td>no</td> + <td>The host name, as set by the <code>Host:</code> header or by a full URI.</td> + </tr> +<tr class="odd"> + <td><code>is_https</code></td> + <td>boolean</td> + <td>no</td> + <td>Whether or not this request is done via HTTPS</td> + </tr> +<tr> + <td><code>is_initial_req</code></td> + <td>boolean</td> + <td>no</td> + <td>Whether this request is the initial request or a sub-request</td> + </tr> +<tr class="odd"> + <td><code>limit_req_body</code></td> + <td>number</td> + <td>no</td> + <td>The size limit of the request body for this request, or 0 if no limit.</td> + </tr> +<tr> + <td><code>log_id</code></td> + <td>string</td> + <td>no</td> + <td>The ID to identify request in access and error log.</td> + </tr> +<tr class="odd"> + <td><code>method</code></td> + <td>string</td> + <td>no</td> + <td>The request method, f.x. <code>GET</code> or <code>POST</code>.</td> + </tr> +<tr> + <td><code>notes</code></td> + <td>table</td> + <td>yes</td> + <td>A list of notes that can be passed on from one module to another. A read-only lua table suitable for iteration is available as r:notes_table().</td> + </tr> +<tr class="odd"> + <td><code>options</code></td> + <td>string</td> + <td>no</td> + <td>The Options directive applied to the current request.</td> + </tr> +<tr> + <td><code>path_info</code></td> + <td>string</td> + <td>no</td> + <td>The PATH_INFO extracted from this request.</td> + </tr> +<tr class="odd"> + <td><code>port</code></td> + <td>number</td> + <td>no</td> + <td>The server port used by the request.</td> + </tr> +<tr> + <td><code>protocol</code></td> + <td>string</td> + <td>no</td> + <td>The protocol used, f.x. <code>HTTP/1.1</code></td> + </tr> +<tr class="odd"> + <td><code>proxyreq</code></td> + <td>string</td> + <td>yes</td> + <td>Denotes whether this is a proxy request or not. This value is generally set in + the post_read_request/pre_translate_name/translate_name phase of a request.</td> + </tr> +<tr> + <td><code>range</code></td> + <td>string</td> + <td>no</td> + <td>The contents of the <code>Range:</code> header.</td> + </tr> +<tr class="odd"> + <td><code>remaining</code></td> + <td>number</td> + <td>no</td> + <td>The number of bytes remaining to be read from the request body.</td> + </tr> +<tr> + <td><code>server_built</code></td> + <td>string</td> + <td>no</td> + <td>The time the server executable was built.</td> + </tr> +<tr class="odd"> + <td><code>server_name</code></td> + <td>string</td> + <td>no</td> + <td>The server name for this request.</td> + </tr> +<tr> + <td><code>some_auth_required</code></td> + <td>boolean</td> + <td>no</td> + <td>Whether some authorization is/was required for this request.</td> + </tr> +<tr class="odd"> + <td><code>subprocess_env</code></td> + <td>table</td> + <td>yes</td> + <td>The environment variables set for this request. A read-only lua table suitable for iteration is available as r:subprocess_env_table().</td> + </tr> +<tr> + <td><code>started</code></td> + <td>number</td> + <td>no</td> + <td>The time the server was (re)started, in seconds since the epoch (Jan 1st, 1970)</td> + </tr> +<tr class="odd"> + <td><code>status</code></td> + <td>number</td> + <td>yes</td> + <td>The (current) HTTP return code for this request, f.x. <code>200</code> or <code>404</code>.</td> + </tr> +<tr> + <td><code>the_request</code></td> + <td>string</td> + <td>no</td> + <td>The request string as sent by the client, f.x. <code>GET /foo/bar HTTP/1.1</code>.</td> + </tr> +<tr class="odd"> + <td><code>unparsed_uri</code></td> + <td>string</td> + <td>no</td> + <td>The unparsed URI of the request</td> + </tr> +<tr> + <td><code>uri</code></td> + <td>string</td> + <td>yes</td> + <td>The URI after it has been parsed by httpd</td> + </tr> +<tr class="odd"> + <td><code>user</code></td> + <td>string</td> + <td>yes</td> + <td>If an authentication check has been made, this is set to the name of the authenticated user.</td> + </tr> +<tr> + <td><code>useragent_ip</code></td> + <td>string</td> + <td>no</td> + <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. + +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:add_output_filter(filter_name) -- add an output filter: + +r:add_output_filter("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: + +if use_sendfile_thing then + r:sendfile("/var/www/large_file.img") +end</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): + +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: + +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, self explanatory</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: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: + +local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</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:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe): + +local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</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:unescape(string) -- Unescapes an URL-escaped string: + +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:construct_url(string) -- Constructs an URL from an URI + +local url = r:construct_url(r.uri)</pre> + + +<pre class="prettyprint lang-lua">r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query: + +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: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:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>: + +local process = r:scoreboard_process(1) +r:puts("Server 1 has PID " .. process.pid)</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:clock() -- Returns the current time with microsecond precision</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:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter</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:loaded_modules() -- Returns a list of modules loaded by httpd: + +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: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: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:set_document_root(file_path) -- Sets the document root for the request to file_path</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:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way</pre> + + +<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Escapes a string for logging</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: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: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: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.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 parameter.</pre> + + +<pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode parameter.</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> + + +</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 +r:trace1("This is a trace log message") -- trace1 through trace8 can be used +r:debug("This is a debug log message") +r:info("This is an info log message") +r:notice("This is a notice log message") +r:warn("This is a warn log message") +r:err("This is an err log message") +r:alert("This is an alert log message") +r:crit("This is a crit log message") +r:emerg("This is an emerg log message")</pre> + + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="apache2" id="apache2">apache2 Package</a></h2> +<p>A package named <code>apache2</code> is available with (at least) the following contents.</p> +<dl> + <dt>apache2.OK</dt> + <dd>internal constant OK. Handlers should return this if they've + handled the request.</dd> + <dt>apache2.DECLINED</dt> + <dd>internal constant DECLINED. Handlers should return this if + they are not going to handle the request.</dd> + <dt>apache2.DONE</dt> + <dd>internal constant DONE.</dd> + <dt>apache2.version</dt> + <dd>Apache HTTP server version string</dd> + <dt>apache2.HTTP_MOVED_TEMPORARILY</dt> + <dd>HTTP status code</dd> + <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt> + <dd>internal constants used by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd> + <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt> + <dd>internal constants used by <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></dd> + +</dl> +<p>(Other HTTP status codes are not yet implemented.)</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="modifying_buckets" id="modifying_buckets">Modifying contents with Lua filters</a></h2> + + <p> + Filter functions implemented via <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code> + or <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> are designed as + three-stage non-blocking functions using coroutines to suspend and resume a + 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) + -- 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 altogether: + if something_bad then + return -- This would skip this filter. + end + -- Regardless of whether we have data to prepend, a yield MUST be called here. + -- Note that only output filters can prepend data. Input filters must use the + -- final stage to append data to the content. + coroutine.yield([optional header to be prepended to the content]) + + -- After we have yielded, buckets will be sent to us, one by one, and we can + -- do whatever we want with them and then pass on the result. + -- Buckets are stored in the global variable 'bucket', so we create a loop + -- that checks if 'bucket' is not nil: + while bucket ~= nil do + local output = mangle(bucket) -- Do some stuff to the content + coroutine.yield(output) -- Return our new content to the filter chain + end + + -- Once the buckets are gone, 'bucket' is set to nil, which will exit the + -- loop and land us here. Anything extra we want to append to the content + -- 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> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="databases" id="databases">Database connectivity</a></h2> + + <p> + Mod_lua implements a simple database feature for querying and running commands + on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle) + as well as mod_dbd.</p> + <p> + The <code>dbType</code> to use as the first parameter of <code>dbacquire</code> + is case sensitive.</p> + <p> + It should be one of <code>mysql</code>, <code>pgsql</code>, <code>freetds</code>, + <code>odbc</code>, <code>sqlite2</code>, <code>sqlite3</code>, <code>oracle</code> + or <code>mod_dbd</code>. + </p> + <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 + for k, row in pairs(rows) do + r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) ) + end + else + r:puts("Database query error: " .. err) + end + database:close() + else + r:puts("Could not connect to the database: " .. err) + end +end</pre> + + <p> + 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> + + <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: +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> + + <p><strong>Using prepared statements (recommended):</strong></p> + <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 +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> + + <p><strong>Escaping values, closing databases etc:</strong></p> + <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> + + + <h3><a name="result_sets" id="result_sets">Working with result sets</a></h3> + + <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: +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 +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) + local a = 0 + local function getnext() + a = a + 1 + local row = resultset(-1) + return row and a or nil, row + end + if not async then + return pairs(resultset(0)) + else + return getnext, self + end +end + +local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u") +if not err then + -- fetch rows asynchronously: + local result, err = statement:select(20) + if not err then + for index, row in rows(result, true) do + .... + end + end + + -- fetch rows synchronously: + local result, err = statement:select(20) + if not err then + for index, row in rows(result, false) do + .... + end + end +end</pre> + + + <h3><a name="closing_databases" id="closing_databases">Closing a database connection</a></h3> + + + <p>Database handles should be closed using <code>database:close()</code> when they are no longer + needed. If you do not close them manually, they will eventually be garbage collected and + closed by mod_lua, but you may end up having too many unused connections to the database + 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 +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> + + + <h3><a name="database_caveat" id="database_caveat">Precautions when working with databases</a></h3> + + <p>Although the standard <code>query</code> and <code>run</code> functions are freely + available, it is recommended that you use prepared statements whenever possible, to + both optimize performance (if your db handle lives on for a long time) and to minimize + the risk of SQL injection attacks. <code>run</code> and <code>query</code> should only + be used when there are no variables inserted into a statement (a static statement). + When using dynamic statements, use <code>db:prepare</code> or <code>db:prepared</code>. + </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="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a> <a name="luaauthzprovider" id="luaauthzprovider">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> +</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr> +<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>Extension</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.4.3 and later</td></tr> +</table> +<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" +LuaAuthzProvider foo authz.lua authz_check_foo +<Location "/"> + Require foo johndoe +</Location></pre> + +<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> + + + + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p> + Specify the behavior of the in-memory code cache. The default + is stat, which stats the top level script (not any included + ones) each time that file is needed, and reloads it if the + modified time indicates it is newer than the one it has + already loaded. The other values cause it to keep the file + cached forever (don't stat and replace) or to never cache the + file.</p> + + <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 +LuaCodeCache forever +LuaCodeCache never</pre> +</div> + + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access_checker phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</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>Extension</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>The optional third argument is supported in 2.3.15 and later</td></tr> +</table> +<p>Add your hook to the access_checker phase. An access checker +hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p> + <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" + control when this script runs relative to other modules.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the auth_checker phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</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>Extension</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>The optional third argument is supported in 2.3.15 and later</td></tr> +</table> +<p>Invoke a lua function in the auth_checker phase of processing +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' + +-- fake authcheck hook +-- If request has no auth info, set the response header and +-- return a 401 to ask the browser for basic auth info. +-- If request has auth info, don't actually look at it, just +-- pretend we got userid 'foo' and validated it. +-- Then check if the userid is 'foo' and accept the request. +function authcheck_hook(r) + + -- look for auth info + auth = r.headers_in['Authorization'] + if auth ~= nil then + -- fake the user + r.user = 'foo' + end + + if r.user == nil then + r:debug("authcheck: user is nil, returning 401") + r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"' + return 401 + elseif r.user == "foo" then + r:debug('user foo: OK') + else + r:debug("authcheck: user='" .. r.user .. "'") + r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"' + return 401 + end + return apache2.OK +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> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the check_user_id phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</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>Extension</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>The optional third argument is supported in 2.3.15 and later</td></tr> +</table><p>...</p> + <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" + control when this script runs relative to other modules.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of a request +processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookFixups /path/to/lua/script.lua hook_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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> +<p> + Just like LuaHookTranslateName, but executed at the fixups phase +</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="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the insert_filter phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookInsertFilter /path/to/lua/script.lua hook_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>Extension</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>Extension</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> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the map_to_storage phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookMapToStorage /path/to/lua/script.lua hook_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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Like <code class="directive">LuaHookTranslateName</code> but executed at the + map-to-storage phase of a request. Modules like <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> 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-lua">require"apache2" +cached_files = {} + +function read_file(filename) + local input = io.open(filename, "r") + if input then + local data = input:read("*a") + cached_files[filename] = data + file = cached_files[filename] + input:close() + end + return cached_files[filename] +end + +function check_cache(r) + if r.filename:match("%.png$") then -- Only match PNG files + local file = cached_files[r.filename] -- Check cache entries + if not file then + file = read_file(r.filename) -- Read file into cache + end + if file then -- If file exists, write it out + r.status = 200 + r:write(file) + r:info(("Sent %s to client from cache"):format(r.filename)) + return apache2.DONE -- skip default handler for PNG files + end + end + return apache2.DECLINED -- If we had nothing to do, let others serve this. +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="LuaHookPreTranslate" id="LuaHookPreTranslate">LuaHookPreTranslate</a> <a name="luahookpretranslate" id="luahookpretranslate">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the pre_translate phase of a request +processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookPreTranslate /path/to/lua/script.lua hook_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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> +<p> + Just like LuaHookTranslateName, but executed at the pre_translate phase, + where the URI-path is not percent decoded. +</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="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the translate name phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</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>Extension</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>The optional third argument is supported in 2.3.15 and later</td></tr> +</table><p> + Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of + request processing. The hook function receives a single + argument, the request_rec, and should return a status code, + which is either an HTTP error code, or the constants defined + in the apache2 module: apache2.OK, apache2.DECLINED, or + apache2.DONE. </p> + + <p>For those new to hooks, basically each hook will be invoked + until one of them returns apache2.OK. If your hook doesn't + want to do the translation it should just return + apache2.DECLINED. If the request should stop processing, then + return apache2.DONE.</p> + + <p>Example:</p> + +<pre class="prettyprint lang-config"># httpd.conf +LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper</pre> + + +<pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua -- +require "apache2" +function silly_mapper(r) + if r.uri == "/" then + r.filename = "/var/www/home.lua" + return apache2.OK + else + return apache2.DECLINED + end +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 + context.</p></div> + + <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late" + control when this script runs relative to other modules.</p></div> + + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the type_checker phase of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTypeChecker /path/to/lua/script.lua hook_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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p> + This directive provides a hook for the type_checker phase of the request processing. + 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-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 + r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested + return apache2.OK + end + + return apache2.DECLINED + 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="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</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>Extension</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.4.0 and later</td></tr> +</table><p>By default, if LuaHook* directives are used in overlapping + Directory or Location configuration sections, the scripts defined in the + more specific section are run <em>after</em> those defined in the more + generic section (LuaInherit parent-first). You can reverse this order, or + make the parent context not apply at all.</p> + + <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook* + directives from parent configuration sections.</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="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a> <a name="luainputfilter" id="luainputfilter">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content input filtering</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr> +<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>Extension</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.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, +first yielding before buffers are sent, then yielding whenever +a bucket needs to be passed down the chain, and finally (optionally) +yielding anything that needs to be appended to the input data. The +global variable <code>bucket</code> holds the buckets as they are passed +onto the Lua script: +</p> + +<pre class="prettyprint lang-config">LuaInputFilter myInputFilter "/www/filter.lua" input_filter +<Files "*.lua"> + SetInputFilter myInputFilter +</Files></pre> + +<pre class="prettyprint lang-lua">--[[ + Example input filter that converts all POST data to uppercase. +]]-- +function input_filter(r) + print("luaInputFilter called") -- debug print + coroutine.yield() -- Yield and wait for buckets + while bucket do -- For each bucket, do... + local output = string.upper(bucket) -- Convert all POST data to uppercase + coroutine.yield(output) -- Send converted data down the chain + end + -- No more buckets available. + coroutine.yield("&filterSignature=1234") -- Append signature at the end +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) + 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> + +<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="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaMapHandler uri-pattern /path/to/lua/script.lua [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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>This directive matches a uri pattern to invoke a specific + handler function in a specific file. It uses PCRE regular + expressions to match the uri, and supports interpolating + 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> + <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> + + <p>This would invoke the "handle" function, which + is the default if no specific function name is + provided.</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="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a> <a name="luaoutputfilter" id="luaoutputfilter">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content output filtering</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr> +<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>Extension</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.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, +first yielding before buffers are sent, then yielding whenever +a bucket needs to be passed down the chain, and finally (optionally) +yielding anything that needs to be appended to the input data. The +global variable <code>bucket</code> holds the buckets as they are passed +onto the Lua script: +</p> + +<pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter +<Files "*.lua"> + SetOutputFilter myOutputFilter +</Files></pre> + +<pre class="prettyprint lang-lua">--[[ + Example output filter that escapes all HTML entities in the output +]]-- +function output_filter(r) + coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Prepend some data to the output, + -- yield and wait for buckets. + while bucket do -- For each bucket, do... + local output = r:escape_html(bucket) -- Escape all output + coroutine.yield(output) -- Send converted data down the chain + end + -- No more buckets available. +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) + 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> + +<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> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Add a path to lua's shared library search path. Follows the same + conventions as lua. This just munges the package.cpath in the + lua vms.</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="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p>Add a path to lua's module search path. Follows the same + 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> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p> + This phase is run immediately after the request has been mapped to a virtual host, + and can be used to either do some request processing before the other phases kick + in, or to serve a request without the need to translate, map to storage et cetera. + As this phase is run before anything else, directives such as <code class="directive"><a href="../mod/core.html#location"><Location></a></code> or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> are void in this phase, just as + URIs have not been properly parsed yet. + </p> + <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 + context.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the base path for resolving relative paths for mod_lua directives</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Specify the base path which will be used to evaluate all + relative paths within mod_lua. If not specified they + will be resolved relative to the current working directory, + which may not always work well for a server.</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="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, thread -- default is once</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread|server [min] [max]</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</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>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <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> + <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd> + + <dt>request:</dt> <dd>use the interpreter to handle anything based on + the same file within this request, which is also + request scoped.</dd> + + <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd> + + <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread + handling the request (only available with threaded MPMs).</dd> + + <dt>server:</dt> <dd>This one is different than others because the + server scope is quite long lived, and multiple threads + will have the same server_rec. To accommodate this, + server scoped Lua states are stored in an apr + resource list. The <code>min</code> and <code>max</code> arguments + specify the minimum and maximum number of Lua states to keep in the + pool.</dd> + </dl> + <p> + Generally speaking, the <code>thread</code> and <code>server</code> scopes + execute roughly 2-3 times faster than the rest, because they don't have to + spawn new Lua states on every request (especially with the event MPM, as + even keepalive requests will use a new thread for each request). If you are + satisfied that your scripts will not have problems reusing a state, then + the <code>thread</code> or <code>server</code> scopes should be used for + maximum performance. While the <code>thread</code> scope will provide the + fastest responses, the <code>server</code> scope will use less memory, as + states are pooled, allowing f.x. 1000 threads to share only 100 Lua states, + thus using only 10% of the memory required by the <code>thread</code> scope. + </p> + +</div> +</div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/mod/mod_lua.html" title="English"> en </a> | +<a href="../fr/mod/mod_lua.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> +</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 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 Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div> +<script type="text/javascript"><!--//--><![CDATA[//><!-- +var comments_shortname = 'httpd'; +var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_lua.html'; +(function(w, d) { + if (w.location.hostname.toLowerCase() == "httpd.apache.org") { + d.write('<div id="comments_thread"><\/div>'); + var s = d.createElement('script'); + s.type = 'text/javascript'; + s.async = true; + s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; + (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); + } + else { + d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); + } +})(window, document); +//--><!]]></script></div><div id="footer"> +<p class="apache">Copyright 2023 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"><!--//--><![CDATA[//><!-- +if (typeof(prettyPrint) !== 'undefined') { + prettyPrint(); +} +//--><!]]></script> +</body></html>
\ No newline at end of file diff --git a/docs/manual/mod/mod_lua.html.fr.utf8 b/docs/manual/mod/mod_lua.html.fr.utf8 new file mode 100644 index 0000000..378a68f --- /dev/null +++ b/docs/manual/mod/mod_lua.html.fr.utf8 @@ -0,0 +1,2079 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr"><head> +<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /> +<!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --> +<title>mod_lua - Serveur HTTP Apache Version 2.4</title> +<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.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">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p> +<p class="apache">Serveur HTTP Apache Version 2.4</p> +<img alt="" src="../images/feather.png" /></div> +<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> +<div id="path"> +<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">Serveur HTTP</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> +<div id="page-content"> +<div id="preamble"><h1>Module Apache mod_lua</h1> +<div class="toplang"> +<p><span>Langues Disponibles: </span><a href="../en/mod/mod_lua.html" hreflang="en" rel="alternate" title="English"> en </a> | +<a href="../fr/mod/mod_lua.html" title="Français"> fr </a></p> +</div> +<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Fournit des points d'entrée Lua dans différentes parties du +traitement des requêtes httpd</td></tr> +<tr><th><a href="module-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="module-dict.html#ModuleIdentifier">Identificateur de Module:</a></th><td>lua_module</td></tr> +<tr><th><a href="module-dict.html#SourceFile">Fichier Source:</a></th><td>mod_lua.c</td></tr> +<tr><th><a href="module-dict.html#Compatibility">Compatibilité:</a></th><td>versions 2.3 et supérieures</td></tr></table> +<h3>Sommaire</h3> + +<p>Ce module permet d'ajouter au serveur des extensions sous forme de +scripts écrits dans le langage de programmation Lua. +<code class="module"><a href="../mod/mod_lua.html">mod_lua</a></code> fournit de nombreuses extensions +(hooks) disponibles avec les modules natifs du serveur HTTP Apache, +comme les associations de requêtes à des fichiers, la génération de +réponses dynamiques, le contrôle d'accès, l'authentification et +l'autorisation.</p> + +<p>Vous trouverez davantage d'informations à propos du langage de +programmation Lua sur <a href="http://www.lua.org/">le site web de +Lua</a>.</p> + +<div class="warning"><h3>Avertissement</h3> +<p>Ce module possède une grande capacité d'action sur le fonctrionnement +de httpd, ce qui lui confère une grande puissance, mais peut aussi +induire un risque de sécurité. Il est déconseillé d'utiliser ce module +sur un serveur partagé avec des utilisateurs auxquels vous ne pouvez pas +accorder une confiance absolue, car il peut permettre de modifier le +fonctionnement interne de httpd.</p> +</div> + +</div> +<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><h3>Sujets</h3> +<ul id="topics"> +<li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Configuration de base</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Ecrire des gestionnaires</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#writingauthzproviders">Ecriture de fournisseurs d'autorisation</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Ecriture de fonctions d'accroche +(hooks)</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Structures de données</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#functions">Méthodes de l'objet request_rec</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#logging">Fonctions de journalisation</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#apache2">Paquet apache2</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modification de contenu avec les filtres lua</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#databases">Connectivité aux bases de données</a></li> +</ul><h3 class="directives">Directives</h3> +<ul id="toc"> +<li><img alt="" src="../images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li> +<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="#luahookpretranslate">LuaHookPreTranslate</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="#luainherit">LuaInherit</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luainputfilter">LuaInputFilter</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luaoutputfilter">LuaOutputFilter</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li> +</ul> +<h3>Traitement des bugs</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">Journal des modifications de httpd</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_lua">Problèmes connus</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_lua">Signaler un bug</a></li></ul><h3>Voir aussi</h3> +<ul class="seealso"> +<li><a href="#comments_section">Commentaires</a></li></ul></div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="basicconf" id="basicconf">Configuration de base</a></h2> + +<p>La directive de base pour le chargement du module est</p> + +<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre> + + +<p> +<code>mod_lua</code> fournit un gestionnaire nommé +<code>lua-script</code> qui peut être utilisé avec une directive +<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> ou <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> :</p> + +<pre class="prettyprint lang-config"><Files "*.lua"> + SetHandler lua-script +</Files></pre> + + +<p> +Ceci aura pour effet de faire traiter les requêtes pour les fichiers +dont l'extension est <code>.lua</code> par <code>mod_lua</code> en +invoquant cette fonction de <code>gestion</code> de fichier. +</p> + +<p>Pour plus de détails, voir la directive +<code class="directive">LuaMapHandler</code>. + </p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="writinghandlers" id="writinghandlers">Ecrire des gestionnaires</a></h2> +<p>Dans l'API du serveur HTTP Apache, un gestionnaire est une sorte de +point d'accroche (hook) spécifique responsable de la génération de la +réponse. <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> et +<code class="module"><a href="../mod/mod_status.html">mod_status</a></code> sont des exemples de modules comportant un +gestionnaire.</p> + +<p><code>mod_lua</code> cherche toujours à invoquer une fonction Lua pour le +gestionnaire, plutôt que de simplement évaluer le corps d'un script dans +le style de CGI. Une fonction de gestionnaire se présente comme suit :</p> + + +<pre class="prettyprint lang-lua"> +<strong>example.lua</strong><br /> +-- exemple de gestionnaire + +require "string" + +--[[ + Il s'agit du nom de méthode par défaut pour les gestionnaires Lua ; + voir les noms de fonctions optionnels dans la directive + LuaMapHandler pour choisir un point d'entrée différent. +--]] +function handle(r) + r.content_type = "text/plain" + + 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 +-- message d'erreur personnalisé + r:puts("Unsupported HTTP method " .. r.method) + r.status = 405 + return apache2.OK + else +-- message d'erreur ErrorDocument + return 501 + end + return apache2.OK +end</pre> + + +<p> +Ce gestionnaire se contente d'afficher les arguments codés d'un uri ou +d'un formulaire dans un page au format texte. +</p> + +<p> +Cela signifie que vous pouvez (et êtes encouragé à) avoir plusieurs +gestionnaires (ou points d'entrée, ou filtres) dans le même script. +</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="writingauthzproviders" id="writingauthzproviders">Ecriture de fournisseurs d'autorisation</a></h2> + + +<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> fournit une interface d'autorisation +de haut niveau bien plus facile à utiliser que dans les hooks +correspondants. Le premier argument de la directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> permet de spécifier le +fournisseur d'autorisation à utiliser. Pour chaque directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>, +<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> appellera le fournisseur d'autorisation +spécifié, le reste de la ligne constituant les paramètres. Le +fournisseur considéré va alors vérifier les autorisations et fournir le +résultat dans une valeur de retour.</p> + +<p>En général, le fournisseur authz est appelé avant l'authentification. +S'il doit connaître le nom d'utilisateur authentifié (ou si +l'utilisateur est appelé à être authentifié), le fournisseur doit +renvoyer <code>apache2.AUTHZ_DENIED_NO_USER</code>, ce qui va +déclancher le processus d'authentification et un deuxième appel du +fournisseur authz.</p> + +<p>La fonction du fournisseur authz ci-dessous accepte deux arguments, +une adresse IP et un nom d'utilisateur. Elle autorise l'accès dans le +cas où la requête provient de l'adresse IP spécifiée, ou si +l'utilisateur authentifié correspond au second argument :</p> + +<pre class="prettyprint lang-lua"> +<strong>authz_provider.lua</strong><br /> + +require 'apache2' + +function authz_check_foo(r, ip, user) + if r.useragent_ip == ip then + return apache2.AUTHZ_GRANTED + elseif r.user == nil then + return apache2.AUTHZ_DENIED_NO_USER + elseif r.user == user then + return apache2.AUTHZ_GRANTED + else + return apache2.AUTHZ_DENIED + end +end</pre> + + +<p>La configuration suivante enregistre cette fonction en tant que +fournisseur <code>foo</code>, et la configure por l'URL <code>/</code> :</p> +<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo +<Location "/"> + Require foo 10.1.2.3 john_doe +</Location></pre> + + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="writinghooks" id="writinghooks">Ecriture de fonctions d'accroche +(hooks)</a></h2> + +<p>Les fonctions d'accroche déterminent la manière dont les modules (et +les scripts Lua) participent au traitement des requêtes. Chaque type +d'accroche proposé par le serveur a un rôle spécifique, comme +l'association de requêtes au système de fichiers, le contrôle d'accès, +ou la définition de types MIME : </p> + +<table class="bordered"><tr class="header"> + <th>Phase d'accroche</th> + <th>Directive mod_lua</th> + <th>Description</th> + </tr> +<tr> + <td>Gestionnaire rapide</td> + <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td> + <td>Il s'agit de la première accroche appelée lorsqu'une requête + a été associée à un serveur ou un serveur virtuel.</td> + </tr> +<tr class="odd"> + <td>Phase de pré-traduction</td> + <td><code class="directive"><a href="#luahookpretranslatename">LuaHookPreTranslateName</a></code></td> + <td>Cette phase traduit l'URI de la requête en nom de fichier sur le + système avant la phase de décodage. Des modules comme + <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> peuvent agir au cours de cette phase.</td> + </tr> +<tr> + <td>Phase de traduction</td> + <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td> + <td>Cette phase traduit l'URI de la requête en nom de fichier + sur le système. Ce sont des modules comme + <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> et <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> qui + interviennent au cours de cette phase.</td> + </tr> +<tr class="odd"> + <td>Choix du lieu de stockage de la ressource</td> + <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td> + <td>Cette phase définit le lieu de stockage de la ressource : + physique, en cache ou externe/mandaté. Elle est assurée par les + modules de mandat ou de mise en cache.</td> + </tr> +<tr> + <td>Autorisation d'accès</td> + <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td> + <td>Cette phase vérifie si un client a l'autorisation d'accès à + la ressource. Elle s'exécute avant l'authentification de + l'utisateur ; il faut donc être prudent. + </td> + </tr> +<tr class="odd"> + <td>Vérification de l'identifiant utilisateur</td> + <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td> + <td>Cette phase vérifie l'identifiant de l'utilisateur ayant + fait l'objet d'une négociation.</td> + </tr> +<tr> + <td>Vérification de l'autorisation d'accès</td> + <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> + ou + <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td> + <td>Cette phase vérifie l'autorisation d'accès d'un utilisateur + en fonction des ses paramètres de connexion, comme + l'identifiant, le certificat, etc... + </td> + </tr> +<tr class="odd"> + <td>Vérification du type de la ressource</td> + <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td> + <td>Cette phase assigne un type de contenu et un gestionnaire à + la ressource.</td> + </tr> +<tr> + <td>Derniers réglages</td> + <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td> + <td>C'est la dernière phase avant l'activation des gestionnaires + de contenu. Toute modification de dernière minute à la requête + doit être effectuée ici.</td> + </tr> +<tr class="odd"> + <td>Gestionnaire de contenu</td> + <td>fichiers fx. <code>.lua</code> ou directive <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td> + <td>C'est durant cette phase que le contenu est traité. Les + fichiers sont lus, interprétés, certains sont exécutés, et le + résultat obtenu est envoyé au client.</td> + </tr> +<tr> + <td>Journalisation</td> + <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td> + <td>Lorsqu'une requête a été traitée, plusieurs phases de + journalisation interviennent, et enregistrent leurs résultats + dans les fichiers d'erreur ou d'accès. Mod_lua peut + s'intercaler au départ de ce processus et ainsi contrôler la + journalisation.</td> + </tr> +</table> + +<p>Les fonctions d'accroche reçoivent l'objet de la requête comme seul +argument (sauf LuaAuthzProvider qui reçoit aussi des arguments en +provenance de la directive Require). Elles peuvent renvoyer une valeur, +selon la fonction, mais il s'agit en général d'un +code d'état HTTP ou des valeurs OK, DONE, ou DECLINED, +que vous pouvez écrire dans Lua sous la forme <code>apache2.OK</code>, +<code>apache2.DONE</code>, ou <code>apache2.DECLINED</code>.</p> + + +<pre class="prettyprint lang-lua"> +<strong>translate_name.lua</strong><br /> +-- exemple d'accroche qui réécrit un URI en chemin du système de fichiers. + +require 'apache2' + +function translate_name(r) + if r.uri == "/translate-name" then + r.filename = r.document_root .. "/find_me.txt" + return apache2.OK + end + -- on ne gère pas cette URL et on donne sa chance à un autre module + return apache2.DECLINED +end</pre> + + + +<pre class="prettyprint lang-lua"> +<strong>translate_name2.lua</strong><br /> +--[[ exemple d'accroche qui réécrit un URI vers un autre URI. Il renvoie + un apache2.DECLINED pour permettre à un autre interpréteur d'URL de + travailler sur la substitution, y compris l'accroche translate_name + de base dont les tables de correspondances se basent sur DocumentRoot. + + Note: utilisez le drapeau early/late de la directive pour + l'exécuter avant ou après mod_alias. +--]] + +require 'apache2' + +function translate_name(r) + if r.uri == "/translate-name" then + r.uri = "/find_me.txt" + return apache2.DECLINED + end + return apache2.DECLINED +end</pre> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="datastructures" id="datastructures">Structures de données</a></h2> + +<dl> +<dt>request_rec</dt> + <dd> + <p>request_rec est considérée en tant que donnée utilisateur. + Elle possède une métatable qui vous permet d'accomplir des + choses intéressantes. Pour la plus grande partie, elle possède + les mêmes champs que la structure request_rec, la + plupart d'entre eux étant accessibles en lecture et écriture (le + contenu des champs de la table peut être modifié, mais les + champs eux-mêmes ne peuvent pas être établis en tant que tables + distinctes).</p> + + <table class="bordered"><tr class="header"> + <th><strong>Nom</strong></th> + <th><strong>Type Lua</strong></th> + <th><strong>Modifiable</strong></th> + <th><strong>Description</strong></th> + </tr> +<tr> + <td><code>allowoverrides</code></td> + <td>string</td> + <td>non</td> + <td>L'option AllowOverride s'applique à la requête courante.</td> + </tr> +<tr class="odd"> + <td><code>ap_auth_type</code></td> + <td>string</td> + <td>non</td> + <td>Ce champ contient le type d'authentification effectuée + (par exemple <code>basic</code>)</td> + </tr> +<tr> + <td><code>args</code></td> + <td>string</td> + <td>oui</td> + <td>La chaîne de paramètres de la requête (par exemple + <code>foo=bar&name=johnsmith</code>)</td> + </tr> +<tr class="odd"> + <td><code>assbackwards</code></td> + <td>boolean</td> + <td>non</td> + <td>contient true s'il s'agit d'une requête de style HTTP/0.9 + (par exemple <code>GET /foo</code> (sans champs d'en-tête) )</td> + </tr> +<tr> + <td><code>auth_name</code></td> + <td>string</td> + <td>non</td> + <td>La chaîne d'identification utilisée pour la vérification + de l'autorisation d'accès (si elle est disponible).</td> + </tr> +<tr class="odd"> + <td><code>banner</code></td> + <td>string</td> + <td>non</td> + <td>La bannière du serveur, par exemple <code>Apache HTTP + Server/2.4.3 openssl/0.9.8c</code></td> + </tr> +<tr> + <td><code>basic_auth_pw</code></td> + <td>string</td> + <td>non</td> + <td>Le mot de passe pour l'authentification de base envoyé + avec la requête, s'il existe</td> + </tr> +<tr class="odd"> + <td><code>canonical_filename</code></td> + <td>string</td> + <td>non</td> + <td>Le nom de fichier canonique de la requête</td> + </tr> +<tr> + <td><code>content_encoding</code></td> + <td>string</td> + <td>non</td> + <td>Le type de codage du contenu de la requête courante</td> + </tr> +<tr class="odd"> + <td><code>content_type</code></td> + <td>string</td> + <td>oui</td> + <td>Le type de contenu de la requête courante, tel qu'il a été + déterminé au cours de la phase type_check (par exemple + <code>image/gif</code> ou <code>text/html</code>)</td> + </tr> +<tr> + <td><code>context_prefix</code></td> + <td>string</td> + <td>non</td> + <td /> + </tr> +<tr class="odd"> + <td><code>context_document_root</code></td> + <td>string</td> + <td>non</td> + <td /> + </tr> +<tr> + <td><code>document_root</code></td> + <td>string</td> + <td>non</td> + <td>La racine des documents du serveur</td> + </tr> +<tr class="odd"> + <td><code>err_headers_out</code></td> + <td>table</td> + <td>non</td> + <td>L'en-tête MIME de l'environnement pour la réponse, écrit + même en cas d'erreur et conservé pendant les redirections + internes. Une table lua en lecture seule est disponible pour + l'itération sous la forme r:err_headers_out_table().</td> + </tr> +<tr> + <td><code>filename</code></td> + <td>string</td> + <td>oui</td> + <td>Le nom de fichier correspondant à la requête, par exemple + /www/example.com/foo.txt. Il peut être modifié au cours des phases + pre-translate-name, translate-name ou map-to-storage du traitement de + la requête pour permettre au gestionnaire par défaut (ou aux + gestionnaires de script) de servir une version du fichier autre que + celle demandée.</td> + </tr> +<tr class="odd"> + <td><code>handler</code></td> + <td>string</td> + <td>oui</td> + <td>Le nom du <a href="../handler.html">gestionnaire</a> qui + doit traiter la requête, par exemple <code>lua-script</code> + si elle doit être traitée par mod_lua. Cette valeur est en + général définie via les directives <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> ou <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code>, mais peut aussi l'être + via mod_lua pour permettre à un autre gestionnaire de traiter + une requête spécifique qui ne serait pas traitée par défaut + par ce dernier. + </td> + </tr> +<tr> + <td><code>headers_in</code></td> + <td>table</td> + <td>oui</td> + <td>Les en-têtes MIME de l'environnement de la requête. Il + s'agit des en-têtes comme <code>Host, User-Agent, + Referer</code>, etc... Une table lua en lecture seule est disponible pour + l'itération sous la forme r:headers_in_table().</td> + </tr> +<tr class="odd"> + <td><code>headers_out</code></td> + <td>table</td> + <td>oui</td> + <td>Les en-têtes MIME de l'environnement de la réponse. Une table lua en lecture seule est disponible pour + l'itération sous la forme r:headers_out_table().</td> + </tr> +<tr> + <td><code>hostname</code></td> + <td>string</td> + <td>non</td> + <td>Le nom d'hôte, tel que défini par l'en-tête + <code>Host:</code> ou par un URI complet.</td> + </tr> +<tr class="odd"> + <td><code>is_https</code></td> + <td>boolean</td> + <td>non</td> + <td>Indique si la requête à été faite via HTTPS</td> + </tr> +<tr> + <td><code>is_initial_req</code></td> + <td>boolean</td> + <td>non</td> + <td>Indique si la requête courante est la requête initiale ou + une sous-requête.</td> + </tr> +<tr class="odd"> + <td><code>limit_req_body</code></td> + <td>number</td> + <td>non</td> + <td>La taille maximale du corps de la requête, ou 0 si aucune + limite.</td> + </tr> +<tr> + <td><code>log_id</code></td> + <td>string</td> + <td>non</td> + <td>L'identifiant de la requête dans les journaux d'accès ou + d'erreur.</td> + </tr> +<tr class="odd"> + <td><code>method</code></td> + <td>string</td> + <td>non</td> + <td>La méthode de la requête, par exemple <code>GET</code> ou + <code>POST</code>.</td> + </tr> +<tr> + <td><code>notes</code></td> + <td>table</td> + <td>oui</td> + <td>Une liste de notes qui peuvent être transmises d'un module + à l'autre. Une table lua en lecture seule est disponible pour + l'itération sous la forme r:notes_table().</td> + </tr> +<tr class="odd"> + <td><code>options</code></td> + <td>string</td> + <td>non</td> + <td>La valeur de la directive Options pour la requête + courante.</td> + </tr> +<tr> + <td><code>path_info</code></td> + <td>string</td> + <td>non</td> + <td>La valeur de PATH_INFO extraite de la requête.</td> + </tr> +<tr class="odd"> + <td><code>port</code></td> + <td>number</td> + <td>non</td> + <td>Le port du serveur utilisé par la requête.</td> + </tr> +<tr> + <td><code>protocol</code></td> + <td>string</td> + <td>non</td> + <td>Le protocole utilisé, par exemple <code>HTTP/1.1</code></td> + </tr> +<tr class="odd"> + <td><code>proxyreq</code></td> + <td>string</td> + <td>oui</td> + <td>Indique s'il s'agit d'une requête mandatée ou non. Cette valeur + est en général définie au cours de la phase + post_read_request/pre_translate_name/translate_name du traitement de + la requête.</td> + </tr> +<tr> + <td><code>range</code></td> + <td>string</td> + <td>non</td> + <td>Le contenu de l'en-tête <code>Range:</code>.</td> + </tr> +<tr class="odd"> + <td><code>remaining</code></td> + <td>number</td> + <td>non</td> + <td>Le nombre d'octets du corps de la requête restant à lire.</td> + </tr> +<tr> + <td><code>server_built</code></td> + <td>string</td> + <td>non</td> + <td>La date de compilation du serveur.</td> + </tr> +<tr class="odd"> + <td><code>server_name</code></td> + <td>string</td> + <td>non</td> + <td>Le nom du serveur pour cette requête.</td> + </tr> +<tr> + <td><code>some_auth_required</code></td> + <td>boolean</td> + <td>non</td> + <td>Indique si une autorisation est/était requise pour cette + requête.</td> + </tr> +<tr class="odd"> + <td><code>subprocess_env</code></td> + <td>table</td> + <td>oui</td> + <td>Le jeu de variables d'environnement pour cette requête. Une table + lua en lecture seule est disponible pour l'itération sous la forme + r:subprocess_env_table().</td> + </tr> +<tr> + <td><code>started</code></td> + <td>number</td> + <td>non</td> + <td>Le moment où le serveur a été (re)démarré, en secondes + depuis epoch (1er janvier 1970)</td> + </tr> +<tr class="odd"> + <td><code>status</code></td> + <td>number</td> + <td>oui</td> + <td>Le code de retour (courant) pour cette requête, par + exemple <code>200</code> ou <code>404</code>.</td> + </tr> +<tr> + <td><code>the_request</code></td> + <td>string</td> + <td>non</td> + <td>La chaîne de la requête telle qu'elle a été envoyée par le + client, par exemple <code>GET /foo/bar HTTP/1.1</code>.</td> + </tr> +<tr class="odd"> + <td><code>unparsed_uri</code></td> + <td>string</td> + <td>non</td> + <td>La partie URI non interprétée de la requête</td> + </tr> +<tr> + <td><code>uri</code></td> + <td>string</td> + <td>oui</td> + <td>L'URI après interprétation par httpd</td> + </tr> +<tr class="odd"> + <td><code>user</code></td> + <td>string</td> + <td>oui</td> + <td>Si une authentification a été effectuée, nom de + l'utilisateur authentifié.</td> + </tr> +<tr> + <td><code>useragent_ip</code></td> + <td>string</td> + <td>non</td> + <td>L'adresse IP de l'agent qui a envoyé la requête</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">Méthodes de l'objet request_rec</a></h2> + +<p>L'objet request_rec possède (au minimum) les méthodes suivantes :</p> + +<pre class="prettyprint lang-lua">r:flush() -- vide le tampon de sortie + -- Renvoie true si le vidage a été effectué avec succès, + -- false dans le cas contraire. + +while nous_avons_des_données_à_envoyer do + r:puts("Bla bla bla\n") -- envoi des données à envoyer vers le tampon + r:flush() -- vidage du tampon (envoi au client) + r.usleep(500000) -- mise en attente pendant 0.5 secondes et bouclage +end</pre> + + +<pre class="prettyprint lang-lua">r:add_output_filter(filter_name) -- ajoute un filtre en sortie + +r:add_output_filter("fooFilter") -- insère le filtre fooFilter dans le flux de sortie</pre> + + +<pre class="prettyprint lang-lua">r:sendfile(filename) -- envoie un fichier entier au client en utilisant sendfile s'il est + -- supporté par la plateforme : + +if use_sendfile_thing then + r:sendfile("/var/www/large_file.img") +end</pre> + + +<pre class="prettyprint lang-lua">r:parseargs() -- renvoie deux tables : une table standard de couples + -- clé/valeur pour les données GET simples, + -- et une autre pour les données + -- multivaluées (par exemple foo=1&foo=2&foo=3) : + +local GET, GETMULTI = r:parseargs() +r:puts("Votre nom est : " .. GET['name'] or "Unknown")</pre> + + + +<pre class="prettyprint lang-lua">r:parsebody()([sizeLimit]) -- interprète le corps de la + -- requête en tant que POST et renvoie + -- deux tables lua, comme r:parseargs(). Un + -- nombre optionnel peut être fourni + -- pour spécifier le nombre maximal + -- d'octets à interpréter. La + -- valeur par défaut est 8192. + +local POST, POSTMULTI = r:parsebody(1024*1024) +r:puts("Votre nom est : " .. POST['name'] or "Unknown")</pre> + + + +<pre class="prettyprint lang-lua">r:puts("bonjour", " le monde", "!") -- affichage dans le corps de la réponse</pre> + + +<pre class="prettyprint lang-lua">r:write("une simple chaîne") -- affichage dans le corps de la réponse</pre> + + +<pre class="prettyprint lang-lua">r:escape_html("<html>test</html>") -- Echappe le code HTML et renvoie le résultat</pre> + + +<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encode une chaîne à l'aide du standard de codage Base64. + +local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre> + + +<pre class="prettyprint lang-lua">r:base64_decode(string) -- Décode une chaîne codée en Base64. + +local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre> + + +<pre class="prettyprint lang-lua">r:md5(string) -- Calcule et renvoie le condensé MD5 d'une chaîne en mode binaire (binary safe). + +local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre> + + +<pre class="prettyprint lang-lua">r:sha1(string) -- Calcule et renvoie le condensé SHA1 d'une chaîne en mode binaire (binary safe). + +local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre> + + +<pre class="prettyprint lang-lua">r:escape(string) -- Echappe une chaîne de type URL. + +local url = "http://foo.bar/1 2 3 & 4 + 5" +local escaped = r:escape(url) -- renvoie 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre> + + +<pre class="prettyprint lang-lua">r:unescape(string) -- Déséchappe une chaîne de type URL. + +local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5" +local unescaped = r:unescape(url) -- renvoie 'http://foo.bar/1 2 3 & 4 + 5'</pre> + + +<pre class="prettyprint lang-lua">r:construct_url(string) -- Construit une URL à partir d'un URI + +local url = r:construct_url(r.uri)</pre> + + +<pre class="prettyprint lang-lua">r.mpm_query(number) -- Interroge le serveur à propos de son module MPM via la requête ap_mpm_query. + +local mpm = r.mpm_query(14) +if mpm == 1 then + r:puts("Ce serveur utilise le MPM Event") +end</pre> + + +<pre class="prettyprint lang-lua">r:expr(string) -- Evalue une chaîne de type <a href="../expr.html">expr</a>. + +if r:expr("%{HTTP_HOST} =~ /^www/") then + r:puts("Ce nom d'hôte commence par www") +end</pre> + + +<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Interroge le serveur à propos du + -- processus à la position <code>a</code>. + +local process = r:scoreboard_process(1) +r:puts("Le serveur 1 a comme PID " .. process.pid)</pre> + + +<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Interroge le serveur à propos du + -- thread <code>b</code>, dans le processus <code>a</code>. + +local thread = r:scoreboard_worker(1, 1) +r:puts("L'ID du thread 1 du serveur 1 est " .. thread.tid .. " et son +état est " .. thread.status)</pre> + + +<pre class="prettyprint lang-lua">r:clock() -- Renvoie l'heure courante avec une précision d'une microseconde.</pre> + + +<pre class="prettyprint lang-lua">r:requestbody(filename) -- Lit et renvoie le corps d'une requête. + -- Si 'filename' est spécifié, le + -- corps de requête n'est pas + -- renvoyé, mais sauvegardé dans + -- le fichier correspondant. + +local input = r:requestbody() +r:puts("Vous m'avez envoyé le corps de requête suivant :\n") +r:puts(input)</pre> + + +<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Ajoute le filtre en entrée 'filter_name'.</pre> + + +<pre class="prettyprint lang-lua">r:module_info(module_name) -- Interroge le serveur à propos d'un 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)) -- affiche toutes les directives + -- implémentées par ce module. + end +end</pre> + + +<pre class="prettyprint lang-lua">r:loaded_modules() -- Renvoie une liste des modules chargés par httpd. + +for k, module in pairs(r:loaded_modules()) do + r:puts("J'ai chargé le module " .. module .. "\n") +end</pre> + + +<pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Génère le nom d'un fichier run-time + -- (par exemple la mémoire partagée + -- "file") relativement au répertoire de run-time.</pre> + + +<pre class="prettyprint lang-lua">r:server_info() -- Renvoie une table contenant des informations à + -- propos du serveur, comme le nom de + -- l'exécutable httpd, le module mpm utilisé, etc...</pre> + + +<pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Définit la racine des documents + -- pour la requête à file_path.</pre> + + +<pre class="prettyprint lang-lua">r:add_version_component(component_string) -- Ajoute un élément à + -- la bannière du serveur.</pre> + + +<pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Définit le préfixe et la + -- racine des documents du contexte pour une requête.</pre> + + +<pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Convertit un chemin du système de + -- fichiers en URL indépendamment du système d'exploitation.</pre> + + +<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Echappe une chaîne pour journalisation.</pre> + + +<pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Vérifie si 'string' correspond à + -- 'pattern' via la fonction strcmp_match (GLOBs). Par exemple, est-ce que + -- 'www.example.com' correspond à '*.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:set_keepalive() -- Définit l'état de persistance d'une requête. + -- Renvoie true dans la mesure du possible, false dans le cas contraire.</pre> + + +<pre class="prettyprint lang-lua">r:make_etag() -- Génère et renvoie le etag pour la requête courante.</pre> + + +<pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Renvoie une réponse d'intérim (1xx) au + -- client. Si 'clear' est vrai, les en-têtes disponibles + -- seront envoyés et effacés.</pre> + + +<pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Génère et définit une réponse + -- personnalisée pour un code d'état particulier. + -- Le fonctionnement est très proche de celui de la directive ErrorDocument. + +r:custom_response(404, "Baleted!")</pre> + + +<pre class="prettyprint lang-lua">r.exists_config_define(string) -- Vérifie si une définition de configuration existe. + +if r.exists_config_define("FOO") then + r:puts("httpd a probablement été lancé avec l'option -DFOO, ou FOO a + été défini dans la configuration") +end</pre> + + +<pre class="prettyprint lang-lua">r:state_query(string) -- Interroge le serveur à propos de son état.</pre> + + +<pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Exécute stat() sur un fichier, et renvoie une table contenant + -- des informations à propos de ce fichier. + +local info = r:stat("/var/www/foo.txt") +if info then + r:puts("Ce fichier existe et a été modifié pour la dernière fois à : " .. info.modified) +end</pre> + + +<pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Exécute une recherche à base d'expression rationnelle + -- sur une chaîne, et renvoie les éventuelles correspondances trouvées. + +local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]]) +if matches then + r:puts("L'expression rationnelle correspond et le dernier mot + capturé ($2) est : " .. matches[2]) +end + +-- Exemple avec insensibilité à la casse : +local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1) + +-- les drapeaux peuvent être une combibaison bit à bit de : +-- 0x01: insensibilité à la casse +-- 0x02: recherche multiligne</pre> + + +<pre class="prettyprint lang-lua">r.usleep(microsecondes) -- Interrompt l'exécution du script pendant le nombre de microsecondes spécifié.</pre> + + +<pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquiert une connexion à une base de données et renvoie une classe database. + -- Voir '<a href="#databases">Connectivité aux bases de données</a>' + -- pour plus de détails.</pre> + + +<pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Défini une variable Inter-VM avec une valeur spécifique. + -- Ces valeurs sont conservées même si la VM est + -- arrêtée ou non utilisée, et ne doivent donc être + -- utilisées que si MaxConnectionsPerChild > 0. + -- Les valeurs peuvent être de type number, string + -- ou boolean et sont stockées séparément pour + -- chaque processus (elles ne seront donc pas d'une + -- grande utilité si l'on utilise le mpm prefork). + +r:ivm_get("key") -- Lit le contenu d'une variable définie via ivm_set. Renvoie + -- le contenu de la variable si elle existe, ou nil + -- dans le cas contraire. + +-- Voici un exemple de lecture/écriture qui sauvegarde une variable +-- globale en dehors de la VM : +function handle(r) + -- La première VM qui effectue l'appel suivant n'obtiendra aucune + -- valeur, et devra la créer + local foo = r:ivm_get("cached_data") + if not foo then + foo = do_some_calcs() -- simulation de valeurs de retour + r:ivm_set("cached_data", foo) -- définition globale de la variable + end + r:puts("La donnée en cache est : ", foo) +end</pre> + +<pre class="prettyprint lang-lua">r:htpassword(string [,algorithm [,cost]]) -- Génère un hash de mot de passe à partir d'une chaîne. + -- algorithm: 0 = APMD5 (défaut), 1 = SHA, 2 = BCRYPT, 3 = CRYPT. + -- cost: ne s'utilise qu'avec l'algorythme BCRYPT (défaut = 5).</pre> + + +<pre class="prettyprint lang-lua">r:mkdir(dir [,mode]) -- Crée un répertoire et définit son mode via le paramètre optionnel mode.</pre> + + +<pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Crée des répertoires de manière récursive et définit + -- leur mode via le paramètre optionnel mode.</pre> + + +<pre class="prettyprint lang-lua">r:rmdir(dir) -- Supprime un répertoire.</pre> + + +<pre class="prettyprint lang-lua">r:touch(file [,mtime]) -- Définit la date de modification d'un fichier à la date courante ou à + -- la valeur optionnelle mtime en msec.</pre> + + +<pre class="prettyprint lang-lua">r:get_direntries(dir) -- Renvoie une table contenant toutes les entrées de répertoires. + +-- Renvoie un chemin sous forme éclatée en chemin, fichier, extension +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) -- Interprète une chaîne date/heure et renvoie l'équivalent en secondes depuis epoche.</pre> + + +<pre class="prettyprint lang-lua">r:getcookie(key) -- Obtient un cookie HTTP</pre> + + +<pre class="prettyprint lang-lua">r:setcookie(key, value, secure, expires) -- Définit un cookie HTTP, par exemple : +r:setcookie("foo", "bar and stuff", false, os.time() + 86400)</pre> + + +<pre class="prettyprint lang-lua">r:wsupgrade() -- Met à jour une connexion vers les WebSockets si possible (et si demandé) : +if r:wsupgrade() then -- si la mise à jour est possible : + r:wswrite("Bienvenue dans les websockets!") -- écrit quelque chose à l'intention du client + r:wsclose() -- Au revoir ! +end</pre> + + +<pre class="prettyprint lang-lua">r:wsread() -- Lit un cadre de websocket depuis une connexion vers websocket mise à jour (voir ci-dessus) : + +local line, isFinal = r:wsread() -- isFinal indique s'il s'agit du cadre final. + -- dans le cas contraire, on peut lire les cadres suivants +r:wswrite("Vous avez écrit : " .. line)</pre> + + +<pre class="prettyprint lang-lua">r:wswrite(line) -- écrit un cadre vers un client WebSocket : +r:wswrite("Bonjour le Monde !")</pre> + + +<pre class="prettyprint lang-lua">r:wsclose() -- ferme une requête WebSocket et l'achève pour httpd : + +if r:wsupgrade() then + r:wswrite("Ecrire quelque chose : ") + local line = r:wsread() or "nothing" + r:wswrite("Vous avez écrit : " .. line); + r:wswrite("Au revoir !") + r:wsclose() +end</pre> + +</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">Fonctions de journalisation</a></h2> + +<pre class="prettyprint lang-lua"> -- exemples de messages de journalisation + r:trace1("Ceci est un message de journalisation de niveau + trace") -- les niveaux valides vont de trace1 à trace8 + r:debug("Ceci est un message de journalisation de niveau debug") + r:info("Ceci est un message de journalisation de niveau info") + r:notice("Ceci est un message de journalisation de niveau notice") + r:warn("Ceci est un message de journalisation de niveau warn") + r:err("Ceci est un message de journalisation de niveau err") + r:alert("Ceci est un message de journalisation de niveau alert") + r:crit("Ceci est un message de journalisation de niveau crit") + r:emerg("Ceci est un message de journalisation de niveau emerg")</pre> + + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="apache2" id="apache2">Paquet apache2</a></h2> +<p>Le paquet nommé <code>apache2</code> est fourni avec (au minimum) le +contenu suivant :</p> +<dl> + <dt>apache2.OK</dt> + <dd>Constante interne OK. Les gestionnaires renverront cette valeur + s'ils ont traité la requête.</dd> + <dt>apache2.DECLINED</dt> + <dd>Constante interne DECLINED. Les gestionnaires renverront cette + valeur s'ils n'ont pas l'intention de traiter la requête.</dd> + <dt>apache2.DONE</dt> + <dd>Constante interne DONE.</dd> + <dt>apache2.version</dt> + <dd>Chaîne contenant la version du serveur HTTP Apache</dd> + <dt>apache2.HTTP_MOVED_TEMPORARILY</dt> + <dd>Code d'état HTTP</dd> + <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt> + <dd>Constantes internes utilisées par <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd> + <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt> + <dd>constantes internes utilisées par <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></dd> + +</dl> +<p>Les autres codes d'état HTTP ne sont pas encore implémentés.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="modifying_buckets" id="modifying_buckets">Modification de contenu avec les filtres lua</a></h2> + + <p> + Les fonctions de filtrage implémentées via les directives <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code> ou <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> sont conçues comme des + fonctions de 3ème phase non blocantes utilisant des sous-routines + pour suspendre et reprendre l'exécution d'une fonction lorsque des + paquets de données sont envoyés à la chaîne de filtrage. La + structure de base d'une telle fonction est : + </p> + <pre class="prettyprint lang-lua">function filter(r) + -- Nous indiquons tout d'abord que nous sommes prêts à recevoir des + -- blocs de données. + -- Avant ceci, nous pouvons définir notre environnement, tester + -- certaines conditions, et, si nous le jugeons nécessaire, refuser le + -- filtrage d'une requête : + if something_bad then + return -- Le filtrage est sauté + end + -- Sans se préoccuper des données que nous devons éventuellement ajouter, un arrêt est réalisé ici. + -- Noter que les filtres de sortie sont les seuls capables d'ajouter des éléments au début des données. + -- Les filtres en entrée peuvent ajouter des éléments à la fin des données au stade final. + + coroutine.yield([optional header to be prepended to the content]) + + -- Après cet arrêt, nous allons recevoir d'autres blocs de données, un par un ; + -- nous pouvons les traiter comme il nous plaît et procéder à la réponse. + -- Ces blocs sont conservés dans la variable globale 'bucket', nous réalisons donc + -- une boucle pour vérifier que 'bucket' n'est pas vide : + while bucket ~= nil do + local output = mangle(bucket) -- Do some stuff to the content + coroutine.yield(output) -- Return our new content to the filter chain + end + + -- Une fois les blocs de données épuisés, 'bucket' est positionné à une valeur vide ('nil'), + -- ce qui va nous faire sortir de cette boucle et nous amener à l'étape suivante. + -- On peut ajouter ce qu'on veut à la fin des données à cette étape, qui constitue le dernier + -- arrêt. Les filtres d'entrée comme de sortie peuvent servir à ajouter des éléments à la fin + -- des données à cette étape. + coroutine.yield([optional footer to be appended to the content]) +end</pre> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="databases" id="databases">Connectivité aux bases de données</a></h2> + + <p>Mod_lua implémente une fonctionnalité basique de connexion aux +bases de données permettant d'envoyer des requêtes ou d'exécuter des +commandes auprès des moteurs de base de données les plus courants +(mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle), ainsi que mod_dbd.</p> + <p> + <code>dbType</code>, le premier paramètre de <code>dbacquire</code>, est + sensible à la casse.</p> + <p> + Ses valeurs possibles sont <code>mysql</code>, <code>pgsql</code>, + <code>freetds</code>, <code>odbc</code>, <code>sqlite2</code>, + <code>sqlite3</code>, <code>oracle</code> ou <code>mod_dbd</code>. + </p> + <p>L'exemple suivant montre comment se connecter à une base de +données et extraire des informations d'une table :</p> + <pre class="prettyprint lang-lua">function handle(r) + -- connexion à la base de données + local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb") + if not err then + -- Sélection de certaines informations + local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1") + if not err then + local rows = results(0) -- extrait tous les enregistrements en mode synchrone + for k, row in pairs(rows) do + r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) ) + end + else + r:puts("Database query error: " .. err) + end + database:close() + else + r:puts("Connexion à la base de données impossible : " .. err) + end +end</pre> + + <p> + Pour utiliser <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, spécifiez +<code>mod_dbd</code> comme type de base de données, ou laissez le champ +vide : + </p> + <pre class="prettyprint lang-lua">local database = r:dbacquire("mod_dbd")</pre> + + <h3><a name="database_object" id="database_object">L'objet database et ses méthodes</a></h3> + + <p>L'objet database renvoyé par <code>dbacquire</code> possède +les méthodes suivantes :</p> + <p><strong>Sélection normale et requête vers une base de données +:</strong></p> + <pre class="prettyprint lang-lua">-- Exécution d'une requête et renvoie du nombre d'enregistrements +affectés : +local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1") + +-- Exécution d'une requête et renvoie du résultat qui peut être utilisé +en mode synchrone ou asynchrone : +local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")</pre> + + <p><strong>Utilisation de requêtes préparées (recommandé) :</strong></p> + <pre class="prettyprint lang-lua">-- Création et exécution d'une requête préparée : +local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u") +if not errmsg then + local result, errmsg = statement:query(20) -- exécute la requête pour age > 20 +end + +-- Extrait une requête préparée depuis une directive DBDPrepareSQL : +local statement, errmsg = database:prepared(r, "someTag") +if not errmsg then + local result, errmsg = statement:select("John Doe", 123) -- injecte les valeurs "John Doe" et 123 dans la requête +end</pre> + + <p><strong>Echappement de valeurs, fermeture de la base données, +etc...</strong></p> + <pre class="prettyprint lang-lua">-- Echappe une valeur pour pouvoir l'utiliser dans une requête : +local escaped = database:escape(r, [["'|blabla]]) + +-- Ferme une base de données et libère les liens vers cette dernière : +database:close() + +-- Vérifie si une connexion à une base de données est en service et +opérationnelle : +local connected = database:active()</pre> + + + <h3><a name="result_sets" id="result_sets">Travail avec les jeux d'enregistrements renvoyés par les requêtes</a></h3> + + <p>Les jeux d'enregistrements renvoyés par <code>db:select</code> ou par des +requêtes préparées créées par <code>db:prepare</code> permettent de +sélectionner des enregistrements en mode synchrone ou +asynchrone, selon le nombre d'enregistrements spécifié :<br /> + <code>result(0)</code> sélectionne tous les enregistrements en mode +synchrone en renvoyant une table d'enregistrements.<br /> + <code>result(-1)</code> sélectionne le prochain enregistrement disponible en +mode asynchrone.<br /> + <code>result(N)</code> sélectionne l'enregistrement numéro +<code>N</code> en mode asynchrone. + </p> + <pre class="prettyprint lang-lua">-- extrait un jeu d'enregistrements via une requête régulière : +local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1") + +local rows = result(0) -- sélectionne tous les enregistrements en mode synchrone +local row = result(-1) -- sélectionne le prochain enregistrement disponible en mode asynchrone +local row = result(1234) -- sélectionne l'enregistrement 1234 en mode asynchrone +local row = result(-1, true) -- Lit l'enregistrement suivant en utilisant les noms d'enregistrements comme index.</pre> + + <p>Il est possible de construire une fonction qui renvoie une +fonction itérative permettant de traiter tous les enregistrement en mode +synchrone ou asynchrone selon la valeur de l'argument async : + </p> + <pre class="prettyprint lang-lua">function rows(resultset, async) + local a = 0 + local function getnext() + a = a + 1 + local row = resultset(-1) + return row and a or nil, row + end + if not async then + return pairs(resultset(0)) + else + return getnext, self + end +end + +local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u") +if not err then + -- sélectionne des enregistrements en mode asynchrone : + local result, err = statement:select(20) + if not err then + for index, row in rows(result, true) do + .... + end + end + + -- sélectionne des enregistrements en mode synchrone : + local result, err = statement:select(20) + if not err then + for index, row in rows(result, false) do + .... + end + end +end</pre> + + + <h3><a name="closing_databases" id="closing_databases">Fermeture d'une connexion à une base de données</a></h3> + + + <p>Lorsqu'elles ne sont plus utilisées, les connexions aux bases de +données doivent être fermées avec <code>database:close()</code>. Si vous +ne les fermez pas manuellement, mod_lua les fermera peut-être en tant +que résidus collectés, mais si ce n'est pas le cas, vous pouvez finir +pas avoir trop de connexions vers la base de données inutilisées. Les +deux mesures suivantes sont pratiquement identiques : + </p> + <pre class="prettyprint lang-lua">-- Méthode 1 : fermeture manuelle de la connexion +local database = r:dbacquire("mod_dbd") +database:close() -- c'est tout + +-- Méthode 2 : on laisse le collecteur de résidus la fermer +local database = r:dbacquire("mod_dbd") +database = nil -- on coupe le lien +collectgarbage() -- fermeture de la connexion par le collecteur de résidus</pre> + + + <h3><a name="database_caveat" id="database_caveat">Précautions à prendre lorsque l'on travaille avec les bases +de données</a></h3> + + <p>Bien que les fonctions <code>query</code> et <code>run</code> +soient toujours disponibles, il est recommandé d'utiliser des requêtes +préparées chaque fois que possible, afin d'une part d'optimiser les +performances (si votre connexion reste longtemps en vie), et d'autre part +minimiser le risque d'attaques par injection SQL. Les fonctions +<code>run</code> et <code>query</code> ne doivent être utilisées que +lorsque la requête ne contient pas de variables (requête statique). Dans +le cas des requêtes dynamiques, utilisez <code>db:prepare</code> ou +<code>db:prepared</code>. + </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="luaauthzprovider" id="luaauthzprovider">Directive</a> <a name="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Branche une fonction fournisseur d'autorisation dans <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> +</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Disponible depuis la version 2.4.3 du serveur HTTP Apache</td></tr> +</table> +<p>Lorsqu'une fonction lua a été enregistrée en tant que fournisseur +d'autorisation, elle peut être appelée via la directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> :</p> + + +<pre class="prettyprint lang-config">LuaRoot "/usr/local/apache2/lua" +LuaAuthzProvider foo authz.lua authz_check_foo +<Location "/"> + Require foo johndoe +</Location></pre> + +<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> + + + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luacodecache" id="luacodecache">Directive</a> <a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure le cache de code compilé.</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Défaut:</a></th><td><code>LuaCodeCache stat</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p> + Cette directive permet de définir le comportement du cache de code + en mémoire. La valeur par défaut est stat ; dans ce cas, le script + du niveau le plus haut (et pas les scripts inclus) est vérifié à + chaque fois que ce fichier est nécessaire, et est rechargé si la + date de modification est plus récente que celle du script déjà + chargé. Les autres valeurs permettent respectivement de garder le + fichier en cache perpétuellement (forever - jamais vérifié ni + remplacé), ou de ne jamais le mettre en cache (never).</p> + + <p>En général, les valeurs stat et forever sont utilisées pour un + serveur en production, et les valeurs stat ou never pour un serveur + en développement.</p> + + <div class="example"><h3>Exemples :</h3><pre class="prettyprint lang-config">LuaCodeCache stat +LuaCodeCache forever +LuaCodeCache never</pre> +</div> + + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a> <a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase access_checker du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookAccessChecker /chemin/vers/lua/script.lua hook_function_name [early|late]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.</td></tr> +</table> +<p>Ajoute votre fonction d'accroche à la phase access_checker. Une +fonction d'accroche access checker renvoie en général OK, DECLINED, ou +HTTP_FORBIDDEN.</p> +<div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luahookauthchecker" id="luahookauthchecker">Directive</a> <a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase auth_checker du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookAuthChecker /chemin/vers/lua/script.lua hook_function_name [early|late]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.</td></tr> +</table> +<p>Invoque une fonction lua au cours de la phase auth_checker du +traitement de la requête. Cette directive peut s'utiliser pour +implémenter une vérification arbitraire de l'authentification et de +l'autorisation. Voici un exemple très simple : +</p> +<pre class="prettyprint lang-lua">require 'apache2' + +-- fonction d'accroche authcheck fictive +-- Si la requête ne contient aucune donnée d'authentification, l'en-tête +-- de la réponse est défini et un code 401 est renvoyé afin de demander au +-- navigateur d'effectuer une authentification basique. Si la requête +-- comporte des données d'authentification, elles ne sont pas vraiment +-- consultées, mais on admet la prise en compte de l'utilisateur 'foo' et +-- on la valide. On vérifie ensuite si l'utilisateur est bien 'foo' et on +-- accepte la requête. +function authcheck_hook(r) + + -- recherche des informations d'authentification + auth = r.headers_in['Authorization'] + if auth ~= nil then + -- définition d'un utilisateur par défaut + r.user = 'foo' + end + + if r.user == nil then + r:debug("authcheck: user is nil, returning 401") + r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"' + return 401 + elseif r.user == "foo" then + r:debug('user foo: OK') + else + r:debug("authcheck: user='" .. r.user .. "'") + r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"' + return 401 + end + return apache2.OK +end</pre> + +<div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a> <a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase check_user_id du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookCheckUserID /chemin/vers/lua/script.lua hook_function_name [early|late]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.</td></tr> +</table><p>...</p> + <div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luahookfixups" id="luahookfixups">Directive</a> <a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase de correction du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookFixups /chemin/vers/lua/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> +<p> + Idem LuaHookTranslateName, mais s'exécute durant la phase de + correction. +</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="luahookinsertfilter" id="luahookinsertfilter">Directive</a> <a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase insert_filter du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookInsertFilter /chemin/vers/lua/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p>Non encore implémenté</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">Directive</a> <a name="LuaHookLog" id="LuaHookLog">LuaHookLog</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Permet une insertion dans la phase de journalisation du +traitement d'une requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookLog /path/to/lua/script.lua log_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> +<p> + Ce dispositif d'insertion simple permet d'exécuter une fonction + lorsque httpd entre dans la phase de journalisation du traitement + d'une requête. Vous pouvez ainsi ajouter des données à vos propres + entrées de journalisation, manipuler les entrées du journal standard + avant leur enregistrement ou empêcher l'enregistrement d'une entrée + dans le journal. Pour empêcher l'enregistrement normal des entrées + du journal, renvoyez simplement <code>apache2.DONE</code> dans votre + gestionnaire de journalisation, ou au contraire, renvoyez + <code>apache2.OK</code> pour que httpd effectue une journalisation + normale. +</p> +<p>Exemple :</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) + -- on joue à pile ou face : + -- Si on obtient 1, on écrit dans notre propre journal Lua et on dit + -- à httpd de ne pas enregistrer d'entrée dans le journal standard.. + -- Si on obtient 2, on nettoie un peu les données avant que httpd ne + -- les enregistre dans le journal standard. + + if math.random(1,2) == 1 then + -- On effectue notre propre journalisation et le journal + -- standard n'est pas alimenté + local f = io.open("/foo/secret.log", "a") + if f then + f:write("Quelque chose de secret est arrivé à " .. r.uri .. "\n") + f:close() + end + return apache2.DONE -- On dit à httpd de ne rien enregistrer + --dans le journal standard + else + r.uri = r.uri:gsub("somesecretstuff", "") -- nettoie les données + return apache2.OK -- et httpd doit alors les enregistrer. + 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">Directive</a> <a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase map_to_storage du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookMapToStorage /chemin/vers/lua/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Identique à la directive + <code class="directive">LuaHookTranslateName</code>, mais s'exécute à la phase + map-to-storage du traitement de la requête. Les modules comme + <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> agissent pendant cette phase, ce qui permet de + présenter un exemple intéressant de ce que l'on peut faire ici :</p> + <pre class="prettyprint lang-config">LuaHookMapToStorage "/path/to/lua/script.lua" check_cache</pre> + + <pre class="prettyprint lang-lua">require"apache2" +cached_files = {} + +function read_file(filename) + local input = io.open(filename, "r") + if input then + local data = input:read("*a") + cached_files[filename] = data + file = cached_files[filename] + input:close() + end + return cached_files[filename] +end + +function check_cache(r) + if r.filename:match("%.png$") then -- Ne concerne que les fichiers PNG + local file = cached_files[r.filename] -- Vérifie les entrées du cache + if not file then + file = read_file(r.filename) -- Lit le fichier vers le cache + end + if file then -- Si le fichier existe, on l'envoie + r.status = 200 + r:write(file) + r:info(("%s a été envoyé au client depuis le cache"):format(r.filename)) + return apache2.DONE -- cout-circuite le gestionnaire par défaut des fichiers PNG + end + end + return apache2.DECLINED -- Si nous n'avons rien eu à faire, nous laissons les autres s'en charger +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="luahookpretranslate" id="luahookpretranslate">Directive</a> <a name="LuaHookPreTranslate" id="LuaHookPreTranslate">LuaHookPreTranslate</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase de pré-traduction du +traitement d'une requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookPreTranslate /path/to/lua/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> +<p> + Identique à LuaHookTranslateName, mais s'exécute au cours de la phase de + pré-traduction où les pourcentages du chemin de l'URI ne sont pas encore + décodés. +</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="luahooktranslatename" id="luahooktranslatename">Directive</a> <a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée à la phase du nom de +traduction du traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookTranslateName /chemin/vers/lua/script.lua nom_fonction_hook [early|late]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.</td></tr> +</table><p> + Cette directive permet d'ajouter un point d'entrée (à + APR_HOOK_MIDDLE) à la phase du nom de traduction du traitement de la + requête. La fonction hook accepte un seul argument, le request_rec, + et doit renvoyer un code d'état qui est soit un code d'erreur HTTP, + ou une constante définie dans le module apache2 : apache2.OK, + apache2.DECLINED, ou apache2.DONE.</p> + + <p>Pour ceux qui ne sont pas familiers avec les points d'entrée + (hook), en gros, chaque hook sera invoqué jusqu'à ce que l'un + d'entre eux renvoie apache2.OK. Si un hook n'effectuer pas la + traduction, il doit juste renvoyer apache2.DECLINED. Si le + traitement de la requête doit être interrompu, la valeur renvoyée + doit être apache2.DONE.</p> + + <p>Exemple :</p> + +<pre class="prettyprint lang-config"># httpd.conf +LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper</pre> + + +<pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua -- +require "apache2" +function silly_mapper(r) + if r.uri == "/" then + r.filename = "/var/www/home.lua" + return apache2.OK + else + return apache2.DECLINED + end +end</pre> + + + <div class="note"><h3>Contexte</h3><p>Cette directive ne peut être + utilisée ni à l'intérieur d'une section <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> ou <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, ni dans un fichier htaccess.</p></div> + + <div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luahooktypechecker" id="luahooktypechecker">Directive</a> <a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase type_checker du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookTypeChecker /chemin/vers/lua/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p> + Cette directive fournit un point d'entrée pour la phase + type_checker du traitement de la requête. Cette phase + correspond au moment où la requête se voit assigner un type et un + gestionnaire de contenu, et peut donc être utilisée pour modifier le + type et le gestionnaire en fonction de l'entrée : + </p> + <pre class="prettyprint lang-config">LuaHookTypeChecker "/path/to/lua/script.lua" type_checker</pre> + + <pre class="prettyprint lang-lua"> function type_checker(r) + if r.uri:match("%.to_gif$") then -- foo.png.to_gif convient + r.content_type = "image/gif" -- affectation du type image/gif + r.handler = "gifWizard" -- force le traitement de la requête par le module gifWizard + r.filename = r.uri:gsub("%.to_gif$", "") -- corrige le nom du fichier demandé + return apache2.OK + end + + return apache2.DECLINED + 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="luainherit" id="luainherit">Directive</a> <a name="LuaInherit" id="LuaInherit">LuaInherit</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contrôle la manière dont les sections de configuration +parentes sont fusionnées dans les enfants</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Défaut:</a></th><td><code>LuaInherit parent-first</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Versions 2.4.0 et supérieures</td></tr> +</table><p>Par défaut, si des directives LuaHook* se trouvent dans + des sections de configuration Directory ou Location qui se + chevauchent, les scripts + définis dans les sections les plus spécifiques s'exécutent + <em>après</em> ceux définis dans les sections plus génériques + (LuaInherit parent-first). Vous pouvez inverser cet ordre, ou faire + en sorte que le contexte parent ne s'applique pas du tout.</p> + + <p>Jusqu'aux versions 2.3.x, le comportement par défaut consistait à + ignorer les directives LuaHook* situées dans les sections de + configuration parentes.</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="luainputfilter" id="luainputfilter">Directive</a> <a name="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit une fonction Lua pour le filtrage en entrée</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Disponible depuis la version 2.4.5 du serveur HTTP +Apache</td></tr> +</table> +<p>Cette directive permet d'ajouter un filtre en entrée sous la forme +d'une fonction Lua. A l'instar des filtres en sorties, les filtres en +entrée fonctionnent comme des sous-routines, intervenant dans un premier +temps avant l'envoi du contenu des tampons, puis chaque fois qu'un +paquet de données doit être transmis à la chaîne, et éventuellement +produisant toute donnée à ajouter aux données en entrée. La variable +globale <code>bucket</code> contient les paquets de données tels qu'ils +sont transmis au script Lua : +</p> + +<pre class="prettyprint lang-config">LuaInputFilter myInputFilter "/www/filter.lua" input_filter +<Files "*.lua"> + SetInputFilter myInputFilter +</Files></pre> + +<pre class="prettyprint lang-lua">--[[ + Exemple de filtre en entrée qui convertit toutes les données POST en + majuscules. +]]-- +function input_filter(r) + print("luaInputFilter called") -- pour débogage + coroutine.yield() -- attend des paquets de données + while bucket do -- Pour chaque paquet, faire ... + local output = string.upper(bucket) -- Convertit toutes les données POST en majuscules + coroutine.yield(output) -- Envoie les données traitées à la chaîne de filtrage + end + -- plus aucune donnée à traiter. + coroutine.yield("&filterSignature=1234") -- Ajoute une signature à la fin +end</pre> + +<p> +Le filtre en entrée peut interdire ou sauter un filtre s'il est +considéré comme indésirable : +</p> +<pre class="prettyprint lang-lua">function input_filter(r) + if not good then + return -- Empêche tout simplement le filtrage et transmet le contenu original + end + coroutine.yield() -- attend des paquets de données + ... -- insert les filtres ici +end</pre> + +<p> +Voir "<a href="#modifying_buckets">Modification de contenu avec les +filtres Lua</a>" pour plus de détails. +</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="luamaphandler" id="luamaphandler">Directive</a> <a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Met en correspondance un chemin avec un gestionnaire lua</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaMapHandler modele-uri /chemin/vers/lua/script.lua +[nom-fonction]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Cette directive permet de faire correspondre un modèle d'uri avec + une fonction de gestionnaire située dans un fichier spécifique. Elle + utilise les expressions rationnelles PCRE pour mettre en + correspondance l'uri, et supporte les groupes de correspondance + d'interpolation dans le chemin du fichier et le nom de la fonction. + Prenez garde aux problèmes de sécurité en écrivant vos expressions + rationnelles.</p> + <div class="example"><h3>Exemples :</h3><pre class="prettyprint lang-config">LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"</pre> +</div> + <p>Cette directive va faire correspondre des uri comme + /photos/show?id=9 au fichier /scripts/photos.lua, et invoquera la + fonction de gestionnaire handle_show au niveau de la vm lua + après chargement de ce fichier.</p> + +<pre class="prettyprint lang-config">LuaMapHandler "/bingo" "/scripts/wombat.lua"</pre> + + <p>Cette directive invoquera la fonction "handle" qui est la + valeur par défaut si aucun nom de fonction spécifique n'est + spécifié.</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="luaoutputfilter" id="luaoutputfilter">Directive</a> <a name="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit une fonction Lua pour le filtrage de contenu en +sortie</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</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">Compatibilité:</a></th><td>Disponible à partir de la version 2.4.5 du serveur HTTP +Apache</td></tr> +</table> +<p>>Cette directive permet d'ajouter un filtre en sortie sous la forme +d'une fonction Lua. A l'instar des filtres en sorties, les filtres en +entrée fonctionnent comme des sous-routines, intervenant dans un premier +temps avant l'envoi du contenu des tampons, puis chaque fois qu'un +paquet de données doit être transmis à la chaîne, et éventuellement +produisant toute donnée à ajouter aux données en sortie. La variable +globale <code>bucket</code> contient les paquets de données tels qu'ils +sont transmis au script Lua : +</p> + +<pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter +<Files "*.lua"> + SetOutputFilter myOutputFilter +</Files></pre> + +<pre class="prettyprint lang-lua">--[[ + Exemple de filtre en sortie qui échappe toutes les entités HTML en + sortie +]]-- +function output_filter(r) + coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Ajoute des données au début de la sortie, + -- puis attend des paquets de données à traiter + while bucket do -- Pour chaque paquet, faire ... + local output = r:escape_html(bucket) -- Echappe les données en sortie + coroutine.yield(output) -- Envoie les données traitées à la chaîne + end + -- plus aucune donnée à traiter. +end</pre> + +<p> +Comme les filres en entrée, le filtre en sortie peut interdire ou sauter un filtre s'il est +considéré comme indésirable : +</p> +<pre class="prettyprint lang-lua">function output_filter(r) + if not r.content_type:match("text/html") then + return -- Empêche tout simplement le filtrage et transmet le contenu original + end + coroutine.yield() -- attend des paquets de données + ... -- insert les filtres ici +end</pre> + +<div class="note"><h3>Les filtres Lua avec <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3> +<p>Lorsqu'on utilise un filtre Lua comme fournisseur sous-jacent via la +directive <code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code>, le +filtrage ne fonctionnera que si <var>filter-name</var> est identique à +<var>provider-name</var>. +</p> </div> + +<p> +Voir "<a href="#modifying_buckets">Modification de contenu avec les +filtres Lua</a>" pour plus de détails. +</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">Directive</a> <a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ajoute un répertoire au package.cpath de lua</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaPackageCPath /chemin/vers/include/?.soa</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Cette directive permet d'ajouter un chemin à la liste des chemins + de recherche des bibliothèques partagées de lua. Ceci modifie le + package.cpath dans les vms lua.</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="luapackagepath" id="luapackagepath">Directive</a> <a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ajoute un répertoire au package.path de lua</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaPackagePath /chemin/vers/include/?.lua</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table><p>Cette directive permet d'ajouter un chemin à la liste des + chemins de recherche du module lua. Elle suit les mêmes conventions + que lua. Ceci modifie le package.path dans les vms lua.</p> + + <div class="example"><h3>Exemples :</h3><pre class="prettyprint lang-config">LuaPackagePath "/scripts/lib/?.lua" +LuaPackagePath "/scripts/lib/?/init.lua"</pre> +</div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luaquickhandler" id="luaquickhandler">Directive</a> <a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la gestion rapide du +traitement de la requête</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Cette phase s'exécute juste après l'attribution de la requête à + un serveur virtuel, et permet d'effectuer certains traitements avant + le déroulement des autres phases, ou de servir une requête sans + avoir à la traduire, l'associer à un espace de stockage, etc... + Comme cette phase s'exécute avant toute autre, les directives telles + que <code class="directive"><a href="../mod/core.html#location"><Location></a></code> ou + <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> ne + sont pas encore prises en compte, car Les URI n'ont pas encore été + entièrement interprétés. + </p> + <div class="note"><h3>Contexte</h3><p>Cette directive ne peut être + utilisée ni à l'intérieur d'une section <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> ou <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, ni dans un fichier htaccess.</p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="luaroot" id="luaroot">Directive</a> <a name="LuaRoot" id="LuaRoot">LuaRoot</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Spécifie le chemin de base pour la résolution des chemins +relatifs dans les directives de mod_lua</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaRoot /chemin/vers/un/répertoire</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Cette directive permet de spécifier le chemin de base qui sera + utilisé pour évaluer tous les chemins relatifs dans mod_lua. En + l'absence de cette directive, les chemins relatifs sont résolus par + rapport au répertoire de travail courant, ce qui ne sera pas + toujours approprié pour un serveur.</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="luascope" id="luascope">Directive</a> <a name="LuaScope" id="LuaScope">LuaScope</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Une valeur parmi once, request, conn, thread -- la valeur par défaut est once</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaScope once|request|conn|thread|server [min] [max]</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Défaut:</a></th><td><code>LuaScope once</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration globale, serveur virtuel, répertoire, .htaccess</td></tr> +<tr><th><a href="directive-dict.html#Override">Surcharges autorisées:</a></th><td>All</td></tr> +<tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr> +</table> + <p>Cette directive permet de spécifier la durée de vie de + l'interpréteur Lua qui sera utilisé dans ce "répertoire". La valeur + par défaut est "once".</p> + + <dl> + <dt>once:</dt> <dd>utilise l'interpréteur une fois.</dd> + + <dt>request:</dt> <dd>utilise l'interpréteur pour traiter tout ce + qui est basé sur le même fichier dans la requête, et qui se trouve + aussi dans la portée de la requête.</dd> + + <dt>conn:</dt> <dd>idem request, mais attaché à connection_rec</dd> + + <dt>thread:</dt> <dd>Utilise l'interpréteur pendant toute la durée + de vie du thread qui traite la requête (disponible seulement avec + les MPMs threadés).</dd> + + <dt>server:</dt> <dd>Le comportement est ici différent, car la + portée du serveur présente une durée de vie assez longue, et + plusieurs threads vont partager le même server_rec. Pour gérer tout + ceci, les états lua du serveur sont stockés dans une liste de ressources + apr. Les arguments <code>min</code> et <code>max</code> permettent + de spécifier les nombres minimaux et maximaux d'états lua à stocker + dans la liste.</dd> + </dl> + <p>En général, les portées <code>thread</code> et <code>server</code> + sont 2 à 3 fois plus rapides que les autres, car elles n'ont pas besoin + de régénérer de nouveaux états Lua à chaque requête (comme c'est le + cas avec le MPM event, où même les connexions persistantes utilisent un + nouveau thread pour chaque requête). Si vous pensez que vos scripts + n'auront pas de problème s'il réutilisent un état, alors les portées + <code>thread</code> ou <code>server</code> doivent être utilisées car + elles présenteront de meilleures performances. Alors que la portée + <code>thread</code> fournira les réponses les plus rapides, la portée + <code>server</code> utilisera moins de mémoire car les états sont + rassemblés dans des jeux, permettant par exemple à 1000 threads de + partager 100 états Lua, ne nécessitant ainsi que 10% de la mémoire + requise par la portée <code>thread</code>. + </p> + +</div> +</div> +<div class="bottomlang"> +<p><span>Langues Disponibles: </span><a href="../en/mod/mod_lua.html" hreflang="en" rel="alternate" title="English"> en </a> | +<a href="../fr/mod/mod_lua.html" title="Français"> fr </a></p> +</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">Commentaires</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 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 Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div> +<script type="text/javascript"><!--//--><![CDATA[//><!-- +var comments_shortname = 'httpd'; +var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_lua.html'; +(function(w, d) { + if (w.location.hostname.toLowerCase() == "httpd.apache.org") { + d.write('<div id="comments_thread"><\/div>'); + var s = d.createElement('script'); + s.type = 'text/javascript'; + s.async = true; + s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; + (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); + } + else { + d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); + } +})(window, document); +//--><!]]></script></div><div id="footer"> +<p class="apache">Copyright 2023 The Apache Software Foundation.<br />Autorisé sous <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">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- +if (typeof(prettyPrint) !== 'undefined') { + prettyPrint(); +} +//--><!]]></script> +</body></html>
\ No newline at end of file |