Kong/lua-kong-nginx-module

This is stars and forks stats for /Kong/lua-kong-nginx-module repository. As of 28 Apr, 2024 this repository has 29 stars and 21 forks.

Name lua-kong-nginx-module - Nginx C module that exposes a Lua API to dynamically control Nginx Table of Contents Name Description Install Directives lua_kong_load_var_index lua_kong_set_static_tag lua_kong_error_log_request_id Methods resty.kong.tls.disable_session_reuse resty.kong.tls.get_full_client_certificate_chain resty.kong.tls.set_upstream_cert_and_key resty.kong.tls.set_upstream_ssl_trusted_store resty.kong.tls.set_upstream_ssl_verify resty.kong.tls.set_upstream_ssl_verify_depth resty.kong.grpc.set_authority resty.kong.tls.disable_proxy_ssl resty.kong.var.patch_metatable resty.kong.tag.get resty.kong.log.set_log_level resty.kong.log.get_log_level License Description Kong often needs to be able to change Nginx behavior at runtime. Traditionally this has been done using various core patches. This module attempts to unify those approaches and ensure the least amount of modifications made directly to Nginx to support future maintainability. Patches from openresty-patches are required for this module to compile successfully. You may use the openresty-build-tools script to automatically build an OpenResty binary with required patches as well as this module included. Install This module can be installed just like any ordinary Nginx C module, using the --add-module configuration option: ./configure --prefix=/usr/local/kong-nginx \ --add-module=/path/to/lua-kong-nginx-module \ ... Directives lua_kong_load_var_index syntax: lua_kong_load_var_index $variable | default; context: http Ensure variable is indexed. Note that variables defined by set directive are always indexed by default and does not need to be defined here again. Common variables defined by other modules that are already indexed: $proxy_host $proxy_internal_body_length $proxy_internal_chunked $remote_addr $remote_user $request $http_referer $http_user_agent $host Specially, use lua_kong_load_var_index default to index commonly used variables as follows: $args $is_args $bytes_sent $content_type $http_authorization $http_connection $http_host $http_kong_debug $http_proxy $http_proxy_connection $http_te $http_upgrade $http_x_forwarded_for $http_x_forwarded_host $http_x_forwarded_path $http_x_forwarded_port $http_x_forwarded_prefix $http_x_forwarded_proto $https $http2 $realip_remote_addr $realip_remote_port $remote_port $request_length $request_method $request_time $request_uri $scheme $server_addr $server_port $ssl_cipher $ssl_client_raw_cert $ssl_client_verify $ssl_protocol $ssl_server_name $upstream_http_connection $upstream_http_trailer $upstream_http_upgrade $upstream_status See resty.kong.var.patch_metatable on how to enable indexed variable access. Back to TOC lua_kong_set_static_tag syntax: lua_kong_set_static_tag value; context: location(http subsystem) server(stream subsystem) Add a static tag string for Nginx's location(http subsystem) or server(stream subsystem) block, which can be accessed in Lua land by resty.kong.tag.get. Notice: the value of tag is bound with the location(http subsystem) or server(stream subsystem) block where it is defined. So if you defined multi tags in different location(http subsystem) or server(stream subsystem) block, you will always get the value where your Lua code runs in but not others. Back to TOC lua_kong_error_log_request_id syntax: lua_kong_error_log_request_id $variable; context: http server location Append a Request ID to the standard error log format, load the ID value from $variable. $variable must be previously defined. For example, with this configuration: lua_kong_error_log_request_id $request_id; An error log line may look similar to the following: 2023/09/06 11:33:36 [error] 94085#0: *6 [lua] content_by_lua(nginx.conf:27):7: hello world, client: 127.0.0.1, server: , request: "GET /foo HTTP/1.1", host: "localhost:8080", request_id: "cd7706e903db672ac5fac333bc8db5ed" Back to TOC Methods resty.kong.tls.disable_session_reuse syntax: succ, err = resty.kong.tls.disable_session_reuse() context: ssl_certificate_by_lua* subsystems: http stream Prevents the TLS session for the current connection from being reused by disabling session ticket and session ID for the current TLS connection. This function returns true when the call is successful. Otherwise it returns nil and a string describing the error. Back to TOC resty.kong.tls.get_full_client_certificate_chain syntax: pem_chain, err = resty.kong.tls.get_full_client_certificate_chain() context: rewrite_by_lua*, access_by_lua*, content_by_lua*, log_by_lua*, preread_by_lua* subsystems: http stream Returns the PEM encoded downstream client certificate chain with the client certificate at the top and intermediate certificates (if any) at the bottom. If client did not present any certificate or if session was reused, then this function will return nil. This is functionally similar to $ssl_client_raw_cert provided by ngx_http_ssl_module, with the notable exception that this function also returns any certificate chain client sent during handshake. If the TLS session was reused, (signaled by $ssl_session_reused returns "r"), then no client certificate information will be available as a full handshake never occurred. In this case caller should use $ssl_session_id to associate this session with one of the previous handshakes to identify the connecting client. Back to TOC resty.kong.tls.set_upstream_cert_and_key syntax: ok, err = resty.kong.tls.set_upstream_cert_and_key(chain, key) context: rewrite_by_lua*, access_by_lua*, balancer_by_lua*, preread_by_lua* subsystems: http stream Overrides and enables sending client certificate while connecting to the upstream in the current request. chain is the client certificate and intermediate chain (if any) returned by functions such as ngx.ssl.parse_pem_cert. key is the private key corresponding to the client certificate returned by functions such as ngx.ssl.parse_pem_priv_key. On success, this function returns true and future handshakes with upstream servers will always use the provided client certificate. Otherwise nil and a string describing the error will be returned. This function can be called multiple times in the same request. Later calls override previous ones. Back to TOC resty.kong.tls.set_upstream_ssl_trusted_store syntax: ok, err = resty.kong.tls.set_upstream_ssl_trusted_store(store) context: rewrite_by_lua*, access_by_lua*, balancer_by_lua*, preread_by_lua* subsystems: http stream Set upstream ssl verification trusted store of current request. Global setting set by proxy_ssl_trusted_certificate will be overwritten for the current request. store is a table object that can be created by resty.openssl.x509.store.new. On success, this function returns true and future handshakes with upstream servers will be verified with given store. Otherwise nil and a string describing the error will be returned. This function can be called multiple times in the same request. Later calls override previous ones. Example: local x509 = require("resty.openssl.x509") local crt, err = x509.new([[-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----]]) if err then ngx.log(ngx.ERR, "failed to parse cert: ", err) ngx.exit(500) end local store = require("resty.openssl.x509.store") local st, err = store.new() if err then ngx.log(ngx.ERR, "failed to create store: ", err) ngx.exit(500) end local ok, err = st:add(crt) if err then ngx.log(ngx.ERR, "failed to add cert to store: ", err) ngx.exit(500) end -- st:add can be called multiple times, also accept a crl -- st:add(another_crt) -- st:add(crl) -- OR -- st:use_default() to load default CA bundle local tls = require("resty.kong.tls") local ok, err = tls.set_upstream_ssl_trusted_store(st.ctx) if err then ngx.log(ngx.ERR, "failed to set upstream trusted store: ", err) ngx.exit(500) end local ok, err = tls.set_upstream_ssl_verify(true) if err then ngx.log(ngx.ERR, "failed to set upstream ssl verify: ", err) ngx.exit(500) end Back to TOC resty.kong.tls.set_upstream_ssl_verify syntax: ok, err = resty.kong.tls.set_upstream_ssl_verify(verify) context: rewrite_by_lua*, access_by_lua*, balancer_by_lua*, preread_by_lua* subsystems: http stream Set upstream ssl verification enablement of current request to the given boolean argument verify. Global setting set by proxy_ssl_verify will be overwritten. On success, this function returns true. Otherwise nil and a string describing the error will be returned. This function can be called multiple times in the same request. Later calls override previous ones. Back to TOC resty.kong.tls.set_upstream_ssl_verify_depth syntax: ok, err = resty.kong.tls.set_upstream_ssl_verify_depth(depth) context: rewrite_by_lua*, access_by_lua*, balancer_by_lua*, preread_by_lua* subsystems: http stream Set upstream ssl verification depth of current request to the given non-negative integer argument depth. Global setting set by proxy_ssl_verify_depth will be overwritten. On success, this function returns true. Otherwise nil and a string describing the error will be returned. This function can be called multiple times in the same request. Later calls override previous ones. Back to TOC resty.kong.grpc.set_authority syntax: ok, err = resty.kong.grpc.set_authority(new_authority) context: rewrite_by_lua*, access_by_lua*, balancer_by_lua* subsystems: http Overrides the :authority pseudo header sent to gRPC upstream by ngx_http_grpc_module. This function is a capability not possible in Nginx through means of config directive alone. Reason being Nginx auto-generates the :authority pseudo header without giving us a way to override it at config time. Closest being grpc_set_header Host "foo.example.com", but this will cause the gRPC module to use the Host header and not generate the :authority pseudo header, causing problems for certain gRPC server. When called, this function accepts a new value to override the :authority pseudo header that will be generated by the ngx_http_grpc_module for the current request. The new_authority parameter can not be an empty string. On success, this function returns true. Otherwise nil and a string describing the error will be returned. This function can be called multiple times in the same request. Later calls override previous ones. If called in the balancer_by_lua context, the request needs to be recreated (see balancer.recreate. Back to TOC resty.kong.tls.disable_proxy_ssl syntax: ok, err = resty.kong.tls.disable_proxy_ssl() context: preread_by_lua*, balancer_by_lua* subsystems: stream Disables the TLS handshake to upstream for ngx_stream_proxy_module. Effectively this overrides proxy_ssl directive to off setting for the current stream session. This function has no side effects if the proxy_ssl off; setting has already been specified inside nginx.conf or if this function has been previously called from the current session. Back to TOC resty.kong.var.patch_metatable syntax: resty.kong.var.patch_metatable() context: init_by_lua subsystems: http Indexed variable access is a faster way of accessing Nginx variables for OpenResty. This method patches the metatable of ngx.var to enable index access to variables that supports it. It should be called once in the init phase which will be effective for all subsequent ngx.var uses. For variables that does not have indexed access, the slower hash based lookup will be used instead (this is the OpenResty default behavior). To ensure a variable can be accessed using index, you can use the lua_kong_load_var_index directive. Back to TOC resty.kong.tag.get syntax: resty.kong.tag.get() context: rewrite_by_lua*, access_by_lua*, content_by_lua*, log_by_lua*, header_filter_by_lua*, body_filter_by_lua* subsystems: http stream Return the tag value which is set by lua_kong_set_static_tag directive. If there is no tag in location(http subsystems) or server(stream subsystems) block, it will return nil. Back to TOC resty.kong.log.set_log_level syntax: resty.kong.log.set_log_level(level, timeout) context: any subsystems: http Dynamically configures the level with a timeout for the current worker, and must be one of the Nginx log level constants. The timeout specifies a number of seconds after which the log level will be reset to the previous value. If timeout is 0, the log level will be reset to the default log_level setting from Nginx configuration immediately. If this method is called again before the timeout, the log level and timeout will be overwritten. If we don’t pass timeout to set_log_level(), it will raise a Lua error. Back to TOC resty.kong.log.get_log_level syntax: resty.kong.log.get_log_level(level) context: any subsystems: http If the dynamic log level is set, it will return the dynamic log level, otherwise it will return level. Please see Nginx log level constants for the possible value of level. Back to TOC License Copyright 2020-2023 Kong Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Back to TOC