Skip to content

ryeyao/stream-lua-nginx-module

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

173 Commits
src
src
 
 
t
t
 
 
util
util
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
config
config
 
 
valgrind.suppress
valgrind.suppress
 
 

Repository files navigation

NOTE To make access_by_lua* work, two nginx patches (nginx-allow_override_stream_access_handler.patch & nginx-init_session_before_access_handler.patch) are needed.

NOTE This modification should work with openresty-bundle-1.9.7.4 (with nginx-1.9.7).

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

Experimental.

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.

In addition, ngx_stream_lua_module provides the following directives:

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.

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.

Back to TOC

TODO

  • Add new directives access_by_lua_block and access_by_lua_file.
  • Add new directives log_by_lua_block and log_by_lua_file.
  • Add new directives balancer_by_lua_block and balancer_by_lua_file.
  • Add new directives ssl_certificate_by_lua_block and ssl_certificate_by_lua_file.
  • Add ngx.semaphore API.
  • Add ngx_meta_lua_module to share as much code as possible between this module and ngx_http_lua_module and allow sharing of lua_shared_dict.
  • 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.9.x >= 1.9.7 (last tested: 1.9.7)

Nginx cores older than 1.9.7 (exclusive) are not supported.

Back to TOC

Installation

This module can be manually compiled into Nginx or OpenResty:

  1. 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.
  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.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

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

Copyright and License

This module is licensed under the BSD license.

Copyright (C) 2009-2016, by Yichun "agentzh" Zhang (章亦春) [email protected], CloudFlare Inc.

Copyright (C) 2009-2016, by Xiaozhe Wang (chaoslawful) [email protected].

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

About

Embed the power of Lua into NGINX TCP servers

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

1 tags

Packages

No packages published

Languages

  • C 92.7%
  • Lua 6.1%
  • Other 1.2%