| <?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>Extension</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 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 a <directive |
| module="core">SetHandler</directive> or |
| <directive module="mod_mime">AddHandler</directive> directive:</p> |
| |
| <highlight language="config"> |
| <Files "*.lua"> |
| SetHandler lua-script |
| </Files> |
| </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" |
| |
| 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 |
| </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 file system, |
| performing access control, or setting mime types:</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>Pre-Translate name</td> |
| <td><directive module="mod_lua">LuaHookPreTranslateName</directive></td> |
| <td>This phase translates the requested URI into a filename on the |
| system, before decoding occurs. Modules such as <module>mod_proxy</module> |
| can operate in this phase.</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><directive module="mod_lua">LuaHookLog</directive></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> |
| |
| |
| <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 writable 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. 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> |
| <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. A read-only lua table suitable for iteration is available as r:headers_in_table().</td> |
| </tr> |
| <tr> |
| <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> |
| <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. A read-only lua table suitable for iteration is available as r:notes_table().</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/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> |
| <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. 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> |
| <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> |
| </dd> |
| </dl> |
| </section> |
| <section id="functions"><title>Built in functions</title> |
| |
| <p>The request_rec object has (at least) the following methods:</p> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="lua"> |
| r:add_output_filter(filter_name) -- add an output filter: |
| |
| r:add_output_filter("fooFilter") -- add the fooFilter to the output stream |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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") |
| </highlight> |
| |
| <highlight language="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") |
| </highlight> |
| |
| <highlight language="lua"> |
| r:puts("hello", " world", "!") -- print to response body, self explanatory |
| </highlight> |
| |
| <highlight language="lua"> |
| r:write("a single string") -- print to response body, self explanatory |
| </highlight> |
| |
| <highlight language="lua"> |
| r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result |
| </highlight> |
| |
| <highlight language="lua"> |
| r:base64_encode(string) -- Encodes a string using the Base64 encoding standard: |
| |
| local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q= |
| </highlight> |
| |
| <highlight language="lua"> |
| r:base64_decode(string) -- Decodes a Base64-encoded string: |
| |
| local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test' |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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' |
| </highlight> |
| |
| <highlight language="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' |
| </highlight> |
| |
| <highlight language="lua"> |
| r:construct_url(string) -- Constructs an URL from an URI |
| |
| local url = r:construct_url(r.uri) |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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) |
| </highlight> |
| |
| <highlight language="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") |
| </highlight> |
| |
| |
| <highlight language="lua"> |
| r:clock() -- Returns the current time with microsecond precision |
| </highlight> |
| |
| <highlight language="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) |
| </highlight> |
| |
| <highlight language="lua"> |
| r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:server_info() -- Returns a table containing server information, such as |
| -- the name of the httpd executable file, mpm used etc. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:set_document_root(file_path) -- Sets the document root for the request to file_path |
| </highlight> |
| |
| <!-- |
| <highlight language="lua"> |
| r:add_version_component(component_string) - - Adds a component to the server banner. |
| </highlight> |
| --> |
| |
| <highlight language="lua"> |
| r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request |
| </highlight> |
| |
| <highlight language="lua"> |
| r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way |
| </highlight> |
| |
| <highlight language="lua"> |
| r:escape_logitem(string) -- Escapes a string for logging |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="lua"> |
| r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:make_etag() -- Constructs and returns the etag for the current request. |
| </highlight> |
| |
| <highlight language="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. |
| </highlight> |
| |
| <highlight language="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!") |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="lua"> |
| r:state_query(string) -- Queries the server for state information |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="lua"> |
| r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds. |
| </highlight> |
| |
| <highlight language="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. |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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). |
| </highlight> |
| |
| <highlight language="lua"> |
| r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode parameter. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode parameter. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:rmdir(dir) -- Removes a directory. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value. |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="lua"> |
| r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche. |
| </highlight> |
| |
| <highlight language="lua"> |
| r:getcookie(key) -- Gets a HTTP cookie |
| </highlight> |
| |
| <highlight language="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 |
| } |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="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) |
| </highlight> |
| |
| <highlight language="lua"> |
| r:wswrite(line) -- Writes a frame to a WebSocket client: |
| r:wswrite("Hello, world!") |
| </highlight> |
| |
| <highlight language="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 |
| </highlight> |
| |
| <highlight language="lua"> |
| r:wspeek() -- Checks if any data is ready to be read |
| |
| -- Sleep while nothing is being sent to us... |
| while r:wspeek() == false do |
| r.usleep(50000) |
| end |
| -- We have data ready! |
| local line = r:wsread() |
| |
| </highlight> |
| |
| |
| <highlight language="lua"> |
| r:config() -- Get a walkable tree of the entire httpd configuration |
| </highlight> |
| |
| <highlight language="lua"> |
| r:activeconfig() -- Get a walkable tree of the active (virtualhost-specific) httpd configuration |
| </highlight> |
| |
| |
| </section> |
| |
| <section id="logging"><title>Logging Functions</title> |
| |
| <highlight language="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") |
| </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 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 |
| </highlight> |
| </section> |
| |
| <section id="databases"> |
| <title>Database connectivity</title> |
| <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> |
| <highlight language="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 |
| </highlight> |
| <p> |
| To utilize <module>mod_dbd</module>, specify <code>mod_dbd</code> |
| as the database type, or leave the field blank: |
| </p> |
| <highlight language="lua"> |
| local database = r:dbacquire("mod_dbd") |
| </highlight> |
| <section id="database_object"> |
| <title>Database object and contained functions</title> |
| <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> |
| <highlight language="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") |
| </highlight> |
| <p><strong>Using prepared statements (recommended):</strong></p> |
| <highlight language="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 |
| |
| </highlight> |
| <p><strong>Escaping values, closing databases etc:</strong></p> |
| <highlight language="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() |
| </highlight> |
| </section> |
| <section id="result_sets"> |
| <title>Working with result sets</title> |
| <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> |
| <highlight language="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. |
| </highlight> |
| <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> |
| <highlight language="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 |
| </highlight> |
| </section> |
| <section id="closing_databases"> |
| <title>Closing a database connection</title> |
| |
| <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> |
| <highlight language="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 |
| </highlight> |
| </section> |
| <section id="database_caveat"> |
| <title>Precautions when working with databases</title> |
| <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> |
| </section> |
| |
| </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 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> |
| </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>LuaHookPreTranslate</name> |
| <description>Provide a hook for the pre_translate phase of a request |
| processing</description> |
| <syntax>LuaHookPreTranslate /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 pre_translate phase, |
| where the URI-path is not percent decoded. |
| </p> |
| </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>LuaHookLog</name> |
| <description>Provide a hook for the access log phase of a request |
| processing</description> |
| <syntax>LuaHookLog /path/to/lua/script.lua log_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 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> |
| <highlight language="config"> |
| LuaHookLog /path/to/script.lua logger |
| </highlight> |
| <highlight language="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 |
| </highlight> |
| </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 <module>mod_cache</module> 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</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context> |
| </contextlist> |
| <override>All</override> |
| <!-- Third argument does not work at the moment! |
| <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 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 <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> |
| <override>All</override> |
| <compatibility>2.4.5 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 |
| <Files "*.lua"> |
| SetInputFilter myInputFilter |
| </Files> |
| </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> |
| <override>All</override> |
| <compatibility>2.4.5 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 |
| <Files "*.lua"> |
| SetOutputFilter myOutputFilter |
| </Files> |
| </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> |
| <note><title>Lua filters with <module>mod_filter</module></title> |
| <p> When a Lua filter is used as the underlying provider via the |
| <directive module="mod_filter">FilterProvider</directive> directive, filtering |
| will only work when the <var>filter-name</var> is identical to the <var>provider-name</var>. |
| </p> </note> |
| |
| <p> |
| See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more |
| information. |
| </p> |
| |
| </usage> |
| </directivesynopsis> |
| |
| |
| |
| </modulesynopsis> |