hannah-eee/nginx-docs huggingface dataset:
Module ngx_http_f4f_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_http_f4f_module

Example Configuration
Directives
f4f
f4f_buffer_size

The ngx_http_f4f_module module provides
server-side support for Adobe HTTP Dynamic Streaming (HDS).

This module implements handling of HTTP Dynamic Streaming requests in the
“/videoSeg1-Frag1” form — extracting the needed fragment
from the videoSeg1.f4f file using the videoSeg1.f4x
index file.
This module is an alternative to the Adobe’s f4f module (HTTP Origin Module)
for Apache.

Usual pre-processing with Adobe’s f4fpackager is required, see relevant
documentation for details.

This module is available as part of our
commercial subscription.

Example Configuration

location /video/ {
f4f;
...
}

Directives

Syntax:

f4f;

Default:

—

Context:

location

Turns on module processing in the surrounding location.

Syntax:

f4f_buffer_size size;

Default:

f4f_buffer_size 512k;

Context:

http, server, location

Sets the size of the buffer used for
reading the .f4x index file.
Module ngx_http_flv_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_http_flv_module

Example Configuration
Directives
flv

The ngx_http_flv_module module provides pseudo-streaming
server-side support for Flash Video (FLV) files.

It handles requests with the start argument in
the request URI’s query string specially, by sending back the contents
of a file starting from the requested byte offset and with the prepended FLV
header.

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

Example Configuration

location ~ \.flv$ {
flv;
}

Directives

Syntax:

flv;

Default:

—

Context:

location

Turns on module processing in a surrounding location.
Module ngx_http_gunzip_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_http_gunzip_module

Example Configuration
Directives
gunzip
gunzip_buffers

The ngx_http_gunzip_module module is a filter that
decompresses responses with “Content-Encoding: gzip”
for clients that do not support “gzip” encoding method.
The module will be useful when it is desirable to store
data compressed to save space and reduce I/O costs.

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

Example Configuration

location /storage/ {
gunzip on;
...
}

Directives

Syntax:

gunzip on | off;

Default:

gunzip off;

Context:

http, server, location

Enables or disables decompression of gzipped responses
for clients that lack gzip support.
If enabled, the following directives are also taken into account
when determining if clients support gzip:
gzip_http_version,
gzip_proxied, and
gzip_disable.
See also the gzip_vary directive.

Syntax:

gunzip_buffers number size;

Default:

gunzip_buffers 32 4k|16 8k;

Context:

http, server, location

Sets the number and size of buffers
used to decompress a response.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.
Module ngx_http_gzip_static_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_http_gzip_static_module

Example Configuration
Directives
gzip_static

The ngx_http_gzip_static_module module allows
sending precompressed files with the “.gz”
filename extension instead of regular files.

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

Example Configuration

gzip_static on;
gzip_proxied expired no-cache no-store private auth;

Directives

Syntax:

gzip_static
on |
off |
always;

Default:

gzip_static off;

Context:

http, server, location

Enables (“on”) or disables (“off”)
checking the existence of precompressed files.
The following directives are also taken into account:
gzip_http_version,
gzip_proxied,
gzip_disable,
and gzip_vary.

With the “always” value (1.3.6), gzipped file is used
in all cases, without checking if the client supports it.
It is useful if there are no uncompressed files on the disk anyway
or the ngx_http_gunzip_module
is used.

The files can be compressed using the gzip command,
or any other compatible one.
It is recommended that the modification date and time of original and
compressed files be the same.
Module ngx_http_index_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_http_index_module

Example Configuration
Directives
index

The ngx_http_index_module module processes requests
ending with the slash character (‘/’).
Such requests can also be processed by the
ngx_http_autoindex_module
and
ngx_http_random_index_module
modules.

Example Configuration

location / {
index index.$geo.html index.html;
}

Directives

Syntax:

index file ...;

Default:

index index.html;

Context:

http, server, location

