ngx_stream_lua_module - Embed the power of Lua into Nginx stream/TCP Servers.
This module is not distributed with the Nginx source. See the installation instructions.
- Name
- Status
- Synopsis
- Description
- TODO
- Nginx Compatibility
- Installation
- Community
- Code Repository
- Bugs and Patches
- Copyright and License
- See Also
Experimental.
events {
worker_connections 1024;
}
stream {
# define a TCP server listening on the port 1234:
server {
listen 1234;
content_by_lua_block {
ngx.say("Hello, Lua!")
}
}
}
Set up as an SSL TCP server:
stream {
server {
listen 4343 ssl;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
content_by_lua_block {
local sock = assert(ngx.req.socket(true))
local data = sock:receive() -- read a line from downstream
if data == "thunder!" then
ngx.say("flash!") -- output data
else
ngx.say("boom!")
end
ngx.say("the end...")
}
}
}
Listening on a UNIX domain socket is also supported:
stream {
server {
listen unix:/tmp/nginx.sock;
content_by_lua_block {
ngx.say("What's up?")
ngx.flush(true) -- flush any pending output and wait
ngx.sleep(3) -- sleeping for 3 sec
ngx.say("Bye bye...")
}
}
}
This is a port of the ngx_http_lua_module to the NGINX "stream" subsystem so as to support generic stream/TCP clients in the downstream.
Lua APIs and directive names rename the same as the ngx_http_lua_module
.
The following directives are ported directly from ngx_http_lua_module
. Please check the
documentation of ngx_http_lua_module
for more details about their usage and behavior.
- lua_code_cache
- lua_regex_cache_max_entries
- lua_package_path
- lua_package_cpath
- init_by_lua_block
- init_by_lua_file
- init_worker_by_lua_block
- init_worker_by_lua_file
- content_by_lua_block
- content_by_lua_file
- lua_shared_dict
- lua_socket_connect_timeout
- lua_socket_buffer_size
- lua_socket_pool_size
- lua_socket_keepalive_timeout
- lua_socket_log_errors
- lua_ssl_ciphers
- lua_ssl_crl
- lua_ssl_protocols
- lua_ssl_trusted_certificate
- lua_ssl_verify_depth
- lua_check_client_abort
- lua_max_pending_timers
- lua_max_running_timers
In addition, ngx_stream_lua_module
provides the following directives:
-
lua_resolver
Just an equivalent to the resolver directive in the NGINX "http" subsystem.
-
lua_resolver_timeout
Just an equivalent to the resolver_timeout directive in the NGINX "http" subsystem.
-
lua_lingering_close
Just an equivalent to the [lingering_close](http://nginx.org/r/lingering_close] directive in the NGINX "http" subsystem.
-
lua_lingering_time
Just an equivalent to the [lingering_time](http://nginx.org/r/lingering_time] directive in the NGINX "http" subsystem.
-
lua_lingering_timeout
Just an equivalent to the [lingering_timeout](http://nginx.org/r/lingering_timeout] directive in the NGINX "http" subsystem.
The send_timeout directive in the NGINX "http" subsystem is missing in the "stream" subsystem.
So ngx_stream_lua_module
uses the lua_socket_send_timeout
for this purpose.
Many Lua API functions are ported from the ngx_http_lua_module
. Check out the official manual of
ngx_http_lua_module
for more details on these Lua API functions.
-
ngx.var.VARIABLE
Unlike the "http" subsystem, the "stream" subsystem of the NGINX core does not support NGINX variables at all. But still we emulate some of the NGINX builtin variables in this
ngx.var
API for compatibility withngx_http_lua_module
and ease of extracting certain session-wise information. Currently the following "variables" are supported:ngx.var.pid
for $pidngx.var.connection
for $connectionngx.var.remote_addr
for $remote_addrngx.var.binary_remote_addr
for $binary_remote_addrngx.var.remote_port
for $remote_portngx.var.nginx_version
for $nginx_versionngx.var.server_addr
for $server_addrngx.var.server_port
for $server_port
-
ngx.OK
,ngx.ERROR
, and etc. -
ngx.ERR
,ngx.WARN
, and etc. -
Only raw request sockets are supported, for obvious reasons. The
raw
argument value is ignored and the raw request socket is always returned. Unlikengx_http_lua_module
, you can still call output API functions likengx.say
,ngx.print
, andngx.flush
after acquiring the raw request socket via this function. -
This call currently ignores the
wait
argument and always wait for all the pending output to be completely flushed out (to the system socket send buffers). -
Always takes the Lua string value
"stream"
in this module.
- Add new directives
access_by_lua_block
andaccess_by_lua_file
. - Add new directives
log_by_lua_block
andlog_by_lua_file
. - Add new directives
balancer_by_lua_block
andbalancer_by_lua_file
. - Add new directives
ssl_certificate_by_lua_block
andssl_certificate_by_lua_file
. - Add
ngx.semaphore
API. - Add
ngx_meta_lua_module
to share as much code as possible between this module andngx_http_lua_module
and allow sharing oflua_shared_dict
. - Add support for lua-resty-core.
- Add
lua_postpone_output
to emulate the postpone_output directive.
The latest version of this module is compatible with the following versions of Nginx:
- 1.9.x >= 1.9.7 (last tested: 1.9.7)
Nginx cores older than 1.9.7 (exclusive) are not supported.
This module can be manually compiled into Nginx or OpenResty:
- Install LuaJIT 2.0 or 2.1 (recommended) or Lua 5.1 (Lua 5.2+ are not supported yet). LuaJIT can be downloaded from the the LuaJIT project website and Lua 5.1, from the Lua project website. Some distribution package managers also distribute LuaJIT and/or Lua.
- Download the latest version of ngx_stream_lua HERE.
- Download the latest supported version of NGINX HERE (See Nginx Compatibility) or the OpenResty bundle from HERE.
Build the source of NGINX or OpenResty with this module, like below:
wget 'http://nginx.org/download/nginx-1.9.7.tar.gz'
tar -xzvf nginx-1.9.7.tar.gz
cd nginx-1.9.7/
# tell nginx's build system where to find LuaJIT 2.0:
export LUAJIT_LIB=/path/to/luajit/lib
export LUAJIT_INC=/path/to/luajit/include/luajit-2.0
# tell nginx's build system where to find LuaJIT 2.1:
export LUAJIT_LIB=/path/to/luajit/lib
export LUAJIT_INC=/path/to/luajit/include/luajit-2.1
# or tell where to find Lua if using Lua instead:
#export LUA_LIB=/path/to/lua/lib
#export LUA_INC=/path/to/lua/include
# Here we assume Nginx is to be installed under /opt/nginx/.
./configure --prefix=/opt/nginx \
--with-ld-opt="-Wl,-rpath,/path/to/luajit-or-lua/lib" \
--with-stream \
--with-stream_ssl_module \
--add-module=/path/to/stream-lua-nginx-module
The openresty-en mailing list is for English speakers.
The openresty mailing list is for Chinese speakers.
The code repository of this project is hosted on github at openresty/stream-lua-nginx-module.
Please submit bug reports, wishlists, or patches by
- creating a ticket on the GitHub Issue Tracker,
- or posting to the OpenResty community.
This module is licensed under the BSD license.
Copyright (C) 2009-2016, by Yichun "agentzh" Zhang (章亦春) agentzh@gmail.com, CloudFlare Inc.
Copyright (C) 2009-2016, by Xiaozhe Wang (chaoslawful) chaoslawful@gmail.com.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
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.
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.