hannah-eee/nginx-docs huggingface dataset:
Security

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Security

All nginx security issues should be reported to
F5SIRT@f5.com
or via one of the methods listed
here.

Patches are signed using one of the
PGP public keys.

Special considerations

njs does not evaluate dynamic code,
especially code received from the network, in any way.
The only way to evaluate that code using njs
is to configure the
js_import
directive in nginx.
JavaScript code is loaded once during nginx start.

In the nginx/njs threat model, JavaScript code is considered a trusted source
in the same way as nginx.conf and sites certificates.
What this means in practice:

memory disclosure and other security issues
triggered by JavaScript code modification
are not considered security vulnerabilities, but rather ordinary bugs

measures should be taken for protecting JavaScript code used by njs

if no js_import
directives are present in nginx.conf,
nginx is safe from JavaScript-related vulnerabilities

Advisories

Heap buffer overflow in js_fetch_proxy
Severity: medium
Advisory
CVE-2026-8711
Not vulnerable: 0.9.9+
Vulnerable: 0.9.4-0.9.8
Writing njs code using TypeScript definition files

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Writing njs code using TypeScript definition files

Compiling TypeScript definition files
API checks and autocompletions
Writing njs type-safe code

TypeScript is
a typed superset of JavaScript
that compiles to plain JavaScript.

TypeScript supports definition files that contain
type information of existing JavaScript libraries.
This enables other programs to use the values defined in the files
as if they were statically typed TypeScript entities.

njs provides TypeScript definition files for its
API which can be used to:

Get autocompletion and API check in an editor

Write njs type-safe code

Compiling TypeScript definition files

$ git clone https://github.com/nginx/njs
$ cd njs && ./configure && make ts
$ ls build/ts/
njs_core.d.ts
njs_shell.d.ts
ngx_http_js_module.d.ts
ngx_stream_js_module.d.ts

API checks and autocompletions

Put *.d.ts files to a place where you editor can find it.

test.js:

/// <reference path="ngx_http_js_module.d.ts" />
/**
* @param {NginxHTTPRequest} r
* */
function content_handler(r) {
r.headersOut['content-type'] = 'text/plain';
r.return(200, "Hello");
}

Writing njs type-safe code

test.ts:

/// <reference path="ngx_http_js_module.d.ts" />
function content_handler(r: NginxHTTPRequest) {
r.headersOut['content-type'] = 'text/plain';
r.return(200, "Hello from TypeScript");
}

TypeScript installation:

# npm install -g typescript

TypeScript compilation:

$ tsc test.ts
$ cat test.js

The resulting test.js file can be used directly with njs.
Module ngx_stream_access_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_access_module

Example Configuration
Directives
allow
deny

The ngx_stream_access_module module (1.9.2) allows
limiting access to certain client addresses.

Example Configuration

server {
...
deny 192.168.1.1;
allow 192.168.1.0/24;
allow 10.1.1.0/16;
allow 2001:0db8::/32;
deny all;
}

The rules are checked in sequence until the first match is found.
In this example, access is allowed only for IPv4 networks
10.1.1.0/16 and 192.168.1.0/24
excluding the address 192.168.1.1,
and for IPv6 network 2001:0db8::/32.

Directives

Syntax:

allow
address |
CIDR |
unix: |
all;

Default:

—

Context:

stream, server

Allows access for the specified network or address.
If the special value unix: is specified,
allows access for all UNIX-domain sockets.

Syntax:

deny
address |
CIDR |
unix: |
all;

Default:

—

Context:

stream, server

Denies access for the specified network or address.
If the special value unix: is specified,
denies access for all UNIX-domain sockets.
Module ngx_stream_geoip_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_geoip_module

Example Configuration
Directives
geoip_country
geoip_city
geoip_org

The ngx_stream_geoip_module module (1.11.3) creates variables
with values depending on the client IP address, using the precompiled
MaxMind databases.

When using the databases with IPv6 support,
IPv4 addresses are looked up as IPv4-mapped IPv6 addresses.

This module is not built by default, it should be enabled with the
--with-stream_geoip_module
configuration parameter.

This module requires the
MaxMind GeoIP library.

Example Configuration