Defines files that will be used as an index.
The file name can contain variables.
Files are checked in the specified order.
The last element of the list can be a file with an absolute path.
Example:

index index.$geo.html index.0.html /index.html;

It should be noted that using an index file causes an internal redirect,
and the request can be processed in a different location.
For example, with the following configuration:

location = / {
index index.html;
}

location / {
...
}

a “/” request will actually be processed in the
second location as “/index.html”.
Module ngx_http_internal_redirect_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_http_internal_redirect_module

Example Configuration
Directives
internal_redirect

The ngx_http_internal_redirect_module module (1.23.4) allows
making an internal redirect.
In contrast to
rewriting URIs,
the redirection is made after checking
request and
connection processing limits,
and access limits.

This module is available as part of our
commercial subscription.

Example Configuration

limit_req_zone $jwt_claim_sub zone=jwt_sub:10m rate=1r/s;

server {
location / {
auth_jwt "realm";
auth_jwt_key_file key.jwk;

internal_redirect @rate_limited;
}

location @rate_limited {
internal;

limit_req zone=jwt_sub burst=10;
proxy_pass http://backend;
}
}

The example implements
per-user
rate limiting.
Implementation without internal_redirect
is vulnerable to DoS attacks by unsigned JWTs, as normally the
limit_req
check is performed
before
auth_jwt check.
Using internal_redirect
allows reordering these checks.

Directives

Syntax:

internal_redirect uri;

Default:

—

Context:

server, location

Sets the URI for internal redirection of the request.
It is also possible to use a
named location
instead of the URI.
The uri value can contain variables.
If the uri value is empty,
then the redirect will not be made.
Module ngx_http_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_http_keyval_module

Example Configuration
Directives
keyval
keyval_zone

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

This module is available as part of our
commercial subscription.

Example Configuration

