Apache 模块 mod_lua

Summary

该模块允许使用以 Lua 编程语言编写的脚本扩展服务器。 mod_lua可用的扩展点(钩子)包括许多本机编译的 Apache HTTP Server 模块可用的钩子，例如将请求 Map 到文件，生成动态响应，访问控制，身份验证和授权

可以在Lua 网站上找到有关 Lua 编程语言的更多信息。

Basic Configuration

基本的模块加载指令是

LoadModule lua_module modules/mod_lua.so

mod_lua提供了一个名为lua-script的处理程序，可以与SetHandler或AddHandler指令一起使用：

<Files "*.lua">
    SetHandler lua-script
</Files>

这将导致mod_lua通过调用该文件的handle函数来处理对以.lua结尾的文件的请求。

要获得更大的灵 Active，请参见LuaMapHandler。

Writing Handlers

在 Apache HTTP Server API 中，处理程序是负责生成响应的特定类型的钩子。包括处理程序的模块示例为mod_proxy，mod_cgi和mod_status。

mod_lua总是希望为处理程序调用 Lua 函数，而不仅仅是评估脚本主体 CGI 样式。处理程序函数如下所示：

example.lua 
-- 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

此处理程序函数仅将 uri 或表单编码的参数输出到纯文本页面。

这意味着(实际上是鼓励)您可以在同一脚本中拥有多个处理程序(或钩子或过滤器)。

编写授权提供者

mod_authz_core提供了高级的授权界面，比直接使用相关的钩子要容易得多。 Require指令的第一个参数给出负责的授权提供者的名称。对于任何Require行，mod_authz_core将调用给定名称的授权提供程序，并将其余行作为参数传递。然后，提供者将检查授权并将结果作为返回值传递。

通常在身份验证之前调用 authz 提供程序。如果需要知道经过身份验证的用户名(或者完全要对用户进行身份验证)，则提供程序必须返回apache2.AUTHZ_DENIED_NO_USER。这将导致身份验证 continue 进行，并再次调用 authz 提供程序。

以下 authz 提供程序功能使用两个参数，一个 IP 地址和一个用户名。它将允许从给定的 ip 地址进行访问而无需身份验证，或者已身份验证的用户与第二个参数匹配：

authz_provider.lua 

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

以下配置将此功能注册为提供程序foo，并将其配置为 URL /：

LuaAuthzProvider foo authz_provider.lua authz_check_foo
<Location "/">
  Require foo 10.1.2.3 john_doe
</Location>

Writing Hooks

钩子函数是模块(和 Lua 脚本)如何参与请求的处理。服务器公开的每种钩子类型都有特定的用途，例如将请求 Map 到文件系统，执行访问控制或设置 mime 类型：

钩子函数作为唯一的参数传递给请求对象(LuaAuthzProvider 除外，该函数也从 Require 指令传递参数)。它们可以返回任何值，具体取决于钩子，但是最常见的是，它们将返回 OK，DONE 或 DECLINED，您可以在 Lua 中将它们写为apache2.OK，apache2.DONE或apache2.DECLINED，或者是 HTTP 状态代码。

translate_name.lua 
-- 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

translate_name2.lua 
--[[ 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

Data Structures

• request_rec

  • request_rec 作为用户数据 Map。它具有一个元表，可让您使用它做有用的事情。在大多数情况下，它具有与 request_rec 结构相同的字段，其中许多字段可写且可读。 (表字段的内容可以更改，但是字段本身不能设置为其他表.)

内置功能

request_rec 对象具有(至少)以下方法：

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

r:add_output_filter(filter_name) -- add an output filter:

r:add_output_filter("fooFilter") -- add the fooFilter to the output stream

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

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")

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")

r:puts("hello", " world", "!") -- print to response body, self explanatory

r:write("a single string") -- print to response body, self explanatory

r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result

r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:

local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=

r:base64_decode(string) -- Decodes a Base64-encoded string:

local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'

r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):

local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339

r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):

local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19

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'

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'

r:construct_url(string) -- Constructs an URL from an URI

local url = r:construct_url(r.uri)

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

r:expr(string) -- Evaluates an expr string.