stream {
geoip_country GeoIP.dat;
geoip_city GeoLiteCity.dat;

map $geoip_city_continent_code $nearest_server {
default example.com;
EU eu.example.com;
NA na.example.com;
AS as.example.com;
}
...
}

Directives

Syntax:

geoip_country file;

Default:

—

Context:

stream

Specifies a database used to determine the country
depending on the client IP address.
The following variables are available when using this database:

$geoip_country_code

two-letter country code, for example,
“RU”, “US”.

$geoip_country_code3

three-letter country code, for example,
“RUS”, “USA”.

$geoip_country_name

country name, for example,
“Russian Federation”, “United States”.

Syntax:

geoip_city file;

Default:

—

Context:

stream

Specifies a database used to determine the country, region, and city
depending on the client IP address.
The following variables are available when using this database:

$geoip_area_code

telephone area code (US only).

This variable may contain outdated information since
the corresponding database field is deprecated.

$geoip_city_continent_code

two-letter continent code, for example,
“EU”, “NA”.

$geoip_city_country_code

two-letter country code, for example,
“RU”, “US”.

$geoip_city_country_code3

three-letter country code, for example,
“RUS”, “USA”.

$geoip_city_country_name

country name, for example,
“Russian Federation”, “United States”.

$geoip_dma_code

DMA region code in US (also known as “metro code”), according to the
geotargeting
in Google AdWords API.

$geoip_latitude

latitude.

$geoip_longitude

longitude.

$geoip_region

two-symbol country region code (region, territory, state, province, federal land
and the like), for example,
“48”, “DC”.

$geoip_region_name

country region name (region, territory, state, province, federal land
and the like), for example,
“Moscow City”, “District of Columbia”.

$geoip_city

city name, for example,
“Moscow”, “Washington”.

$geoip_postal_code

postal code.

Syntax:

geoip_org file;

Default:

—

Context:

stream

Specifies a database used to determine the organization
depending on the client IP address.
The following variable is available when using this database:

$geoip_org

organization name, for example, “The University of Melbourne”.
Module ngx_stream_geo_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_geo_module

Example Configuration
Directives
geo

The ngx_stream_geo_module module (1.11.3) creates variables
with values depending on the client IP address.

Example Configuration

geo $geo {
default 0;

127.0.0.1 2;
192.168.1.0/24 1;
10.1.0.0/16 1;

::1 2;
2001:0db8::/32 1;
}

Directives

Syntax:

geo [$address] $variable { ... }

Default:

—

Context:

stream

Describes the dependency of values of the specified variable
on the client IP address.
By default, the address is taken from the $remote_addr variable,
but it can also be taken from another variable, for example:

geo $arg_remote_addr $geo {
...;
}

Since variables are evaluated only when used, the mere existence
of even a large number of declared “geo” variables
does not cause any extra costs for connection processing.

If the value of a variable does not represent a valid IP address
then the “255.255.255.255” address is used.

Addresses are specified either as prefixes in CIDR notation
(including individual addresses) or as ranges.

The following special parameters are also supported:

delete

deletes the specified network.

default

a value set to the variable if the client address does not
match any of the specified addresses.
When addresses are specified in CIDR notation,
“0.0.0.0/0” and “::/0”
can be used instead of default.
When default is not specified, the default
value will be an empty string.

include

includes a file with addresses and values.
There can be several inclusions.

ranges

indicates that addresses are specified as ranges.
This parameter should be the first.
To speed up loading of a geo base, addresses should be put in ascending order.

volatile

indicates that the variable is not cacheable (1.29.3).

Example:

geo $country {
default ZZ;
include conf/geo.conf;
delete 127.0.0.0/16;

127.0.0.0/24 US;
127.0.0.1/32 RU;
10.1.0.0/16 RU;
192.168.1.0/24 UK;
}

The conf/geo.conf file could contain the following lines:

10.2.0.0/16 RU;
192.168.2.0/24 RU;

A value of the most specific match is used.
For example, for the 127.0.0.1 address the value “RU”
will be chosen, not “US”.

Example with ranges:

