Skip to content

Latest commit

 

History

History
562 lines (407 loc) · 24.6 KB

README.md

File metadata and controls

562 lines (407 loc) · 24.6 KB
Raw

Name

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.

Table of Contents

Status

Producty ready.

The API is still in flux and may change without notice.

Synopsis

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

Description

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.

Back to TOC

Directives

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.

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.

Note: the lingering close directive that used to exist in older version of stream_lua_nginx_module has been removed and can now be simulated with the newly added tcpsock:shutdown method if necessary.

Back to TOC

preread_by_lua_block

syntax: preread_by_lua_block { lua-script }

context: stream, server

phase: preread

Acts as a preread phase handler and executes Lua code string specified in lua-script for every connection (or packet in datagram mode). The Lua code may make API calls and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox).

It is possible to acquire raw request socket using ngx.req.socket and receive data from or send data to the client. However, keep in mind that calling the receive() method of the request socket will consume the data from the buffer and those data will not be seen by handlers further down the chain.

The preread_by_lua_block code will always run at the end of the preread processing phase unless preread_by_lua_no_postpone is turned on.

This directive was first introduced in the v0.0.3 release.

Back to TOC

preread_by_lua_file

syntax: preread_by_lua_file <path-to-lua-script-file>

context: stream, server

phase: preread

Equivalent to preread_by_lua_block, except that the file specified by <path-to-lua-script-file> contains the Lua code or LuaJIT bytecode to be executed.

Nginx variables can be used in the <path-to-lua-script-file> string to provide flexibility. This however carries some risks and is not ordinarily recommended.

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.

When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching lua_code_cache off in nginx.conf to avoid reloading Nginx.

This directive was first introduced in the v0.0.3 release.

Back to TOC

log_by_lua_block

syntax: log_by_lua_block { lua-script }

context: stream, server

phase: log

Runs the Lua source code inlined as the <lua-script-str> at the log request processing phase. This does not replace the current access logs, but runs before.

Yielding APIs in this phase, such as ngx.req.socket, ngx.socket.*, ngx.sleep, ngx.say are not available in this phase.

This directive was first introduced in the v0.0.3 release.

Back to TOC

log_by_lua_file

syntax: log_by_lua_file <path-to-lua-script-file>

context: stream, server

phase: log

Equivalent to log_by_lua_block, except that the file specified by <path-to-lua-script-file> contains the Lua code or LuaJIT bytecode to be executed.

Nginx variables can be used in the <path-to-lua-script-file> string to provide flexibility. This however carries some risks and is not ordinarily recommended.

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.

When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching lua_code_cache off in nginx.conf to avoid reloading Nginx.

This directive was first introduced in the v0.0.3 release.

Back to TOC

lua_add_variable

syntax: lua_add_variable $var

context: stream

Add variable $var to the stream subsystem and makes it changeable. If $var already exists, this directive will do nothing.

By default, variables added using this directive are considered "not found" and reading them using ngx.var will return nil. However, they could be re-assigned using ngx.var code at any time.

This directive was first introduced in the v0.0.4 release.

Back to TOC

preread_by_lua_no_postpone

syntax: preread_by_lua_no_postpone on|off

context: stream

Controls whether or not to disable postponing preread_by_lua* directives to run at the end of the preread processing phase. By default, this directive is turned off and the Lua code is postponed to run at the end of the preread phase.

This directive was first introduced in the v0.0.4 release.

Back to TOC

Nginx API for Lua

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.

This module fully supports the new variable subsystem inside the NGINX stream core. You may access any built-in variables provided by the stream core or other stream modules.

Only raw request sockets are supported, for obvious reasons. The raw argument value is ignored and the raw request socket is always returned. Unlike ngx_http_lua_module, you can still call output API functions like ngx.say, ngx.print, and ngx.flush after acquiring the raw request socket via this function.