if r:expr("%{HTTP_HOST} =~ /^www/") then
    r:puts("This host name starts with www")
end

r:scoreboard_process(a) -- Queries the server for information about the process at position a:

local process = r:scoreboard_process(1)
r:puts("Server 1 has PID " .. process.pid)

r:scoreboard_worker(a, b) -- Queries for information about the worker thread, b, in process a:

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")

r:clock() -- Returns the current time with microsecond precision

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)

r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter

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

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

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.

r:server_info() -- Returns a table containing server information, such as 
                -- the name of the httpd executable file, mpm used etc.

r:set_document_root(file_path) -- Sets the document root for the request to file_path

r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request

r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way

r:escape_logitem(string) -- Escapes a string for logging

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

r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.

r:make_etag() -- Constructs and returns the etag for the current request.

r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
                       -- if 'clear' is true, available headers will be sent and cleared.

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!")

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

r:state_query(string) -- Queries the server for state information

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

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

r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.

r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
                        -- See 'Database connectivity' for details.

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

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).

r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode parameter.

r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode parameter.

r:rmdir(dir) -- Removes a directory.

r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.

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

r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.

r:getcookie(key) -- Gets a HTTP cookie

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
}

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

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)

r:wswrite(line) -- Writes a frame to a WebSocket client:
r:wswrite("Hello, world!")

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

Logging Functions

-- 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")

apache2 Package

名为apache2的软件包可(至少)包含以下内容。

• apache2.OK

  • 内部常量确定。如果处理程序处理了请求，则应返回此值。

• apache2.DECLINED

  • 内部常量 DECLINED。如果处理程序不打算处理请求，则应返回此值。

• apache2.DONE

  • 内部常量 DONE。

• apache2.version

  • Apache HTTP 服务器版本字符串

• apache2.HTTP_MOVED_TEMPORARILY

  • HTTP 状态码

• apache2.PROXYREQ_NONE，apache2.PROXYREQ_PROXY，apache2.PROXYREQ_REVERSE，apache2.PROXYREQ_RESPONSE

  • mod_proxy使用的内部常量

• apache2.AUTHZ_DENIED，apache2.AUTHZ_GRANTED，apache2.AUTHZ_NEUTRAL，apache2.AUTHZ_GENERAL_ERROR，apache2.AUTHZ_DENIED_NO_USER

  • mod_authz_core使用的内部常量

(其他 HTTP 状态代码尚未实现.)

使用 Lua 过滤器修改内容

通过LuaInputFilter或LuaOutputFilter实现的过滤器功能被设计为三级非阻塞函数，使用协程在存储桶沿着过滤器链向下发送时挂起和恢复该函数。该功能的核心结构是：

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

Database connectivity

Mod_lua 实现了一种简单的数据库功能，用于在最流行的数据库引擎(mySQL，PostgreSQL，FreeTDS，ODBC，SQLite，Oracle)以及 mod_dbd 上查询和运行命令。

下面的示例显示如何获取数据库句柄并从表中返回信息：

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
", 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

要使用mod_dbd，请指定mod_dbd作为数据库类型，或将该字段留空：

local database = r:dbacquire("mod_dbd")

数据库对象和包含的功能

dbacquire返回的数据库对象具有以下方法：

从数据库中正常选择和查询：

-- 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")

使用准备好的语句(推荐)：

-- 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

转义值，关闭数据库等：

-- 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()

处理结果集

db:select或通过db:prepare创建的 prepared 语句函数返回的结果集可用于同步或异步获取行，具体取决于指定的行号：
result(0)以同步方式获取所有行，并返回一个行表。
result(-1)异步获取集合中的下一个可用行。
result(N)异步获取行号N：

-- 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.

可以构造一个函数，该函数返回一个迭代函数，以异步或异步方式遍历所有行，具体取决于 async 参数：

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

关闭数据库连接

当不再需要数据库句柄时，应使用database:close()关闭它们。如果不手动关闭它们，它们最终将被垃圾回收并由 mod_lua 关闭，但是如果您将关闭保留为 mod_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

使用数据库时的注意事项