http {

keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval;
keyval $arg_text $text zone=one;
...
server {
...
location / {
return 200 $text;
}

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

Directives

Syntax:

keyval
key
$variable
zone=name;

Default:

—

Context:

http

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:

http

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_http_mirror_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_http_mirror_module

Example Configuration
Directives
mirror
mirror_request_body

The ngx_http_mirror_module module (1.13.4) implements
mirroring of an original request
by creating background mirror subrequests.
Responses to mirror subrequests are ignored.

Example Configuration

location / {
mirror /mirror;
proxy_pass http://backend;
}

location = /mirror {
internal;
proxy_pass http://test_backend$request_uri;
}

Directives

Syntax:

mirror uri | off;

Default:

mirror off;

Context:

http, server, location

Sets the URI to which an original request will be mirrored.
Several mirrors can be specified on the same configuration level.

Syntax:

mirror_request_body on | off;

Default:

mirror_request_body on;

Context:

http, server, location

Indicates whether the client request body is mirrored.
When enabled, the client request body will be read
prior to creating mirror subrequests.
In this case, unbuffered client request body proxying
set by the
proxy_request_buffering,
fastcgi_request_buffering,
scgi_request_buffering,
and
uwsgi_request_buffering
directives will be disabled.

location / {
mirror /mirror;
mirror_request_body off;
proxy_pass http://backend;
}

location = /mirror {
internal;
proxy_pass http://log_backend;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
Module ngx_http_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_http_num_map_module

Example Configuration
Directives
num_map

The ngx_http_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:

http

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 request 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_http_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_http_proxy_protocol_vendor_module

Example Configuration
Embedded Variables

The ngx_http_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

proxy_set_header X-Conn-ID $proxy_protocol_tlv_gcp_conn_id;

server {
listen 80 proxy_protocol;
listen 443 ssl proxy_protocol;
...
}

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_http_random_index_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_http_random_index_module

Example Configuration
Directives
random_index

The ngx_http_random_index_module module processes requests
ending with the slash character (‘/’) and picks a random
file in a directory to serve as an index file.
The module is processed before the
ngx_http_index_module
module.

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

Example Configuration

location / {
random_index on;
}

Directives

Syntax:

random_index on | off;

Default:

random_index off;

Context:

location

Enables or disables module processing in a surrounding location.
Module ngx_http_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_http_realip_module

Example Configuration
Directives
set_real_ip_from
real_ip_header
real_ip_recursive
Embedded Variables

The ngx_http_realip_module module is used
to change the client address and optional port
to those sent in the specified header field.

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

Example Configuration

set_real_ip_from 192.168.1.0/24;
set_real_ip_from 192.168.2.1;
set_real_ip_from 2001:0db8::/32;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Directives

Syntax:

set_real_ip_from
address |
CIDR |
unix:;

Default:

—

Context:

http, server, location

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.
Trusted addresses may also be specified using a hostname (1.13.1).

IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1.

Syntax:

real_ip_header
field |
X-Real-IP |
X-Forwarded-For |
proxy_protocol;

Default:

real_ip_header X-Real-IP;

Context:

http, server, location

Defines the request header field
whose value will be used to replace the client address.

The request header field value that contains an optional port
is also used to replace the client port (1.11.0).
The address and port should be specified according to
RFC 3986.

The proxy_protocol parameter (1.5.12) changes
the client address to the one from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the
proxy_protocol parameter
in the listen directive.

Syntax:

real_ip_recursive on | off;

Default:

real_ip_recursive off;

Context:

http, server, location

This directive appeared in versions 1.3.0 and 1.2.1.

If recursive search is disabled, the original client address that
matches one of the trusted addresses is replaced by the last
address sent in the request header field defined by the
real_ip_header directive.
If recursive search is enabled, the original client address that
matches one of the trusted addresses is replaced by the last
non-trusted address sent in the request header field.

Embedded Variables

$realip_remote_addr

keeps the original client address (1.9.7)

$realip_remote_port

keeps the original client port (1.11.0)
Module ngx_http_referer_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_http_referer_module

Example Configuration
Directives
referer_hash_bucket_size
referer_hash_max_size
valid_referers
Embedded Variables

The ngx_http_referer_module module is used to block
access to a site for requests with invalid values in the
“Referer” header field.
It should be kept in mind that fabricating a request with an appropriate
“Referer” field value is quite easy, and so the intended
purpose of this module is not to block such requests thoroughly but to block
the mass flow of requests sent by regular browsers.
It should also be taken into consideration that regular browsers may
not send the “Referer” field even for valid requests.

Example Configuration

valid_referers none blocked server_names
*.example.com example.* www.example.org/galleries/
~\.google\.;

if ($invalid_referer) {
return 403;
}

Directives

Syntax:

referer_hash_bucket_size size;

Default:

referer_hash_bucket_size 64;

Context:

server, location

This directive appeared in version 1.0.5.

Sets the bucket size for the valid referers hash tables.
The details of setting up hash tables are provided in a separate
document.

Syntax:

referer_hash_max_size size;

Default:

referer_hash_max_size 2048;

Context:

server, location

This directive appeared in version 1.0.5.

Sets the maximum size of the valid referers hash tables.
The details of setting up hash tables are provided in a separate
document.

Syntax:

valid_referers
none |
blocked |
server_names |
string
...;

Default:

—

Context:

server, location

Specifies the “Referer” request header field values
that will cause the embedded $invalid_referer variable to
be set to an empty string.
Otherwise, the variable will be set to “1”.
Search for a match is case-insensitive.

Parameters can be as follows:

none

the “Referer” field is missing in the request header;

blocked

the “Referer” field is present in the request header,
but its value has been deleted by a firewall or proxy server;
such values are strings that do not start with
“http://” or “https://”;

server_names

the “Referer” request header field contains
one of the server names;

arbitrary string

defines a server name and an optional URI prefix.
A server name can have an “*” at the beginning or end.
During the checking, the server’s port in the “Referer” field
is ignored;

regular expression

the first symbol should be a “~”.
It should be noted that an expression will be matched against
the text starting after the “http://”
or “https://”.

Example:

valid_referers none blocked server_names
*.example.com example.* www.example.org/galleries/
~\.google\.;

Embedded Variables

$invalid_referer

Empty string, if the “Referer” request header field
value is considered
valid, otherwise “1”.
Module ngx_http_session_log_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_http_session_log_module

Example Configuration
Directives
session_log
session_log_format
session_log_zone
Embedded Variables

The ngx_http_session_log_module module enables logging
sessions (that is, aggregates of multiple HTTP requests) instead of
individual HTTP requests.

This module is available as part of our
commercial subscription.

Example Configuration

The following configuration sets up a session log and maps requests to
sessions according to the request client address and “User-Agent”
request header field:

session_log_zone /path/to/log format=combined
zone=one:1m timeout=30s
md5=$binary_remote_addr$http_user_agent;

location /media/ {
session_log one;
}

Directives

Syntax:

session_log name | off;

Default:

session_log off;

Context:

http, server, location

Enables the use of the specified session log.
The special value off cancels the effect
of the session_log directives
inherited from the previous configuration level.

Syntax:

session_log_format
name
string ...;

Default:

session_log_format combined "...";

Context:

http

Specifies the output format of a log.
The value of the $body_bytes_sent variable is aggregated across
all requests in a session.
The values of all other variables available for logging correspond to the
first request in a session.

Syntax:

session_log_zone
path
zone=name:size
[format=format]
[timeout=time]
[id=id]
[md5=md5]
;

Default:

—

Context:

http

Sets the path to a log file and configures the shared memory zone that is used
to store currently active sessions.

A session is considered active for as long as the time elapsed since
the last request in the session does not exceed the specified
timeout (by default, 30 seconds).
Once a session is no longer active, it is written to the log.

The id parameter identifies the
session to which a request is mapped.
The id parameter is set to the hexadecimal representation
of an MD5 hash (for example, obtained from a cookie using variables).
If this parameter is not specified or does not represent the valid
MD5 hash, nginx computes the MD5 hash from the value of
the md5 parameter and creates a new session using this hash.
Both the id and md5 parameters
can contain variables.

The format parameter sets the custom session log
format configured by the session_log_format directive.
If format is not specified, the predefined
“combined” format is used.

Embedded Variables

The ngx_http_session_log_module module supports
two embedded variables:

$session_log_id

current session ID;

$session_log_binary_id

current session ID in binary form (16 bytes).
Module ngx_http_slice_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_http_slice_module

Known Issues
Example Configuration
Directives
slice
Embedded Variables

The ngx_http_slice_module module (1.9.8) is a filter
that splits a request into subrequests,
each returning a certain range of response.
The filter provides more effective caching of big responses.

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

Known Issues

Currently, the module does not work as expected in subrequests such as

background cache update.
In this case, a request is constructed without byte-range support.

Example Configuration

location / {
slice 1m;
proxy_cache cache;
proxy_cache_key $uri$is_args$args$slice_range;
proxy_set_header Range $slice_range;
proxy_cache_valid 200 206 1h;
proxy_pass http://localhost:8000;
}

In this example,
the response is split into 1-megabyte cacheable slices.

Directives

Syntax:

slice size;

Default:

slice 0;

Context:

http, server, location

Sets the size of the slice.
The zero value disables splitting responses into slices.
Note that a too low value may result in excessive memory usage
and opening a large number of files.

In order for a subrequest to return the required range,
the $slice_range variable should be
passed to
the proxied server as the Range request header field.
If
caching
is enabled, $slice_range should be added to the
cache key
and caching of responses with 206 status code should be
enabled.

Embedded Variables

The ngx_http_slice_module module
supports the following embedded variables:

$slice_range

the current slice range in
HTTP
byte range format,
for example, bytes=0-1048575.
Module ngx_http_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_http_split_clients_module

Example Configuration
Directives
split_clients

The ngx_http_split_clients_module module creates
variables suitable for A/B testing, also known as split testing.

Example Configuration

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

server {
location / {
index index${variant}.html;

Directives

Syntax:

split_clients
string
$variable { ... }

Default:

—

Context:

http

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_http_stub_status_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_http_stub_status_module

Example Configuration
Directives
stub_status
Data
Embedded Variables

The ngx_http_stub_status_module module provides
access to basic status information.

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

Example Configuration

location = /basic_status {
stub_status;
}

This configuration creates a simple web page
with basic status data which may look like as follows:

Active connections: 291
server accepts handled requests
16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106

Directives

Syntax:

stub_status;

Default:

—

Context:

server, location

The basic status information will be accessible from the surrounding location.

In versions prior to 1.7.5,
the directive syntax required an arbitrary argument, for example,
“stub_status on”.

Data

The following status information is provided:

Active connections

The current number of active client connections
including Waiting connections.

accepts

The total number of accepted client connections.

handled

The total number of handled connections.
Generally, the parameter value is the same as accepts
unless some resource limits have been reached
(for example, the
worker_connections limit).

requests

The total number of client requests.

Reading

The current number of connections where nginx is reading the request header.

Writing

The current number of connections
where nginx is writing the response back to the client.

Waiting

The current number of idle client connections waiting for a request.

Embedded Variables

The ngx_http_stub_status_module module
supports the following embedded variables (1.3.14):

$connections_active

same as the Active connections value;

$connections_reading

same as the Reading value;

$connections_writing

same as the Writing value;

$connections_waiting

same as the Waiting value.
Module ngx_http_sub_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_http_sub_module

Example Configuration
Directives
sub_filter
sub_filter_last_modified
sub_filter_once
sub_filter_types

The ngx_http_sub_module module is a filter
that modifies a response by replacing one specified string by another.

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

Example Configuration

location / {
sub_filter '<a href="http://127.0.0.1:8080/' '<a href="https://$host/';
sub_filter '<img src="http://127.0.0.1:8080/' '<img src="https://$host/';
sub_filter_once on;
}

Directives

Syntax:

sub_filter string replacement;

Default:

—

Context:

http, server, location

Sets a string to replace and a replacement string.
The string to replace is matched ignoring the case.
The string to replace (1.9.4) and replacement string can contain variables.
Several sub_filter directives
can be specified on the same configuration level (1.9.4).
These directives are inherited from the previous configuration level
if and only if there are no sub_filter directives
defined on the current level.

Syntax:

sub_filter_last_modified on | off;

Default:

sub_filter_last_modified off;

Context:

http, server, location

This directive appeared in version 1.5.1.

Allows preserving the “Last-Modified” header field
from the original response during replacement
to facilitate response caching.

By default, the header field is removed as contents of the response
are modified during processing.

Syntax:

sub_filter_once on | off;

Default:

sub_filter_once on;

Context:

http, server, location

Indicates whether to look for each string to replace
once or repeatedly.

Syntax:

sub_filter_types mime-type ...;

Default:

sub_filter_types text/html;

Context:

http, server, location

Enables string replacement in responses with the specified MIME types
in addition to “text/html”.
The special value “*” matches any MIME type (0.8.29).
WebSocket proxying

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

WebSocket proxying

To turn a connection between a client and server from HTTP/1.1 into WebSocket,
the protocol
switch mechanism available in HTTP/1.1 is used.

There is one subtlety however: since the “Upgrade” is a
hop-by-hop
header, it is not passed from a client to proxied server.
With forward proxying, clients may use the CONNECT
method to circumvent this issue.
This does not work with reverse proxying however,
since clients are not aware of any proxy servers,
and special processing on a proxy server is required.

Since version 1.3.13,
nginx implements special mode of operation
that allows setting up a tunnel between a client and proxied
server if the proxied server returned a response with the code
101 (Switching Protocols),
and the client asked for a protocol switch via the “Upgrade”
header in a request.

As noted above, hop-by-hop headers including “Upgrade”
and “Connection” are not passed from a client to proxied
server, therefore in order for the proxied server to know about the client’s
intention to switch a protocol to WebSocket, these headers have to be
passed explicitly:

location /chat/ {
proxy_pass http://backend;
# proxy_http_version 1.1; # before version 1.29.7
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}

A more sophisticated example
in which a value of the “Connection” header field
in a request to the proxied server depends on the presence of
the “Upgrade” field in the client request header:

http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}

server {
...

location /chat/ {
proxy_pass http://backend;
# proxy_http_version 1.1; # before version 1.29.7
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}

By default, the connection will be closed
if the proxied server does not transmit any data within 60 seconds.
This timeout can be increased with the
proxy_read_timeout directive.
Alternatively, the proxied server can be configured
to periodically send WebSocket ping frames to reset the timeout
and check if the connection is still alive.
Module ngx_mail_imap_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_mail_imap_module

Directives
imap_auth
imap_capabilities
imap_client_buffer

Directives

Syntax:

imap_auth method ...;

Default:

imap_auth plain;

Context:

mail, server

Sets permitted methods of authentication for IMAP clients.
Supported methods are:

plain

LOGIN,
AUTH=PLAIN

login

AUTH=LOGIN

cram-md5

AUTH=CRAM-MD5.
In order for this method to work, the password must be stored unencrypted.

external

AUTH=EXTERNAL (1.11.6).

Plain text authentication methods
(the LOGIN command, AUTH=PLAIN,
and AUTH=LOGIN) are always enabled,
though if the plain and login methods
are not specified,
AUTH=PLAIN and AUTH=LOGIN
will not be automatically included in imap_capabilities.

Syntax:

imap_capabilities extension ...;

Default:

imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;

Context:

mail, server

Sets the
IMAP protocol
extensions list that is passed to the client in response to
the CAPABILITY command.
The authentication methods specified in the imap_auth directive and
STARTTLS
are automatically added to this list depending on the
starttls directive value.

It makes sense to specify the extensions
supported by the IMAP backends
to which the clients are proxied (if these extensions are related to commands
used after the authentication, when nginx transparently proxies a client
connection to the backend).

The current list of standardized extensions is published at
www.iana.org.

Syntax:

imap_client_buffer size;

Default:

imap_client_buffer 4k|8k;

Context:

mail, server

Sets the size of the buffer used for reading IMAP commands.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.
Module ngx_mail_pop3_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_mail_pop3_module

Directives
pop3_auth
pop3_capabilities

Directives

Syntax:

pop3_auth method ...;

Default:

pop3_auth plain;

Context:

mail, server

Sets permitted methods of authentication for POP3 clients.
Supported methods are:

plain

USER/PASS,
AUTH PLAIN,
AUTH LOGIN

apop

APOP.
In order for this method to work, the password must be stored unencrypted.

cram-md5

AUTH CRAM-MD5.
In order for this method to work, the password must be stored unencrypted.

external

AUTH EXTERNAL (1.11.6).

Plain text authentication methods
(USER/PASS, AUTH PLAIN,
and AUTH LOGIN) are always enabled,
though if the plain method is not specified,
AUTH PLAIN and AUTH LOGIN
will not be automatically included in pop3_capabilities.

Syntax:

pop3_capabilities extension ...;

Default:

pop3_capabilities TOP USER UIDL;

Context:

mail, server

Sets the
POP3 protocol
extensions list that is passed to the client in response to
the CAPA command.
The authentication methods specified in the pop3_auth directive
(SASL extension) and
STLS
are automatically added to this list depending on the
starttls directive value.

It makes sense to specify the extensions
supported by the POP3 backends
to which the clients are proxied (if these extensions are related to commands
used after the authentication, when nginx transparently proxies the client
connection to the backend).

The current list of standardized extensions is published at
www.iana.org.
Module ngx_mail_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_mail_realip_module

Example Configuration
Directives
set_real_ip_from

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

Example Configuration

listen 110 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:

mail, 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.
Module ngx_mail_smtp_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_mail_smtp_module

Directives
smtp_auth
smtp_capabilities
smtp_client_buffer
smtp_greeting_delay

Directives

Syntax:

smtp_auth method ...;

Default:

smtp_auth plain login;

Context:

mail, server

Sets permitted methods of
SASL authentication
for SMTP clients.
Supported methods are:

plain

AUTH PLAIN

login

AUTH LOGIN

cram-md5

AUTH CRAM-MD5.
In order for this method to work, the password must be stored unencrypted.

external

AUTH EXTERNAL (1.11.6).

none

Authentication is not required.

Plain text authentication methods
(AUTH PLAIN and AUTH LOGIN)
are always enabled,
though if the plain and login methods
are not specified,
AUTH PLAIN and AUTH LOGIN
will not be automatically included in smtp_capabilities.

Syntax:

smtp_capabilities extension ...;

Default:

—

Context:

mail, server

Sets the SMTP protocol extensions list
that is passed to the client in response to the
EHLO command.
The authentication methods specified in the smtp_auth directive and
STARTTLS
are automatically added to this list depending on the
starttls directive value.

It makes sense to specify the extensions
supported by the MTA
to which the clients are proxied (if these extensions are related to commands
used after the authentication, when nginx transparently proxies the client
connection to the backend).

The current list of standardized extensions is published at
www.iana.org.

Syntax:

smtp_client_buffer size;

Default:

smtp_client_buffer 4k|8k;

Context:

mail, server

Sets the size of the buffer used for reading SMTP commands.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.

Syntax:

smtp_greeting_delay time;

Default:

smtp_greeting_delay 0;

Context:

mail, server

Allows setting a delay before sending an SMTP greeting
in order to reject clients who fail to wait for the greeting before
sending SMTP commands.
Command-line interface

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

Command-line interface

njs scripts development and debugging can be performed
from the command-line.
The command-line utility is available after the installation of
the Linux package
or after building from the
sources.
Compared to njs running inside nginx,
nginx objects
(HTTP and
Stream)
are not available in the utility.

$ echo "2**3" | njs -q
8

$ njs
>> globalThis
global {
njs: njs {
version: '0.3.9'
},
global: [Circular],
process: process {
argv: [
'/usr/bin/njs'
],
env: {
PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
HOSTNAME: 'f777c149d4f8',
TERM: 'xterm',
NGINX_VERSION: '1.17.9',
NJS_VERSION: '0.3.9',
PKG_RELEASE: '1~buster',
HOME: '/root'
}
},
console: {
log: [Function: native],
dump: [Function: native],
time: [Function: native],
timeEnd: [Function: native]
},
print: [Function: native]
}
>>
JavaScript Engine

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

JavaScript Engine

Starting from version 0.8.6,
multiple JavaScript engines are supported.
To specify a particular engine, use the js_engine directive
available for both the
http
and
stream.
By default, the njs engine is used.

njs engine

njs is an embeddable JavaScript engine
developed as a part of the njs module.
See the Сompatibility section for details.

QuickJS engine

QuickJS is a lightweight,
embeddable JavaScript engine that supports
the ES2023 specification,
including features as modules, asynchronous generators, proxies and BigInt.

Since version 0.8.6,
a drop-in replacement for
njs/nginx objects
has been introduced
to ensure compatibility with the njs engine, with the following exceptions:

njs-specific API:
njs.dump(),
console.dump().

deprecated API:
require(),
use the import statement instead.

js_preload_object directive for
http
and
stream.

njs built-in modules status:

buffer:
since 0.8.6.

crypto:
since 0.8.10.

fs:
since 0.8.9.

querystring:
since 0.8.10.

WebCrypto:
since 0.8.10.

xml:
since 0.8.10.

zlib:
since 0.8.5.

njs built-in objects status:

process:
since 0.8.8.

TextDecoder:
since 0.8.10.

TextEncoder:
since 0.8.10.

nginx built-in objects status:

ngx.fetch:
since 0.9.1.

shared dictionary:
since 0.8.8.
nginx JavaScript 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

nginx JavaScript module

njs is an nginx module that extends the server's functionality through
JavaScript scripting, enabling the creation of custom
server-side logic and more.

Download and install

Changes

Reference

JavaScript Engine

Native modules

Examples

Security

Compatibility

Command-line interface

Understanding preloaded objects

Tested OS and platforms

ngx_http_js_module

ngx_stream_js_module

Writing njs code using TypeScript definition files

Using node modules with njs

Use cases

Complex access control and security checks in njs
before a request reaches an upstream server

Manipulating response headers

Writing flexible asynchronous content handlers and filters

See examples
for more njs use cases.

Basic HTTP Example

To use njs in nginx:

install njs scripting language

create an njs script file, for example, http.js.
See Reference
for the list of njs properties and methods.

function hello(r) {
r.return(200, "Hello world!");
}

export default {hello};

in the nginx.conf file, enable
ngx_http_js_module module
and specify the
js_import
directive
with the http.js script file:

load_module modules/ngx_http_js_module.so;

events {}

http {
js_import http.js;

server {
listen 8000;

location / {
js_content http.hello;
}
}
}

There is also a standalone command line utility
that can be used independently of nginx for njs development and debugging.

Tested OS and platforms

FreeBSD / amd64;

Linux / x86, amd64, arm64, ppc64el;

Solaris 11 / amd64;

macOS / x86_64;

Presentation at nginx.conf 2018
Download and install

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

Download and install

Installing as a Linux package
Building from the sources
Adding QuickJS engine support
Building njs command-line utility

Installing as a Linux package

For Linux, njs modules
packages can be used:

nginx-module-njs — njs
dynamic modules

nginx-module-njs-dbg — debug symbols for the
nginx-module-njs package

After package installation, njs dynamic modules need to be loaded with the
load_module
directive:

load_module modules/ngx_http_js_module.so;

or

load_module modules/ngx_stream_js_module.so;

Building from the sources

The repository
with njs sources can be cloned with the following command
(requires Git client):

git clone https://github.com/nginx/njs

Then the modules should be compiled from
nginx root directory using the
--add-module configuration parameter:

./configure --add-module=path-to-njs/nginx

The modules can also be built as
dynamic:

./configure --add-dynamic-module=path-to-njs/nginx

Adding QuickJS engine support

Make sure you have built the QuickJS library:

git clone https://github.com/bellard/quickjs
cd quickjs
CFLAGS='-fPIC' make libquickjs.a

At the module compilation step, also
specify the include (-I) and library (-L)
paths with the
--with-cc-opt= and
--with-ld-opt= configuration parameters:

./configure --add-module=path-to-njs/nginx \
--with-cc-opt="-I path-to-quickjs" \
--with-ld-opt="-L path-to-quickjs"

Building njs command-line utility

To build only the njs command-line utility, run
./configure and make njs commands
from njs root directory.
After building, the utility is available as ./build/njs.
Understanding preloaded objects

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

Understanding preloaded objects

For each incoming request njs creates a separate virtual machine.
This brings a lot of benefits such as predictable memory consumption
or requests isolation.
However, as all requests are isolated,
if a request handler needs to access some data,
it has to read it by itself.
This is not efficient especially when the amount of data is large.

To address this limitation,
a preloaded shared object was introduced.
Such objects are created immutable and do not have prototype chains:
their values cannot be changed, properties cannot be added or removed.

Working with preload objects

Here are some examples of how to work with a preload object in njs:

access properties by name:

preloaded_object.prop_name
preloaded_object[prop_name]

enumerate properties:

for (i in preloaded_object_name) {
...
}

apply non-modifying built-in methods using call():

Array.prototype.filter.call(preloaded_object_name, ...)