配置

syntax = 语法   default = 默认值   context = 配置的地方
lua_use_default_type
syntax：lua_use_default_type on | off
default：on
context：http, server, location, location if
说明：
Specifies whether to use the MIME type specified by the default_type directive for the default value of the Content-Type response header. If you do not want a default Content-Type response header for your Lua request handlers, then turn this directive off.
指定MIME 的类型
扩展阅读：http://hi.baidu.com/tangzhonghai/item/0df26339f80b17f8de22219b


lua_code_cache
syntax：lua_code_cache on | off
default：on
context: http, server, location, location if
说明：
缓存 set_by_lua_file, content_by_lua_file, rewrite_by_lua_file, and access_by_lua_file, 的文件。
一般是开发的时候关闭， 线上开启，速度加快很多，如果没有关闭你修改代码得到的结果可能和你预期的不一样


lua_regex_cache_max_entries
syntax: lua_regex_cache_max_entries <num>
default: lua_regex_cache_max_entries 1024
context: http
说明：
指定正则编译的缓存的最大数量
会缓存 ngx.re.match, ngx.re.gmatch, ngx.re.sub, and ngx.re.gsub
默认缓存1024长度，如果超过的话就不会缓存



lua_regex_match_limit
syntax: lua_regex_match_limit <num>
default: lua_regex_match_limit 0
context: http
说明：
Specifies the "match limit" used by the PCRE library when executing the ngx.re API. To quote the PCRE manpage, "the limit ... has the effect of limiting the amount of backtracking that can take place."
When the limit is hit, the error string "pcre_exec() failed: -8" will be returned by the ngx.re API functions on the Lua land.
When setting the limit to 0, the default "match limit" when compiling the PCRE library is used. And this is the default value of this directive.
当执行 ngx.re API 时指定使用PCRE库的匹配限制。
如果达到匹配限制，ngx.re API会返回-8
设为0时，匹配限制就是PCRE库的限制



lua_package_path
syntax: lua_package_path <lua-style-path-str>
default: The content of LUA_PATH environ variable or Lua's compiled-in defaults.
context: http
设置lua模块搜索的路径。  就是包含了模块文件就可以直接 用require “模块名”



lua_package_cpath
syntax: lua_package_cpath <lua-style-cpath-str>
default: The content of LUA_CPATH environment variable or Lua's compiled-in defaults.
context: http
设置lua C 模块的搜索路径



init_by_lua
syntax: init_by_lua <lua-script-str>
context: http
phase: loading-config
说明：
Nginx主进程load lua配置的时候，就可以在lua虚拟机的层面执行
nginx接到 HUP 信号， 重新load配置文件的时候 lua 虚拟机会重建，init_by_lua会在新的虚拟机执行
通常你可以在lua环境变量或者在服务启动时预加载。例子：
 init_by_lua 'cjson = require "cjson"';

  server {
      location = /api {
          content_by_lua '
              ngx.say(cjson.encode({dog = 5, cat = 6}))
          ';
      }
  }

在这个阶段你也可以初始化 lua_shared_dict 的存储，例子：
    lua_shared_dict dogs 1m;
 
    init_by_lua '
        local dogs = ngx.shared.dogs;
        dogs:set("Tom", 56)
    ';
 
    server {
        location = /api {
            content_by_lua '
                local dogs = ngx.shared.dogs;
                ngx.say(dogs:get("Tom"))
            ';
        }
    }
但是使用lua_shared_dict 在配置被重新载入的时候是不会被清除的。
所以在这个例子里，如果你不想在你的 init_by_lua 代码里重新初始化shm存储，
你必须定义一个标示，然后在init_by_lua 代码里检查标示。
其他详细说明看文档。


init_by_lua_file
syntax: init_by_lua_file <path-to-lua-script-file>
context: http
phase: loading-config
说明： 和 init_by_lua 差不多，除了指定的文件<path-to-lua-script-file>包含lua代码或Lua的/ LuaJIT字节码的执行。
当给 foo/bar.lua 的时候， 会转为绝对路径。可以在服务器启动的时候使用-p 来相对




set_by_lua
syntax: set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]
context: server, server if, location, location if
phase: server-rewrite, rewrite
说明：
使用参数 执行 在<lua-script-str> 指定的代码，返回string 结果到$res
<lua-script-str> 的代码可以使用API 调用，然后使用 ngx.arg 接收结果，索引从1开始
这个指令是设计用来执行短、快的代码的，应该避免耗时的代码
不能在这里使用的API函数：
 Output API functions (e.g., ngx.say and ngx.send_headers)
 Control API functions (e.g., ngx.exit)
 Subrequest API functions (e.g., ngx.location.capture and ngx.location.capture_multi)
 Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).