尽管可以免费使用标准的query和run函数，但是建议您尽可能使用准备好的语句，以优化性能(如果您的数据库句柄可以长期使用)并最大程度地降低 SQL 注入攻击的风险。 run和query仅在没有变量插入到语句(静态语句)中时使用。使用动态语句时，请使用db:prepare或db:prepared。

LuaAuthzProvider Directive

lua 函数注册为授权提供程序后，可以与Require指令一起使用：

LuaRoot "/usr/local/apache2/lua"
LuaAuthzProvider foo authz.lua authz_check_foo
<Location "/">
  Require foo johndoe
</Location>

require "apache2"
function authz_check_foo(r, who)
    if r.user ~= who then return apache2.AUTHZ_DENIED
    return apache2.AUTHZ_GRANTED
end

LuaCodeCache Directive

指定内存中代码缓存的行为。默认值为 stat，它在每次需要该文件时统计顶级脚本(不包含任何脚本)，如果修改后的时间表明该文件比已加载的文件新，则重新加载该脚本。其他值使它永久保留文件缓存(不统计和替换)或从不缓存文件。

通常，统计数据或永远对生产有利，而统计数据或永不对 Developing 有利。

Examples:

LuaCodeCache stat
LuaCodeCache forever
LuaCodeCache never

LuaHookAccessChecker Directive

将您的钩子添加到 access_checker 阶段。访问检查器钩子函数通常返回 OK，DECLINED 或 HTTP_FORBIDDEN。

LuaHookAuthChecker Directive

在处理请求的 auth_checker 阶段调用 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

LuaHookCheckUserID Directive

...

LuaHookFixups Directive

就像 LuaHookTranslateName 一样，但是在修正阶段执行

LuaHookInsertFilter Directive

尚未实现

LuaHookLog Directive

这个简单的日志钩子可让您在 httpd 进入请求的日志记录阶段时运行功能。使用它，您可以将数据追加到自己的日志中，可以在写入常规日志之前处理数据，或者阻止创建日志条目。为了防止发生通常的日志记录，只需在日志记录处理程序中返回apache2.DONE，否则返回apache2.OK告诉 httpd 正常记录。

Example:

LuaHookLog "/path/to/script.lua" logger

-- /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

LuaHookMapToStorage Directive

类似于LuaHookTranslateName，但在请求的 Map 到存储阶段执行。诸如 mod_cache 之类的模块在此阶段运行，这为此处的操作提供了一个有趣的示例：

LuaHookMapToStorage "/path/to/lua/script.lua" check_cache

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

LuaHookTranslateName Directive

在请求处理的翻译名称阶段添加一个钩子(位于 APR_HOOK_MIDDLE)。 hook 函数接收单个参数 request_rec，并应返回状态代码，该状态代码可以是 HTTP 错误代码，也可以返回 apache2 模块中定义的常量：apache2.OK，apache2.DECLINED 或 apache2.DONE。

对于那些新的钩子，基本上每个钩子都会被调用，直到其中一个返回 apache2.OK。如果您的钩子不想执行翻译，则应仅返回 apache2.DECLINED。如果请求应停止处理，则返回 apache2.DONE。

Example:

# httpd.conf
LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper

-- /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

LuaHookTypeChecker Directive

该指令为请求处理的 type_checker 阶段提供了一个钩子。在此阶段，为请求分配了 Content Type 和处理程序，因此可用于根据 Importing 来修改类型和处理程序：

LuaHookTypeChecker "/path/to/lua/script.lua" type_checker

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

LuaInherit Directive

默认情况下，如果在重叠的“目录”或“位置”配置节中使用 LuaHook *指令，则在“更具体”节中定义的脚本之后(在“更通用”节中定义的脚本之后运行)(LuaInherit parent-first)。您可以颠倒此 Sequences，或使父上下文根本不适用。

在以前的 2.3.x 版本中，默认设置实际上是忽略父配置节中的 LuaHook *指令。

LuaInputFilter Directive

提供一种添加 Lua 函数作为 Importing 过滤器的方法。与输出过滤器一样，Importing 过滤器充当协程，首先在发送缓冲区之前屈服，然后在需要将存储桶沿链向下传递时屈服，最后(可选)产生需要附加到 Importing 数据的任何内容。全局变量bucket在将存储桶传递到 Lua 脚本时保持存储桶：

