Repository files navigation

ngx_stream_lua_module - Embed the power of Lua into Nginx stream/TCP Servers.

This module is a core component of OpenResty. If you are using this module,then you are essentially using OpenResty.

This module is not distributed with the Nginx source. Seethe installationinstructions.

• Name
• Status
• Version
• Synopsis
• Description
  • Directives
  • Nginx API for Lua
• TODO
• Nginx Compatibility
• Installation
• Community
  • English Mailing List
  • Chinese Mailing List
• Code Repository
• Bugs and Patches
• Acknowledgments
• Copyright and License
• See Also

Production ready.

This document describes ngx_stream_luav0.0.16, which was releasedon 17 Jan, 2025.

events{worker_connections1024;}stream{    # define a TCP server listening on the port 1234:server{listen1234;        content_by_lua_block{            ngx.say("Hello, Lua!")}}}

Set up as an SSL TCP server:

stream{server{listen4343ssl;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_timeout10m;        content_by_lua_block{            local sock = assert(ngx.req.socket(true))            local data = sock:receive()  -- read a line from downstreamif 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)  -- sleepingfor 3 sec            ngx.say("Bye bye...")}}}

Back to TOC

This is a port of thengx_http_lua_module tothe Nginx "stream" subsystem so as to support generic stream/TCP clients.

The available Lua APIs and Nginx directives remain the same as those of thengx_http_lua module.

Back to TOC

The following directives are ported directly from ngx_http_lua. Please checkthe documentation of ngx_http_lua for more details about their usage andbehavior.

• lua_load_resty_core
• 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
• preread_by_lua_block
• preread_by_lua_file
• content_by_lua_block
• content_by_lua_file
• balancer_by_lua_block
• balancer_by_lua_file
• log_by_lua_block
• log_by_lua_file
• ssl_client_hello_by_lua_block
• ssl_client_hello_by_lua_file
• ssl_certificate_by_lua_block
• ssl_certificate_by_lua_file
• proxy_ssl_verify_by_lua_block
• proxy_ssl_verify_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_certificate
• lua_ssl_certificate_key
• lua_ssl_trusted_certificate
• lua_ssl_verify_depth
• lua_ssl_key_log
• lua_ssl_conf_command
• lua_upstream_skip_openssl_default_verify
• lua_check_client_abort
• lua_max_pending_timers
• lua_max_running_timers
• lua_sa_restart
• lua_add_variable
• lua_capture_error_log
• preread_by_lua_no_postpone

Thesend_timeout directive in the Nginx"http" subsystem is missing in the "stream" subsystem. As such,ngx_stream_lua_module uses thelua_socket_send_timeout directive for thispurpose instead.

Note: the lingering close directive that used to exist in older version ofstream_lua_nginx_module has been removed and can now be simulated with thenewly addedtcpsock:shutdown API if necessary.

Back to TOC

syntax:preread_by_lua_block { lua-script }

context:stream, server

phase:preread

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

It is possible to acquire the raw request socket usingngx.req.socketand receive data from or send data to the client. However, keep in mind that calling thereceive() methodof the request socket will consume the data from the buffer and such consumed data will not be seen by handlersfurther down the chain.

Thepreread_by_lua_block code will always run at the end of thepreread processing phase unlesspreread_by_lua_no_postpone is turned on.

This directive was first introduced in thev0.0.3 release.

Back to TOC

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

context:stream, server

phase:preread

Equivalent topreread_by_lua_block, except that the file specified by<path-to-lua-script-file> contains the Lua codeor 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 likefoo/bar.lua is given, it will be turned into the absolute path relative to theserver prefix path determined by the-p PATH command-line option given when starting the Nginx server.

When the Lua code cache is turned on (by default), the user code is loaded once at the first connection and cached. 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 switchinglua_code_cacheoff innginx.conf to avoid having to reload Nginx.

This directive was first introduced in thev0.0.3 release.

Back to TOC

syntax:log_by_lua_block { lua-script }

context:stream, server

phase:log

Runs the Lua source code specified as<lua-script> during thelog request processing phase. This does not replace the current access logs, but runs before.

Yielding APIs such asngx.req.socket,ngx.socket.*,ngx.sleep, orngx.say arenot available in this phase.

This directive was first introduced in thev0.0.3 release.

Back to TOC

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

context:stream, server

phase:log

Equivalent tolog_by_lua_block, except that the file specified by<path-to-lua-script-file> contains the Lua codeor 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 likefoo/bar.lua is given, it will be turned into the absolute path relative to theserver prefix path determined by the-p PATH command-line option given when starting the Nginx server.

When the Lua code cache is turned on (by default), the user code is loaded once at the first connection and cached. 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 switchinglua_code_cacheoff innginx.conf to avoid having to reload Nginx.

This directive was first introduced in thev0.0.3 release.