此外，这个指令一次只能返回一个nginx变量值，替代的解决方法时  ngx.var.VARIABLE 。例子：
   location /foo {
        set $diff ''; # we have to predefine the $diff variable here
 
        set_by_lua $sum '
            local a = 32
            local b = 56
 
            ngx.var.diff = a - b;  -- write to $diff directly
            return a + b;          -- return the $sum value normally
        ';
 
        echo "sum = $sum, diff = $diff";
    }
    
你可以自由混用  HttpRewriteModule, HttpSetMiscModule, and HttpArrayVarModule   模块的所有指令 
    set $foo 32;
    set_by_lua $bar 'tonumber(ngx.var.foo) + 1';
    set $baz "bar: $bar";  # $baz == "bar: 33"
这个模块需要 ngx_devel_kit 模块





set_by_lua_file
syntax: set_by_lua_file $res <path-to-lua-script-file> [$arg1 $arg2 ...]
context: server, server if, location, location if
phase: server-rewrite, rewrite
说明：
和set_by_lua差不多,除了使用<path-to-lua-script-file> 包含的lua代码
 <path-to-lua-script-file> 支持nginx字符串变量参数，但要特别注意注入攻击
使用 -p  启动nginx服务器， 类似foo/bar.lua  这样的相对路径 会转为绝对路径
当lua代码缓存开启的时候，用户的代码只会在第一次请求的时候加载并缓存，当lua源代码修改的时候，nginx的配置文件每一次都必须重新加载
所以当你调试lua代码的时候最好把lua_code_cache 关掉
这个指令需要 ngx_devel_kit 模块



content_by_lua
syntax: content_by_lua <lua-script-str>
context: location, location if
phase: content
说明：
类似内容处理，每一次请求的时候都会执行<lua-script-str>的代码，
这个lua代码可以用 API调用，，执行的上时候每一次都会在全局环境下催生新的协程
不要在同一个location中和其他的内容处理一起使用这个指令。比如这个指令不能和 proxy_pass 指令在同一个location使用




content_by_lua_file
syntax: content_by_lua_file <path-to-lua-script-file>
context: location, location if
phase: content
说明：
和content_by_lua差不多,除了使用<path-to-lua-script-file> 包含的lua代码
nginx变量在 <path-to-lua-script-file> 中使用，让他能更灵活。但是这个带有一定的风险，一般不推荐使用





rewrite_by_lua
syntax: rewrite_by_lua <lua-script-str>
context: http, server, location, location if
phase: rewrite tail
做为每一次请求都重写阶段处理程序和在 <lua-script-str>执行lua代码，在lua代码中可以使用api调用，可以在独立的全局环境中催生新的协程
备注，这个通常是运行在 HttpRewriteModule模块之后，例子：
location /foo {
     set $a 12; # create and initialize $a
     set $b ""; # create and initialize $b
     rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';
     echo "res = $b";
 }
因为在rewrite_by_lua之前设置了$a和$b，所以正常运行

以下例子运行结果和预期的不一样：
 location /foo {
          set $a 12; # create and initialize $a
          set $b ''; # create and initialize $b
          rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';
          if ($b = '13') {
             rewrite ^ /bar redirect;
             break;
          }
    
          echo "res = $b";
      }
因为是在 rewrite_by_lua 之后。
正确的写法应该全写在 rewrite_by_lua里，例子：
set $a '12';
set $b '';
rewrite_by_lua '
    ngx.var.b = tonumber(ngx.var.a)+1
    if tonumber(ngx.var.b)==13 then
        return ngx.redirect("/bar")
    end
'; 
echo "res=$b";


ngx_eval 模块和rewrite_by_lua模块近似，例子：
 location / {
        eval $res {
            proxy_pass http://foo.com/check-spam;
        }
 
        if ($res = 'spam') {
            rewrite ^ /terms-of-use.html redirect;
        }
 
        fastcgi_pass ...;
    }
    
 用ngx_lua实现：
   location = /check-spam {
        internal;
        proxy_pass http://foo.com/check-spam;
    }
 
    location / {
        rewrite_by_lua '
            local res = ngx.location.capture("/check-spam")
            if res.body == "spam" then
                return ngx.redirect("/terms-of-use.html")
            end
        ';
 
        fastcgi_pass ...;
    }


