mirror of
https://github.com/apache/httpd.git
synced 2025-07-05 16:21:14 +03:00
edf0f80ad9
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1377592 13f79535-47bb-0310-9956-ffa450edef68
1346 lines
48 KiB
XML
1346 lines
48 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_lua.xml.meta">
|
|
|
|
<name>mod_lua</name>
|
|
|
|
<description>Provides Lua hooks into various portions of the httpd
|
|
request processing</description>
|
|
<status>Experimental</status>
|
|
<sourcefile>mod_lua.c</sourcefile>
|
|
<identifier>lua_module</identifier>
|
|
<compatibility>2.3 and later</compatibility>
|
|
|
|
<summary>
|
|
<p>This module allows the server to be extended with scripts written in the
|
|
Lua programming language. The extension points (hooks) available with
|
|
<module>mod_lua</module> 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>
|
|
|
|
<note><code>mod_lua</code> is still in experimental state.
|
|
Until it is declared stable, usage and behavior may change
|
|
at any time, even between stable releases of the 2.4.x series.
|
|
Be sure to check the CHANGES file before upgrading.</note>
|
|
|
|
<note type="warning"><title>Warning</title>
|
|
<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>
|
|
</note>
|
|
|
|
</summary>
|
|
|
|
<section id="basicconf"><title>Basic Configuration</title>
|
|
|
|
<p>The basic module loading directive is</p>
|
|
|
|
<highlight language="config">
|
|
LoadModule lua_module modules/mod_lua.so
|
|
</highlight>
|
|
|
|
<p>
|
|
<code>mod_lua</code> provides a handler named <code>lua-script</code>,
|
|
which can be used with an <code>AddHandler</code> directive:</p>
|
|
|
|
<highlight language="config">
|
|
AddHandler lua-script .lua
|
|
</highlight>
|
|
|
|
<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 <directive>LuaMapHandler</directive>.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section id="writinghandlers"><title>Writing Handlers</title>
|
|
<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 <module>mod_proxy</module>, <module>mod_cgi</module>,
|
|
and <module>mod_status</module>.</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>
|
|
|
|
|
|
<highlight language="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"
|
|
r:puts("Hello Lua World!\n")
|
|
|
|
if r.method == 'GET' then
|
|
for k, v in pairs( r:parseargs() ) do
|
|
r:puts( string.format("%s: %s\n", k, v) )
|
|
end
|
|
elseif r.method == 'POST' then
|
|
for k, v in pairs( r:parsebody() ) do
|
|
r:puts( string.format("%s: %s\n", k, v) )
|
|
end
|
|
else
|
|
r:puts("Unsupported HTTP method " .. r.method)
|
|
end
|
|
end
|
|
</highlight>
|
|
|
|
<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>
|
|
|
|
</section>
|
|
|
|
<section id="writingauthzproviders">
|
|
<title>Writing Authorization Providers</title>
|
|
|
|
<p><module>mod_authz_core</module> 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
|
|
<directive module="mod_authz_core">Require</directive> directive gives
|
|
the name of the responsible authorization provider. For any
|
|
<directive module="mod_authz_core">Require</directive> line,
|
|
<module>mod_authz_core</module> 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>
|
|
|
|
<highlight language="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
|
|
</highlight>
|
|
|
|
<p>The following configuration registers this function as provider
|
|
<code>foo</code> and configures it for URL <code>/</code>:</p>
|
|
<highlight language="config">
|
|
LuaAuthzProvider foo authz_provider.lua authz_check_foo
|
|
<Location />
|
|
Require foo 10.1.2.3 john_doe
|
|
</Location>
|
|
</highlight>
|
|
|
|
</section>
|
|
|
|
<section id="writinghooks"><title>Writing Hooks</title>
|
|
|
|
<p>Hook functions are how modules (and Lua scripts) participate in the
|
|
processing of requests. Each type of hook exposed by the server exists for
|
|
a specific purpose, such as mapping requests to the filesystem,
|
|
performing access control, or setting mimetypes:</p>
|
|
|
|
<table border="1" style="zebra">
|
|
<tr>
|
|
<th>Hook phase</th>
|
|
<th>mod_lua directive</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Quick handler</td>
|
|
<td><directive module="mod_lua">LuaQuickHandler</directive></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>
|
|
<td>Translate name</td>
|
|
<td><directive module="mod_lua">LuaHookTranslateName</directive></td>
|
|
<td>This phase translates the requested URI into a filename on the
|
|
system. Modules such as <module>mod_alias</module> and
|
|
<module>mod_rewrite</module> operate in this phase.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Map to storage</td>
|
|
<td><directive module="mod_lua">LuaHookMapToStorage</directive></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><directive module="mod_lua">LuaHookAccessChecker</directive></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>
|
|
<td>Check User ID</td>
|
|
<td><directive module="mod_lua">LuaHookCheckUserID</directive></td>
|
|
<td>This phase it used to check the negotiated user ID</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Check Authorization</td>
|
|
<td><directive module="mod_lua">LuaHookAuthChecker</directive> or
|
|
<directive module="mod_lua">LuaAuthzProvider</directive></td>
|
|
<td>This phase authorizes a user based on the negotiated credentials, such as
|
|
user ID, client certificate etc.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Check Type</td>
|
|
<td><directive module="mod_lua">LuaHookTypeChecker</directive></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><directive module="mod_lua">LuaHookFixups</directive></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>
|
|
<td>Content handler</td>
|
|
<td>fx. <code>.lua</code> files or through <directive module="mod_lua">LuaMapHandler</directive></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>(none)</td>
|
|
<td>Once a request has been handled, it enters several logging phases,
|
|
which logs the request in either the error or access log</td>
|
|
</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>
|
|
|
|
|
|
<highlight language="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
|
|
</highlight>
|
|
|
|
|
|
<highlight language="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
|
|
</highlight>
|
|
</section>
|
|
|
|
<section id="datastructures"><title>Data Structures</title>
|
|
|
|
<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 writeable as
|
|
well as readable. (The table fields' content can be changed, but the
|
|
fields themselves cannot be set to different tables.)</p>
|
|
|
|
<table border="1" style="zebra">
|
|
|
|
<tr>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>context_document_root</code></td>
|
|
<td>string</td>
|
|
<td>no</td>
|
|
<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>
|
|
<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</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 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>
|
|
<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
|
|
<directive module="mod_mime">AddHandler</directive> or <directive module="core">SetHandler</directive>
|
|
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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>headers_out</code></td>
|
|
<td>table</td>
|
|
<td>yes</td>
|
|
<td>MIME header environment for the response.</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>
|
|
<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>
|
|
<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>
|
|
<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.</td>
|
|
</tr>
|
|
<tr>
|
|
<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>
|
|
<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>
|
|
<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/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>
|
|
<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>
|
|
<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>
|
|
<td><code>subprocess_env</code></td>
|
|
<td>table</td>
|
|
<td>yes</td>
|
|
<td>The environment variables set for this request.</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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
|
|
<p>The request_rec has (at least) the following methods:</p>
|
|
|
|
<highlight language="lua">
|
|
r:flush() -- flushes the output buffer
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:addoutputfilter(name|function) -- add an output filter
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:parseargs() -- returns a Lua table containing the request's query string arguments
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:parsebody([sizeLimit]) -- parse the request body as a POST and return a lua table.
|
|
-- An optional number may be passed to specify the maximum number
|
|
-- of bytes to parse. Default is 8192 bytes.
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:puts("hello", " world", "!") -- print to response body
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:write("a single string") -- print to response body
|
|
</highlight>
|
|
|
|
<highlight language="lua">
|
|
r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result
|
|
</highlight>
|
|
</dd>
|
|
</dl>
|
|
|
|
</section>
|
|
|
|
<section id="logging"><title>Logging Functions</title>
|
|
|
|
<highlight language="lua">
|
|
-- examples of logging messages<br />
|
|
r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
|
|
r:debug("This is a debug log message")<br />
|
|
r:info("This is an info log message")<br />
|
|
r:notice("This is a notice log message")<br />
|
|
r:warn("This is a warn log message")<br />
|
|
r:err("This is an err log message")<br />
|
|
r:alert("This is an alert log message")<br />
|
|
r:crit("This is a crit log message")<br />
|
|
r:emerg("This is an emerg log message")<br />
|
|
</highlight>
|
|
|
|
</section>
|
|
|
|
<section id="apache2"><title>apache2 Package</title>
|
|
<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 <module>mod_proxy</module></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 <module>mod_authz_core</module></dd>
|
|
|
|
</dl>
|
|
<p>(Other HTTP status codes are not yet implemented.)</p>
|
|
</section>
|
|
|
|
<section id="modifying_buckets">
|
|
<title>Modifying contents with Lua filters</title>
|
|
<p>
|
|
Filter functions implemented via <directive module="mod_lua">LuaInputFilter</directive>
|
|
or <directive module="mod_lua">LuaOutputFilter</directive> 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>
|
|
<highlight language="lua">
|
|
function filter(r)
|
|
-- Our first yield is to signal that we are ready to receive buckets.
|
|
-- Before this yield, we can set up our environment, check for conditions,
|
|
-- and, if we deem it necessary, decline filtering a request alltogether:
|
|
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
|
|
</highlight>
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaRoot</name>
|
|
<description>Specify the base path for resolving relative paths for mod_lua directives</description>
|
|
<syntax>LuaRoot /path/to/a/directory</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
|
|
<usage>
|
|
<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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaScope</name>
|
|
<description>One of once, request, conn, thread -- default is once</description>
|
|
<syntax>LuaScope once|request|conn|thread|server [min] [max]</syntax>
|
|
<default>LuaScope once</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
|
|
<usage>
|
|
<p>Specify the lifecycle 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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaMapHandler</name>
|
|
<description>Map a path to a lua handler</description>
|
|
<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage>
|
|
<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>
|
|
<example><title>Examples:</title>
|
|
<highlight language="config">
|
|
LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
|
|
</highlight>
|
|
</example>
|
|
<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>
|
|
|
|
<highlight language="config">
|
|
LuaMapHandler /bingo /scripts/wombat.lua
|
|
</highlight>
|
|
<p>This would invoke the "handle" function, which
|
|
is the default if no specific function name is
|
|
provided.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaPackagePath</name>
|
|
<description>Add a directory to lua's package.path</description>
|
|
<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage><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>
|
|
|
|
<example><title>Examples:</title>
|
|
<highlight language="config">
|
|
LuaPackagePath /scripts/lib/?.lua
|
|
LuaPackagePath /scripts/lib/?/init.lua
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaPackageCPath</name>
|
|
<description>Add a directory to lua's package.cpath</description>
|
|
<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
|
|
<usage>
|
|
<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>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaCodeCache</name>
|
|
<description>Configure the compiled code cache.</description>
|
|
<syntax>LuaCodeCache stat|forever|never</syntax>
|
|
<default>LuaCodeCache stat</default>
|
|
<contextlist>
|
|
<context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
|
|
<usage><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>
|
|
|
|
<example><title>Examples:</title>
|
|
<highlight language="config">
|
|
LuaCodeCache stat
|
|
LuaCodeCache forever
|
|
LuaCodeCache never
|
|
</highlight>
|
|
</example>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookTranslateName</name>
|
|
<description>Provide a hook for the translate name phase of request processing</description>
|
|
<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
|
|
|
|
<usage><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>
|
|
|
|
<highlight language="config">
|
|
# httpd.conf
|
|
LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
|
|
</highlight>
|
|
|
|
<highlight language="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
|
|
</highlight>
|
|
|
|
<note><title>Context</title><p>This directive is not valid in <directive
|
|
type="section" module="core">Directory</directive>, <directive
|
|
type="section" module="core">Files</directive>, or htaccess
|
|
context.</p></note>
|
|
|
|
<note><title>Ordering</title><p>The optional arguments "early" or "late"
|
|
control when this script runs relative to other modules.</p></note>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookFixups</name>
|
|
<description>Provide a hook for the fixups phase of a request
|
|
processing</description>
|
|
<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage>
|
|
<p>
|
|
Just like LuaHookTranslateName, but executed at the fixups phase
|
|
</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookMapToStorage</name>
|
|
<description>Provide a hook for the map_to_storage phase of request processing</description>
|
|
<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage>
|
|
<p>Like <directive>LuaHookTranslateName</directive> but executed at the
|
|
map-to-storage phase of a request. Modules like mod_cache run at this phase,
|
|
which makes for an interesting example on what to do here:</p>
|
|
<highlight language="config">
|
|
LuaHookMapToStorage /path/to/lua/script.lua check_cache
|
|
</highlight>
|
|
<highlight language="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
|
|
</highlight>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookCheckUserID</name>
|
|
<description>Provide a hook for the check_user_id phase of request processing</description>
|
|
<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
|
|
<usage><p>...</p>
|
|
<note><title>Ordering</title><p>The optional arguments "early" or "late"
|
|
control when this script runs relative to other modules.</p></note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookTypeChecker</name>
|
|
<description>Provide a hook for the type_checker phase of request processing</description>
|
|
<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage><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>
|
|
<highlight language="config">
|
|
LuaHookTypeChecker /path/to/lua/script.lua type_checker
|
|
</highlight>
|
|
<highlight language="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
|
|
</highlight>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookAuthChecker</name>
|
|
<description>Provide a hook for the auth_checker phase of request processing</description>
|
|
<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
|
|
<usage>
|
|
<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>
|
|
<highlight language="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
|
|
</highlight>
|
|
<note><title>Ordering</title><p>The optional arguments "early" or "late"
|
|
control when this script runs relative to other modules.</p></note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookAccessChecker</name>
|
|
<description>Provide a hook for the access_checker phase of request processing</description>
|
|
<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
|
|
<usage>
|
|
<p>Add your hook to the access_checker phase. An access checker
|
|
hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
|
|
<note><title>Ordering</title><p>The optional arguments "early" or "late"
|
|
control when this script runs relative to other modules.</p></note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaHookInsertFilter</name>
|
|
<description>Provide a hook for the insert_filter phase of request processing</description>
|
|
<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage><p>Not Yet Implemented</p></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaInherit</name>
|
|
<description>Controls how parent configuration sections are merged into children</description>
|
|
<syntax>LuaInherit none|parent-first|parent-last</syntax>
|
|
<default>LuaInherit parent-first</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<compatibility>2.4.0 and later</compatibility>
|
|
<usage><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></usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaQuickHandler</name>
|
|
<description>Provide a hook for the quick handler of request processing</description>
|
|
<syntax>LuaQuickHandler /path/to/script.lua hook_function_name</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<override>All</override>
|
|
<usage>
|
|
<p>
|
|
This phase is run immediately after the request has been mapped to a virtal 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 <directive
|
|
type="section" module="core">Location</directive> or <directive
|
|
type="section" module="core">Directory</directive> are void in this phase, just as
|
|
URIs have not been properly parsed yet.
|
|
</p>
|
|
<note><title>Context</title><p>This directive is not valid in <directive
|
|
type="section" module="core">Directory</directive>, <directive
|
|
type="section" module="core">Files</directive>, or htaccess
|
|
context.</p></note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaAuthzProvider</name>
|
|
<description>Plug an authorization provider function into <module>mod_authz_core</module>
|
|
</description>
|
|
<syntax>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</syntax>
|
|
<contextlist><context>server config</context> </contextlist>
|
|
<compatibility>2.4.3 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>After a lua function has been registered as authorization provider, it can be used
|
|
with the <directive module="mod_authz_core">Require</directive> directive:</p>
|
|
|
|
<highlight language="config">
|
|
LuaRoot /usr/local/apache2/lua
|
|
LuaAuthzProvider foo authz.lua authz_check_foo
|
|
<Location />
|
|
Require foo johndoe
|
|
</Location>
|
|
</highlight>
|
|
<highlight language="lua">
|
|
require "apache2"
|
|
function authz_check_foo(r, who)
|
|
if r.user ~= who then return apache2.AUTHZ_DENIED
|
|
return apache2.AUTHZ_GRANTED
|
|
end
|
|
</highlight>
|
|
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
|
|
<directivesynopsis>
|
|
<name>LuaInputFilter</name>
|
|
<description>Provide a Lua function for content input filtering</description>
|
|
<syntax>LuaInputFilter filter_name /path/to/lua/script.lua function_name</syntax>
|
|
<contextlist><context>server config</context> </contextlist>
|
|
<compatibility>2.5.0 and later</compatibility>
|
|
|
|
<usage>
|
|
<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>
|
|
|
|
<highlight language="config">
|
|
LuaInputFilter myInputFilter /www/filter.lua input_filter
|
|
<FilesMatch "\.lua>
|
|
SetInputFilter myInputFilter
|
|
</FilesMatch>
|
|
</highlight>
|
|
<highlight language="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
|
|
</highlight>
|
|
<p>
|
|
The input filter supports denying/skipping a filter if it is deemed unwanted:
|
|
</p>
|
|
<highlight language="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
|
|
</highlight>
|
|
<p>
|
|
See "<a href="#modifying_buckets">Modifying contents with Lua
|
|
filters</a>" for more information.
|
|
</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LuaOutputFilter</name>
|
|
<description>Provide a Lua function for content output filtering</description>
|
|
<syntax>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</syntax>
|
|
<contextlist><context>server config</context> </contextlist>
|
|
<compatibility>2.5.0 and later</compatibility>
|
|
|
|
<usage>
|
|
<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>
|
|
|
|
<highlight language="config">
|
|
LuaOutputFilter myOutputFilter /www/filter.lua output_filter
|
|
<FilesMatch "\.lua>
|
|
SetOutputFilter myOutputFilter
|
|
</FilesMatch>
|
|
</highlight>
|
|
<highlight language="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
|
|
</highlight>
|
|
<p>
|
|
As with the input filter, the output filter supports denying/skipping a filter
|
|
if it is deemed unwanted:
|
|
</p>
|
|
<highlight language="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
|
|
</highlight>
|
|
<p>
|
|
See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more
|
|
information.
|
|
</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
|
|
|
|
</modulesynopsis>
|