Back to TOC

syntax:lua_add_variable $var

context:stream

Add the 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 themusingngx.var will returnnil. However, they could be re-assigned via thengx.var.VARIABLE API at any time.

This directive was first introduced in thev0.0.4 release.

Back to TOC

syntax:preread_by_lua_no_postpone on|off

context:stream

Controls whether or not to disable postponingpreread_by_lua* directivesto run at the end of thepreread processing phase. By default, this directive is turned offand the Lua code is postponed to run at the end of thepreread phase.

This directive was first introduced in thev0.0.4 release.

Back to TOC

Many Lua API functions are ported from ngx_http_lua. Check out the officialmanual of ngx_http_lua for more details on these Lua API functions.

• ngx.var.VARIABLE

This module fully supports the new variable subsystem inside the Nginx stream core. You may access anybuilt-in variables provided by the stream core orother stream modules.

• Core constants

  ngx.OK,ngx.ERROR, and etc.

• Nginx log level constants

  ngx.ERR,ngx.WARN, and etc.

• print

• ngx.ctx

• ngx.balancer

• ngx.req.socket

Only raw request sockets are supported, for obvious reasons. Theraw argument valueis ignored and the raw request socket is always returned. Unlike ngx_http_lua,you can still call output API functions likengx.say,ngx.print, andngx.flushafter acquiring the raw request socket via this function.

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

The raw TCP sockets returned by this module will contain the following extra method:

Back to TOC

syntax:data, err = reqsock:receiveany(max)

context:content_by_lua*, ngx.timer.*, ssl_certificate_by_lua*

This method is similar totcpsock:receiveany method

This method was introduced intostream-lua-nginx-module sincev0.0.8.

Back to TOC

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 clientand sends TCP FIN, while keeping the reading half open.

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

If you called any output functions (likengx.say)before calling this method, consider usengx.flush(true) to make sure all busy buffers are complelyflushed before shutting down the socket. If any busy buffers were detected, this method will returnnilwill error message"socket busy writing".

This feature is particularly useful for protocols that generate a response before actuallyfinishing consuming all incoming data. Normally, the kernel will send RST to the client whentcpsock:close is called withoutemptying the receiving buffer first. Calling this method will allow you to keep reading fromthe receiving buffer and prevents RST from being sent.

You can also use this method to simulate lingering close similar to thatprovided by the ngx_http_core_modulefor protocols in need of such behavior. Here is an example:

localLINGERING_TIME=30-- 30 secondslocalLINGERING_TIMEOUT=5000-- 5 secondslocalok,err=sock:shutdown("send")ifnotokthenngx.log(ngx.ERR,"failed to shutdown:",err)returnendlocaldeadline=ngx.time()+LINGERING_TIMEsock:settimeouts(nil,nil,LINGERING_TIMEOUT)repeatlocaldata,_,partial=sock:receive(1024)until (notdataandnotpartial)orngx.time()>=deadline

Back to TOC

syntax:ok, err = reqsock:peek(size)

context:preread_by_lua*

Peeks into theprereadbuffer that contains downstream data sent by the client without consuming them.That is, data returned by this API will still be forwarded upstream in later phases.

This function takes a single required argument,size, which is the number of bytes to be peeked.Repeated calls to this function always returns data from the beginning of the preread buffer.

Note that preread phase happens after the TLS handshake. If the stream server was configured withTLS enabled, the returned data will be in clear text.

If preread buffer does not have the requested amount of data, then the current Lua thread willbe yielded until more data is available,preread_buffer_sizehas been exceeded, orpreread_timeouthas elapsed. Successful calls always return the requested amounts of data, that is, no partialdata will be returned.

Whenpreread_buffer_sizehas been exceeded, the current stream session will be terminated with thesession status code400immediately by the stream core module, with error message"preread buffer full" that will be printed to the error log.

Whenpreread_timeout has been exceeded,the current stream session will be terminated with thesession status code200 immediately by the stream core module.

In both cases, no further processing on the session is possible (exceptlog_by_lua*). The connection will be closed by thestream core module automatically.

Note that this API cannot be used if consumption of client data has occurred. For example, after callingreqsock:receive. If such an attempt was made, the Lua error"attempt to peek on a consumed socket" willbe thrown. Consuming client data after calling this API is allowed and safe.

Here is an example of using this API:

localsock=assert(ngx.req.socket())localdata=assert(sock:peek(1))-- peek the first 1 byte that contains the lengthdata=string.byte(data)data=assert(sock:peek(data+1))-- peek the length + the size bytelocalpayload=data:sub(2)-- trim the length byte to get actual payloadngx.log(ngx.INFO,"payload is:",payload)

This API was first introduced in thev0.0.6 release.

Back to TOC

• ngx.print

• ngx.say

• ngx.log