就像其他重写处理程序， rewrite_by_lua 也运行子请求
备注，当在 rewrite_by_lua 内调用ngx.exit(ngx.OK)，nginx请求处理控制流程将会继续处理内容。
在rewrite_by_lua内终止请求，调用 ngx.exit 将会在成功的时候返回 status >= 200 (ngx.HTTP_OK) 到status < 300 (ngx.HTTP_SPECIAL_RESPONSE) 之间
失败的时候会ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR) (or its friends) 


如果HttpRewriteModule的rewrite指令用来修改URI和 在location重新查找， 在location里的任何 rewrite_by_lua 或 rewrite_by_lua_file都不会运行，例子：
location /foo {
        rewrite ^ /bar;
        rewrite_by_lua 'ngx.exit(503)';
}
location /bar {
  ...
}
在这里， ngx.exit(503) 将永远不会运行. 这是在 如果rewrite ^ /bar 是最后使用，进行内部重定向的情况下。
如果改用break这个就不会进行内部重定向，rewrite_by_lua的代码会执行
rewrite_by_lua通常是用在请求处理的最后重写，至少在 rewrite_by_lua_no_postpone 开启的时候是这样



rewrite_by_lua_file
syntax: rewrite_by_lua_file <path-to-lua-script-file>
context: http, server, location, location if
phase: rewrite tail
说明：
和rewrite_by_lua是一样的除了通过  <path-to-lua-script-file> 包含的lua代码
nginx 变量可以在 <path-to-lua-script-file>中使用提高灵活。
相对路径使用-p的时候自动转绝对路径
lua_code_cache开启有效（同上）
rewrite_by_lua_file通常是用在请求处理的最后重写，至少在 rewrite_by_lua_no_postpone 开启的时候是这样



access_by_lua
syntax: access_by_lua <lua-script-str>
context: http, server, location, location if
phase: access tail
说明：
做为每一次请求都重写阶段处理程序和在 <lua-script-str>执行lua代码，在lua代码中可以使用api调用，可以在独立的全局环境中催生新的协程
通常是在 HttpAccessModule模块后面运行的
 location / {
        deny    192.168.1.1;
        allow   192.168.1.0/24;
        allow   10.1.1.0/16;
        deny    all;
 
        access_by_lua '
            local res = ngx.location.capture("/mysql", { ... })
            ...
        ';
 
        # proxy_pass/fastcgi_pass/...
    }

如果客户端IP在黑名单，在执行sql查询前会被禁止，然后执行access_by
_lua 进行复杂的验证
 ngx_auth_request模块和access_by_lua类似。
 location / {
        auth_request /auth;
 
        # proxy_pass/fastcgi_pass/postgres_pass/...
    }

ngx_lua实现：
    location / {
        access_by_lua '
            local res = ngx.location.capture("/auth")
 
            if res.status == ngx.HTTP_OK then
                return
            end
 
            if res.status == ngx.HTTP_FORBIDDEN then
                ngx.exit(res.status)
            end
 
            ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
        ';
 
        # proxy_pass/fastcgi_pass/postgres_pass/...
    }
    
有其他处理程序的时候子请求access_by_lua不会执行    
备注，当在  access_by_lua  内调用ngx.exit(ngx.OK)，nginx请求处理控制流程将会继续处理内容。
在 access_by_lua 内终止请求，调用 ngx.exit 将会在成功的时候返回 status >= 200 (ngx.HTTP_OK) 到status < 300 (ngx.HTTP_SPECIAL_RESPONSE) 之间
失败的时候会ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR) (or its friends) 


access_by_lua_file
syntax: access_by_lua_file <path-to-lua-script-file>
context: http, server, location, location if
phase: access tail
说明：就不说明了和其他的一样



header_filter_by_lua
syntax: header_filter_by_lua <lua-script-str>
context: http, server, location, location if
phase: output-header-filter
说明：
在 <lua-script-str>中指定输出的头信息过滤器
可以使用api关闭这个选项：
Output API functions (e.g., ngx.say and ngx.send_headers)
Control API functions (e.g., ngx.exit and ngx.exec)
Subrequest API functions (e.g., ngx.location.capture and ngx.location.capture_multi)
Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).
这有个覆盖返回头信息的例子：
location / {
        proxy_pass http://mybackend;
        header_filter_by_lua 'ngx.header.Foo = "blah"';
    }




header_filter_by_lua_file
syntax: header_filter_by_lua_file <path-to-lua-script-file>
context: http, server, location, location if
phase: output-header-filter
说明：就不说明了和其他的一样