geo $country {
ranges;
default ZZ;
127.0.0.0-127.0.0.0 US;
127.0.0.1-127.0.0.1 RU;
127.0.0.1-127.0.0.255 US;
10.1.0.0-10.1.255.255 RU;
192.168.1.0-192.168.1.255 UK;
}
Module ngx_stream_keyval_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_keyval_module

Example Configuration
Directives
keyval
keyval_zone

The ngx_stream_keyval_module module (1.13.7) creates variables
with values taken from key-value pairs managed by the
API
or a variable that can also be set with
njs.

This module is available as part of our
commercial subscription.

Example Configuration

http {

server {
...
location /api {
api write=on;
}
}
}

stream {

keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval;
keyval $ssl_server_name $name zone=one;

server {
listen 12345 ssl;
proxy_pass $name;
ssl_certificate /usr/local/nginx/conf/cert.pem;
ssl_certificate_key /usr/local/nginx/conf/cert.key;
}
}

Directives

Syntax:

keyval
key
$variable
zone=name;

Default:

—

Context:

stream

Creates a new $variable whose value
is looked up by the key in the key-value database.
Matching rules are defined by the
type parameter of the
keyval_zone directive.
The database is stored in a shared memory zone
specified by the zone parameter.

Syntax:

keyval_zone
zone=name:size
[state=file]
[timeout=time]
[type=string|ip|prefix]
[sync];

Default:

—

Context:

stream

Sets the name and size of the shared memory zone
that keeps the key-value database.
Key-value pairs are managed by the
API.

The optional state parameter specifies a file
that keeps the current state of the key-value database in the JSON format
and makes it persistent across nginx restarts.
Changing the file content directly should be avoided.

Examples:

keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; # path for Linux
keyval_zone zone=one:32k state=/var/db/nginx/state/one.keyval; # path for FreeBSD

The optional timeout parameter (1.15.0) sets
the time after which key-value pairs are removed from the zone.

The optional type parameter (1.17.1) activates
an extra index optimized for matching the key of a certain type
and defines matching rules when evaluating
a keyval $variable.

The index is stored in the same shared memory zone
and thus requires additional storage.

type=string

default, no index is enabled;
variable lookup is performed using exact match
of the record key and a search key

type=ip

the search key is the textual representation of IPv4 or IPv6 address
or CIDR range;
to match a record key, the search key must belong to a subnet
specified by a record key or exactly match an IP address

type=prefix

variable lookup is performed using prefix match
of a record key and a search key (1.17.5);
to match a record key, the record key must be a prefix of the search key

The optional sync parameter (1.15.0) enables
synchronization
of the shared memory zone.
The synchronization requires the
timeout parameter to be set.

If the synchronization is enabled, removal of key-value pairs (no matter
one
or
all)
will be performed only on a target cluster node.
The same key-value pairs on other cluster nodes
will be removed upon timeout.
Module ngx_stream_limit_conn_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_limit_conn_module

Example Configuration
Directives
limit_conn
limit_conn_dry_run
limit_conn_log_level
limit_conn_zone
Embedded Variables

The ngx_stream_limit_conn_module module (1.9.3) is used to
limit the number of connections per the defined key, in
particular, the number of connections from a single IP address.

Example Configuration

stream {
limit_conn_zone $binary_remote_addr zone=addr:10m;

...

server {

...

limit_conn addr 1;
limit_conn_log_level error;
}
}

Directives

Syntax:

limit_conn zone number;

Default:

—

Context:

stream, server

Sets the shared memory zone
and the maximum allowed number of connections for a given key value.
When this limit is exceeded, the server will close the connection.
For example, the directives

limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
...
limit_conn addr 1;
}

allow only one connection per an IP address at a time.

When several limit_conn directives are specified,
any configured limit will apply.

These directives are inherited from the previous configuration level
if and only if there are no limit_conn directives
defined on the current level.

Syntax:

limit_conn_dry_run on | off;

Default:

limit_conn_dry_run off;

Context:

stream, server

This directive appeared in version 1.17.6.

Enables the dry run mode.
In this mode, the number of connections is not limited, however,
in the shared memory zone, the number of excessive connections is accounted
as usual.

Syntax:

limit_conn_log_level
info |
notice |
warn |
error;

Default:

limit_conn_log_level error;

Context:

stream, server