• ngx.flush

  This call currently ignores thewait argument and always wait for all the pendingoutput to be completely flushed out (to the system socket send buffers).

• ngx.exit

• ngx.eof

• ngx.sleep

• ngx.escape_uri

• ngx.unescape_uri

• ngx.encode_args

• ngx.decode_args

• ngx.encode_base64

• ngx.decode_base64

• ngx.crc32_short

• ngx.crc32_long

• ngx.hmac_sha1

• ngx.md5

• ngx.md5_bin

• ngx.sha1_bin

• ngx.quote_sql_str

• ngx.today

• ngx.time

• ngx.now

• ngx.update_time

• ngx.localtime

• ngx.utctime

• ngx.re.match

• ngx.re.find

• ngx.re.gmatch

• ngx.re.sub

• ngx.re.gsub

• ngx.shared.DICT

• ngx.socket.tcp

• ngx.socket.udp

• ngx.socket.connect

• ngx.get_phase

• ngx.thread.spawn

• ngx.thread.wait

• ngx.thread.kill

• ngx.on_abort

• ngx.timer.at

• ngx.timer.running_count

• ngx.timer.pending_count

• ngx.config.debug

• ngx.config.subsystem

  Always takes the Lua string value"stream" in this module.

• ngx.config.prefix

• ngx.config.nginx_version

• ngx.config.nginx_configure

• ngx.config.ngx_lua_version

• ngx.worker.exiting

• ngx.worker.pid

• ngx.worker.pids

• ngx.worker.count

• ngx.worker.id

• coroutine.create

• coroutine.resume

• coroutine.yield

• coroutine.wrap

• coroutine.running

• coroutine.status

Back to TOC

• Add new directivesaccess_by_lua_block andaccess_by_lua_file.
• Addlua_postpone_output to emulate thepostpone_output directive.

Back to TOC

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

• 1.29.x (last tested: 1.29.2)
• 1.27.x (last tested: 1.27.1)
• 1.25.x (last tested: 1.25.1)
• 1.21.x (last tested: 1.21.4)
• 1.19.x (last tested: 1.19.3)
• 1.17.x (last tested: 1.17.8)
• 1.15.x (last tested: 1.15.8)
• 1.13.x (last tested: 1.13.6)

Nginx cores older than 1.13.6 (exclusive) arenot tested and may or may notwork. Use at your own risk!

Back to TOC

It ishighly recommended to useOpenResty releaseswhich bundle Nginx, ngx_http_lua, ngx_stream_lua, (this module), LuaJIT, aswell as other powerful companion Nginx modules and Lua libraries.

It is discouraged to build this module with Nginx yourself since it is trickyto set up exactly right.

Note that Nginx, LuaJIT, and OpenSSL official releases have various limitationsand long standing bugs that can cause some of this module's features to bedisabled, not work properly, or run slower. Official OpenResty releases arerecommended because they bundleOpenResty's optimized LuaJIT 2.1 fork andNginx/OpenSSLpatches.

Alternatively, ngx_stream_lua can be manually compiled into Nginx:

1. LuaJIT can be downloaded from thelatest release of OpenResty's LuaJIT fork. The official LuaJIT 2.x releases are also supported, although performance will be significantly lower for reasons elaborated above
2. Download the latest version of ngx_stream_luaHERE
3. Download the latest supported version of NginxHERE (SeeNginx Compatibility)

Build the source with this module:

wget'https://nginx.org/download/nginx-1.13.6.tar.gz'tar -xzvf nginx-1.13.6.tar.gzcd nginx-1.13.6/# tell nginx's build system where to find LuaJIT 2.1:export LUAJIT_LIB=/path/to/luajit/libexport LUAJIT_INC=/path/to/luajit/include/luajit-2.1# 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 installmake -j4make 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 "http"subsystem.

Back to TOC

Back to TOC

Theopenresty-en mailing list is for English speakers.

Back to TOC

Theopenresty mailing list is for Chinese speakers.

Back to TOC

The code repository of this project is hosted on GitHub atopenresty/stream-lua-nginx-module.

Back to TOC

Please submit bug reports, wishlists, or patches by

1. creating a ticket on theGitHub Issue Tracker,
2. or posting to theOpenResty community.

Back to TOC

We appreciateKong Inc. for kindly sponsoringOpenResty Inc. on the followingwork:

• Compatibility with Nginx core 1.13.3.
• Development ofmeta-lua-nginx-moduleto make code sharing between this module andlua-nginx-module possible.
• balancer_by_lua_*,preread_by_lua_*,log_by_lua_* andssl_certby_lua* phases support.
• reqsock:peek API support.

Back to TOC

This module is licensed under the BSD license.

Copyright (C) 2009-2025, 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

• ngx_http_lua_module
• ngx_stream_echo_module
• OpenResty

Back to TOC