body_filter_by_lua
syntax: body_filter_by_lua <lua-script-str>
context: http, server, location, location if
phase: output-body-filter
说明：
在 <lua-script-str>中指定输出body信息过滤器
输入的数据通过ngx.arg[1]传递和用EOF标记响应正文的结尾。通过 ngx.arg[2] 传递
eof 只是标记last_buf 或者last_in_chain 标记 类似nginx的链条缓冲区.
输出数据可以使用 Lua语句立即终止：
return ngx.ERROR
这将会截断响应体，通常会产生残缺的和无效的响应。
lua代码可以通过用lua字符串或table重写ngx.arg[1]输入数据块的修改版本到nginx输出体过滤器，比如转换响应体的所有小写字母，我们可以这样写：
    location / {
        proxy_pass http://mybackend;
        body_filter_by_lua 'ngx.arg[1] = string.upper(ngx.arg[1])';
    }
    
当把 ngx.arg[1]设置成nil或者空，将不会有任何数据块通过过滤器
同样新的eof也能指定设置 ngx.arg[2] 的值，例子：
  location /t {
        echo hello world;
        echo hiya globe;
 
        body_filter_by_lua '
            local chunk = ngx.arg[1]
            if string.match(chunk, "hello") then
                ngx.arg[2] = true  -- new eof
                return
            end
 
            -- just throw away any remaining chunk data
            ngx.arg[1] = nil
        ';
    }
    
然后  GET 访问 /t会输出：
   hello world
这是因为过滤器看到块包含hello，然后它就会立即把eof设置成true，返回被阶段，但依旧是有效的响应体
当lua代码修改响应体的长度，然后必须强制输出流明确内容响应头长度，如：
location /foo {
    # fastcgi_pass/proxy_pass/...

    header_filter_by_lua 'ngx.header.content_length = nil';
    body_filter_by_lua 'ngx.arg[1] = string.len(ngx.arg[1]) .. "\\n"';
}
    
请注意下列api在这个环境下已经禁用：
Output API functions (e.g., ngx.say and ngx.send_headers)
Control API functions (e.g., ngx.exit and ngx.exec)
Subrequest API functions (e.g., ngx.location.capture and ngx.location.capture_multi)
Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).

Nginx输出过滤器也许会在一次请求中被调用多次，因为响应体可能会在块中传送。在单次的http生命周期中lua代码的这个指令也可能会被调用多次



body_filter_by_lua_file
syntax: body_filter_by_lua_file <path-to-lua-script-file>
context: http, server, location, location if
phase: output-body-filter
说明：和其他的大部分一样





log_by_lua
syntax: log_by_lua <lua-script-str>
context: http, server, location, location if
phase: log
内联 <lua-script-str> 运行lua源代码的日志。这个不会代替access 日志，但是会在之后运行
下面的API将被禁用：
Output API functions (e.g., ngx.say and ngx.send_headers)
Control API functions (e.g., ngx.exit)
Subrequest API functions (e.g., ngx.location.capture and ngx.location.capture_multi)
Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).
这有一个采集 $upstream_response_time 平均数据的例子：

 lua_shared_dict log_dict 5M;
 
    server {
        location / {
            proxy_pass http://mybackend;
 
            log_by_lua '
                local log_dict = ngx.shared.log_dict
                local upstream_time = tonumber(ngx.var.upstream_response_time)
 
                local sum = log_dict:get("upstream_time-sum") or 0
                sum = sum + upstream_time
                log_dict:set("upstream_time-sum", sum)
 
                local newval, err = log_dict:incr("upstream_time-nb", 1)
                if not newval and err == "not found" then
                    log_dict:add("upstream_time-nb", 0)
                    log_dict:incr("upstream_time-nb", 1)
                end
            ';
        }
 
        location = /status {
            content_by_lua '
                local log_dict = ngx.shared.log_dict
                local sum = log_dict:get("upstream_time-sum")
                local nb = log_dict:get("upstream_time-nb")
 
                if nb and sum then
                    ngx.say("average upstream response time: ", sum / nb,
                            " (", nb, " reqs)")
                else
                    ngx.say("no data yet")
                end
            ';
        }
    }


log_by_lua_file
syntax: log_by_lua_file <path-to-lua-script-file>
context: http, server, location, location if
phase: log
说明：和其他的大部分一样




