granicus.if.org Git - apache/blob - docs/manual/mod/mod_lua.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_lua.xml.meta">
  24
  25 <name>mod_lua</name>
  26
  27 <description>Provides Lua hooks into various portions of the httpd
  28 request processing</description>
  29 <status>Experimental</status>
  30 <sourcefile>mod_lua.c</sourcefile>
  31 <identifier>lua_module</identifier>
  32 <compatibility>2.3 and later</compatibility>
  33
  34 <summary>
  35 <p>This module allows the server to be extended with scripts written in the
  36 Lua programming language.  The extension points (hooks) available with
  37 <module>mod_lua</module> include many of the hooks available to
  38 natively compiled Apache HTTP Server modules, such as mapping requests to
  39 files, generating dynamic responses, access control, authentication, and
  40 authorization</p>
  41
  42 <p>More information on the Lua programming language can be found at the
  43 <a href="http://www.lua.org/">the Lua website</a>.</p>
  44
  45 <note><code>mod_lua</code> is still in experimental state.
  46 Until it is declared stable, usage and behavior may change
  47 at any time, even between stable releases of the 2.4.x series.
  48 Be sure to check the CHANGES file before upgrading.</note>
  49
  50 </summary>
  51
  52 <section id="basicconf"><title>Basic Configuration</title>
  53
  54 <p>The basic module loading directive is</p>
  55
  56 <highlight language="config">
  57     LoadModule lua_module modules/mod_lua.so
  58 </highlight>
  59
  60 <p>
  61 <code>mod_lua</code> provides a handler named <code>lua-script</code>,
  62 which can be used with an <code>AddHandler</code> directive:</p>
  63
  64 <highlight language="config">
  65 AddHandler lua-script .lua
  66 </highlight>
  67
  68 <p>
  69 This will cause <code>mod_lua</code> to handle requests for files
  70 ending in <code>.lua</code> by invoking that file's
  71 <code>handle</code> function.
  72 </p>
  73
  74 <p>For more flexibility, see <directive>LuaMapHandler</directive>.
  75 </p>
  76
  77 </section>
  78
  79 <section id="writinghandlers"><title>Writing Handlers</title>
  80 <p> In the Apache HTTP Server API, the handler is a specific kind of hook
  81 responsible for generating the response.  Examples of modules that include a
  82 handler are <module>mod_proxy</module>, <module>mod_cgi</module>,
  83 and <module>mod_status</module>.</p>
  84
  85 <p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
  86 just evaluating a script body CGI style. A handler function looks
  87 something like this:</p>
  88
  89
  90 <highlight language="lua">
  91 <strong>example.lua</strong>
  92 -- example handler
  93
  94 require "string"
  95
  96 --[[
  97      This is the default method name for Lua handlers, see the optional
  98      function-name in the LuaMapHandler directive to choose a different
  99      entry point.
 100 --]]
 101 function handle(r)
 102     r.content_type = "text/plain"
 103     r:puts("Hello Lua World!\n")
 104
 105     if r.method == 'GET' then
 106         for k, v in pairs( r:parseargs() ) do
 107             r:puts( string.format("%s: %s\n", k, v) )
 108         end
 109     elseif r.method == 'POST' then
 110         for k, v in pairs( r:parsebody() ) do
 111             r:puts( string.format("%s: %s\n", k, v) )
 112         end
 113     else
 114         r:puts("Unsupported HTTP method " .. r.method)
 115     end
 116 end
 117 </highlight>
 118
 119 <p>
 120 This handler function just prints out the uri or form encoded
 121 arguments to a plaintext page.
 122 </p>
 123
 124 <p>
 125 This means (and in fact encourages) that you can have multiple
 126 handlers (or hooks, or filters) in the same script.
 127 </p>
 128
 129 </section>
 130
 131 <section id="writingauthzproviders">
 132 <title>Writing Authorization Providers</title>
 133
 134 <p><module>mod_authz_core</module> provides a high-level interface to
 135 authorization that is much easier to use than using into the relevant
 136 hooks directly. The first argument to the
 137 <directive module="mod_authz_core">Require</directive> directive gives
 138 the name of the responsible authorization provider. For any
 139 <directive module="mod_authz_core">Require</directive> line,
 140 <module>mod_authz_core</module> will call the authorization provider
 141 of the given name, passing the rest of the line as parameters. The
 142 provider will then check authorization and pass the result as return
 143 value.</p>
 144
 145 <p>The authz provider is normally called before authentication. If it needs to
 146 know the authenticated user name (or if the user will be authenticated at
 147 all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
 148 This will cause authentication to proceed and the authz provider to be
 149 called a second time.</p>
 150
 151 <p>The following authz provider function takes two arguments, one ip
 152 address and one user name. It will allow access from the given ip address
 153 without authentication, or if the authenticated user matches the second
 154 argument:</p>
 155
 156 <highlight language="lua">
 157 <strong>authz_provider.lua</strong>
 158
 159 require 'apache2'
 160
 161 function authz_check_foo(r, ip, user)
 162     if r.useragent_ip == ip then
 163         return apache2.AUTHZ_GRANTED
 164     elseif r.user == nil then
 165         return apache2.AUTHZ_DENIED_NO_USER
 166     elseif r.user == user then
 167         return apache2.AUTHZ_GRANTED
 168     else
 169         return apache2.AUTHZ_DENIED
 170     end
 171 end
 172 </highlight>
 173
 174 <p>The following configuration registers this function as provider
 175 <code>foo</code> and configures it for URL <code>/</code>:</p>
 176 <highlight language="config">
 177 LuaAuthzProvider foo authz_provider.lua authz_check_foo
 178 &lt;Location /&gt;
 179   Require foo 10.1.2.3 john_doe
 180 &lt;/Location&gt;
 181 </highlight>
 182
 183 </section>
 184
 185 <section id="writinghooks"><title>Writing Hooks</title>
 186
 187 <p>Hook functions are how modules (and Lua scripts) participate in the
 188 processing of requests. Each type of hook exposed by the server exists for
 189 a specific purposes such as mapping requests to the filesystem,
 190 performing access control, or setting mimetypes.  General purpose hooks
 191 that simply run at handy times in the request lifecycle exist as well.</p>
 192
 193 <p>Hook functions are passed the request object as their only argument.
 194 They can return any value, depending on the hook, but most commonly
 195 they'll return OK, DONE, or DECLINED, which you can write in lua as
 196 <code>apache2.OK</code>, <code>apache2.DONE</code>, or
 197 <code>apache2.DECLINED</code>, or else an HTTP status code.</p>
 198
 199 <highlight language="lua">
 200 <strong>translate_name.lua</strong>
 201 -- example hook that rewrites the URI to a filesystem path.
 202
 203 require 'apache2'
 204
 205 function translate_name(r)
 206     if r.uri == "/translate-name" then
 207         r.filename = r.document_root .. "/find_me.txt"
 208         return apache2.OK
 209     end
 210     -- we don't care about this URL, give another module a chance
 211     return apache2.DECLINED
 212 end
 213 </highlight>
 214
 215 <highlight language="lua">
 216 <strong>translate_name2.lua</strong>
 217 --[[ example hook that rewrites one URI to another URI. It returns a
 218      apache2.DECLINED to give other URL mappers a chance to work on the
 219      substitution, including the core translate_name hook which maps based
 220      on the DocumentRoot.
 221
 222      Note: It is currently undefined as to whether this runs before or after
 223      mod_alias.
 224 --]]
 225
 226 require 'apache2'
 227
 228 function translate_name(r)
 229     if r.uri == "/translate-name" then
 230         r.uri = "/find_me.txt"
 231         return apache2.DECLINED
 232     end
 233     return apache2.DECLINED
 234 end
 235 </highlight>
 236 </section>
 237
 238 <section id="datastructures"><title>Data Structures</title>
 239
 240 <dl>
 241 <dt>request_rec</dt>
 242         <dd>
 243         <p>The request_rec is mapped in as a userdata. It has a metatable
 244         which lets you do useful things with it. For the most part it
 245         has the same fields as the request_rec struct (see httpd.h
 246         until we get better docs here) many of which are writeable as
 247         well as readable.  (The table fields' content can be changed, but the
 248         fields themselves cannot be set to different tables.)</p>
 249
 250         <table border="1">
 251
 252         <tr>
 253           <th><strong>Name</strong></th>
 254           <th><strong>Lua type</strong></th>
 255           <th><strong>Writable</strong></th>
 256         </tr>
 257         <tr>
 258           <td><code>ap_auth_type</code></td>
 259           <td>string</td>
 260           <td>no</td>
 261         </tr>
 262         <tr>
 263           <td><code>args</code></td>
 264           <td>string</td>
 265           <td>yes</td>
 266         </tr>
 267         <tr>
 268           <td><code>assbackwards</code></td>
 269           <td>boolean</td>
 270           <td>no</td>
 271         </tr>
 272
 273         <tr>
 274           <td><code>canonical_filename</code></td>
 275           <td>string</td>
 276           <td>no</td>
 277         </tr>
 278         <tr>
 279           <td><code>content_encoding</code></td>
 280           <td>string</td>
 281           <td>no</td>
 282         </tr>
 283         <tr>
 284           <td><code>content_type</code></td>
 285           <td>string</td>
 286           <td>yes</td>
 287         </tr>
 288         <tr>
 289           <td><code>context_prefix</code></td>
 290           <td>string</td>
 291           <td>no</td>
 292         </tr>
 293         <tr>
 294           <td><code>context_document_root</code></td>
 295           <td>string</td>
 296           <td>no</td>
 297         </tr>
 298
 299         <tr>
 300           <td><code>document_root</code></td>
 301           <td>string</td>
 302           <td>no</td>
 303         </tr>
 304         <tr>
 305           <td><code>err_headers_out</code></td>
 306           <td>table</td>
 307           <td>no</td>
 308         </tr>
 309         <tr>
 310           <td><code>filename</code></td>
 311           <td>string</td>
 312           <td>yes</td>
 313         </tr>
 314         <tr>
 315           <td><code>handler</code></td>
 316           <td>string</td>
 317           <td>yes</td>
 318         </tr>
 319
 320         <tr>
 321           <td><code>headers_in</code></td>
 322           <td>table</td>
 323           <td>yes</td>
 324         </tr>
 325         <tr>
 326           <td><code>headers_out</code></td>
 327           <td>table</td>
 328           <td>yes</td>
 329         </tr>
 330         <tr>
 331           <td><code>hostname</code></td>
 332           <td>string</td>
 333           <td>no</td>
 334         </tr>
 335         <tr>
 336           <td><code>log_id</code></td>
 337           <td>string</td>
 338           <td>no</td>
 339         </tr>
 340         <tr>
 341           <td><code>method</code></td>
 342           <td>string</td>
 343           <td>no</td>
 344         </tr>
 345         <tr>
 346           <td><code>notes</code></td>
 347           <td>table</td>
 348           <td>yes</td>
 349         </tr>
 350         <tr>
 351           <td><code>path_info</code></td>
 352           <td>string</td>
 353           <td>no</td>
 354         </tr>
 355         <tr>
 356           <td><code>protocol</code></td>
 357           <td>string</td>
 358           <td>no</td>
 359         </tr>
 360         <tr>
 361           <td><code>proxyreq</code></td>
 362           <td>string</td>
 363           <td>yes</td>
 364         </tr>
 365         <tr>
 366           <td><code>range</code></td>
 367           <td>string</td>
 368           <td>no</td>
 369         </tr>
 370         <tr>
 371           <td><code>subprocess_env</code></td>
 372           <td>table</td>
 373           <td>yes</td>
 374         </tr>
 375         <tr>
 376           <td><code>status</code></td>
 377           <td>number</td>
 378           <td>yes</td>
 379         </tr>
 380         <tr>
 381           <td><code>the_request</code></td>
 382           <td>string</td>
 383           <td>no</td>
 384         </tr>
 385         <tr>
 386           <td><code>unparsed_uri</code></td>
 387           <td>string</td>
 388           <td>no</td>
 389         </tr>
 390         <tr>
 391           <td><code>uri</code></td>
 392           <td>string</td>
 393           <td>yes</td>
 394         </tr>
 395         <tr>
 396           <td><code>user</code></td>
 397           <td>string</td>
 398           <td>yes</td>
 399         </tr>
 400         <tr>
 401           <td><code>useragent_ip</code></td>
 402           <td>string</td>
 403           <td>no</td>
 404         </tr>
 405         </table>
 406
 407         <p>The request_rec has (at least) the following methods:</p>
 408
 409         <highlight language="lua">
 410         r:addoutputfilter(name|function) -- add an output filter
 411         </highlight>
 412
 413         <highlight language="lua">
 414         r:parseargs() -- returns a lua table containing the request's query string arguments
 415         </highlight>
 416 <!--
 417 /* Not supported yet */
 418         <highlight language="lua">
 419         r:parsebody() &dash;- parse the request body as a POST and return  a lua table
 420         </highlight>
 421 -->
 422         <highlight language="lua">
 423         r:puts("hello", " world", "!") -- print to response body
 424         </highlight>
 425
 426         <highlight language="lua">
 427         r:write("a single string") -- print to response body
 428         </highlight>
 429         </dd>
 430     </dl>
 431
 432 </section>
 433
 434 <section id="logging"><title>Logging Functions</title>
 435
 436 <highlight language="lua">
 437         -- examples of logging messages<br />
 438         r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
 439         r:debug("This is a debug log message")<br />
 440         r:info("This is an info log message")<br />
 441         r:notice("This is an notice log message")<br />
 442         r:warn("This is an warn log message")<br />
 443         r:err("This is an err log message")<br />
 444         r:alert("This is an alert log message")<br />
 445         r:crit("This is an crit log message")<br />
 446         r:emerg("This is an emerg log message")<br />
 447 </highlight>
 448
 449 </section>
 450
 451 <section id="apache2"><title>apache2 Package</title>
 452 <p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
 453 <dl>
 454   <dt>apache2.OK</dt>
 455   <dd>internal constant OK.  Handlers should return this if they've
 456   handled the request.</dd>
 457   <dt>apache2.DECLINED</dt>
 458   <dd>internal constant DECLINED.  Handlers should return this if
 459   they are not going to handle the request.</dd>
 460   <dt>apache2.DONE</dt>
 461   <dd>internal constant DONE.</dd>
 462   <dt>apache2.version</dt>
 463   <dd>Apache HTTP server version string</dd>
 464   <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
 465   <dd>HTTP status code</dd>
 466   <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
 467   <dd>internal constants used by <module>mod_proxy</module></dd>
 468 </dl>
 469 <p>(Other HTTP status codes are not yet implemented.)</p>
 470 </section>
 471
 472 <directivesynopsis>
 473 <name>LuaRoot</name>
 474 <description>Specify the base path for resolving relative paths for mod_lua directives</description>
 475 <syntax>LuaRoot /path/to/a/directory</syntax>
 476 <contextlist><context>server config</context><context>virtual host</context>
 477 <context>directory</context><context>.htaccess</context>
 478 </contextlist>
 479 <override>All</override>
 480
 481 <usage>
 482     <p>Specify the base path which will be used to evaluate all
 483     relative paths within mod_lua. If not specified they
 484     will be resolved relative to the current working directory,
 485     which may not always work well for a server.</p>
 486 </usage>
 487 </directivesynopsis>
 488
 489 <directivesynopsis>
 490 <name>LuaScope</name>
 491 <description>One of once, request, conn, server -- default is once</description>
 492 <syntax>LuaScope once|request|conn|server [max|min max]</syntax>
 493 <default>LuaScope once</default>
 494 <contextlist><context>server config</context><context>virtual host</context>
 495 <context>directory</context><context>.htaccess</context>
 496 </contextlist>
 497 <override>All</override>
 498
 499 <usage>
 500     <p>Specify the lifecycle scope of the Lua interpreter which will
 501     be used by handlers in this "Directory." The default is "once"</p>
 502
 503    <dl>
 504     <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
 505
 506     <dt>request:</dt> <dd>use the interpreter to handle anything based on
 507              the same file within this request, which is also
 508              request scoped.</dd>
 509
 510     <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
 511
 512     <dt>server:</dt>  <dd>This one is different than others because the
 513             server scope is quite long lived, and multiple threads
 514             will have the same server_rec. To accommodate this
 515             server scoped interpreter are stored in an apr
 516             resource list. The min and max arguments are intended
 517             to specify the pool size, but are unused at this time.</dd>
 518    </dl>
 519 </usage>
 520 </directivesynopsis>
 521
 522 <directivesynopsis>
 523 <name>LuaMapHandler</name>
 524 <description>Map a path to a lua handler</description>
 525 <syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
 526 <contextlist><context>server config</context><context>virtual host</context>
 527 <context>directory</context><context>.htaccess</context>
 528 </contextlist>
 529 <override>All</override>
 530 <usage>
 531     <p>This directive matches a uri pattern to invoke a specific
 532     handler function in a specific file. It uses PCRE regular
 533     expressions to match the uri, and supports interpolating
 534     match groups into both the file path and the function name
 535     be careful writing your regular expressions to avoid security
 536     issues.</p>
 537    <example><title>Examples:</title>
 538    <highlight language="config">
 539     LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
 540     </highlight>
 541    </example>
 542         <p>This would match uri's such as /photos/show?id=9
 543         to the file /scripts/photos.lua and invoke the
 544         handler function handle_show on the lua vm after
 545         loading that file.</p>
 546
 547 <highlight language="config">
 548     LuaMapHandler /bingo /scripts/wombat.lua
 549 </highlight>
 550         <p>This would invoke the "handle" function, which
 551         is the default if no specific function name is
 552         provided.</p>
 553 </usage>
 554 </directivesynopsis>
 555
 556 <directivesynopsis>
 557 <name>LuaPackagePath</name>
 558 <description>Add a directory to lua's package.path</description>
 559 <syntax>LuaPackagePath /path/to/include/?.lua</syntax>
 560 <contextlist><context>server config</context><context>virtual host</context>
 561 <context>directory</context><context>.htaccess</context>
 562 </contextlist>
 563 <override>All</override>
 564     <usage><p>Add a path to lua's module search path. Follows the same
 565     conventions as lua. This just munges the package.path in the
 566     lua vms.</p>
 567
 568     <example><title>Examples:</title>
 569     <highlight language="config">
 570 LuaPackagePath /scripts/lib/?.lua
 571 LuaPackagePath /scripts/lib/?/init.lua
 572     </highlight>
 573     </example>
 574 </usage>
 575 </directivesynopsis>
 576
 577 <directivesynopsis>
 578 <name>LuaPackageCPath</name>
 579 <description>Add a directory to lua's package.cpath</description>
 580 <syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
 581 <contextlist><context>server config</context><context>virtual host</context>
 582 <context>directory</context><context>.htaccess</context>
 583 </contextlist>
 584 <override>All</override>
 585
 586 <usage>
 587     <p>Add a path to lua's shared library search path. Follows the same
 588     conventions as lua. This just munges the package.cpath in the
 589     lua vms.</p>
 590
 591 </usage>
 592 </directivesynopsis>
 593
 594 <directivesynopsis>
 595 <name>LuaCodeCache</name>
 596 <description>Configure the compiled code cache.</description>
 597 <syntax>LuaCodeCache stat|forever|never</syntax>
 598 <default>LuaCodeCache stat</default>
 599 <contextlist><context>server config</context><context>virtual host</context>
 600 <context>directory</context><context>.htaccess</context>
 601 </contextlist>
 602 <override>All</override>
 603
 604 <usage><p>
 605     Specify the behavior of the in-memory code cache. The default
 606     is stat, which stats the top level script (not any included
 607     ones) each time that file is needed, and reloads it if the
 608     modified time indicates it is newer than the one it has
 609     already loaded. The other values cause it to keep the file
 610     cached forever (don't stat and replace) or to never cache the
 611     file.</p>
 612
 613     <p>In general stat or forever is good for production, and stat or never
 614     for development.</p>
 615
 616     <example><title>Examples:</title>
 617     <highlight language="config">
 618 LuaCodeCache stat
 619 LuaCodeCache forever
 620 LuaCodeCache never
 621     </highlight>
 622     </example>
 623
 624 </usage>
 625 </directivesynopsis>
 626
 627 <directivesynopsis>
 628 <name>LuaHookTranslateName</name>
 629 <description>Provide a hook for the translate name phase of request processing</description>
 630 <syntax>LuaHookTranslateName  /path/to/lua/script.lua  hook_function_name [early|late]</syntax>
 631 <contextlist><context>server config</context><context>virtual host</context>
 632 <context>directory</context>
 633 </contextlist>
 634 <override>All</override>
 635 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
 636
 637 <usage><p>
 638     Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
 639     request processing. The hook function receives a single
 640     argument, the request_rec, and should return a status code,
 641     which is either an HTTP error code, or the constants defined
 642     in the apache2 module: apache2.OK, apache2.DECLINED, or
 643     apache2.DONE. </p>
 644
 645     <p>For those new to hooks, basically each hook will be invoked
 646     until one of them returns apache2.OK. If your hook doesn't
 647     want to do the translation it should just return
 648     apache2.DECLINED. If the request should stop processing, then
 649     return apache2.DONE.</p>
 650
 651     <p>Example:</p>
 652
 653 <highlight language="config">
 654 # httpd.conf
 655 LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
 656 </highlight>
 657
 658 <highlight language="lua">
 659 -- /scripts/conf/hooks.lua --
 660 require "apache2"
 661 function silly_mapper(r)
 662     if r.uri == "/" then
 663         r.filename = "/var/www/home.lua"
 664         return apache2.OK
 665     else
 666         return apache2.DECLINED
 667     end
 668 end
 669 </highlight>
 670
 671    <note><title>Context</title><p>This directive is not valid in <directive
 672    type="section" module="core">Directory</directive>, <directive
 673    type="section" module="core">Files</directive>, or htaccess
 674    context.</p></note>
 675
 676    <note><title>Ordering</title><p>The optional arguments "early" or "late"
 677    control when this script runs relative to other modules.</p></note>
 678
 679 </usage>
 680 </directivesynopsis>
 681
 682 <directivesynopsis>
 683 <name>LuaHookFixups</name>
 684 <description>Provide a hook for the fixups phase of request
 685 processing</description>
 686 <syntax>LuaHookFixups  /path/to/lua/script.lua hook_function_name</syntax>
 687 <contextlist><context>server config</context><context>virtual host</context>
 688 <context>directory</context><context>.htaccess</context>
 689 </contextlist>
 690 <override>All</override>
 691 <usage>
 692 <p>
 693     Just like LuaHookTranslateName, but executed at the fixups phase
 694 </p>
 695 </usage>
 696 </directivesynopsis>
 697
 698 <directivesynopsis>
 699 <name>LuaHookMapToStorage</name>
 700 <description>Provide a hook for the map_to_storage phase of request processing</description>
 701 <syntax>LuaHookMapToStorage  /path/to/lua/script.lua hook_function_name</syntax>
 702 <contextlist><context>server config</context><context>virtual host</context>
 703 <context>directory</context><context>.htaccess</context>
 704 </contextlist>
 705 <override>All</override>
 706     <usage><p>...</p></usage>
 707 </directivesynopsis>
 708
 709 <directivesynopsis>
 710 <name>LuaHookCheckUserID</name>
 711 <description>Provide a hook for the check_user_id phase of request processing</description>
 712 <syntax>LuaHookCheckUserID  /path/to/lua/script.lua hook_function_name [early|late]</syntax>
 713 <contextlist><context>server config</context><context>virtual host</context>
 714 <context>directory</context><context>.htaccess</context>
 715 </contextlist>
 716 <override>All</override>
 717 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
 718 <usage><p>...</p>
 719    <note><title>Ordering</title><p>The optional arguments "early" or "late"
 720    control when this script runs relative to other modules.</p></note>
 721 </usage>
 722 </directivesynopsis>
 723
 724 <directivesynopsis>
 725 <name>LuaHookTypeChecker</name>
 726 <description>Provide a hook for the type_checker phase of request processing</description>
 727 <syntax>LuaHookTypeChecker  /path/to/lua/script.lua hook_function_name</syntax>
 728 <contextlist><context>server config</context><context>virtual host</context>
 729 <context>directory</context><context>.htaccess</context>
 730 </contextlist>
 731 <override>All</override>
 732     <usage><p>...</p></usage>
 733 </directivesynopsis>
 734
 735 <directivesynopsis>
 736 <name>LuaHookAuthChecker</name>
 737 <description>Provide a hook for the auth_checker phase of request processing</description>
 738 <syntax>LuaHookAuthChecker  /path/to/lua/script.lua hook_function_name [early|late]</syntax>
 739 <contextlist><context>server config</context><context>virtual host</context>
 740 <context>directory</context><context>.htaccess</context>
 741 </contextlist>
 742 <override>All</override>
 743 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
 744 <usage>
 745 <p>Invoke a lua function in the auth_checker phase of processing
 746 a request.  This can be used to implement arbitrary authentication
 747 and authorization checking.  A very simple example:
 748 </p>
 749 <highlight language="lua">
 750 require 'apache2'
 751
 752 -- fake authcheck hook
 753 -- If request has no auth info, set the response header and
 754 -- return a 401 to ask the browser for basic auth info.
 755 -- If request has auth info, don't actually look at it, just
 756 -- pretend we got userid 'foo' and validated it.
 757 -- Then check if the userid is 'foo' and accept the request.
 758 function authcheck_hook(r)
 759
 760    -- look for auth info
 761    auth = r.headers_in['Authorization']
 762    if auth ~= nil then
 763      -- fake the user
 764      r.user = 'foo'
 765    end
 766
 767    if r.user == nil then
 768       r:debug("authcheck: user is nil, returning 401")
 769       r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
 770       return 401
 771    elseif r.user == "foo" then
 772       r:debug('user foo: OK')
 773    else
 774       r:debug("authcheck: user='" .. r.user .. "'")
 775       r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
 776       return 401
 777    end
 778    return apache2.OK
 779 end
 780 </highlight>
 781    <note><title>Ordering</title><p>The optional arguments "early" or "late"
 782    control when this script runs relative to other modules.</p></note>
 783 </usage>
 784 </directivesynopsis>
 785
 786 <directivesynopsis>
 787 <name>LuaHookAccessChecker</name>
 788 <description>Provide a hook for the access_checker phase of request processing</description>
 789 <syntax>LuaHookAccessChecker  /path/to/lua/script.lua  hook_function_name [early|late]</syntax>
 790 <contextlist><context>server config</context><context>virtual host</context>
 791 <context>directory</context><context>.htaccess</context>
 792 </contextlist>
 793 <override>All</override>
 794 <compatibility>The optional third argument is supported in 2.3.15 and later</compatibility>
 795 <usage>
 796 <p>Add your hook to the access_checker phase.  An access checker
 797 hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
 798    <note><title>Ordering</title><p>The optional arguments "early" or "late"
 799    control when this script runs relative to other modules.</p></note>
 800 </usage>
 801 </directivesynopsis>
 802
 803 <directivesynopsis>
 804 <name>LuaHookInsertFilter</name>
 805 <description>Provide a hook for the insert_filter phase of request processing</description>
 806 <syntax>LuaHookInsertFilter  /path/to/lua/script.lua hook_function_name</syntax>
 807 <contextlist><context>server config</context><context>virtual host</context>
 808 <context>directory</context><context>.htaccess</context>
 809 </contextlist>
 810 <override>All</override>
 811     <usage><p>Not Yet Implemented</p></usage>
 812 </directivesynopsis>
 813
 814 <directivesynopsis>
 815 <name>LuaInherit</name>
 816 <description>Controls how parent configuration sections are merged into children</description>
 817 <syntax>LuaInherit none|parent-first|parent-last</syntax>
 818 <default>LuaInherit parent-first</default>
 819 <contextlist><context>server config</context><context>virtual host</context>
 820 <context>directory</context><context>.htaccess</context>
 821 </contextlist>
 822 <override>All</override>
 823 <compatibility>2.4.0 and later</compatibility>
 824     <usage><p>By default, if LuaHook* directives are used in overlapping
 825     Directory or Location configuration sections, the scripts defined in the
 826     more specific section are run <em>after</em> those defined in the more
 827     generic section (LuaInherit parent-first).  You can reverse this order, or
 828     make the parent context not apply at all.</p>
 829
 830     <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
 831     directives from parent configuration sections.</p></usage>
 832 </directivesynopsis>
 833
 834 <directivesynopsis>
 835 <name>LuaQuickHandler</name>
 836 <description>Provide a hook for the quick handler of request processing</description>
 837 <syntax></syntax>
 838 <contextlist><context>server config</context><context>virtual host</context>
 839 <context>directory</context><context>.htaccess</context>
 840 </contextlist>
 841 <override>All</override>
 842 <usage><p>...</p>
 843    <note><title>Context</title><p>This directive is not valid in <directive
 844    type="section" module="core">Directory</directive>, <directive
 845    type="section" module="core">Files</directive>, or htaccess
 846    context.</p></note>
 847 </usage>
 848 </directivesynopsis>
 849
 850 <directivesynopsis>
 851 <name>LuaAuthzProvider</name>
 852 <description>Plug an authorization provider function into <module>mod_authz_core</module>
 853 </description>
 854 <syntax>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</syntax>
 855 <contextlist><context>server config</context> </contextlist>
 856 <compatibility>2.5.0 and later</compatibility>
 857
 858 <usage>
 859 <p>After a lua function has been registered as authorization provider, it can be used
 860 with the <directive module="mod_authz_core">Require</directive> directive:</p>
 861
 862 <example>
 863 <highlight language="config">
 864 LuaRoot /usr/local/apache2/lua
 865 LuaAuthzProvider foo authz.lua authz_check_foo
 866 &lt;Location /&gt;
 867   Require foo bar
 868 &lt;/Location&gt;
 869 </highlight>
 870 </example>
 871
 872 </usage>
 873 </directivesynopsis>
 874
 875
 876 </modulesynopsis>