Sets the desired logging level for cases when the server
limits the number of connections.

Syntax:

limit_conn_zone
key
zone=name:size;

Default:

—

Context:

stream

Sets parameters for a shared memory zone
that will keep states for various keys.
In particular, the state includes the current number of connections.
The key can contain text, variables,
and their combinations (1.11.2).
Connections with an empty key value are not accounted.
Usage example:

limit_conn_zone $binary_remote_addr zone=addr:10m;

Here, the key is a client IP address set by the
$binary_remote_addr variable.
The size of $binary_remote_addr
is 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.
The stored state always occupies 32 or 64 bytes
on 32-bit platforms and 64 bytes on 64-bit platforms.
One megabyte zone can keep about 32 thousand 32-byte states
or about 16 thousand 64-byte states.
If the zone storage is exhausted, the server will close the connection.

Additionally, as part of our
commercial subscription,
the
status information
for each such shared memory zone can be
obtained or
reset
with the API since 1.17.7.

Embedded Variables

$limit_conn_status

keeps the result of limiting the number of connections (1.17.6):
PASSED,
REJECTED, or
REJECTED_DRY_RUN
Module ngx_stream_mqtt_filter_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_mqtt_filter_module

Example Configuration
Directives
mqtt
mqtt_buffers
mqtt_rewrite_buffer_size
mqtt_set_connect

The ngx_stream_mqtt_filter_module module (1.23.4) provides
support for Message Queuing Telemetry Transport protocol (MQTT) versions
3.1.1
and
5.0.

This module is available as part of our
commercial subscription.

Example Configuration

listen 127.0.0.1:18883;
proxy_pass backend;
proxy_buffer_size 16k;

mqtt on;
mqtt_set_connect clientid "$client";
mqtt_set_connect username "$name";

Directives

Syntax:

mqtt on | off;

Default:

mqtt off;

Context:

stream, server

Enables the MQTT protocol for the given virtual server.

Syntax:

mqtt_buffers number size;

Default:

mqtt_buffers 100 1k;

Context:

stream, server

This directive appeared in version 1.25.1.

Sets the number and size of the buffers
used for handling MQTT messages,
for a single connection.

Syntax:

mqtt_rewrite_buffer_size size;

Default:

mqtt_rewrite_buffer_size 4k|8k;

Context:

server

This directive is obsolete since version 1.25.1.
The mqtt_buffers
directive should be used instead.

Sets the size of the buffer
used for writing a modified message.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.
It can be made smaller, however.

Syntax:

mqtt_set_connect field value;

Default:

—

Context:

server

Sets the message field
to the given value for CONNECT message.
The following fields are supported:
clientid,
username, and
password.
The value can contain text, variables, and their combination.

Several mqtt_set_connect directives
can be specified on the same level:

mqtt_set_connect clientid "$client";
mqtt_set_connect username "$name";
Module ngx_stream_mqtt_preread_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_mqtt_preread_module

Example Configuration
Directives
mqtt_preread
Embedded Variables

The ngx_stream_mqtt_preread_module module (1.23.4) allows
extracting information from the CONNECT message
of the Message Queuing Telemetry Transport protocol (MQTT) versions
3.1.1
and
5.0,
for example, a username or a client ID.

This module is available as part of our
commercial subscription.

Example Configuration

mqtt_preread on;
return $mqtt_preread_clientid;

Directives

Syntax:

mqtt_preread on | off;

Default:

mqtt_preread off;

Context:

stream, server

Enables extracting information from the MQTT CONNECT message at
the preread phase.

Embedded Variables

$mqtt_preread_clientid

the clientid value from the CONNECT message

$mqtt_preread_username

the username value from the CONNECT message
Module ngx_stream_num_map_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_num_map_module

Example Configuration
Directives
num_map

The ngx_stream_num_map_module module (1.29.3)
creates variables whose values depend on numeric values
or numeric value ranges.

This module is available as part of our
commercial subscription.

Example Configuration

num_map $remote_port $port_allow {
default 0;

80 1;
443 1;
<=1023 0;
8080-8090 1;
}

Directives

Syntax:

num_map
[$number]
$variable { ... }

Default:

—

Context:

stream

