Apache 模組 mod_lua

基本設定

基本的模組載入指令為

LoadModule lua_module modules/mod_lua.so

mod_lua 提供一個名為 lua-script 的處理常式，可用於 SetHandler 或 AddHandler 指令

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

這將導致 mod_lua 處理以 .lua 結尾的檔案請求，並呼叫該檔案的 handle 函數。

如需更多彈性，請參閱 LuaMapHandler。

撰寫處理常式

在 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 會呼叫指定名稱的授權提供者，並將行的其餘部分作為參數傳遞。然後提供者會檢查授權，並將結果傳遞為回傳值。

認證提供程序通常在認證之前被呼叫。如果認證提供程序需要知道經過驗證的使用者名稱（或使用者是否已通過驗證），則提供程序必須傳回 apache2.AUTHZ_DENIED_NO_USER。這將導致認證繼續進行，並第二次呼叫認證提供程序。

下列認證提供程序函式會接收兩個參數，一個 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>

撰寫掛勾

掛勾函式是模組（和 Lua 腳本）參與處理請求的方式。伺服器公開的每種類型的掛勾都有特定的目的，例如將請求對應到檔案系統、執行存取控制或設定 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

資料結構

request_rec

request_rec 被指定為使用者資料。它有一個元資料表，讓你能夠以有用的方式來使用它。它大部分都和 request_rec 結構擁有相同的欄位，其中許多欄位都可以寫入也能夠讀取。(表格欄位的內容可以變更，但欄位本身不能設定為不同的表格。)

名稱	Lua 類型	可寫入	說明
allowoverrides	字串	否	套用於當前請求的 AllowOverride 選項。
ap_auth_type	字串	否	如果進行身份驗證檢查，這裡會設定為身分驗證類型 (例如 basic)
args	字串	是	從請求中萃取的查詢字串參數 (例如 foo=bar&name=johnsmith)
assbackwards	布林	否	如果是 HTTP/0.9 風格的請求，則設定為 true (例如 GET /foo (沒有標頭) )
auth_name	字串	否	用於授權的領域名稱 (如果適用)。
banner	字串	否	伺服器標語，例如 Apache HTTP Server/2.4.3 openssl/0.9.8c
basic_auth_pw	字串	否	隨這個請求一起傳送的基本授權密碼 (如果有)
canonical_filename	字串	否	這個請求的標準檔名
content_encoding	字串	否	當前請求的內容編碼
content_type	字串	是	當前請求的內容類型，在 type_check 階段確定 (例如 image/gif 或 text/html)
context_prefix	字串	否
context_document_root	字串	否
document_root	字串	否	主機的存放區根目錄
err_headers_out	表格	否	回應的 MIME 標頭環境，會列印出來，即使在發生錯誤和跨內部重新導向時也會列印。可用的只讀 lua 表格適合進行重複操作，可以用做為 r:err_headers_out_table()。
filename	字串	是	請求對應到的檔案名稱，例如 /www/example.com/foo.txt。這可以在請求的 pre-translate-name、translate-name 或 map-to-storage 階段進行變更，以允許預設的處理常式 (或指令碼處理常式) 提供和請求不同的檔案。
handler	字串	是	這項處理程式的名稱應服務這項要求。例如，如果要由 mod_lua 服務，則為 lua-script。這通常是由 AddHandler 或 SetHandler 指令設定，但也可以透過 mod_lua 設定，以允許另一個處理程式服務特定的要求，否則不會由其服務。
headers_in	表格	是	來自要求的 MIME 標頭環境。這包含標頭，例如 Host、User-Agent、Referer 等，並以適用於反覆運算的唯讀 Lua 表格 r:headers_in_table() 提供。
headers_out	表格	是	回應的 MIME 標頭環境。以適用於反覆運算的唯讀 Lua 表格 r:headers_out_table() 提供。
hostname	字串	否	主機名稱，由 Host: 標頭或完整 URI 設定。
is_https	布林	否	此要求是否透過 HTTPS 執行
is_initial_req	布林	否	此要求是初始要求還是次級要求
limit_req_body	數字	否	此要求的要求主體大小限制，如果沒有限制，則為 0
log_id	字串	否	識別存取和錯誤記錄中要求的 ID
method	字串	否	要求方法，例如 GET 或 POST。
notes	表格	是	可以從一個模組傳遞到另一個模組的筆記清單。以適用於反覆運算的唯讀 Lua 表格 r:notes_table() 提供。
options	字串	否	套用於目前要求的 Options 指令。
path_info	字串	否	從此要求中擷取的 PATH_INFO
port	數字	否	要求使用的伺服器埠
protocol	字串	否	使用的通訊協定，例如 HTTP/1.1
proxyreq	字串	是	表示這是代理程式要求還是不是。此值通常在要求的 post_read_request/pre_translate_name/translate_name 階段設定。
range	字串	否	Range: 標頭的內容。
remaining	數字	否	要求主體中仍有剩餘的位元組數。
server_built	字串	否	伺服器執行檔建立的時間
server_name	字串	否	此要求的伺服器名稱
some_auth_required	布林	否	此要求是否需要/曾經需要一些授權
subprocess_env	表格	是	為此要求設定的環境變數。以適用於反覆運算的唯讀 Lua 表格 r:subprocess_env_table() 提供。
started	數字	否	自時間基準（1970 年 1 月 1 日）以來的秒數，伺服器（重新）啟動的時間
status	數字	是	此要求的（目前）HTTP 回傳碼，例如 200 或 404。
the_request	字串	否	客戶端傳送的要求字串，例如 GET /foo/bar HTTP/1.1。
unparsed_uri	字串	否	要求的未剖析 URI
uri	字串	是	由 httpd 剖析後的 URI
user	字串	是	如果已經進行驗證檢查，它會設定為驗證過的使用者名稱。
useragent_ip	字串	否	提出要求之使用者代理人的 IP

內建函式

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

記錄函式

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

名為 apache2 的套件提供（至少）下列內容。

apache2.OK

內部常數「確定」。如果處理程式處理了要求，應傳回此常數。

apache2.DECLINED

內部常數「拒絕」。如果處理程式不會處理要求，應傳回此常數。

apache2.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使用的內部常數。