lua_need_request_body
syntax: lua_need_request_body <on|off>
default: off
context: main | server | location
phase: depends on usage
说明：
确定是否在 rewrite/access/access_by_lua*  之前要强制读取请求数据。nginx核心默认是不读取客户端的请求体
如果需要请求体的数据，这个指令必须开启 或者在lua代码中必须调用ngx.req.read_body
读取请求体变量 $request_body ， client_body_buffer_size 必须和 client_max_body_size值一样。
因为当内容长度超过client_body_buffer_size 但是却低于 client_max_body_size,nginx将会把缓冲区的数据写入硬盘的临时文件，然后 $request_body 的值就会变成空的
如果location包含 rewrite_by_lua 或 rewrite_by_lua_file指令，只会读取 rewrite_by_lua 或 rewrite_by_lua_file 之前的请求体
同样的，如果只指定 content_by_lua，那么请求体在 lua代码处理程序之前是不会被调用的
这边推荐用 ngx.req.read_body 和ngx.req.discard_body控制请求体读取
这也适用于 access_by_lua 和 access_by_lua_file.




lua_shared_dict
syntax: lua_shared_dict <name> <size>
default: no
context: http
phase: depends on usage
说明：
定义一个共享内存，  ngx.shared.<name> 在服务端存储lua字典
<size>  的参数单位是m:
 http {
        lua_shared_dict dogs 10m;
        ...
    }

详情查看ngx.shared.DICT



lua_socket_connect_timeout
syntax: lua_socket_connect_timeout
default: lua_socket_connect_timeout 60s
context: http, server, location
这个指令控制默认的TCP/unix-domain里的socket对象连接过期时间，可以使用 settimeout 覆盖
<time>参数是一个整型，单位可以是s (秒), ms (毫秒), m (分钟)，默认的单位是秒，默认设置是60秒




lua_socket_send_timeout
syntax: lua_socket_send_timeout <time>
default: lua_socket_send_timeout 60s
context: http, server, location
这个指令控制默认的TCP/unix-domain里的socket对象发送的过期时间，可以使用 settimeout 覆盖
<time>参数是一个整型，单位可以是s (秒), ms (毫秒), m (分钟)，默认的单位是秒，默认设置是60秒




lua_socket_send_lowat
syntax: lua_socket_send_lowat <size>
default: lua_socket_send_lowat 0
context: http, server, location
控制cosocket发送的缓冲。



lua_socket_read_timeout
syntax: lua_socket_read_timeout <time>
default: lua_socket_read_timeout 60s
context: http, server, location
phase: depends on usage
这个指令控制默认的TCP/unix-domain里的socket对象接收和迭代返回单位接收的过期时间，可以使用 settimeout 覆盖
<time>参数是一个整型，单位可以是s (秒), ms (毫秒), m (分钟)，默认的单位是秒，默认设置是60秒



lua_socket_buffer_size
syntax: lua_socket_buffer_size <size>
default: lua_socket_buffer_size 4k/8k
context: http, server, location
说明：
指定cosocket读取操作的缓冲区大小
这个缓冲区不用每个都那么大，因为cosocket 100%支持非缓冲区的读和解析。所以即使是1个字节也可以正常工作，但是处处这样可能是可怕的




lua_socket_pool_size
syntax: lua_socket_pool_size <size>
default: lua_socket_pool_size 30
context: http, server, location
说明：
指定每一个远程服务器关联cosocket池的限制。
默认每个池 30连接
当连接池数超过设置的值，最早的连接会被关闭 来让当前的连接可以用。
注：cosocket连接池是每个nginx的工作进程而不是每个nginx的服务实例
所以在这边指定限制同时也适用每个单nginx工作进程




lua_socket_keepalive_timeout
syntax: lua_socket_keepalive_timeout <time>
default: lua_socket_keepalive_timeout 60s
context: http, server, location
说明：
这个指令控制cosocket 内建连接池的默认最大空闲时间。当时间过期空闲连接将会被关闭然后从连接池中删除。这个设置会被 setkeepalive覆盖
<time>参数是一个整型，单位可以是s (秒), ms (毫秒), m (分钟)，默认的单位是秒，默认设置是60秒




lua_socket_log_errors
syntax: lua_socket_log_errors on|off
default: lua_socket_log_errors on
context: http, server, location
说明：
这个指令可以在TCP 或 UDP cosockets遇到错误的时候转为错误日志。
如果你已经在你的代码里正确的处理和记录 错误，推荐把这个指令关闭，来让你的日志文件刷新




lua_http10_buffering
syntax: lua_http10_buffering on|off
default: lua_http10_buffering on
context: http, server, location, location-if
测试测试