LuaInputFilter myInputFilter "/www/filter.lua" input_filter
<Files "*.lua">
  SetInputFilter myInputFilter
</Files>

--[[
    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

如果认为不需要过滤器，Importing 过滤器支持拒绝/跳过过滤器：

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

有关更多信息，请参见“ 用 Lua 过滤器修改内容”。

LuaMapHandler Directive

该指令与 uri 模式匹配，以调用特定文件中的特定处理函数。它使用 PCRE 正则表达式来匹配 uri，并支持将匹配组内插到文件路径和函数名称中。小心编写正则表达式，以避免安全问题。

Examples:

LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"

这会将 uri(例如/ photos/show？id = 9)与文件/scripts/photos.lua 匹配，并在加载该文件后在 lua vm 上调用处理函数 handle_show。

LuaMapHandler "/bingo" "/scripts/wombat.lua"

这将调用“句柄”功能，如果未提供特定的功能名称，则为默认功能。

LuaOutputFilter Directive

提供一种添加 Lua 函数作为输出过滤器的方法。与 Importing 过滤器一样，输出过滤器充当协程，首先在发送缓冲区之前产生，然后在需要将存储桶沿链向下传递时产生，最后(可选)产生需要附加到 Importing 数据的任何内容。全局变量bucket在将存储桶传递到 Lua 脚本时保持存储桶：

LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter
<Files "*.lua">
  SetOutputFilter myOutputFilter
</Files>

--[[
    Example output filter that escapes all HTML entities in the output
]]--
function output_filter(r)
    coroutine.yield("(Handled by myOutputFilter)
\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

与 Importing 过滤器一样，输出过滤器支持拒绝/跳过被认为是不需要的过滤器：

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

有关更多信息，请参见“ 用 Lua 过滤器修改内容”。

LuaPackageCPath Directive

将路径添加到 lua 的共享库搜索路径。遵循与 lua 相同的约定。这只是在 lua vms 中修改了 package.cpath。

LuaPackagePath Directive

将路径添加到 lua 的模块搜索路径。遵循与 lua 相同的约定。这只是在 lua vms 中修改了 package.path。

Examples:

LuaPackagePath "/scripts/lib/?.lua"
LuaPackagePath "/scripts/lib/?/init.lua"

LuaQuickHandler Directive

该阶段在将请求 Map 到病毒宿主后立即运行，可用于在其他阶段启动之前执行一些请求处理，或用于服务请求而无需翻译，Map 到存储等。由于此阶段先于其他任何阶段运行，因此诸如<Location>或<Directory>之类的指令在此阶段无效，就像尚未正确解析 URI 一样。

LuaRoot Directive

指定将用于评估 mod_lua 中所有相对路径的基本路径。如果未指定，它们将相对于当前工作目录进行解析，这对于服务器而言可能并不总是很好。

LuaScope Directive

在此“目录”中，指定处理程序将使用的 Lua 解释器的生命周期范围。默认值为“一次”

• once:

  • 一次使用解释器，将其丢弃。

• request:

  • 使用解释器来处理基于此请求中相同文件的任何内容，该文件也属于请求范围。

• conn:

  • 与请求相同，但附加到 connection_rec

• thread:

  • 在处理请求的线程的生存期内使用解释器(仅适用于线程 MPM)。

• server:

  • 此服务器与其他服务器有所不同，因为服务器范围的寿命很长，并且多个线程将具有相同的 server_rec。为了适应这种情况，服务器范围的 Lua 状态存储在 apr 资源列表中。 min和max参数指定要保留在池中的 Lua 状态的最小和最大数目。

一般而言，thread和server范围的执行速度比其余范围快 2-3 倍，因为它们不必在每个请求上都产生新的 Lua 状态(尤其是在事件 MPM 时，因为即使 keepalive 请求也将使用新线程来执行)每个请求)。如果您对脚本重用状态不会感到满意，则应使用thread或server范围以实现最佳性能。 thread范围将提供最快的响应，而server范围将使用较少的内存，因为状态被合并，从而允许 f.x。 1000 个线程仅共享 100 个 Lua 状态，因此仅使用thread范围所需的内存的 10％。