Describes how the values of the specified variable depend on numeric values
or numeric value ranges.

Since variables are evaluated only when used, the mere existence
of even a large number of declared “num_map” variables
does not cause any extra costs for connection processing.

Parameters inside the num_map block specify a mapping
between source and resulting values.

Source values are specified as numbers or as numeric ranges.

The following special parameters are also supported:

default

sets the resulting value if the source value matches none
of the specified variants.
When default is not specified, the default
resulting value will be an empty string.

include

includes a file with values.
There can be several inclusions.

volatile

indicates that the variable is not cacheable.
Module ngx_stream_pass_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_pass_module

Example Configuration
Directives
pass

The ngx_stream_pass_module module (1.25.5) allows
passing the accepted connection directly to any configured listening socket
in http, stream, mail,
and other similar modules.

Example Configuration

http {
server {
listen 8000;

location / {
root html;
}
}
}

stream {
server {
listen 12345 ssl;

ssl_certificate domain.crt;
ssl_certificate_key domain.key;

pass 127.0.0.1:8000;
}
}

In the example,
after terminating SSL/TLS in the stream module
the connection is passed to the http module.

Directives

Syntax:

pass address;

Default:

—

Context:

server

Sets server address to pass client connection to.
The address can be specified as an IP address
and a port:

pass 127.0.0.1:12345;

or as a UNIX-domain socket path:

pass unix:/tmp/stream.socket;

The address can also be specified using variables:

pass $upstream;
Module ngx_stream_proxy_protocol_vendor_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_proxy_protocol_vendor_module

Example Configuration
Embedded Variables

The ngx_stream_proxy_protocol_vendor_module module (1.23.3)
allows obtaining additional information about a connection in
cloud platforms from application-specific TLVs of the
PROXY
protocol
header.

Supported cloud platforms:

Amazon Web Services

Google Cloud Platform

Microsoft Azure

The PROXY protocol must be previously enabled by setting the
proxy_protocol parameter
in the listen directive.

This module is available as part of our
commercial subscription.

Example Configuration

server {
listen 12345 proxy_protocol;
return $proxy_protocol_tlv_gcp_conn_id;
}

Embedded Variables

$proxy_protocol_tlv_aws_vpce_id

TLV value from the PROXY Protocol header representing the
ID
of AWS VPC endpoint

$proxy_protocol_tlv_azure_pel_id

TLV value from the PROXY Protocol header representing the
LinkID
of Azure private endpoint

$proxy_protocol_tlv_gcp_conn_id

TLV value from the PROXY Protocol header representing
Google Cloud PSC
connection ID
Module ngx_stream_realip_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_realip_module

Example Configuration
Directives
set_real_ip_from
Embedded Variables

The ngx_stream_realip_module module is used
to change the client address and port
to the ones sent in the PROXY protocol header (1.11.4).
The PROXY protocol must be previously enabled by setting the
proxy_protocol parameter
in the listen directive.

This module is not built by default, it should be enabled with the
--with-stream_realip_module
configuration parameter.

Example Configuration

listen 12345 proxy_protocol;

set_real_ip_from 192.168.1.0/24;
set_real_ip_from 192.168.2.1;
set_real_ip_from 2001:0db8::/32;

Directives

Syntax:

set_real_ip_from
address |
CIDR |
unix:;

Default:

—

Context:

stream, server

Defines trusted addresses that are known to send correct
replacement addresses.
If the special value unix: is specified,
all UNIX-domain sockets will be trusted.

Embedded Variables

$realip_remote_addr

keeps the original client address

$realip_remote_port

keeps the original client port
Module ngx_stream_return_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_return_module

Example Configuration
Directives
return

The ngx_stream_return_module module (1.11.2) allows
sending a specified value to the client and then closing the connection.

Example Configuration

server {
listen 12345;
return $time_iso8601;
}

Directives

Syntax:

return value;

Default:

—

Context:

server

Specifies a value to send to the client.
The value can contain text, variables, and their combination.
Module ngx_stream_set_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_set_module

Example Configuration
Directives
set

The ngx_stream_set_module module (1.19.3) allows
setting a value for a variable.

Example Configuration

server {
listen 12345;
set $true 1;
}

Directives