When stream server is in UDP mode, reading from the downstream socket returned by the ngx.req.socket call will only return the content of a single packet. Therefore the reading call will never block and will return nil, "no more data" when all the data from the datagram has been consumed. However, you may choose to send multiple UDP packets back to the client using the downstream socket.

Raw TCP request socket returned by this module will contain the following extra method:

tcpsock:shutdown

syntax: ok, err = tcpsock:shutdown("send")

context: content_by_lua*

Shuts down the write part of the request socket, prevents all further writing to the client and sends TCP FIN, while keeping the reading half open.

Currently only the "send" direction is supported. Using any parameters other than "send" will return an error.

If you called any output functions (like ngx.say) before calling this method, consider use ngx.flush(true) to make sure all busy buffers are complely flushed before shutting down the socket. If any busy buffers were detected, this method will return nil will error message "socket busy writing".

This feature is particularly useful for protocols that generates response before actually finishes consuming all incoming data. Normally Kernel will send out RST to the client when tcpsock:close is called without emptying the receiving buffer first. Calling this method will allow you to keep reading from the receiving buffer and prevents RST from being sent.

You can also use this method to simulate lingering close similar to that provided by the ngx_http_core_module for protocols that needs such behavior. Here is an example:

local LINGERING_TIME = 30 -- 30 seconds
local LINGERING_TIMEOUT = 5000 -- 5 seconds

local ok, err = sock:shutdown("send")
if not ok then
    ngx.log(ngx.ERR, "failed to shutdown: ", err)
    return
end

local deadline = ngx.time() + LINGERING_TIME

sock:settimeouts(nil, nil, LINGERING_TIMEOUT)

repeat
    local data, _, partial = sock:receive(1024)
until (not data and not partial) or ngx.time() >= deadline

Back to TOC

Back to TOC

TODO

  • Add new directives access_by_lua_block and access_by_lua_file.
  • Add new directives ssl_certificate_by_lua_block and ssl_certificate_by_lua_file.
  • Add ngx.semaphore API.
  • Add support for lua-resty-core.
  • Add lua_postpone_output to emulate the postpone_output directive.

Back to TOC

Nginx Compatibility

The latest version of this module is compatible with the following versions of Nginx:

  • 1.13.x >= 1.13.6

Nginx cores older than 1.13.6 (exclusive) are not tested and may or may not work. Use at your own risk!

Back to TOC

Installation

This module can be manually compiled into Nginx or OpenResty:

  1. Install LuaJIT 2.1 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.
  2. Download the latest version of ngx_stream_lua HERE.
  3. 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.13.6.tar.gz'
tar -xzvf nginx-1.13.6.tar.gz
cd nginx-1.13.6/

# 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

# Build and install
make -j4
make install

You may use --without-http if you do not wish to use this module with the HTTP subsystem. ngx_stream_lua will work perfectly fine without the presense of the HTTP subsystem.

Back to TOC

Community

Back to TOC

English Mailing List

The openresty-en mailing list is for English speakers.

Back to TOC

Chinese Mailing List

The openresty mailing list is for Chinese speakers.

Back to TOC

Code Repository

The code repository of this project is hosted on github at openresty/stream-lua-nginx-module.

Back to TOC

Bugs and Patches

Please submit bug reports, wishlists, or patches by

  1. creating a ticket on the GitHub Issue Tracker,
  2. or posting to the OpenResty community.

Back to TOC

Acknowledgments

  • We appreciate Mashape, Inc. for kindly sponsoring OpenResty Inc. to make this module compatible with Nginx core 1.13.3. In addition, they sponsored the work on making code sharing between this module and lua-nginx-module, as well as balancer_by_lua_, preread_by_lua_ and log_by_lua_* support possible.

Copyright and License

This module is licensed under the BSD license.

Copyright (C) 2009-2018, by Yichun "agentzh" Zhang (章亦春) agentzh@gmail.com, OpenResty 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.

Back to TOC

See Also

Back to TOC