stream-lua #
ngx_stream_lua_module - Embed the power of Lua into Nginx stream/TCP Servers.
Source: upstream source
Directives
balancer_by_lua_block #
syntax: balancer_by_lua_block no args; · context: stream/upstream
Selects an upstream peer for the current stream session by running inline Lua code during the balancer phase.
balancer_by_lua_file #
syntax: balancer_by_lua_file 1 arg; · context: stream/upstream
Equivalent to balancer_by_lua_block but loads the Lua balancer code from an external file.
content_by_lua #
syntax: content_by_lua 1 arg; · context: stream/server
content_by_lua "<inline script>"
content_by_lua_block #
syntax: content_by_lua_block no args; · context: stream/server
content_by_lua_block { <inline script> }
content_by_lua_file #
syntax: content_by_lua_file 1 arg; · context: stream/server
content_by_lua_file rel/or/abs/path/to/script
init_by_lua #
syntax: init_by_lua 1 arg; · context: stream
Deprecated inline-string form of init_by_lua_block; runs Lua source given directly as an Nginx string literal at config load time.
init_by_lua_block #
syntax: init_by_lua_block no args; · context: stream
Runs Lua code once when the master process loads or reloads the config, before workers fork, for global initialization.
init_by_lua_file #
syntax: init_by_lua_file 1 arg; · context: stream
Equivalent to init_by_lua_block but loads the initialization Lua code from an external file.
init_worker_by_lua #
syntax: init_worker_by_lua 1 arg; · context: stream
Deprecated inline-string form of init_worker_by_lua_block; runs Lua source as an escaped string literal on worker startup.
init_worker_by_lua_block #
syntax: init_worker_by_lua_block no args; · context: stream
Runs Lua code on every worker process startup, commonly used to create per-worker timers.
init_worker_by_lua_file #
syntax: init_worker_by_lua_file 1 arg; · context: stream
Equivalent to init_worker_by_lua_block but loads the Lua code from an external file.
log_by_lua_block #
syntax: log_by_lua_block no args; · context: stream, stream/server
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 specified as <lua-script> during the log request processing phase.
log_by_lua_file #
syntax: log_by_lua_file 1 arg; · context: stream, stream/server
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.
lua_add_variable #
syntax: lua_add_variable 1 arg; · context: stream
Registers a new nginx stream-subsystem variable with the given name, making it assignable via ngx.var at runtime.
lua_capture_error_log #
syntax: lua_capture_error_log 1 arg; · context: stream
Allocates a fixed-size buffer to capture all nginx error log messages in memory, retrievable later without reading log files.
lua_check_client_abort #
syntax: lua_check_client_abort on | off (on/off flag); · context: stream, stream/server
Boolean directive — set to "on" or "off".
lua_code_cache #
syntax: lua_code_cache on | off; · context: stream, stream/server
The Lua code cache can be temporarily disabled during development by switching lua_code_cache off in nginx.conf to avoid having to reload Nginx.
lua_load_resty_core #
syntax: lua_load_resty_core on | off; · context: stream
Is deprecated and has no effect, since resty.core is always loaded automatically since v0.10.16.
lua_malloc_trim #
syntax: lua_malloc_trim 1 arg; · context: stream
Requests libc to release cached free memory back to the operating system every specified number of processed requests.
lua_max_pending_timers #
syntax: lua_max_pending_timers 1 arg (integer); · context: stream
Limits the maximum number of pending timers permitted at any time in a single nginx worker process.
lua_max_running_timers #
syntax: lua_max_running_timers 1 arg (integer); · context: stream
Limits the maximum number of concurrently running Lua timers permitted in a single nginx worker process.
lua_package_cpath #
syntax: lua_package_cpath 1 arg; · context: stream
Sets the Lua C module search path (cpath) for the stream module, supporting standard Lua cpath syntax and "$prefix" notation.
lua_package_path #
syntax: lua_package_path 1 arg; · context: stream
Sets the Lua module search path used by Lua directives in the stream module, supporting ";;" and "$prefix" notation.
lua_regex_cache_max_entries #
syntax: lua_regex_cache_max_entries 1 arg (integer); · context: stream
Sets the maximum number of entries allowed in the worker-process-level compiled regular expression cache.
lua_regex_match_limit #
syntax: lua_regex_match_limit 1 arg (integer); · context: stream
Sets the PCRE match limit controlling backtracking during ngx.re regex execution, using PCRE's default when set to zero.
lua_sa_restart #
syntax: lua_sa_restart on | off (on/off flag); · context: stream
Controls whether interrupted system calls automatically restart via the SA_RESTART signal flag.
lua_socket_buffer_size #
syntax: lua_socket_buffer_size 1 arg (size (k/m/g)); · context: stream, stream/server
Size in bytes; accepts k / m / g suffixes.
lua_socket_connect_timeout #
syntax: lua_socket_connect_timeout 1 arg (duration in ms); · context: stream, stream/server
Duration in milliseconds; accepts ms / s / m suffixes.
lua_socket_keepalive_timeout #
syntax: lua_socket_keepalive_timeout 1 arg (duration in ms); · context: stream, stream/server
Duration in milliseconds; accepts ms / s / m suffixes.
lua_socket_log_errors #
syntax: lua_socket_log_errors on | off (on/off flag); · context: stream, stream/server
Controls whether cosocket TCP/UDP/Unix-domain-socket errors are logged to the nginx error log.
lua_socket_pool_size #
syntax: lua_socket_pool_size 1 arg (integer); · context: stream, stream/server
Integer value.
lua_socket_read_timeout #
syntax: lua_socket_read_timeout 1 arg (duration in ms); · context: stream, stream/server
Duration in milliseconds; accepts ms / s / m suffixes.
lua_socket_send_lowat #
syntax: lua_socket_send_lowat 1 arg (size (k/m/g)); · context: stream, stream/server
Size in bytes; accepts k / m / g suffixes.
lua_socket_send_timeout #
syntax: lua_socket_send_timeout 1 arg (duration in ms); · context: stream, stream/server
Duration in milliseconds; accepts ms / s / m suffixes.
lua_ssl_certificate #
syntax: lua_ssl_certificate 1 arg (list of strings); · context: stream, stream/server
Appends a string to a list; may be specified multiple times.
lua_ssl_certificate_key #
syntax: lua_ssl_certificate_key 1 arg (list of strings); · context: stream, stream/server
Appends a string to a list; may be specified multiple times.
lua_ssl_ciphers #
syntax: lua_ssl_ciphers 1 arg (string); · context: stream, stream/server
Stores a single string value.
lua_ssl_conf_command #
syntax: lua_ssl_conf_command 2 args (key value pair); · context: stream, stream/server
Sets OpenSSL configuration commands applying to SSL/TLS connections initiated by cosockets.
lua_ssl_crl #
syntax: lua_ssl_crl 1 arg (string); · context: stream, stream/server
Stores a single string value.
lua_ssl_key_log #
syntax: lua_ssl_key_log 1 arg (string); · context: stream, stream/server
Stores a single string value.
lua_ssl_protocols #
syntax: lua_ssl_protocols 1+ args (bitmask); · context: stream, stream/server
Bitmask — combine several keywords.
lua_ssl_trusted_certificate #
syntax: lua_ssl_trusted_certificate 1 arg (string); · context: stream, stream/server
Specifies a PEM file of trusted CA certificates used to verify the SSL/TLS server certificate during a cosocket sslhandshake call.
lua_ssl_verify_depth #
syntax: lua_ssl_verify_depth 1 arg (integer); · context: stream, stream/server
Sets the maximum verification depth for the peer certificate chain when cosockets perform SSL/TLS handshakes.
lua_upstream_skip_openssl_default_verify #
syntax: lua_upstream_skip_openssl_default_verify on | off (on/off flag); · context: stream/server
Boolean directive — set to "on" or "off".
preread_by_lua_block #
syntax: preread_by_lua_block no args; · context: stream, stream/server
Runs inline Lua code as a preread-phase handler for every connection or datagram packet before proxying decisions are made.
preread_by_lua_file #
syntax: preread_by_lua_file 1 arg; · context: stream, stream/server
Runs Lua code or LuaJIT bytecode from the specified file as a preread-phase handler, equivalent to preread_by_lua_block.
preread_by_lua_no_postpone #
syntax: preread_by_lua_no_postpone on | off (on/off flag); · context: stream
Controls whether preread-phase Lua handlers are postponed to run at the end of the preread processing phase.
proxy_ssl_certificate_by_lua_block #
syntax: proxy_ssl_certificate_by_lua_block no args; · context: stream/server
same context as proxy_pass directive
proxy_ssl_certificate_by_lua_file #
syntax: proxy_ssl_certificate_by_lua_file 1 arg; · context: stream/server
Sets the client SSL certificate/key for proxied upstream TCP/SSL connections via Lua code loaded from a file.
proxy_ssl_verify_by_lua_block #
syntax: proxy_ssl_verify_by_lua_block no args; · context: stream/server
Runs inline Lua code to verify the upstream server's SSL certificate for proxied stream connections.
proxy_ssl_verify_by_lua_file #
syntax: proxy_ssl_verify_by_lua_file 1 arg; · context: stream/server
Equivalent to proxy_ssl_verify_by_lua_block but loads the verification Lua code from an external file.
ssl_certificate_by_lua_block #
syntax: ssl_certificate_by_lua_block no args; · context: stream, stream/server
Runs inline Lua code to dynamically select the SSL certificate served to a downstream client, per connection.
ssl_certificate_by_lua_file #
syntax: ssl_certificate_by_lua_file 1 arg; · context: stream, stream/server
Equivalent to ssl_certificate_by_lua_block but loads the certificate-selection Lua code from an external file.
ssl_client_hello_by_lua_block #
syntax: ssl_client_hello_by_lua_block no args; · context: stream, stream/server
Runs inline Lua code right after nginx processes the SSL client hello message, before the full handshake, for dynamic per-connection SSL handling.
ssl_client_hello_by_lua_file #
syntax: ssl_client_hello_by_lua_file 1 arg; · context: stream, stream/server
Runs Lua code or LuaJIT bytecode from the specified file right after nginx processes the SSL client hello message, equivalent to ssl_client_hello_by_lua_block.
Example
location = /back {
lua_socket_log_errors on;
content_by_lua_block {
ngx.send_headers()
ngx.flush(true)
local sock, err = ngx.req.socket()
if not sock then
ngx.say("failed to get socket: ", err)
return nil
end
sock:settimeout(100);
local reader = sock:receiveuntil("no-such-terminator")
local data, err, partial = reader()
if not data then
ngx.say("err: ", err, ", partial: ", partial)
else
ngx.say("received: ", data)
end
ngx.sleep(0.1)
local data, err, partial = sock:receive()
if err then
ngx.say("err: ", err, ", partial: ", partial)
else
ngx.say("received: ", data)
end
}
}