Syntax:

set $variable value;

Default:

—

Context:

server

Sets a value for the specified variable.
The value can contain text, variables, and their combination.
Module ngx_stream_split_clients_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_split_clients_module

Example Configuration
Directives
split_clients

The ngx_stream_split_clients_module module (1.11.3) creates
variables suitable for A/B testing, also known as split testing.

Example Configuration

stream {
...
split_clients "${remote_addr}AAA" $upstream {
0.5% feature_test1;
2.0% feature_test2;
* production;
}

server {
...
proxy_pass $upstream;
}
}

Directives

Syntax:

split_clients
string
$variable { ... }

Default:

—

Context:

stream

Creates a variable for A/B testing, for example:

split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}

The value of the original string is hashed using MurmurHash2.
In the example given, hash values from 0 to 21474835 (0.5%)
correspond to the
value ".one" of the $variant variable,
hash values from 21474836 to 107374180 (2%) correspond to
the value ".two",
and hash values from 107374181 to 4294967295 correspond to
the value "" (an empty string).
Module ngx_stream_ssl_preread_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_stream_ssl_preread_module

Example Configuration
Directives
ssl_preread
Embedded Variables

The ngx_stream_ssl_preread_module module (1.11.5) allows
extracting information from the
ClientHello
message without terminating SSL/TLS,
for example, the server name requested through
SNI
or protocols advertised in
ALPN.
This module is not built by default, it should be enabled with the
--with-stream_ssl_preread_module
configuration parameter.

Example Configuration

Selecting an upstream based on server name:

map $ssl_preread_server_name $name {
backend.example.com backend;
default backend2;
}

upstream backend {
server 192.168.0.1:12345;
server 192.168.0.2:12345;
}

upstream backend2 {
server 192.168.0.3:12345;
server 192.168.0.4:12345;
}

server {
listen 12346;
proxy_pass $name;
ssl_preread on;
}

Selecting an upstream based on protocol:

map $ssl_preread_alpn_protocols $proxy {
~\bh2\b 127.0.0.1:8001;
~\bhttp/1.1\b 127.0.0.1:8002;
~\bxmpp-client\b 127.0.0.1:8003;
}

server {
listen 9000;
proxy_pass $proxy;
ssl_preread on;
}

Selecting an upstream based on SSL protocol version:

map $ssl_preread_protocol $upstream {
"" ssh.example.com:22;
"TLSv1.2" new.example.com:443;
default tls.example.com:443;
}

# ssh and https on the same port
server {
listen 192.168.0.1:443;
proxy_pass $upstream;
ssl_preread on;
}

Directives

Syntax:

ssl_preread on | off;

Default:

ssl_preread off;

Context:

stream, server

Enables extracting information from the ClientHello message at
the preread phase.

Embedded Variables

$ssl_preread_protocol

the highest SSL protocol version supported by the client (1.15.2)

$ssl_preread_server_name

server name requested through SNI

$ssl_preread_alpn_protocols

list of protocols advertised by the client through ALPN (1.13.10).
The values are separated by commas.
How nginx processes a TCP/UDP session

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

How nginx processes a TCP/UDP session

A TCP/UDP session from a client is processed
in successive steps called phases:

Post-accept

The first phase after accepting a client connection.
The ngx_stream_realip_module
module is invoked at this phase.

Pre-access

Preliminary check for access.
The
ngx_stream_limit_conn_module
and
ngx_stream_set_module
modules are invoked at this phase.

Access

Client access limitation before actual data processing.
At this phase,
the ngx_stream_access_module
module is invoked,
for njs,
the js_access directive
is invoked.

SSL

TLS/SSL termination.
The ngx_stream_ssl_module
module is invoked at this phase.

Preread

Reading initial bytes of data into the
preread buffer
to allow modules such as
ngx_stream_ssl_preread_module
analyze the data before its processing.
For njs,
the js_preread directive
is invoked at this phase.

Content

Mandatory phase where data is actually processed, usually
proxied to
upstream servers,
or a specified value
is returned to a client.
For njs,
the js_filter directive
is invoked at this phase.

Log

The final phase
where the result of a client session processing is recorded.
The ngx_stream_log_module
module is invoked at this phase.