├── README.md └── doc ├── access_by_lua.md ├── access_by_lua_file.md ├── body_filter_by_lua.md ├── body_filter_by_lua_file.md ├── bugs-and-patches.md ├── c-macro-configurations.md ├── changes.md ├── code-repository.md ├── content_by_lua.md ├── content_by_lua_file.md ├── copyright-and-license.md ├── core-constants.md ├── coroutinecreate.md ├── coroutineresume.md ├── coroutinerunning.md ├── coroutinestatus.md ├── coroutinewrap.md ├── coroutineyield.md ├── cosockets-not-available-everywhere.md ├── data-sharing-within-an-nginx-worker.md ├── description.md ├── directives.md ├── header_filter_by_lua.md ├── header_filter_by_lua_file.md ├── http-10-support.md ├── http-method-constants.md ├── http-status-constants.md ├── init_by_lua.md ├── init_by_lua_file.md ├── init_worker_by_lua.md ├── init_worker_by_lua_file.md ├── installation-on-ubuntu-1110.md ├── installation.md ├── introduction.md ├── locations-configured-by-subrequest-directives-of-other-modules.md ├── log_by_lua.md ├── log_by_lua_file.md ├── lua-code-cache.md ├── lua-coroutine-yieldingresuming.md ├── lua-use-default-type.md ├── lua-variable-scope.md ├── lua_check_client_abort.md ├── lua_http10_buffering.md ├── lua_max_pending_timers.md ├── lua_max_running_timers.md ├── lua_need_request_body.md ├── lua_package_cpath.md ├── lua_package_path.md ├── lua_regex_cache_max_entries.md ├── lua_regex_match_limit.md ├── lua_shared_dict.md ├── lua_socket_buffer_size.md ├── lua_socket_connect_timeout.md ├── lua_socket_keepalive_timeout.md ├── lua_socket_log_errors.md ├── lua_socket_pool_size.md ├── lua_socket_read_timeout.md ├── lua_socket_send_lowat.md ├── lua_socket_send_timeout.md ├── lua_ssl_ciphers.md ├── lua_ssl_crl.md ├── lua_ssl_protocols.md ├── lua_ssl_trusted_certificate.md ├── lua_ssl_verify_depth.md ├── lua_transform_underscores_in_response_headers.md ├── lualuajit-bytecode-support.md ├── missing-data-on-short-circuited-requests.md ├── mixing-with-ssi-not-supported.md ├── name.md ├── ndkset_vardirective.md ├── nginx-api-for-lua.md ├── nginx-compatibility.md ├── nginx-log-level-constants.md ├── ngxarg.md ├── ngxconfigdebug.md ├── ngxconfignginx_configure.md ├── ngxconfignginx_version.md ├── ngxconfigngx_lua_version.md ├── ngxconfigprefix.md ├── ngxcookie_time.md ├── ngxcrc32_long.md ├── ngxcrc32_short.md ├── ngxctx.md ├── ngxdecode_args.md ├── ngxdecode_base64.md ├── ngxencode_args.md ├── ngxencode_base64.md ├── ngxeof.md ├── ngxescape_uri.md ├── ngxexec.md ├── ngxexit.md ├── ngxflush.md ├── ngxget_phase.md ├── ngxheaderheader.md ├── ngxheaders_sent.md ├── ngxhmac_sha1.md ├── ngxhttp_time.md ├── ngxis_subrequest.md ├── ngxlocaltime.md ├── ngxlocationcapture.md ├── ngxlocationcapture_multi.md ├── ngxlog.md ├── ngxmd5.md ├── ngxmd5_bin.md ├── ngxnow.md ├── ngxon_abort.md ├── ngxparse_http_time.md ├── ngxprint.md ├── ngxquote_sql_str.md ├── ngxredirect.md ├── ngxrefind.md ├── ngxregmatch.md ├── ngxregsub.md ├── ngxrematch.md ├── ngxreqappend_body.md ├── ngxreqclear_header.md ├── ngxreqdiscard_body.md ├── ngxreqfinish_body.md ├── ngxreqget_body_data.md ├── ngxreqget_body_file.md ├── ngxreqget_headers.md ├── ngxreqget_method.md ├── ngxreqget_post_args.md ├── ngxreqget_uri_args.md ├── ngxreqhttp_version.md ├── ngxreqinit_body.md ├── ngxreqraw_header.md ├── ngxreqread_body.md ├── ngxreqset_body_data.md ├── ngxreqset_body_file.md ├── ngxreqset_header.md ├── ngxreqset_method.md ├── ngxreqset_uri.md ├── ngxreqset_uri_args.md ├── ngxreqsocket.md ├── ngxreqstart_time.md ├── ngxrespget_headers.md ├── ngxresub.md ├── ngxsay.md ├── ngxsend_headers.md ├── ngxsha1_bin.md ├── ngxshareddict.md ├── ngxshareddictadd.md ├── ngxshareddictdelete.md ├── ngxshareddictflush_all.md ├── ngxshareddictflush_expired.md ├── ngxshareddictget.md ├── ngxshareddictget_keys.md ├── ngxshareddictget_stale.md ├── ngxshareddictincr.md ├── ngxshareddictreplace.md ├── ngxshareddictsafe_add.md ├── ngxshareddictsafe_set.md ├── ngxshareddictset.md ├── ngxsleep.md ├── ngxsocketconnect.md ├── ngxsockettcp.md ├── ngxsocketudp.md ├── ngxstatus.md ├── ngxthreadkill.md ├── ngxthreadspawn.md ├── ngxthreadwait.md ├── ngxtime.md ├── ngxtimerat.md ├── ngxtoday.md ├── ngxunescape_uri.md ├── ngxupdate_time.md ├── ngxutctime.md ├── ngxvarvariable.md ├── ngxworkerexiting.md ├── ngxworkerpid.md ├── obsolete-sections.md ├── print.md ├── rewrite_by_lua.md ├── rewrite_by_lua_file.md ├── rewrite_by_lua_no_postpone.md ├── see-also.md ├── set_by_lua.md ├── set_by_lua_file.md ├── spdy-mode-not-fully-supported.md ├── special-escaping-sequences.md ├── special-pcre-sequences.md ├── statically-linking-pure-lua-modules.md ├── status.md ├── synopsis.md ├── system-environment-variable-support.md ├── tcp-socket-connect-operation-issues.md ├── tcpsockclose.md ├── tcpsockconnect.md ├── tcpsockgetreusedtimes.md ├── tcpsockreceive.md ├── tcpsockreceiveuntil.md ├── tcpsocksend.md ├── tcpsocksetkeepalive.md ├── tcpsocksetoption.md ├── tcpsocksettimeout.md ├── tcpsocksslhandshake.md ├── test-suite.md ├── todo.md ├── typical-uses.md ├── udpsockclose.md ├── udpsockreceive.md ├── udpsocksend.md ├── udpsocksetpeername.md └── udpsocksettimeout.md /doc/access_by_lua_file.md: -------------------------------------------------------------------------------- 1 | access_by_lua_file 2 | ------------------ 3 | 4 | **语法:** *access_by_lua_file <path-to-lua-script-file>* 5 | 6 | **环境:** *http, server, location, location if* 7 | 8 | **阶段:** *access tail* 9 | 10 | 除了通过文件``的内容指定 Lua 代码外，该指令与[access_by_lua](#access_by_lua)是等价的，该指令从`v0.5.0rc32`开始支持[Lua/LuaJIT bytecode](#lualuajit-bytecode-support)的执行。 11 | 12 | 在``中可以使用 Nginx 的内置变量用来提高灵活性，然而这带有一定的风险，通常并不推荐使用。 13 | 14 | 当给定了一个相对路径如`foo/bar.lua`，它将会被转换成绝对路径，前面增加的部分路径是 Nginx 服务启动时通过命令行选项`-p PATH`决定的`server prefix`。 15 | 16 | 当 Lua 代码缓存开启（默认），用户代码在第一次请求时完成加载（只有一次）并缓存，当 Lua 文件被修改时，每次都要对 Nginx 配置进行重新加载。Lua 代码缓存是可以暂时被禁用，通过开关[lua_code_cache](#lua_code_cache)在`nginx.conf`中设置为`off`，这样就可以避免反复重新加载 Nginx。 17 | 18 | 支持通过 Nginx 变量完成动态调度文件路径，就像 [content_by_lua_file](#content_by_lua_file) 一样。 19 | 20 | [返回目录](#directives) 21 | 22 | access_by_lua_file 23 | ------------------ 24 | 25 | **syntax:** *access_by_lua_file <path-to-lua-script-file>* 26 | 27 | **context:** *http, server, location, location if* 28 | 29 | **phase:** *access tail* 30 | 31 | Equivalent to [access_by_lua](#access_by_lua), except that the file specified by `` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. 32 | 33 | Nginx variables can be used in the `` string to provide flexibility. This however carries some risks and is not ordinarily recommended. 34 | 35 | When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. 36 | 37 | When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 38 | and the Nginx config must be reloaded each time the Lua source file is modified. 39 | The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid repeatedly reloading Nginx. 40 | 41 | Nginx variables are supported in the file path for dynamic dispatch just as in [content_by_lua_file](#content_by_lua_file). 42 | 43 | [Back to TOC](#directives) 44 | -------------------------------------------------------------------------------- /doc/body_filter_by_lua_file.md: -------------------------------------------------------------------------------- 1 | body_filter_by_lua_file 2 | ----------------------- 3 | 4 | **语法:** *body_filter_by_lua_file <path-to-lua-script-file>* 5 | 6 | **环境:** *http, server, location, location if* 7 | 8 | **阶段:** *output-body-filter* 9 | 10 | 除了通过文件``的内容指定 Lua 代码外，该指令与[body_filter_by_lua](#body_filter_by_lua)是等价的，该指令从`v0.5.0rc32`开始支持[Lua/LuaJIT bytecode](#lualuajit-bytecode-support)的执行。 11 | 12 | 当给定了一个相对路径如`foo/bar.lua`，它将会被转换成绝对路径，前面增加的部分路径是 Nginx 服务启动时通过命令行选项`-p PATH`决定的`server prefix`。 13 | 14 | 该指令是在`v0.5.0rc32`版本第一次引入。 15 | 16 | [返回目录](#directives) 17 | 18 | > English source: 19 | 20 | body_filter_by_lua_file 21 | ----------------------- 22 | 23 | **syntax:** *body_filter_by_lua_file <path-to-lua-script-file>* 24 | 25 | **context:** *http, server, location, location if* 26 | 27 | **phase:** *output-body-filter* 28 | 29 | Equivalent to [body_filter_by_lua](#body_filter_by_lua), except that the file specified by `` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. 30 | 31 | When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. 32 | 33 | This directive was first introduced in the `v0.5.0rc32` release. 34 | 35 | [Back to TOC](#directives) -------------------------------------------------------------------------------- /doc/bugs-and-patches.md: -------------------------------------------------------------------------------- 1 | Bugs和补丁 2 | ================ 3 | 4 | 提交bug报告、想法或补丁，可按照下面两个方式： 5 | 6 | 1. 创建一个ticket [GitHub Issue Tracker](https://github.com/openresty/lua-nginx-module/issues) 7 | 1. 或者发到这里 [OpenResty community](#community). 8 | 9 | [返回目录](#table-of-contents) 10 | 11 | > English source: 12 | 13 | Bugs and Patches 14 | ================ 15 | 16 | Please submit bug reports, wishlists, or patches by 17 | 18 | 1. creating a ticket on the [GitHub Issue Tracker](https://github.com/openresty/lua-nginx-module/issues), 19 | 1. or posting to the [OpenResty community](#community). 20 | 21 | [Back to TOC](#table-of-contents) 22 | -------------------------------------------------------------------------------- /doc/c-macro-configurations.md: -------------------------------------------------------------------------------- 1 | C 宏定义配置 2 | ---------------------- 3 | 通过OpenResty或者Nginx内核方式构建该模块，你可以定义下面的C宏定义作为可选项提供给C编译器： 4 | 5 | * `NGX_LUA_USE_ASSERT` 6 | 声明后，将在ngx_lua C代码中开启断言。推荐用在调试或者测试版本中。启用后，它会引入额外一些（小的）运行时开销。在`v0.9.10`版本中首次引入此选项。 7 | 8 | * `NGX_LUA_ABORT_AT_PANIC` 9 | 当Lua/LuaJIT虚拟机出现panic错误时，ngx_lua默认会让当前的工作进程优雅退出。通过指定这个宏定义，ngx_lua将立即终止当前的nginx工作进程（通常会生成一个core dump文件）。这个选项主要用来调试虚拟机的panic错误。在`v0.9.8`版本中首次引入此选项。 10 | * `NGX_LUA_NO_FFI_API` 11 | 去除Nginx中FFI-based Lua API需要的的纯C函数(例如 [lua-resty-core](https://github.com/openresty/lua-resty-core#readme) 所需要的)。开启这个宏可以让Nginx二进制代码更小。 12 | 13 | 在NGINX或者OpenResty启用一个或多个宏定义，只用传给`./configure`脚本几个额外的C编译选项。例如： 14 | 15 | ``` 16 | # ./configure --with-cc-opt="-DNGX_LUA_USE_ASSERT -DNGX_LUA_ABORT_AT_PANIC" 17 | ``` 18 | 19 | [返回目录](#table-of-contents) 20 | 21 | > English source: 22 | 23 | C Macro Configurations 24 | ---------------------- 25 | 26 | While building this module either via OpenResty or with the NGINX core, you can define the following C macros via the C compiler options: 27 | 28 | * `NGX_LUA_USE_ASSERT` 29 | When defined, will enable assertions in the ngx_lua C code base. Recommended for debugging or testing builds. It can introduce some (small) runtime overhead when enabled. This macro was first introduced in the `v0.9.10` release. 30 | * `NGX_LUA_ABORT_AT_PANIC` 31 | When the Lua/LuaJIT VM panics, ngx_lua will instruct the current nginx worker process to quit gracefully by default. By specifying this C macro, ngx_lua will abort the current nginx worker process (which usually result in a core dump file) immediately. This option is useful for debugging VM panics. This option was first introduced in the `v0.9.8` release. 32 | * `NGX_LUA_NO_FFI_API` 33 | Excludes pure C API functions for FFI-based Lua API for NGINX (as required by [lua-resty-core](https://github.com/openresty/lua-resty-core#readme), for example). Enabling this macro can make the resulting binary code size smaller. 34 | 35 | To enable one or more of these macros, just pass extra C compiler options to the `./configure` script of either NGINX or OpenResty. For instance, 36 | 37 | 38 | ./configure --with-cc-opt="-DNGX_LUA_USE_ASSERT -DNGX_LUA_ABORT_AT_PANIC" 39 | 40 | 41 | [Back to TOC](#table-of-contents) 42 | -------------------------------------------------------------------------------- /doc/changes.md: -------------------------------------------------------------------------------- 1 | 变更日志 2 | ======= 3 | 4 | 该模块每个发行版本的变更，都记录在ngx_openresty绑定的变更日志中： 5 | 6 | 7 | 8 | [返回目录](#table-of-contents) 9 | 10 | > English source: 11 | 12 | Changes 13 | ======= 14 | 15 | The changes of every release of this module can be obtained from the ngx_openresty bundle's change logs: 16 | 17 | 18 | 19 | [Back to TOC](#table-of-contents) 20 | -------------------------------------------------------------------------------- /doc/code-repository.md: -------------------------------------------------------------------------------- 1 | 代码仓库 2 | =============== 3 | 4 | 本项目代码放在github上 [openresty/lua-nginx-module](https://github.com/openresty/lua-nginx-module)。 5 | 6 | [返回目录](#table-of-contents) 7 | 8 | > English source: 9 | 10 | Code Repository 11 | =============== 12 | 13 | The code repository of this project is hosted on github at [openresty/lua-nginx-module](https://github.com/openresty/lua-nginx-module). 14 | 15 | [Back to TOC](#table-of-contents) 16 | -------------------------------------------------------------------------------- /doc/content_by_lua.md: -------------------------------------------------------------------------------- 1 | content_by_lua 2 | -------------- 3 | **语法：** *content_by_lua <lua-script-str>* 4 | 5 | **环境：** *location, location if* 6 | 7 | **阶段：** *content* 8 | 9 | 作为"内容处理程序"，为每一个请求执行``中指定的Lua代码。 10 | 11 | 这些 Lua 代码可以调用[全部 API](#nginx-api-for-lua)，并作为一个新的协程，在一个独立的全局环境中执行（就像一个沙盒）。 12 | 13 | 不要将本指令和其他内容处理程序指令放到同一个location中。 14 | 比如，本指令和[proxy_pass](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass)指令就不能在同一个location中使用。 15 | 16 | [返回目录](#directives) 17 | 18 | > English Source 19 | 20 | 21 | **syntax:** *content_by_lua <lua-script-str>* 22 | 23 | **context:** *location, location if* 24 | 25 | **phase:** *content* 26 | 27 | Acts as a "content handler" and executes Lua code string specified in `` for every request. 28 | The Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox). 29 | 30 | Do not use this directive and other content handler directives in the same location. For example, this directive and the [proxy_pass](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive should not be used in the same location. 31 | 32 | [Back to TOC](#directives) 33 | -------------------------------------------------------------------------------- /doc/content_by_lua_file.md: -------------------------------------------------------------------------------- 1 | content_by_lua_file 2 | ------------------- 3 | 4 | **语法:** *content_by_lua_file <path-to-lua-script-file>* 5 | 6 | **环境:** *location, location if* 7 | 8 | **阶段:** *content* 9 | 10 | 除了通过文件``的内容指定 Lua 代码外，该指令与[content_by_lua](#content_by_lua)是等价的，该指令从`v0.5.0rc32`开始支持[Lua/LuaJIT bytecode](#lualuajit-bytecode-support)的执行。 11 | 12 | 在``中可以使用 Nginx 的内置变量用来提高灵活性，然而这带有一定的风险，通常并不推荐使用。 13 | 14 | 当给定了一个相对路径如`foo/bar.lua`，它将会被转换成绝对路径，前面增加的部分路径是 Nginx 服务启动时通过命令行选项`-p PATH`决定的`server prefix`。 15 | 16 | 当 Lua 代码缓存开启（默认），用户代码在第一次请求时完成加载（只有一次）并缓存，当 Lua 文件被修改时，每次都要对 Nginx 配置进行重新加载。Lua 代码缓存是可以暂时被禁用，通过开关[lua_code_cache](#lua_code_cache)在`nginx.conf`中设置为`off`，这样就可以避免反复重新加载 Nginx。 17 | 18 | 支持通过 Nginx 变量完成动态调度文件路径，例如： 19 | 20 | ```nginx 21 | 22 | # 注意: nginx 变量必须要小心过滤，否则它将带来严重的安全风险！ 23 | location ~ ^/app/([-_a-zA-Z0-9/]+) { 24 | set $path $1; 25 | content_by_lua_file /path/to/lua/app/root/$path.lua; 26 | } 27 | ``` 28 | 29 | 一定要非常小心恶意用户的输入，并始终仔细验证或过滤掉用户提供的路径项。 30 | 31 | [返回目录](#directives) 32 | 33 | > English source: 34 | 35 | content_by_lua_file 36 | ------------------- 37 | 38 | **syntax:** *content_by_lua_file <path-to-lua-script-file>* 39 | 40 | **context:** *location, location if* 41 | 42 | **phase:** *content* 43 | 44 | Equivalent to [content_by_lua](#content_by_lua), except that the file specified by `` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. 45 | 46 | Nginx variables can be used in the `` string to provide flexibility. This however carries some risks and is not ordinarily recommended. 47 | 48 | When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. 49 | 50 | When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 51 | and the Nginx config must be reloaded each time the Lua source file is modified. 52 | The Lua code cache can be temporarily disabled during development by 53 | switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx. 54 | 55 | Nginx variables are supported in the file path for dynamic dispatch, for example: 56 | 57 | ```nginx 58 | 59 | # WARNING: contents in nginx var must be carefully filtered, 60 | # otherwise there'll be great security risk! 61 | location ~ ^/app/([-_a-zA-Z0-9/]+) { 62 | set $path $1; 63 | content_by_lua_file /path/to/lua/app/root/$path.lua; 64 | } 65 | ``` 66 | 67 | But be very careful about malicious user inputs and always carefully validate or filter out the user-supplied path components. 68 | 69 | [Back to TOC](#directives) 70 | -------------------------------------------------------------------------------- /doc/copyright-and-license.md: -------------------------------------------------------------------------------- 1 | 版权与许可 2 | ===================== 3 | 4 | 该模块是根据BSD许可证授权。 5 | 6 | Copyright (C) 2009-2015, by Xiaozhe Wang (chaoslawful) . 7 | 8 | Copyright (C) 2009-2015, by Yichun "agentzh" Zhang (章亦春) , CloudFlare Inc. 9 | 10 | 版权所有。 11 | 12 | 在源代码和二进制形式的二次发行和使用，无论修改与否，允许的前提是满足以下条件： 13 | 14 | * 二次发行源代码必须保留以上版权声明、条件列表和下面的免责声明。 15 | * 二次发行二进制形式必须复制上述版权声明、此条件列表和文档和或在分发提供的其他材料中的下列免责声明。 16 | 17 | ``` 18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 19 | ``` 20 | 21 | [返回目录](#table-of-contents) 22 | 23 | > English source: 24 | 25 | Copyright and License 26 | ===================== 27 | 28 | This module is licensed under the BSD license. 29 | 30 | Copyright (C) 2009-2015, by Xiaozhe Wang (chaoslawful) . 31 | 32 | Copyright (C) 2009-2015, by Yichun "agentzh" Zhang (章亦春) , CloudFlare Inc. 33 | 34 | All rights reserved. 35 | 36 | Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 37 | 38 | * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 39 | 40 | * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 41 | 42 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 43 | 44 | [Back to TOC](#table-of-contents) 45 | -------------------------------------------------------------------------------- /doc/core-constants.md: -------------------------------------------------------------------------------- 1 | 核心常量 2 | -------- 3 | **环境:** *init_by_lua*\**, set_by_lua*\**, rewrite_by_lua*\**, access_by_lua*\**, content_by_lua*\**, header_filter_by_lua*\**, body_filter_by_lua, *\**log_by_lua*\**, ngx.timer.*\* 4 | ```lua 5 | ngx.OK (0) 6 | ngx.ERROR (-1) 7 | ngx.AGAIN (-2) 8 | ngx.DONE (-4) 9 | ngx.DECLINED (-5) 10 | ``` 11 | 12 | 请注意，这些常量中只有三个可以被 [Nginx API for Lua](#nginx-api-for-lua) 使用 13 | (即 [ngx.exit](#ngxexit) 只接受 `NGX_OK`, `NGX_ERROR`, 和 `NGX_DECLINED` 作为输入)。 14 | 15 | ```lua 16 | 17 | ngx.null 18 | ``` 19 | 20 | `ngx.null` 常量是一个 `NULL` 的[轻量用户数据](http://www.lua.org/pil/28.5.html)，一般被用来表达 Lua table 等里面的 nil (空) 值，类似于 [lua-cjson](http://www.kyne.com.au/~mark/software/lua-cjson.php) 库中的 `cjson.null` 常量。在`v0.5.0rc5` 版本中首次引入这个常量。 21 | 22 | `ngx.DECLINED` 这个常量在`v0.5.0rc19`版本中首次引入。 23 | 24 | 25 | > English Source 26 | 27 | **context:** *init_by_lua*\**, set_by_lua*\**, rewrite_by_lua*\**, access_by_lua*\**, content_by_lua*\**, header_filter_by_lua*\**, body_filter_by_lua, *\**log_by_lua*\**, ngx.timer.*\* 28 | 29 | ```lua 30 | 31 | ngx.OK (0) 32 | ngx.ERROR (-1) 33 | ngx.AGAIN (-2) 34 | ngx.DONE (-4) 35 | ngx.DECLINED (-5) 36 | ``` 37 | 38 | Note that only three of these constants are utilized by the [Nginx API for Lua](#nginx-api-for-lua) (i.e., [ngx.exit](#ngxexit) accepts `NGX_OK`, `NGX_ERROR`, and `NGX_DECLINED` as input). 39 | 40 | ```lua 41 | 42 | ngx.null 43 | ``` 44 | 45 | The `ngx.null` constant is a `NULL` light userdata usually used to represent nil values in Lua tables etc and is similar to the [lua-cjson](http://www.kyne.com.au/~mark/software/lua-cjson.php) library's `cjson.null` constant. This constant was first introduced in the `v0.5.0rc5` release. 46 | 47 | The `ngx.DECLINED` constant was first introduced in the `v0.5.0rc19` release. 48 | 49 | [返回目录](#nginx-api-for-lua) 50 | -------------------------------------------------------------------------------- /doc/coroutinecreate.md: -------------------------------------------------------------------------------- 1 | coroutine.create 2 | ---------------- 3 | **语法:** *co = coroutine.create(f)* 4 | 5 | **环境:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 6 | 7 | 通过一个 Lua 函数创建一个用户的 Lua 协程，并返回一个协程对象。、 8 | 9 | 类似标准的 Lua [coroutine.create](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create) API，但它是在 ngx_lua 创建的 Lua 协程环境中运行。 10 | 11 | 该 API 在 [init_by_lua*](#init_by_lua) 的环境中可用，是从 `0.9.2` 开始的。 12 | 13 | 该 API 在`v0.6.0`版本首次引入。 14 | 15 | [返回目录](#nginx-api-for-lua) 16 | 17 | > English source: 18 | 19 | coroutine.create 20 | ---------------- 21 | **syntax:** *co = coroutine.create(f)* 22 | 23 | **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 24 | 25 | Creates a user Lua coroutines with a Lua function, and returns a coroutine object. 26 | 27 | Similar to the standard Lua [coroutine.create](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create) API, but works in the context of the Lua coroutines created by ngx_lua. 28 | 29 | This API was first usable in the context of [init_by_lua*](#init_by_lua) since the `0.9.2`. 30 | 31 | This API was first introduced in the `v0.6.0` release. 32 | 33 | [Back to TOC](#nginx-api-for-lua) 34 | -------------------------------------------------------------------------------- /doc/coroutineresume.md: -------------------------------------------------------------------------------- 1 | coroutine.resume 2 | ---------------- 3 | **语法:** *ok, ... = coroutine.resume(co, ...)* 4 | 5 | **环境:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 6 | 7 | 恢复以前挂起或刚创建的用户 Lua 协程对象的执行。 8 | Resume the executation of a user Lua coroutine object previously yielded or just created. 9 | 10 | 类似标准的 Lua [coroutine.resume](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume) API，但它是在 ngx_lua 创建的 Lua 协程环境中运行。 11 | 12 | 该 API 在 [init_by_lua*](#init_by_lua) 的环境中可用，是从 `0.9.2` 开始的。 13 | 14 | 该 API 在 `v0.6.0` 版本首次引入。 15 | 16 | [返回目录](#nginx-api-for-lua) 17 | 18 | > English source: 19 | 20 | coroutine.resume 21 | ---------------- 22 | **syntax:** *ok, ... = coroutine.resume(co, ...)* 23 | 24 | **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 25 | 26 | Resumes the executation of a user Lua coroutine object previously yielded or just created. 27 | 28 | Similar to the standard Lua [coroutine.resume](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume) API, but works in the context of the Lua coroutines created by ngx_lua. 29 | 30 | This API was first usable in the context of [init_by_lua*](#init_by_lua) since the `0.9.2`. 31 | 32 | This API was first introduced in the `v0.6.0` release. 33 | 34 | [Back to TOC](#nginx-api-for-lua) 35 | 36 | -------------------------------------------------------------------------------- /doc/coroutinerunning.md: -------------------------------------------------------------------------------- 1 | coroutine.running 2 | ----------------- 3 | **语法:** *co = coroutine.running()* 4 | 5 | **环境:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 6 | 7 | 与标准的 Lua [coroutine.running](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.running) API 相同。 8 | 9 | 该 API 在 [init_by_lua*](#init_by_lua) 的环境中可用，是从 `0.9.2` 开始的。 10 | 11 | 该 API 在 `v0.6.0` 版本首次引入。 12 | 13 | [返回目录](#nginx-api-for-lua) 14 | 15 | > English source: 16 | 17 | coroutine.running 18 | ----------------- 19 | **syntax:** *co = coroutine.running()* 20 | 21 | **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 22 | 23 | Identical to the standard Lua [coroutine.running](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.running) API. 24 | 25 | This API was first usable in the context of [init_by_lua*](#init_by_lua) since the `0.9.2`. 26 | 27 | This API was first enabled in the `v0.6.0` release. 28 | 29 | [Back to TOC](#nginx-api-for-lua) 30 | 31 | -------------------------------------------------------------------------------- /doc/coroutinestatus.md: -------------------------------------------------------------------------------- 1 | coroutine.status 2 | ---------------- 3 | **语法:** *status = coroutine.status(co)* 4 | 5 | **环境:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 6 | 7 | 与标准的 Lua [coroutine.status](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.status) API 相同。 8 | 9 | 该 API 在 [init_by_lua*](#init_by_lua) 的环境中可用，是从 `0.9.2` 开始的。 10 | 11 | 该 API 在 `v0.6.0` 版本首次引入。 12 | 13 | [返回目录](#nginx-api-for-lua) 14 | 15 | > English source: 16 | 17 | coroutine.status 18 | ---------------- 19 | **syntax:** *status = coroutine.status(co)* 20 | 21 | **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 22 | 23 | Identical to the standard Lua [coroutine.status](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.status) API. 24 | 25 | This API was first usable in the context of [init_by_lua*](#init_by_lua) since the `0.9.2`. 26 | 27 | This API was first enabled in the `v0.6.0` release. 28 | 29 | [Back to TOC](#nginx-api-for-lua) 30 | 31 | -------------------------------------------------------------------------------- /doc/coroutinewrap.md: -------------------------------------------------------------------------------- 1 | coroutine.wrap 2 | -------------- 3 | **语法:** *co = coroutine.wrap(f)* 4 | 5 | **环境:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 6 | 7 | 类似标准的 Lua [coroutine.wrap](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap) API，但它是在 ngx_lua 创建的 Lua 协程环境中运行。 8 | 9 | 该 API 在 [init_by_lua*](#init_by_lua) 的环境中可用，是从 `0.9.2` 开始的。 10 | 11 | 该 API 在 `v0.6.0` 版本首次引入。 12 | 13 | [返回目录](#nginx-api-for-lua) 14 | 15 | > English source: 16 | 17 | coroutine.wrap 18 | -------------- 19 | **syntax:** *co = coroutine.wrap(f)* 20 | 21 | **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 22 | 23 | Similar to the standard Lua [coroutine.wrap](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap) API, but works in the context of the Lua coroutines created by ngx_lua. 24 | 25 | This API was first usable in the context of [init_by_lua*](#init_by_lua) since the `0.9.2`. 26 | 27 | This API was first introduced in the `v0.6.0` release. 28 | 29 | [Back to TOC](#nginx-api-for-lua) 30 | -------------------------------------------------------------------------------- /doc/coroutineyield.md: -------------------------------------------------------------------------------- 1 | coroutine.yield 2 | --------------- 3 | **语法:** *... = coroutine.yield(...)* 4 | 5 | **环境:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 6 | 7 | 挂起当前用户 Lua 协程的执行。 8 | 9 | 类似标准的 Lua [coroutine.yield](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield) API，但它是在 ngx_lua 创建的 Lua 协程环境中运行。 10 | 11 | 该 API 在 [init_by_lua*](#init_by_lua) 的环境中可用，是从 `0.9.2` 开始的。 12 | 13 | 该 API 在 `v0.6.0` 版本首次引入。 14 | 15 | [返回目录](#nginx-api-for-lua) 16 | 17 | > English source: 18 | 19 | coroutine.yield 20 | --------------- 21 | **syntax:** *... = coroutine.yield(...)* 22 | 23 | **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*, header_filter_by_lua*, body_filter_by_lua** 24 | 25 | Yields the executation of the current user Lua coroutine. 26 | 27 | Similar to the standard Lua [coroutine.yield](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield) API, but works in the context of the Lua coroutines created by ngx_lua. 28 | 29 | This API was first usable in the context of [init_by_lua*](#init_by_lua) since the `0.9.2`. 30 | 31 | This API was first introduced in the `v0.6.0` release. 32 | 33 | [Back to TOC](#nginx-api-for-lua) 34 | -------------------------------------------------------------------------------- /doc/cosockets-not-available-everywhere.md: -------------------------------------------------------------------------------- 1 | Cosockets 不是在任何地方都可用 2 | ---------------------------------- 3 | 4 | 归咎于`nginx`内核的各种限制规则，cosocket API 在这些场景中是被禁的： 5 | [set_by_lua*](#set_by_lua)， [log_by_lua*](#log_by_lua)， [header_filter_by_lua*](#header_filter_by_lua)， 和 [body_filter_by_lua](#body_filter_by_lua)。 6 | 7 | cosocket在[init_by_lua*](#init_by_lua) 和 [init_worker_by_lua*](#init_worker_by_lua)小节中也是被禁的，但我们后面将会添加这些环境的支持，因为在nginx内核上是没有这个限制的（或者这个限制是可以被绕过的）。 8 | 9 | 这里有个绕路方法，前提是原始场景 *不* 需要等待cosocket结果。就是说，通过[ngx.timer.at](#ngxtimerat) API 创建一个零延迟的`timer`，在`timer`中完成cosocket的处理结果，用这种异步的方式进行协作。 10 | 11 | [返回目录](#table-of-contents) 12 | 13 | > English source: 14 | 15 | Cosockets Not Available Everywhere 16 | ---------------------------------- 17 | 18 | Due the internal limitations in the nginx core, the cosocket API are disabled in the following contexts: [set_by_lua*](#set_by_lua), [log_by_lua*](#log_by_lua), [header_filter_by_lua*](#header_filter_by_lua), and [body_filter_by_lua](#body_filter_by_lua). 19 | 20 | The cosockets are currently also disabled in the [init_by_lua*](#init_by_lua) and [init_worker_by_lua*](#init_worker_by_lua) directive contexts but we may add support for these contexts in the future because there is no limitation in the nginx core (or the limitation might be worked around). 21 | 22 | There exists a work-around, however, when the original context does *not* need to wait for the cosocket results. That is, creating a 0-delay timer via the [ngx.timer.at](#ngxtimerat) API and do the cosocket results in the timer handler, which runs asynchronously as to the original context creating the timer. 23 | 24 | [Back to TOC](#table-of-contents) 25 | -------------------------------------------------------------------------------- /doc/header_filter_by_lua.md: -------------------------------------------------------------------------------- 1 | 2 | header_filter_by_lua 3 | --------------- 4 | 5 | **语法：** *header_filter_by_lua <lua-script-str>* 6 | 7 | **环境：** *http, server, location, location if* 8 | 9 | **阶段：** *output-header-filter* 10 | 11 | 用``中指名的lua代码，来完成应答消息头部的过滤。 12 | 13 | 注意，下列的接口函数在这个执行阶段是被禁用的： 14 | 15 | - 输出类函数（例：ngx.say 和 ngx.send_headers） 16 | 17 | - 控制类函数（例：ngx.redirect 和 ngx.exec） 18 | 19 | - 子请求相关函数（例：ngx.location.capture和ngx.location.capture_multi） 20 | 21 | - cosocket 类函数（例：ngx.socket.tcp 和 ngx.req.socket） 22 | 23 | 这里有个使用 Lua 过滤完成覆盖应答头的例子（如果没有则添加）： 24 | 25 | ```nginx 26 | 27 | location / { 28 | proxy_pass http://mybackend; 29 | header_filter_by_lua 'ngx.header.Foo = "blah"'; 30 | } 31 | 32 | ``` 33 | 34 | 该指令在版本 `v0.2.1rc20` 中第一次引入。 35 | 36 | [返回目录](#directives) 37 | 38 | 39 | > English Source 40 | 41 | **syntax:** *header_filter_by_lua <lua-script-str>* 42 | 43 | **context:** *http, server, location, location if* 44 | 45 | **phase:** *output-header-filter* 46 | 47 | Uses Lua code specified in `` to define an output header filter. 48 | 49 | Note that the following API functions are currently disabled within this context: 50 | 51 | - Output API functions (e.g., ngx.say and ngx.send_headers) 52 | 53 | - Control API functions (e.g., ngx.redirect and ngx.exec) 54 | 55 | - Subrequest API functions (e.g., ngx.location.capture and ngx.location.capture_multi) 56 | 57 | - Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket). 58 | 59 | Here is an example of overriding a response header (or adding one if absent) in our Lua header filter: 60 | 61 | ```nginx 62 | 63 | location / { 64 | proxy_pass http://mybackend; 65 | header_filter_by_lua 'ngx.header.Foo = "blah"'; 66 | } 67 | 68 | ``` 69 | 70 | This directive was first introduced in the `v0.2.1rc20` release. 71 | 72 | [BACK TO TOC](#directives) 73 | -------------------------------------------------------------------------------- /doc/header_filter_by_lua_file.md: -------------------------------------------------------------------------------- 1 | header_filter_by_lua_file 2 | ------------------------- 3 | 4 | **语法:** *header_filter_by_lua_file <path-to-lua-script-file>* 5 | 6 | **环境:** *http, server, location, location if* 7 | 8 | **阶段:** *output-header-filter* 9 | 10 | 除了通过文件``的内容指定 Lua 代码外，该指令与[header_filter_by_lua](#header_filter_by_lua)是等价的，该指令从`v0.5.0rc32`开始支持[Lua/LuaJIT bytecode](#lualuajit-bytecode-support)的执行。 11 | 12 | 当给定了一个相对路径如`foo/bar.lua`，它将会被转换成绝对路径，前面增加的部分路径是 Nginx 服务启动时通过命令行选项`-p PATH`决定的`server prefix`。 13 | 14 | 该指令是在`v0.2.1rc20`版本第一次引入。 15 | 16 | [返回目录](#directives) 17 | 18 | > English source: 19 | 20 | header_filter_by_lua_file 21 | ------------------------- 22 | 23 | **syntax:** *header_filter_by_lua_file <path-to-lua-script-file>* 24 | 25 | **context:** *http, server, location, location if* 26 | 27 | **phase:** *output-header-filter* 28 | 29 | Equivalent to [header_filter_by_lua](#header_filter_by_lua), except that the file specified by `` contains the Lua code, or as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. 30 | 31 | When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. 32 | 33 | This directive was first introduced in the `v0.2.1rc20` release. 34 | 35 | [Back to TOC](#directives) -------------------------------------------------------------------------------- /doc/http-10-support.md: -------------------------------------------------------------------------------- 1 | HTTP 1.0 支持 2 | ============= 3 | 4 | HTTP 1.0 协议不支持分块输出，当响应体不为空时，需要在响应头中明确指定 `Content-Length`，以支持 HTTP 1.0 长连接。所以当把 [lua_http10_buffering](#lua_http10_buffering) 设置为 `on` 输出 HTTP 1.0 响应时，ngx_lua 将缓存 [ngx.say](#ngxsay) 和 [ngx.print](#ngxprint) 的所有输出，同时延迟发送响应头直到接收到所有输出内容。这时 ngx_lua 可以计算响应体的总长度，并为 HTTP 1.0 客户端创建一个正确的 `Content-Length` 响应头。如果在正在执行的 Lua 代码中设置 `Content-Length` 响应头，这种缓冲模式将被禁用，即使已经将 [lua_http10_buffering](#lua_http10_buffering) 指令设置为 `on`。 5 | 6 | 对于大型流式响应输出，禁用 [lua_http10_buffering](#lua_http10_buffering) 以最小化内存占用非常重要。 7 | 8 | 请注意，一些常见的 HTTP 性能测试工具，例如 `ab` 和 `http_load` 默认发送 HTTP 1.0 请求。要强制 `curl` 发送 HTTP 1.0 请求，使用 `-0` 选项。 9 | 10 | > Engslish Source 11 | 12 | The HTTP 1.0 protocol does not support chunked output and requires an explicit `Content-Length` header when the response body is not empty in order to support the HTTP 1.0 keep-alive. 13 | So when a HTTP 1.0 request is made and the [lua_http10_buffering](#lua_http10_buffering) directive is turned `on`, ngx_lua will buffer the 14 | output of [ngx.say](#ngxsay) and [ngx.print](#ngxprint) calls and also postpone sending response headers until all the response body output is received. 15 | At that time ngx_lua can calculate the total length of the body and construct a proper `Content-Length` header to return to the HTTP 1.0 client. 16 | If the `Content-Length` response header is set in the running Lua code, however, this buffering will be disabled even if the [lua_http10_buffering](#lua_http10_buffering) directive is turned `on`. 17 | 18 | For large streaming output responses, it is important to disable the [lua_http10_buffering](#lua_http10_buffering) directive to minimise memory usage. 19 | 20 | Note that common HTTP benchmark tools such as `ab` and `http_load` issue HTTP 1.0 requests by default. 21 | To force `curl` to send HTTP 1.0 requests, use the `-0` option. 22 | 23 | [返回目录](#table-of-contents) -------------------------------------------------------------------------------- /doc/http-method-constants.md: -------------------------------------------------------------------------------- 1 | HTTP 方法常量 2 | ------------- 3 | **环境:** *init_by_lua*\**, set_by_lua*\**, rewrite_by_lua*\**, access_by_lua*\**, content_by_lua*\**, header_filter_by_lua*\**, body_filter_by_lua, log_by_lua*\**, ngx.timer.*\* 4 | 5 | 6 | ngx.HTTP_GET 7 | ngx.HTTP_HEAD 8 | ngx.HTTP_PUT 9 | ngx.HTTP_POST 10 | ngx.HTTP_DELETE 11 | ngx.HTTP_OPTIONS (v0.5.0rc24 版本加入) 12 | ngx.HTTP_MKCOL (v0.8.2 版本加入) 13 | ngx.HTTP_COPY (v0.8.2 版本加入) 14 | ngx.HTTP_MOVE (v0.8.2 版本加入) 15 | ngx.HTTP_PROPFIND (v0.8.2 版本加入) 16 | ngx.HTTP_PROPPATCH (v0.8.2 版本加入) 17 | ngx.HTTP_LOCK (v0.8.2 版本加入) 18 | ngx.HTTP_UNLOCK (v0.8.2 版本加入) 19 | ngx.HTTP_PATCH (v0.8.2 版本加入) 20 | ngx.HTTP_TRACE (v0.8.2 版本加入) 21 | 22 | 23 | 这些常量一般被用在 [ngx.location.capture](#ngxlocationcapture) 和 [ngx.location.capture_multi](#ngxlocationcapture_multi) 方法中。 24 | 25 | 26 | > English Source 27 | 28 | **context:** *init_by_lua*\**, set_by_lua*\**, rewrite_by_lua*\**, access_by_lua*\**, content_by_lua*\**, header_filter_by_lua*\**, body_filter_by_lua, log_by_lua*\**, ngx.timer.*\* 29 | 30 | 31 | ngx.HTTP_GET 32 | ngx.HTTP_HEAD 33 | ngx.HTTP_PUT 34 | ngx.HTTP_POST 35 | ngx.HTTP_DELETE 36 | ngx.HTTP_OPTIONS (added in the v0.5.0rc24 release) 37 | ngx.HTTP_MKCOL (added in the v0.8.2 release) 38 | ngx.HTTP_COPY (added in the v0.8.2 release) 39 | ngx.HTTP_MOVE (added in the v0.8.2 release) 40 | ngx.HTTP_PROPFIND (added in the v0.8.2 release) 41 | ngx.HTTP_PROPPATCH (added in the v0.8.2 release) 42 | ngx.HTTP_LOCK (added in the v0.8.2 release) 43 | ngx.HTTP_UNLOCK (added in the v0.8.2 release) 44 | ngx.HTTP_PATCH (added in the v0.8.2 release) 45 | ngx.HTTP_TRACE (added in the v0.8.2 release) 46 | 47 | 48 | These constants are usually used in [ngx.location.capture](#ngxlocationcapture) and [ngx.location.capture_multi](#ngxlocationcapture_multi) method calls. 49 | 50 | [返回目录](#nginx-api-for-lua) -------------------------------------------------------------------------------- /doc/http-status-constants.md: -------------------------------------------------------------------------------- 1 | HTTP 状态常量 2 | ------------- 3 | **环境:** *init_by_lua*\**, set_by_lua*\**, rewrite_by_lua*\**, access_by_lua*\**, content_by_lua*\**, header_filter_by_lua*\**, body_filter_by_lua, log_by_lua*\**, ngx.timer.*\* 4 | 5 | ```nginx 6 | 7 | value = ngx.HTTP_OK (200) 8 | value = ngx.HTTP_CREATED (201) 9 | value = ngx.HTTP_SPECIAL_RESPONSE (300) 10 | value = ngx.HTTP_MOVED_PERMANENTLY (301) 11 | value = ngx.HTTP_MOVED_TEMPORARILY (302) 12 | value = ngx.HTTP_SEE_OTHER (303) 13 | value = ngx.HTTP_NOT_MODIFIED (304) 14 | value = ngx.HTTP_BAD_REQUEST (400) 15 | value = ngx.HTTP_UNAUTHORIZED (401) 16 | value = ngx.HTTP_FORBIDDEN (403) 17 | value = ngx.HTTP_NOT_FOUND (404) 18 | value = ngx.HTTP_NOT_ALLOWED (405) 19 | value = ngx.HTTP_GONE (410) 20 | value = ngx.HTTP_INTERNAL_SERVER_ERROR (500) 21 | value = ngx.HTTP_METHOD_NOT_IMPLEMENTED (501) 22 | value = ngx.HTTP_SERVICE_UNAVAILABLE (503) 23 | value = ngx.HTTP_GATEWAY_TIMEOUT (504) (v0.3.1rc38 版本加入) 24 | ``` 25 | 26 | > English Source 27 | 28 | **context:** *init_by_lua*\**, set_by_lua*\**, rewrite_by_lua*\**, access_by_lua*\**, content_by_lua*\**, header_filter_by_lua*\**, body_filter_by_lua, log_by_lua*\**, ngx.timer.*\* 29 | 30 | ```nginx 31 | 32 | value = ngx.HTTP_OK (200) 33 | value = ngx.HTTP_CREATED (201) 34 | value = ngx.HTTP_SPECIAL_RESPONSE (300) 35 | value = ngx.HTTP_MOVED_PERMANENTLY (301) 36 | value = ngx.HTTP_MOVED_TEMPORARILY (302) 37 | value = ngx.HTTP_SEE_OTHER (303) 38 | value = ngx.HTTP_NOT_MODIFIED (304) 39 | value = ngx.HTTP_BAD_REQUEST (400) 40 | value = ngx.HTTP_UNAUTHORIZED (401) 41 | value = ngx.HTTP_FORBIDDEN (403) 42 | value = ngx.HTTP_NOT_FOUND (404) 43 | value = ngx.HTTP_NOT_ALLOWED (405) 44 | value = ngx.HTTP_GONE (410) 45 | value = ngx.HTTP_INTERNAL_SERVER_ERROR (500) 46 | value = ngx.HTTP_METHOD_NOT_IMPLEMENTED (501) 47 | value = ngx.HTTP_SERVICE_UNAVAILABLE (503) 48 | value = ngx.HTTP_GATEWAY_TIMEOUT (504) (first added in the v0.3.1rc38 release) 49 | ``` 50 | 51 | [返回目录](#nginx-api-for-lua) -------------------------------------------------------------------------------- /doc/init_by_lua_file.md: -------------------------------------------------------------------------------- 1 | init_by_lua_file 2 | ---------------- 3 | 4 | **语法:** *init_by_lua_file <path-to-lua-script-file>* 5 | 6 | **环境:** *http* 7 | 8 | **阶段:** *loading-config* 9 | 10 | 与[init_by_lua](#init_by_lua)等价，通过``指定文件的Lua 代码 或 [Lua/LuaJIT 字节码](#lualuajit-bytecode-support)来执行。 11 | 12 | 当给定了一个相对路径如`foo/bar.lua`，它将会被转换成绝对路径，前面增加的部分路径是Nginx服务启动时通过命令行选项`-p PATH`决定的`server prefix`。 13 | 14 | 该指令在`v0.5.5`发行版第一次被引入。 15 | 16 | [返回目录](#directives) 17 | 18 | > English source: 19 | 20 | init_by_lua_file 21 | ---------------- 22 | 23 | **syntax:** *init_by_lua_file <path-to-lua-script-file>* 24 | 25 | **context:** *http* 26 | 27 | **phase:** *loading-config* 28 | 29 | Equivalent to [init_by_lua](#init_by_lua), except that the file specified by `` contains the Lua code or [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. 30 | 31 | When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. 32 | 33 | This directive was first introduced in the `v0.5.5` release. 34 | 35 | [Back to TOC](#directives) 36 | -------------------------------------------------------------------------------- /doc/init_worker_by_lua.md: -------------------------------------------------------------------------------- 1 | init_worker_by_lua 2 | ------------------ 3 | 4 | **语法:** *init_worker_by_lua <lua-script-str>* 5 | 6 | **环境:** *http* 7 | 8 | **阶段:** *starting-worker* 9 | 10 | 开启master进程模式，Nginx工作进程启动时执行指定的Lua代码。关闭master模式，将在[init_by_lua*](#init_by_lua)后直接运行。 11 | 12 | 这个指令经常被用来创建单进程的反复执行定时器（通过[ngx.timer.at](#ngxtimerat) Lua API创建），可以是后端服务健康检查，也可以是其他定时的日常工作。下面是个例子： 13 | 14 | ```nginx 15 | 16 | init_worker_by_lua ' 17 | local delay = 3 -- in seconds 18 | local new_timer = ngx.timer.at 19 | local log = ngx.log 20 | local ERR = ngx.ERR 21 | local check 22 | 23 | check = function(premature) 24 | if not premature then 25 | -- do the health check or other routine work 26 | local ok, err = new_timer(delay, check) 27 | if not ok then 28 | log(ERR, "failed to create timer: ", err) 29 | return 30 | end 31 | end 32 | end 33 | 34 | local ok, err = new_timer(delay, check) 35 | if not ok then 36 | log(ERR, "failed to create timer: ", err) 37 | return 38 | end 39 | '; 40 | ``` 41 | 42 | 这个指令是在`v0.9.5`发行版第一次引入。 43 | 44 | [返回目录](#directives) 45 | 46 | > English source: 47 | 48 | init_worker_by_lua 49 | ------------------ 50 | 51 | **syntax:** *init_worker_by_lua <lua-script-str>* 52 | 53 | **context:** *http* 54 | 55 | **phase:** *starting-worker* 56 | 57 | Runs the specified Lua code upon every Nginx worker process's startup when the master process is enabled. When the master process is disabled, this hook will just run after [init_by_lua*](#init_by_lua). 58 | 59 | This hook is often used to create per-worker reoccurring timers (via the [ngx.timer.at](#ngxtimerat) Lua API), either for backend healthcheck or other timed routine work. Below is an example, 60 | 61 | ```nginx 62 | 63 | init_worker_by_lua ' 64 | local delay = 3 -- in seconds 65 | local new_timer = ngx.timer.at 66 | local log = ngx.log 67 | local ERR = ngx.ERR 68 | local check 69 | 70 | check = function(premature) 71 | if not premature then 72 | -- do the health check or other routine work 73 | local ok, err = new_timer(delay, check) 74 | if not ok then 75 | log(ERR, "failed to create timer: ", err) 76 | return 77 | end 78 | end 79 | end 80 | 81 | local ok, err = new_timer(delay, check) 82 | if not ok then 83 | log(ERR, "failed to create timer: ", err) 84 | return 85 | end 86 | '; 87 | ``` 88 | 89 | This directive was first introduced in the `v0.9.5` release. 90 | 91 | [Back to TOC](#directives) 92 | 93 | -------------------------------------------------------------------------------- /doc/init_worker_by_lua_file.md: -------------------------------------------------------------------------------- 1 | init_worker_by_lua_file 2 | ----------------------- 3 | 4 | **语法:** *init_worker_by_lua_file <lua-file-path>* 5 | 6 | **环境:** *http* 7 | 8 | **阶段:** *starting-worker* 9 | 10 | 与[init_worker_by_lua](#init_worker_by_lua)等价，通过``指定的Lua 或 [Lua/LuaJIT 字节码](#lualuajit-bytecode-support)文件来执行。 11 | 12 | 该指令是在`v0.9.5`发行版第一次引入。 13 | 14 | [返回目录](#directives) 15 | 16 | > English source: 17 | 18 | init_worker_by_lua_file 19 | ----------------------- 20 | 21 | **syntax:** *init_worker_by_lua_file <lua-file-path>* 22 | 23 | **context:** *http* 24 | 25 | **phase:** *starting-worker* 26 | 27 | Similar to [init_worker_by_lua](#init_worker_by_lua), but accepts the file path to a Lua source file or Lua bytecode file. 28 | 29 | This directive was first introduced in the `v0.9.5` release. 30 | 31 | [Back to TOC](#directives) 32 | -------------------------------------------------------------------------------- /doc/installation-on-ubuntu-1110.md: -------------------------------------------------------------------------------- 1 | 在Ubuntu 11.10上安装 2 | ---------------------------- 3 | 4 | 注意：这里推荐使用LuaJIT 2.0 或 LuaJIT 2.1替换掉标准Lua 5.1解析器。 5 | 6 | 如果标准解析器是必须的，执行下面的命令完成在Ubuntu上的安装： 7 | 8 | ```bash 9 | 10 | apt-get install -y lua5.1 liblua5.1-0 liblua5.1-0-dev 11 | ``` 12 | 13 | 所有反馈都应该是正确的，除了一条小"纠结"： 14 | 15 | `liblua.so`库在liblua5.1包中已经发生改变，只能使用`liblua5.1.so`，并且需要被连接到`/usr/lib`，这样才可以在configure执行阶段被找到。 16 | 17 | ```bash 18 | 19 | ln -s /usr/lib/x86_64-linux-gnu/liblua5.1.so /usr/lib/liblua.so 20 | ``` 21 | 22 | [返回目录](#table-of-contents) 23 | 24 | > English source: 25 | 26 | Installation on Ubuntu 11.10 27 | ---------------------------- 28 | 29 | Note that it is recommended to use LuaJIT 2.0 or LuaJIT 2.1 instead of the standard Lua 5.1 interpreter wherever possible. 30 | 31 | If the standard Lua 5.1 interpreter is required however, run the following command to install it from the Ubuntu repository: 32 | 33 | ```bash 34 | 35 | apt-get install -y lua5.1 liblua5.1-0 liblua5.1-0-dev 36 | ``` 37 | 38 | Everything should be installed correctly, except for one small tweak. 39 | 40 | Library name `liblua.so` has been changed in liblua5.1 package, it only comes with `liblua5.1.so`, which needs to be symlinked to `/usr/lib` so it could be found during the configuration process. 41 | 42 | ```bash 43 | 44 | ln -s /usr/lib/x86_64-linux-gnu/liblua5.1.so /usr/lib/liblua.so 45 | ``` 46 | 47 | [Back to TOC](#table-of-contents) -------------------------------------------------------------------------------- /doc/introduction.md: -------------------------------------------------------------------------------- 1 | 介绍 2 | ---- 3 | 4 | `nginx.conf` 文件中各种 `*_by_lua` 和 `*_by_lua_file` 配置指令的作用是提供 Lua API 的网关。下面介绍的这些 Lua API 指令，只能在上述配置指令的环境中，通过用户 Lua 代码调用。 5 | 6 | Lua 中使用的 API 以两个标准模块的形式封装：`ngx` 和 `ndk`。这两个模块在 ngx_lua 默认的全局作用域中，在 ngx_lua 指令中总是可用。 7 | 8 | 这两个模块可以被用在外部 Lua 模块中，例如： 9 | 10 | ```lua 11 | 12 | local say = ngx.say 13 | 14 | local _M = {} 15 | 16 | function _M.foo(a) 17 | say(a) 18 | end 19 | 20 | return _M 21 | ``` 22 | 23 | 强烈不推荐使用 [package.seeall](http://www.lua.org/manual/5.1/manual.html#pdf-package.seeall) 标记，因为它有很多不好的副作用。 24 | 25 | 在外部 Lua 模块中也可以直接 require 这两个模块： 26 | 27 | ```lua 28 | 29 | local ngx = require "ngx" 30 | local ndk = require "ndk" 31 | ``` 32 | 33 | 自 `v0.2.1rc19` 版开始可以 requrie 这两个模块。 34 | 35 | 用户代码中的网络 I/O 操作应该使用这些 Nginx Lua API 实现，否则 Nginx 的事件循环可能被阻塞，从而严重影响性能。相对小数据量的磁盘操作可以通过标准的 Lua `io` 库来实现，但大规模的文件读写如果可能应该避免，因为可能会严重阻塞 Nginx 进程。为获得最好性能，强烈建议将所有网络和磁盘 I/O 操作发送到 Nginx 的子请求中 (通过类似 [ngx.location.capture](#ngxlocationcapture) 的方法) 处理。 36 | 37 | 38 | > Engslish Source 39 | 40 | The various `*_by_lua` and `*_by_lua_file` configuration directives serve as gateways to the Lua API within the `nginx.conf` file. The Nginx Lua API described below can only be called within the user Lua code run in the context of these configuration directives. 41 | 42 | The API is exposed to Lua in the form of two standard packages `ngx` and `ndk`. These packages are in the default global scope within ngx_lua and are always available within ngx_lua directives. 43 | 44 | The packages can be introduced into external Lua modules like this: 45 | 46 | ```lua 47 | 48 | local say = ngx.say 49 | 50 | local _M = {} 51 | 52 | function _M.foo(a) 53 | say(a) 54 | end 55 | 56 | return _M 57 | ``` 58 | 59 | Use of the [package.seeall](http://www.lua.org/manual/5.1/manual.html#pdf-package.seeall) flag is strongly discouraged due to its various bad side-effects. 60 | 61 | It is also possible to directly require the packages in external Lua modules: 62 | 63 | ```lua 64 | 65 | local ngx = require "ngx" 66 | local ndk = require "ndk" 67 | ``` 68 | 69 | The ability to require these packages was introduced in the `v0.2.1rc19` release. 70 | 71 | Network I/O operations in user code should only be done through the Nginx Lua API calls as the Nginx event loop may be blocked and performance drop off dramatically otherwise. Disk operations with relatively small amount of data can be done using the standard Lua `io` library but huge file reading and writing should be avoided wherever possible as they may block the Nginx process significantly. Delegating all network and disk I/O operations to Nginx's subrequests (via the [ngx.location.capture](#ngxlocationcapture) method and similar) is strongly recommended for maximum performance. 72 | 73 | [返回目录](#nginx-api-for-lua) -------------------------------------------------------------------------------- /doc/locations-configured-by-subrequest-directives-of-other-modules.md: -------------------------------------------------------------------------------- 1 | 某些指令无法用于子请求 Location 配置 2 | -------------------------------------------------------------- 3 | [ngx.location.capture](#ngxlocationcapture) 和 [ngx.location.capture_multi](#ngxlocationcapture_multi) 指令无法抓取包含以下指令的 location： [add_before_body](http://nginx.org/en/docs/http/ngx_http_addition_module.html#add_before_body), [add_after_body](http://nginx.org/en/docs/http/ngx_http_addition_module.html#add_after_body), [auth_request](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html#auth_request), [echo_location](http://github.com/openresty/echo-nginx-module#echo_location), [echo_location_async](http://github.com/openresty/echo-nginx-module#echo_location_async), [echo_subrequest](http://github.com/openresty/echo-nginx-module#echo_subrequest), 或 [echo_subrequest_async](http://github.com/openresty/echo-nginx-module#echo_subrequest_async) 。 4 | 5 | ```nginx 6 | 7 | location /foo { 8 | content_by_lua ' 9 | res = ngx.location.capture("/bar") 10 | '; 11 | } 12 | location /bar { 13 | echo_location /blah; 14 | } 15 | location /blah { 16 | echo "Success!"; 17 | } 18 | ``` 19 | 20 | ```nginx 21 | 22 | $ curl -i http://example.com/foo 23 | ``` 24 | 25 | 将不会如预期一样的工作。 26 | 27 | 28 | > English Source 29 | 30 | The [ngx.location.capture](#ngxlocationcapture) and [ngx.location.capture_multi](#ngxlocationcapture_multi) directives cannot capture locations that include the [add_before_body](http://nginx.org/en/docs/http/ngx_http_addition_module.html#add_before_body), [add_after_body](http://nginx.org/en/docs/http/ngx_http_addition_module.html#add_after_body), [auth_request](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html#auth_request), [echo_location](http://github.com/openresty/echo-nginx-module#echo_location), [echo_location_async](http://github.com/openresty/echo-nginx-module#echo_location_async), [echo_subrequest](http://github.com/openresty/echo-nginx-module#echo_subrequest), or [echo_subrequest_async](http://github.com/openresty/echo-nginx-module#echo_subrequest_async) directives. 31 | 32 | ```nginx 33 | 34 | location /foo { 35 | content_by_lua ' 36 | res = ngx.location.capture("/bar") 37 | '; 38 | } 39 | location /bar { 40 | echo_location /blah; 41 | } 42 | location /blah { 43 | echo "Success!"; 44 | } 45 | ``` 46 | 47 | ```nginx 48 | 49 | $ curl -i http://example.com/foo 50 | ``` 51 | 52 | will not work as expected. 53 | 54 | [返回目录](#nginx-api-for-lua) -------------------------------------------------------------------------------- /doc/log_by_lua_file.md: -------------------------------------------------------------------------------- 1 | log_by_lua_file 2 | --------------- 3 | 4 | **语法:** *log_by_lua_file <path-to-lua-script-file>* 5 | 6 | **环境:** *http, server, location, location if* 7 | 8 | **阶段:** *log* 9 | 10 | 除了通过文件``的内容指定 Lua 代码外，该指令与[log_by_lua](#log_by_lua)是等价的，该指令从`v0.5.0rc32`开始支持[Lua/LuaJIT bytecode](#lualuajit-bytecode-support)的执行。 11 | 12 | 当给定了一个相对路径如`foo/bar.lua`，它将会被转换成绝对路径，前面增加的部分路径是 Nginx 服务启动时通过命令行选项`-p PATH`决定的`server prefix`。 13 | 14 | 该指令是在`v0.5.0rc31`版本第一次引入。 15 | 16 | [Back to TOC](#directives) 17 | 18 | > English source: 19 | 20 | log_by_lua_file 21 | --------------- 22 | 23 | **syntax:** *log_by_lua_file <path-to-lua-script-file>* 24 | 25 | **context:** *http, server, location, location if* 26 | 27 | **phase:** *log* 28 | 29 | Equivalent to [log_by_lua](#log_by_lua), except that the file specified by `` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. 30 | 31 | When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. 32 | 33 | This directive was first introduced in the `v0.5.0rc31` release. 34 | 35 | [Back to TOC](#directives) 36 | -------------------------------------------------------------------------------- /doc/lua-code-cache.md: -------------------------------------------------------------------------------- 1 | lua_code_cache 2 | 语法: lua_code_cache on | off 3 | 4 | 默认: lua_code_cache on 5 | 6 | 环境: http, server, location, location if 7 | 8 | 可以在所有 *_by_lua_file 指令（类似 set_by_lua_file 和 content_by_lua_file）中打开或关闭 Lua 代码缓存和模块。 9 | 10 | 当它关闭时，每个请求都将会运行在一个单独的 Lua 虚拟机中，在 v0.9.3 release 版本中引入。所以在 set_by_lua_file, content_by_lua_file, access_by_lua_file 中引用 lua 文件时不会被缓存并且模块每次会重新加载。有了这个选项开发者很容易通过编辑文件并重新请求的方法进行测试。 11 | 12 | 13 | 然而需要注意的是，当你在编辑直接写在 nginx 配置中的 lua 代码时，它并不是像 set_by_lua,content_by_lua, access_by_lua, rewrite_by_lua 指令一样通过保存就能更新。 只有 nginx 的配置解释器才能正确解析 nginx 的配置文件，所以此时唯一的办法是向 nginx 发送重新加载配置文件的指令或者重启 nginx 进程的指令。 14 | 15 | ```shell 16 | kill -HUP pid 17 | nginx -s reload 18 | ``` 19 | 20 | 即使代码缓存指定打开时，在 *_by_lua_file 指令中使用 dofile 或 loadfile 函数时内容不会被缓存（除非你自己直接缓存结果）。通常你可以在 init_by_lua 或 init_by_lua_file 指令中加载这些文件或通过真正的 lua 模块去实现他们。 21 | 22 | 23 | 现在 ngx_lua 模块的还不支持 Apache mod_lua 的可用统计模块。 24 | 25 | 26 | 不推荐在生产环境中关闭 lua 代码缓存，请确保它只在开发环境中使用，他对整体性能有非常明显的影响。举个例子，输出“你好世界”在没有开启 lua 代码缓存时可以降低一个量级。 27 | 28 | 29 | > English source: 30 | lua_code_cache 31 | syntax: lua_code_cache on | off 32 | 33 | default: lua_code_cache on 34 | 35 | context: http, server, location, location if 36 | 37 | Enables or disables the Lua code cache for Lua code in *_by_lua_file directives (like set_by_lua_file and content_by_lua_file) and Lua modules. 38 | 39 | When turning off, every request served by ngx_lua will run in a separate Lua VM instance, starting from the 0.9.3 release. So the Lua files referenced in set_by_lua_file, content_by_lua_file, access_by_lua_file, and etc will not be cached and all Lua modules used will be loaded from scratch. With this in place, developers can adopt an edit-and-refresh approach. 40 | 41 | Please note however, that Lua code written inlined within nginx.conf such as those specified by set_by_lua, content_by_lua, access_by_lua, and rewrite_by_lua will not be updated when you edit the inlined Lua code in your nginx.conf file because only the Nginx config file parser can correctly parse the nginx.conf file and the only way is to reload the config file by sending a HUP signal or just to restart Nginx. 42 | 43 | Even when the code cache is enabled, Lua files which are loaded by dofile or loadfile in *_by_lua_file cannot be cached (unless you cache the results yourself). Usually you can either use the init_by_lua or init_by_lua_file directives to load all such files or just make these Lua files true Lua modules and load them via require. 44 | 45 | The ngx_lua module does not support the stat mode available with the Apache mod_lua module (yet). 46 | 47 | Disabling the Lua code cache is strongly discouraged for production use and should only be used during development as it has a significant negative impact on overall performance. For example, the performance a "hello world" Lua example can drop by an order of magnitude after disabling the Lua code cache. -------------------------------------------------------------------------------- /doc/lua-coroutine-yieldingresuming.md: -------------------------------------------------------------------------------- 1 | Lua 协程 Yielding/Resuming 2 | ------------------------------- 3 | 4 | 无论Lua 5.1 and LuaJIT 2.0/2.1，内建的 `dofile` 和 `require` 当前都是通过绑定 C 函数的方式，如果Lua文件的加载是`dofile` 或 `require` 并调用[ngx.location.capture*](#ngxlocationcapture), [ngx.exec](#ngxexec), [ngx.exit](#ngxexit), 或者Lua中其他 API 函数的 *top-level* 范围调用 yielding ，均会得到"attempt to yield across C-call boundary"的错误信息。为了避免这个情况，把需要调用yielding部分放到你自己的 Lua 函数中，这样在当前文件就不再是 *top-level* 范围。 5 | 6 | 7 | 对于标准 Lua 5.1 解析器的虚拟机唤醒支持是不完善的，[ngx.location.capture](#ngxlocationcapture), [ngx.location.capture_multi](#ngxlocationcapture_multi), [ngx.redirect](#ngxredirect), [ngx.exec](#ngxexec), 和 [ngx.exit](#ngxexit) 方法，在 Lua [pcall()](http://www.lua.org/manual/5.1/manual.html#pdf-pcall) 或 [xpcall()](http://www.lua.org/manual/5.1/manual.html#pdf-xpcall) 中是不能使用的。甚至`for ... in ...` 小节的第一行在标准Lua 5.1解析器中都会报错 `attempt to yield across metamethod/C-call boundary`。 请使用 LuaJIT 2.x，它可以完美支持虚拟机唤醒，避免这些问题。 8 | 9 | [Back to TOC](#table-of-contents) 10 | 11 | > English source: 12 | 13 | Lua Coroutine Yielding/Resuming 14 | ------------------------------- 15 | * Because Lua's `dofile` and `require` builtins are currently implemented as C functions in both Lua 5.1 and LuaJIT 2.0/2.1, if the Lua file being loaded by `dofile` or `require` invokes [ngx.location.capture*](#ngxlocationcapture), [ngx.exec](#ngxexec), [ngx.exit](#ngxexit), or other API functions requiring yielding in the *top-level* scope of the Lua file, then the Lua error "attempt to yield across C-call boundary" will be raised. To avoid this, put these calls requiring yielding into your own Lua functions in the Lua file instead of the top-level scope of the file. 16 | * As the standard Lua 5.1 interpreter's VM is not fully resumable, the methods [ngx.location.capture](#ngxlocationcapture), [ngx.location.capture_multi](#ngxlocationcapture_multi), [ngx.redirect](#ngxredirect), [ngx.exec](#ngxexec), and [ngx.exit](#ngxexit) cannot be used within the context of a Lua [pcall()](http://www.lua.org/manual/5.1/manual.html#pdf-pcall) or [xpcall()](http://www.lua.org/manual/5.1/manual.html#pdf-xpcall) or even the first line of the `for ... in ...` statement when the standard Lua 5.1 interpreter is used and the `attempt to yield across metamethod/C-call boundary` error will be produced. Please use LuaJIT 2.x, which supports a fully resumable VM, to avoid this. 17 | 18 | [Back to TOC](#table-of-contents) -------------------------------------------------------------------------------- /doc/lua-use-default-type.md: -------------------------------------------------------------------------------- 1 | lua_use_default_type 2 | 语法: lua_use_default_type on | off 3 | 4 | 默认: lua_use_default_type on 5 | 6 | 环境: http, server, location, location if 7 | 8 | 指定是否使用默认的媒体类型在内容响应头中。 9 | 如果在一个lua请求中不想要一个默认内容类型响应，请关闭这个指令。 10 | 11 | 默认情况下该指令被打开。 12 | 13 | 这个指令最早被引入于 v0.9.1 release 版本中。 14 | 15 | > English source: 16 | 17 | lua_use_default_type 18 | syntax: lua_use_default_type on | off 19 | 20 | default: lua_use_default_type on 21 | 22 | context: http, server, location, location if 23 | 24 | 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. 25 | 26 | This directive is turned on by default. 27 | 28 | This directive was first introduced in the v0.9.1 release. -------------------------------------------------------------------------------- /doc/lua_http10_buffering.md: -------------------------------------------------------------------------------- 1 | lua_http10_buffering 2 | -------------------- 3 | 4 | **语法:** *lua_http10_buffering on|off* 5 | 6 | **默认:** *lua_http10_buffering on* 7 | 8 | **环境:** *http, server, location, location-if* 9 | 10 | 对 HTTP 1.0（或更老）请求，启用或禁用自动应答缓冲区。这个缓冲机制主要用于应答头包含合适`Content-Length`长度的 HTTP 1.0 长连接。 11 | 12 | 如果 Lua 代码在发送应答头之前明确设置了应答头的`Content-Length`（调用 [ngx.send_headers](#ngxsend_headers) 或 隐式首次调用 [ngx.say](#ngxsay) 或 [ngx.print](#ngxprint) 其中任何一个），HTTP 1.0应答缓冲区都将被禁用，即使这个指令是打开的。 13 | 14 | 流式输出（例如，调用 [ngx.flush](#ngxflush)）非常大的应答体，为了占用内存最小，该指令必须设置为`off`。 15 | 16 | 该指令默认值是`on`。 17 | 18 | 该指令是在`v0.5.0rc19`版本首次引入的。 19 | 20 | [返回目录](#directives) 21 | 22 | > English source: 23 | 24 | lua_http10_buffering 25 | -------------------- 26 | 27 | **syntax:** *lua_http10_buffering on|off* 28 | 29 | **default:** *lua_http10_buffering on* 30 | 31 | **context:** *http, server, location, location-if* 32 | 33 | Enables or disables automatic response buffering for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper `Content-Length` response header. 34 | 35 | If the Lua code explicitly sets a `Content-Length` response header before sending the headers (either explicitly via [ngx.send_headers](#ngxsend_headers) or implicitly via the first [ngx.say](#ngxsay) or [ngx.print](#ngxprint) call), then the HTTP 1.0 response buffering will be disabled even when this directive is turned on. 36 | 37 | To output very large response data in a streaming fashion (via the [ngx.flush](#ngxflush) call, for example), this directive MUST be turned off to minimize memory usage. 38 | 39 | This directive is turned `on` by default. 40 | 41 | This directive was first introduced in the `v0.5.0rc19` release. 42 | 43 | [Back to TOC](#directives) 44 | -------------------------------------------------------------------------------- /doc/lua_max_pending_timers.md: -------------------------------------------------------------------------------- 1 | lua_max_pending_timers 2 | ---------------------- 3 | 4 | **语法:** *lua_max_pending_timers <count>* 5 | 6 | **默认:** *lua_max_pending_timers 1024* 7 | 8 | **环境:** *http* 9 | 10 | 控制允许使用的`pending timers`最大数量。 11 | 12 | `pending timers` 指的是还没有过期的 `timers` 。 13 | 14 | 当超过这个限制， [ngx.timer.at](#ngxtimerat) 调用将立即返回 `nil` 和 错误信息 “too many pending timers”。 15 | 16 | 该指令是在`v0.8.0`版本首次引入的。 17 | 18 | [返回目录](#directives) 19 | 20 | > English source: 21 | 22 | lua_max_pending_timers 23 | ---------------------- 24 | 25 | **syntax:** *lua_max_pending_timers <count>* 26 | 27 | **default:** *lua_max_pending_timers 1024* 28 | 29 | **context:** *http* 30 | 31 | Controls the maximum number of pending timers allowed. 32 | 33 | Pending timers are those timers that have not expired yet. 34 | 35 | When exceeding this limit, the [ngx.timer.at](#ngxtimerat) call will immediately return `nil` and the error string "too many pending timers". 36 | 37 | This directive was first introduced in the `v0.8.0` release. 38 | 39 | [Back to TOC](#directives) 40 | -------------------------------------------------------------------------------- /doc/lua_max_running_timers.md: -------------------------------------------------------------------------------- 1 | lua_max_running_timers 2 | ---------------------- 3 | 4 | **语法:** *lua_max_running_timers <count>* 5 | 6 | **默认:** *lua_max_running_timers 256* 7 | 8 | **环境:** *http* 9 | 10 | 控制允许的"running timers"最大数量。 11 | 12 | "running timers" 指的是那些正在执行用户回调函数的 timers 。 13 | 14 | 当超过这个限制，Nginx 将停止执行新近过期的 timers 回调，并记录一个错误日志 “N lua_max_running_timers are not enough”，这里的 "N" 是这个指令的当前值。 15 | 16 | 该指令是在`v0.8.0`版本首次引入的。 17 | 18 | [返回目录](#directives) 19 | 20 | > English source: 21 | 22 | lua_max_running_timers 23 | ---------------------- 24 | 25 | **syntax:** *lua_max_running_timers <count>* 26 | 27 | **default:** *lua_max_running_timers 256* 28 | 29 | **context:** *http* 30 | 31 | Controls the maximum number of "running timers" allowed. 32 | 33 | Running timers are those timers whose user callback functions are still running. 34 | 35 | When exceeding this limit, Nginx will stop running the callbacks of newly expired timers and log an error message "N lua_max_running_timers are not enough" where "N" is the current value of this directive. 36 | 37 | This directive was first introduced in the `v0.8.0` release. 38 | 39 | [Back to TOC](#directives) 40 | -------------------------------------------------------------------------------- /doc/lua_package_cpath.md: -------------------------------------------------------------------------------- 1 | lua_package_cpath 2 | ----------------- 3 | 4 | **语法:** *lua_package_cpath <lua-style-cpath-str>* 5 | 6 | **默认:** *The content of LUA_CPATH environment variable or Lua's compiled-in defaults.* 7 | 8 | **环境:** *http* 9 | 10 | 设置[set_by_lua](#set_by_lua)，[content_by_lua](#content_by_lua) 和 其他脚本对Lua C模块的查找路径。 cpath路径字符串是标准Luacpath路径格式，`;;` 可被用来代表原始cpath路径。 11 | 12 | 从`v0.5.0rc29`发行版开始，特殊符号`$prefix` 或 `${prefix}`可用于搜索路径字符串中。`server prefix`的值，通常是由Nginx服务启动时的`-p PATH`命令行决定的。 13 | 14 | [返回目录](#directives) 15 | 16 | > English source: 17 | 18 | lua_package_cpath 19 | ----------------- 20 | 21 | **syntax:** *lua_package_cpath <lua-style-cpath-str>* 22 | 23 | **default:** *The content of LUA_CPATH environment variable or Lua's compiled-in defaults.* 24 | 25 | **context:** *http* 26 | 27 | Sets the Lua C-module search path used by scripts specified by [set_by_lua](#set_by_lua), 28 | [content_by_lua](#content_by_lua) and others. The cpath string is in standard Lua cpath form, and `;;` 29 | can be used to stand for the original cpath. 30 | 31 | As from the `v0.5.0rc29` release, the special notation `$prefix` or `${prefix}` can be used in the search path string to indicate the path of the `server prefix` usually determined by the `-p PATH` command-line option while starting the Nginx server. 32 | 33 | [Back to TOC](#directives) 34 | 35 | 36 | -------------------------------------------------------------------------------- /doc/lua_package_path.md: -------------------------------------------------------------------------------- 1 | lua_package_path 2 | ---------------- 3 | 4 | **语法:** *lua_package_path <lua-style-path-str>* 5 | 6 | **默认:** *The content of LUA_PATH environ variable or Lua's compiled-in defaults.* 7 | 8 | **环境:** *http* 9 | 10 | 设置[set_by_lua](#set_by_lua)，[content_by_lua](#content_by_lua) 和 其他脚本对Lua模块的查找路径。 路径字符串是标准Lua路径格式，`;;` 可被用来代表原始搜索路径。 11 | 12 | 从`v0.5.0rc29`发行版开始，特殊符号`$prefix` 或 `${prefix}`可用于搜索路径字符串中。`server prefix`的值，通常是由Nginx服务启动时的`-p PATH`命令行决定的。 13 | 14 | [Back to TOC](#directives) 15 | 16 | > English source: 17 | 18 | lua_package_path 19 | ---------------- 20 | 21 | **syntax:** *lua_package_path <lua-style-path-str>* 22 | 23 | **default:** *The content of LUA_PATH environ variable or Lua's compiled-in defaults.* 24 | 25 | **context:** *http* 26 | 27 | Sets the Lua module search path used by scripts specified by [set_by_lua](#set_by_lua), 28 | [content_by_lua](#content_by_lua) and others. The path string is in standard Lua path form, and `;;` 29 | can be used to stand for the original search paths. 30 | 31 | As from the `v0.5.0rc29` release, the special notation `$prefix` or `${prefix}` can be used in the search path string to indicate the path of the `server prefix` usually determined by the `-p PATH` command-line option while starting the Nginx server. 32 | 33 | [Back to TOC](#directives) -------------------------------------------------------------------------------- /doc/lua_regex_cache_max_entries.md: -------------------------------------------------------------------------------- 1 | lua_regex_cache_max_entries 2 | --------------------------- 3 | **语法:** *lua_regex_cache_max_entries <num>* 4 | 5 | **默认:** *lua_regex_cache_max_entries 1024* 6 | 7 | **环境:** *http* 8 | 9 | 在工作进程级别，指定正则表达式编译缓存允许的最大数目。 10 | 11 | 正则表达式被用于[ngx.re.match](#ngxrematch)， [ngx.re.gmatch](#ngxregmatch)， [ngx.re.sub](#ngxresub)， 和 [ngx.re.gsub](#ngxregsub)，如果使用`o` (既，编译一次的标识)正则选项，将会被缓存。 12 | 13 | 允许的默认数量为1024，当达到此限制，新的正则表达式将不会被缓存（就像没指定`o`选项一样），将会有且仅只有一个告警信息在 `error.log` 文件中： 14 | 15 | 2011/08/27 23:18:26 [warn] 31997#0: *1 lua exceeding regex cache max entries (1024), ... 16 | 17 | 对于部分正则表达式（字符串的各种替换，如 [ngx.re.sub](#ngxresub) 和 [ngx.re.gsub](#ngxregsub)），不要使用`o`选项，这类正则每次都不一样，缓存无法被利用。这样我们可以避免撞上最大数的限制。 18 | 19 | [Back to TOC](#directives) 20 | 21 | > English source: 22 | 23 | lua_regex_cache_max_entries 24 | --------------------------- 25 | **syntax:** *lua_regex_cache_max_entries <num>* 26 | 27 | **default:** *lua_regex_cache_max_entries 1024* 28 | 29 | **context:** *http* 30 | 31 | Specifies the maximum number of entries allowed in the worker process level compiled regex cache. 32 | 33 | The regular expressions used in [ngx.re.match](#ngxrematch), [ngx.re.gmatch](#ngxregmatch), [ngx.re.sub](#ngxresub), and [ngx.re.gsub](#ngxregsub) will be cached within this cache if the regex option `o` (i.e., compile-once flag) is specified. 34 | 35 | The default number of entries allowed is 1024 and when this limit is reached, new regular expressions will not be cached (as if the `o` option was not specified) and there will be one, and only one, warning in the `error.log` file: 36 | 37 | 38 | 2011/08/27 23:18:26 [warn] 31997#0: *1 lua exceeding regex cache max entries (1024), ... 39 | 40 | 41 | Do not activate the `o` option for regular expressions (and/or `replace` string arguments for [ngx.re.sub](#ngxresub) and [ngx.re.gsub](#ngxregsub)) that are generated *on the fly* and give rise to infinite variations to avoid hitting the specified limit. 42 | 43 | [Back to TOC](#directives) -------------------------------------------------------------------------------- /doc/lua_regex_match_limit.md: -------------------------------------------------------------------------------- 1 | lua_regex_match_limit 2 | --------------------- 3 | **语法:** *lua_regex_match_limit <num>* 4 | 5 | **默认:** *lua_regex_match_limit 0* 6 | 7 | **环境:** *http* 8 | 9 | 指定执行[ngx.re API](#ngxrematch)时使用PCRE库的"匹配限制"。引述PCRE手册，“the limit ... has the effect of limiting the amount of backtracking that can take place.”。 10 | 11 | 当触发了这个限制，在Lua代码的[ngx.re API](#ngxrematch)函数，将返回错误信息"pcre_exec() failed: -8"。 12 | 13 | 当设置了限制为0，将使用编译PCRE库的默认"match limit"。这也是这个配置的默认值。 14 | 15 | 这个指令是在`v0.8.5`发行版被首次引入的。 16 | 17 | [Back to TOC](#directives) 18 | 19 | > English source: 20 | 21 | lua_regex_match_limit 22 | --------------------- 23 | **syntax:** *lua_regex_match_limit <num>* 24 | 25 | **default:** *lua_regex_match_limit 0* 26 | 27 | **context:** *http* 28 | 29 | Specifies the "match limit" used by the PCRE library when executing the [ngx.re API](#ngxrematch). To quote the PCRE manpage, "the limit ... has the effect of limiting the amount of backtracking that can take place." 30 | 31 | When the limit is hit, the error string "pcre_exec() failed: -8" will be returned by the [ngx.re API](#ngxrematch) functions on the Lua land. 32 | 33 | 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. 34 | 35 | This directive was first introduced in the `v0.8.5` release. 36 | 37 | [Back to TOC](#directives) 38 | 39 | -------------------------------------------------------------------------------- /doc/lua_shared_dict.md: -------------------------------------------------------------------------------- 1 | lua_shared_dict 2 | --------------- 3 | 4 | **语法:** *lua_shared_dict <name> <size>* 5 | 6 | **默认:** *no* 7 | 8 | **环境:** *http* 9 | 10 | **阶段:** *depends on usage* 11 | 12 | 声明一个共享内存区块 ``，用来存储基于共享内存的 Lua 字典 `ngx.shared.`。 13 | 14 | 在当前 Nginx 服务器实例中，共享内存区块被所有 nginx worker 进程共享。 15 | 16 | `` 参数可以通过类似 `k` 和 `m` 的大小单位来设置。 17 | 18 | ```nginx 19 | 20 | http { 21 | lua_shared_dict dogs 10m; 22 | ... 23 | } 24 | ``` 25 | 26 | 更多细节请参考 [ngx.shared.DICT](#ngxshareddict)。 27 | 28 | 这个指令最早出现在版本 `v0.3.1rc22` 中。 29 | 30 | 31 | > English Source 32 | 33 | **syntax:** *lua_shared_dict <name> <size>* 34 | 35 | **default:** *no* 36 | 37 | **context:** *http* 38 | 39 | **phase:** *depends on usage* 40 | 41 | Declares a shared memory zone, ``, to serve as storage for the shm based Lua dictionary `ngx.shared.`. 42 | 43 | Shared memory zones are always shared by all the nginx worker processes in the current nginx server instance. 44 | 45 | The `` argument accepts size units such as `k` and `m`: 46 | 47 | ```nginx 48 | 49 | http { 50 | lua_shared_dict dogs 10m; 51 | ... 52 | } 53 | ``` 54 | 55 | See [ngx.shared.DICT](#ngxshareddict) for details. 56 | 57 | This directive was first introduced in the `v0.3.1rc22` release. 58 | 59 | [返回目录](#directives) -------------------------------------------------------------------------------- /doc/lua_socket_buffer_size.md: -------------------------------------------------------------------------------- 1 | lua_socket_buffer_size 2 | ---------------------- 3 | 4 | **语法:** *lua_socket_buffer_size <size>* 5 | 6 | **默认:** *lua_socket_buffer_size 4k/8k* 7 | 8 | **环境:** *http, server, location* 9 | 10 | 指定使用 cosocket 进行读取操作时的缓冲区大小。 11 | Specifies the buffer size used by cosocket reading operations. 12 | 13 | 这个缓冲区不必为了同时解决所有事情而设置的太大，因为 cosocket 支持100%的非缓存读取和解析。所以即使是`1`字节的缓冲区大小依旧可以在任何地方正常工作，只不过效率比较糟糕。 14 | 15 | 该指令是在`v0.5.0rc1`版本首次引入。 16 | 17 | [返回目录](#directives) 18 | 19 | > English source: 20 | 21 | lua_socket_buffer_size 22 | ---------------------- 23 | 24 | **syntax:** *lua_socket_buffer_size <size>* 25 | 26 | **default:** *lua_socket_buffer_size 4k/8k* 27 | 28 | **context:** *http, server, location* 29 | 30 | Specifies the buffer size used by cosocket reading operations. 31 | 32 | This buffer does not have to be that big to hold everything at the same time because cosocket supports 100% non-buffered reading and parsing. So even `1` byte buffer size should still work everywhere but the performance could be terrible. 33 | 34 | This directive was first introduced in the `v0.5.0rc1` release. 35 | 36 | [Back to TOC](#directives) 37 | 38 | -------------------------------------------------------------------------------- /doc/lua_socket_connect_timeout.md: -------------------------------------------------------------------------------- 1 | lua_socket_connect_timeout 2 | -------------------------- 3 | 4 | **语法:** *lua_socket_connect_timeout <time>* 5 | 6 | **默认:** *lua_socket_connect_timeout 60s* 7 | 8 | **环境:** *http, server, location* 9 | 10 | 该指令控制 TCP/unix-domain socket 对象的[connect](#tcpsockconnect)方法默认超时时间，这个值可以被[settimeout](#tcpsocksettimeout)方法覆盖。 11 | 12 | `