<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_scgi_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_http_scgi_module

Example Configuration
Directives
     scgi_allow_upstream
     scgi_bind
     scgi_bind_dynamic
     scgi_buffer_size
     scgi_buffering
     scgi_buffers
     scgi_busy_buffers_size
     scgi_cache
     scgi_cache_background_update
     scgi_cache_bypass
     scgi_cache_key
     scgi_cache_lock
     scgi_cache_lock_age
     scgi_cache_lock_timeout
     scgi_cache_max_range_offset
     scgi_cache_methods
     scgi_cache_min_uses
     scgi_cache_path
     scgi_cache_purge
     scgi_cache_revalidate
     scgi_cache_use_stale
     scgi_cache_valid
     scgi_connect_timeout
     scgi_force_ranges
     scgi_hide_header
     scgi_ignore_client_abort
     scgi_ignore_headers
     scgi_intercept_errors
     scgi_limit_rate
     scgi_max_temp_file_size
     scgi_next_upstream
     scgi_next_upstream_timeout
     scgi_next_upstream_tries
     scgi_no_cache
     scgi_param
     scgi_pass
     scgi_pass_header
     scgi_pass_request_body
     scgi_pass_request_headers
     scgi_read_timeout
     scgi_request_buffering
     scgi_request_dynamic
     scgi_send_timeout
     scgi_socket_keepalive
     scgi_store
     scgi_store_access
     scgi_temp_file_write_size
     scgi_temp_path

The ngx_http_scgi_module module allows passing
requests to an SCGI server.

Example Configuration

location / {
    include   scgi_params;
    scgi_pass localhost:9000;
}

Directives

            Syntax:

            scgi_allow_upstream string ...;

            Default:

            —

            Context:

            http, server, location

This directive appeared in version 1.29.3.

Defines conditions under which access to an SCGI server
is allowed or denied.
If all string parameters are not empty
and not equal to “0” then the access is allowed.
The conditions are evaluated each time
before a connection to an SCGI server is established.
Parameter values can contain variables:

geo $upstream_last_addr $allow {
    volatile;
    10.10.0.0/24        1;
}

server {
    listen 127.0.0.1:8080;

    location / {
        scgi_pass           localhost:9000;
        scgi_allow_upstream $allow;
        ...
    }
}

This directive is available as part of our
commercial subscription.

            Syntax:

            scgi_bind
    address
    [transparent] |
    off;

            Default:

            —

            Context:

            http, server, location

Makes outgoing connections to an SCGI server originate
from the specified local IP address with an optional port (1.11.2).
Parameter value can contain variables (1.3.12).
The special value off (1.3.12) cancels the effect
of the scgi_bind directive
inherited from the previous configuration level, which allows the
system to auto-assign the local IP address and port.

The transparent parameter (1.11.0) allows
outgoing connections to an SCGI server originate
from a non-local IP address,
for example, from a real IP address of a client:

scgi_bind $remote_addr transparent;

In order for this parameter to work,
it is usually necessary to run nginx worker processes with the
superuser privileges.
On Linux it is not required (1.13.8) as if
the transparent parameter is specified, worker processes
inherit the CAP_NET_RAW capability from the master process.
It is also necessary to configure kernel routing table
to intercept network traffic from the SCGI server.

            Syntax:

            scgi_bind_dynamic on | off;

            Default:

scgi_bind_dynamic off;

            Context:

            http, server, location

This directive appeared in version 1.29.3.

When enabled, makes the bind operation
at each connection attempt.

This directive is available as part of our
commercial subscription.

            Syntax:

            scgi_buffer_size size;

            Default:

scgi_buffer_size 4k|8k;

            Context:

            http, server, location

Sets the size of the buffer used for reading the first part
of the response received from the SCGI server.
This part usually contains a small response header;
if it exceeds the buffer size, the response is considered
invalid.
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:

            scgi_buffering on | off;

            Default:

scgi_buffering on;

            Context:

            http, server, location

Enables or disables buffering of responses from the SCGI server.

When buffering is enabled, nginx receives a response from the SCGI server
as soon as possible, saving it into the buffers set by the
scgi_buffer_size and scgi_buffers directives.
If the whole response does not fit into memory, a part of it can be saved
to a temporary file on the disk.
Writing to temporary files is controlled by the
scgi_max_temp_file_size and
scgi_temp_file_write_size directives.

When buffering is disabled, the response is passed to a client synchronously,
immediately as it is received.
nginx will not try to read the whole response from the SCGI server.
The maximum size of the data that nginx can receive from the server
at a time is set by the scgi_buffer_size directive.

Buffering can also be enabled or disabled by passing
“yes” or “no” in the
“X-Accel-Buffering” response header field.
This capability can be disabled using the
scgi_ignore_headers directive.

            Syntax:

            scgi_buffers number size;

            Default:

scgi_buffers 8 4k|8k;

            Context:

            http, server, location

Sets the number and size of the
buffers used for reading a response from the SCGI server,
for a single connection.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.

            Syntax:

            scgi_busy_buffers_size size;

            Default:

scgi_busy_buffers_size 8k|16k;

            Context:

            http, server, location

When buffering of responses from the SCGI
server is enabled, limits the total size of buffers that
can be busy sending a response to the client while the response is not
yet fully read.
In the meantime, the rest of the buffers can be used for reading the response
and, if needed, buffering part of the response to a temporary file.
By default, size is limited by the size of two buffers set by the
scgi_buffer_size and scgi_buffers directives.

            Syntax:

            scgi_cache zone | off;

            Default:

scgi_cache off;

            Context:

            http, server, location

Defines a shared memory zone used for caching.
The same zone can be used in several places.
Parameter value can contain variables (1.7.9).
The off parameter disables caching inherited
from the previous configuration level.

            Syntax:

            scgi_cache_background_update on | off;

            Default:

scgi_cache_background_update off;

            Context:

            http, server, location

This directive appeared in version 1.11.10.

Allows starting a background subrequest
to update an expired cache item,
while a stale cached response is returned to the client.
Note that it is necessary to
allow
the usage of a stale cached response when it is being updated.

            Syntax:

            scgi_cache_bypass string ...;

            Default:

            —

            Context:

            http, server, location

Defines conditions under which the response will not be taken from a cache.
If at least one value of the string parameters is not empty and is not
equal to “0” then the response will not be taken from the cache:

scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma    $http_authorization;

Can be used along with the scgi_no_cache directive.

            Syntax:

            scgi_cache_key string;

            Default:

            —

            Context:

            http, server, location

Defines a key for caching, for example

scgi_cache_key localhost:9000$request_uri;

            Syntax:

            scgi_cache_lock on | off;

            Default:

scgi_cache_lock off;

            Context:

            http, server, location

This directive appeared in version 1.1.12.

When enabled, only one request at a time will be allowed to populate
a new cache element identified according to the scgi_cache_key
directive by passing a request to an SCGI server.
Other requests of the same cache element will either wait
for a response to appear in the cache or the cache lock for
this element to be released, up to the time set by the
scgi_cache_lock_timeout directive.

            Syntax:

            scgi_cache_lock_age time;

            Default:

scgi_cache_lock_age 5s;

            Context:

            http, server, location

This directive appeared in version 1.7.8.

If the last request passed to the SCGI server
for populating a new cache element
has not completed for the specified time,
one more request may be passed to the SCGI server.

            Syntax:

            scgi_cache_lock_timeout time;

            Default:

scgi_cache_lock_timeout 5s;

            Context:

            http, server, location

This directive appeared in version 1.1.12.

Sets a timeout for scgi_cache_lock.
When the time expires,
the request will be passed to the SCGI server,
however, the response will not be cached.

Before 1.7.8, the response could be cached.

            Syntax:

            scgi_cache_max_range_offset number;

            Default:

            —

            Context:

            http, server, location

This directive appeared in version 1.11.6.

Sets an offset in bytes for byte-range requests.
If the range is beyond the offset,
the range request will be passed to the SCGI server
and the response will not be cached.

            Syntax:

            scgi_cache_methods
    GET |
    HEAD |
    POST
    ...;

            Default:

scgi_cache_methods GET HEAD;

            Context:

            http, server, location

If the client request method is listed in this directive then
the response will be cached.
“GET” and “HEAD” methods are always
added to the list, though it is recommended to specify them explicitly.
See also the scgi_no_cache directive.

            Syntax:

            scgi_cache_min_uses number;

            Default:

scgi_cache_min_uses 1;

            Context:

            http, server, location

Sets the number of requests after which the response
will be cached.

            Syntax:

            scgi_cache_path
    path
    [levels=levels]
    [use_temp_path=on|off]
    keys_zone=name:size
    [inactive=time]
    [max_size=size]
    [min_free=size]
    [manager_files=number]
    [manager_sleep=time]
    [manager_threshold=time]
    [loader_files=number]
    [loader_sleep=time]
    [loader_threshold=time]
    [purger=on|off]
    [purger_files=number]
    [purger_sleep=time]
    [purger_threshold=time];

            Default:

            —

            Context:

            http

Sets the path and other parameters of a cache.
Cache data are stored in files.
The file name in a cache is a result of
applying the MD5 function to the
cache key.
The levels parameter defines hierarchy levels of a cache:
from 1 to 3, each level accepts values 1 or 2.
For example, in the following configuration

scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

file names in a cache will look like this:

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

A cached response is first written to a temporary file,
and then the file is renamed.
Starting from version 0.8.9, temporary files and the cache can be put on
different file systems.
However, be aware that in this case a file is copied
across two file systems instead of the cheap renaming operation.
It is thus recommended that for any given location both cache and a directory
holding temporary files
are put on the same file system.
A directory for temporary files is set based on
the use_temp_path parameter (1.7.10).
If this parameter is omitted or set to the value on,
the directory set by the scgi_temp_path directive
for the given location will be used.
If the value is set to off,
temporary files will be put directly in the cache directory.

In addition, all active keys and information about data are stored
in a shared memory zone, whose name and size
are configured by the keys_zone parameter.
One megabyte zone can store about 8 thousand keys.

As part of
commercial subscription,
the shared memory zone also stores extended
cache information,
thus, it is required to specify a larger zone size for the same number of keys.
For example,
one megabyte zone can store about 4 thousand keys.

Cached data that are not accessed during the time specified by the
inactive parameter get removed from the cache
regardless of their freshness.
By default, inactive is set to 10 minutes.

The special “cache manager” process monitors the maximum cache size set
by the max_size parameter,
and the minimum amount of free space set
by the min_free (1.19.1) parameter
on the file system with cache.
When the size is exceeded or there is not enough free space,
it removes the least recently used data.
The data is removed in iterations configured by
manager_files,
manager_threshold, and
manager_sleep parameters (1.11.5).
During one iteration no more than manager_files items
are deleted (by default, 100).
The duration of one iteration is limited by the
manager_threshold parameter (by default, 200 milliseconds).
Between iterations, a pause configured by the manager_sleep
parameter (by default, 50 milliseconds) is made.

A minute after the start the special “cache loader” process is activated.
It loads information about previously cached data stored on file system
into a cache zone.
The loading is also done in iterations.
During one iteration no more than loader_files items
are loaded (by default, 100).
Besides, the duration of one iteration is limited by the
loader_threshold parameter (by default, 200 milliseconds).
Between iterations, a pause configured by the loader_sleep
parameter (by default, 50 milliseconds) is made.

Additionally,
the following parameters are available as part of our
commercial subscription:

purger=on|off

Instructs whether cache entries that match a
wildcard key
will be removed from the disk by the cache purger (1.7.12).
Setting the parameter to on
(default is off)
will activate the “cache purger” process that
permanently iterates through all cache entries
and deletes the entries that match the wildcard key.

purger_files=number

Sets the number of items that will be scanned during one iteration (1.7.12).
By default, purger_files is set to 10.

purger_threshold=number

Sets the duration of one iteration (1.7.12).
By default, purger_threshold is set to 50 milliseconds.

purger_sleep=number

Sets a pause between iterations (1.7.12).
By default, purger_sleep is set to 50 milliseconds.

In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed.
Previously cached responses will be considered invalid
after upgrading to a newer nginx version.

            Syntax:

            scgi_cache_purge string ...;

            Default:

            —

            Context:

            http, server, location

This directive appeared in version 1.5.7.

Defines conditions under which the request will be considered a cache
purge request.
If at least one value of the string parameters is not empty and is not equal
to “0” then the cache entry with a corresponding
cache key is removed.
The result of successful operation is indicated by returning
the 204 (No Content) response.

If the cache key of a purge request ends
with an asterisk (“*”), all cache entries matching the
wildcard key will be removed from the cache.
However, these entries will remain on the disk until they are deleted
for either inactivity,
or processed by the cache purger (1.7.12),
or a client attempts to access them.

Example configuration:

scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        scgi_pass        backend;
        scgi_cache       cache_zone;
        scgi_cache_key   $uri;
        scgi_cache_purge $purge_method;
    }
}

This functionality is available as part of our
commercial subscription.

            Syntax:

            scgi_cache_revalidate on | off;

            Default:

scgi_cache_revalidate off;

            Context:

            http, server, location

This directive appeared in version 1.5.7.

Enables revalidation of expired cache items using conditional requests with
the “If-Modified-Since” and “If-None-Match”
header fields.

            Syntax:

            scgi_cache_use_stale
    error |
    timeout |
    invalid_header |
    updating |
    http_500 |
    http_503 |
    http_403 |
    http_404 |
    http_429 |
    off
    ...;

            Default:

scgi_cache_use_stale off;

            Context:

            http, server, location

Determines in which cases a stale cached response can be used
when an error occurs during communication with the SCGI server.
The directive’s parameters match the parameters of the
scgi_next_upstream directive.

The error parameter also permits
using a stale cached response if an SCGI server to process a request
cannot be selected.

Additionally, the updating parameter permits
using a stale cached response if it is currently being updated.
This allows minimizing the number of accesses to SCGI servers
when updating cached data.

Using a stale cached response
can also be enabled directly in the response header
for a specified number of seconds after the response became stale (1.11.10).
This has lower priority than using the directive parameters.

The
“stale-while-revalidate”
extension of the “Cache-Control” header field permits
using a stale cached response if it is currently being updated.

The
“stale-if-error”
extension of the “Cache-Control” header field permits
using a stale cached response in case of an error.

To minimize the number of accesses to SCGI servers when
populating a new cache element, the scgi_cache_lock
directive can be used.

            Syntax:

            scgi_cache_valid [code ...] time;

            Default:

            —

            Context:

            http, server, location

Sets caching time for different response codes.
For example, the following directives

scgi_cache_valid 200 302 10m;
scgi_cache_valid 404      1m;

set 10 minutes of caching for responses with codes 200 and 302
and 1 minute for responses with code 404.

If only caching time is specified

scgi_cache_valid 5m;

then only 200, 301, and 302 responses are cached.

In addition, the any parameter can be specified
to cache any responses:

scgi_cache_valid 200 302 10m;
scgi_cache_valid 301      1h;
scgi_cache_valid any      1m;

Parameters of caching can also be set directly
in the response header.
This has higher priority than setting of caching time using the directive.

The “X-Accel-Expires” header field sets caching time of a
response in seconds.
The zero value disables caching for a response.
If the value starts with the @ prefix, it sets an absolute
time in seconds since Epoch, up to which the response may be cached.

If the header does not include the “X-Accel-Expires” field,
parameters of caching may be set in the header fields
“Expires” or “Cache-Control”.

If the header includes the “Set-Cookie” field, such a
response will not be cached.

If the header includes the “Vary” field
with the special value “*”, such a
response will not be cached (1.7.7).
If the header includes the “Vary” field
with another value, such a response will be cached
taking into account the corresponding request header fields (1.7.7).

Processing of one or more of these response header fields can be disabled
using the scgi_ignore_headers directive.

            Syntax:

            scgi_connect_timeout time;

            Default:

scgi_connect_timeout 60s;

            Context:

            http, server, location

Defines a timeout for establishing a connection with an SCGI server.
It should be noted that this timeout cannot usually exceed 75 seconds.

            Syntax:

            scgi_force_ranges on | off;

            Default:

scgi_force_ranges off;

            Context:

            http, server, location

This directive appeared in version 1.7.7.

Enables byte-range support
for both cached and uncached responses from the SCGI server
regardless of the “Accept-Ranges” field in these responses.

            Syntax:

            scgi_hide_header field;

            Default:

            —

            Context:

            http, server, location

By default,
nginx does not pass the header fields “Status” and
“X-Accel-...” from the response of an SCGI
server to a client.
The scgi_hide_header directive sets additional fields
that will not be passed.
If, on the contrary, the passing of fields needs to be permitted,
the scgi_pass_header directive can be used.

            Syntax:

            scgi_ignore_client_abort on | off;

            Default:

scgi_ignore_client_abort off;

            Context:

            http, server, location

Determines whether the connection with an SCGI server should be
closed when a client closes the connection without waiting
for a response.

            Syntax:

            scgi_ignore_headers field ...;

            Default:

            —

            Context:

            http, server, location

Disables processing of certain response header fields from the SCGI server.
The following fields can be ignored: “X-Accel-Redirect”,
“X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6),
“X-Accel-Buffering” (1.1.6),
“X-Accel-Charset” (1.1.6), “Expires”,
“Cache-Control”, “Set-Cookie” (0.8.44),
and “Vary” (1.7.7).

If not disabled, processing of these header fields has the following
effect:

“X-Accel-Expires”, “Expires”,
“Cache-Control”, “Set-Cookie”,
and “Vary”
set the parameters of response caching;

“X-Accel-Redirect” performs an
internal
redirect to the specified URI;

“X-Accel-Limit-Rate” sets the
rate
limit for transmission of a response to a client;

“X-Accel-Buffering” enables or disables
buffering of a response;

“X-Accel-Charset” sets the desired
charset
of a response.

            Syntax:

            scgi_intercept_errors on | off;

            Default:

scgi_intercept_errors off;

            Context:

            http, server, location

Determines whether an SCGI server responses with codes greater than or equal
to 300 should be passed to a client
or be intercepted and redirected to nginx for processing
with the error_page directive.

            Syntax:

            scgi_limit_rate rate;

            Default:

scgi_limit_rate 0;

            Context:

            http, server, location

This directive appeared in version 1.7.7.

Limits the speed of reading the response from the SCGI server.
The rate is specified in bytes per second.
The zero value disables rate limiting.
The limit is set per a request, and so if nginx simultaneously opens
two connections to the SCGI server,
the overall rate will be twice as much as the specified limit.
The limitation works only if
buffering of responses from the SCGI
server is enabled.
Parameter value can contain variables (1.27.0).

            Syntax:

            scgi_max_temp_file_size size;

            Default:

scgi_max_temp_file_size 1024m;

            Context:

            http, server, location

When buffering of responses from the SCGI
server is enabled, and the whole response does not fit into the buffers
set by the scgi_buffer_size and scgi_buffers
directives, a part of the response can be saved to a temporary file.
This directive sets the maximum size of the temporary file.
The size of data written to the temporary file at a time is set
by the scgi_temp_file_write_size directive.

The zero value disables buffering of responses to temporary files.

This restriction does not apply to responses
that will be cached
or stored on disk.

            Syntax:

            scgi_next_upstream
    error |
    timeout |
    denied |
    invalid_header |
    http_500 |
    http_503 |
    http_403 |
    http_404 |
    http_429 |
    non_idempotent |
    off
    ...;

            Default:

scgi_next_upstream error timeout;

            Context:

            http, server, location

Specifies in which cases a request should be passed to the next server:

error

an error occurred while establishing a connection with the
server, passing a request to it, or reading the response header;

timeout

a timeout has occurred while establishing a connection with the
server, passing a request to it, or reading the response header;

denied

the server denied
the connection (1.29.3);

This parameter is available as part of our
commercial subscription.

invalid_header

a server returned an empty or invalid response;

http_500

a server returned a response with the code 500;

http_503

a server returned a response with the code 503;

http_403

a server returned a response with the code 403;

http_404

a server returned a response with the code 404;

http_429

a server returned a response with the code 429 (1.11.13);

non_idempotent

normally, requests with a
non-idempotent
method
(POST, LOCK, PATCH)
are not passed to the next server
if a request has been sent to an upstream server (1.9.13);
enabling this option explicitly allows retrying such requests;

off

disables passing a request to the next server.

One should bear in mind that passing a request to the next server is
only possible if nothing has been sent to a client yet.
That is, if an error or timeout occurs in the middle of the
transferring of a response, fixing this is impossible.

The directive also defines what is considered an
unsuccessful
attempt of communication with a server.
The cases of error, timeout,
denied and
invalid_header are always considered unsuccessful attempts,
even if they are not specified in the directive.
The cases of http_500, http_503,
and http_429 are
considered unsuccessful attempts only if they are specified in the directive.
The cases of http_403 and http_404
are never considered unsuccessful attempts.

Passing a request to the next server can be limited by
the number of tries
and by time.

            Syntax:

            scgi_next_upstream_timeout time;

            Default:

scgi_next_upstream_timeout 0;

            Context:

            http, server, location

This directive appeared in version 1.7.5.

Limits the time during which a request can be passed to the
next server.
The 0 value turns off this limitation.

            Syntax:

            scgi_next_upstream_tries number;

            Default:

scgi_next_upstream_tries 0;

            Context:

            http, server, location

This directive appeared in version 1.7.5.

Limits the number of possible tries for passing a request to the
next server.
The 0 value turns off this limitation.

            Syntax:

            scgi_no_cache string ...;

            Default:

            —

            Context:

            http, server, location

Defines conditions under which the response will not be saved to a cache.
If at least one value of the string parameters is not empty and is not
equal to “0” then the response will not be saved:

scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma    $http_authorization;

Can be used along with the scgi_cache_bypass directive.

            Syntax:

            scgi_param
    parameter value
    [if_not_empty];

            Default:

scgi_param HTTP_HOST $host$is_request_port$request_port;

            Context:

            http, server, location

Sets a parameter that should be passed to the SCGI server.
The value can contain text, variables, and their combination.
These directives are inherited from the previous configuration level
if and only if there are no scgi_param directives
defined on the current level.

Standard
CGI
environment variables
should be provided as SCGI headers, see the scgi_params file
provided in the distribution:

location / {
    include scgi_params;
    ...
}

If the directive is specified with if_not_empty (1.1.11) then
such a parameter will be passed to the server only if its value is not empty:

scgi_param HTTPS $https if_not_empty;

            Syntax:

            scgi_pass address;

            Default:

            —

            Context:

            location, if in location

Sets the address of an SCGI server.
The address can be specified as a domain name or IP address,
and a port:

scgi_pass localhost:9000;

or as a UNIX-domain socket path:

scgi_pass unix:/tmp/scgi.socket;

If a domain name resolves to several addresses, all of them will be
used in a round-robin fashion.
In addition, an address can be specified as a
server group.

Parameter value can contain variables.
In this case, if an address is specified as a domain name,
the name is searched among the described
server groups,
and, if not found, is determined using a
resolver.

            Syntax:

            scgi_pass_header field;

            Default:

            —

            Context:

            http, server, location

Permits passing otherwise disabled header
fields from an SCGI server to a client.

            Syntax:

            scgi_pass_request_body on | off;

            Default:

scgi_pass_request_body on;

            Context:

            http, server, location

Indicates whether the original request body is passed
to the SCGI server.
See also the scgi_pass_request_headers directive.

            Syntax:

            scgi_pass_request_headers on | off;

            Default:

scgi_pass_request_headers on;

            Context:

            http, server, location

Indicates whether the header fields of the original request are passed
to the SCGI server.
See also the scgi_pass_request_body directive.

            Syntax:

            scgi_read_timeout time;

            Default:

scgi_read_timeout 60s;

            Context:

            http, server, location

Defines a timeout for reading a response from the SCGI server.
The timeout is set only between two successive read operations,
not for the transmission of the whole response.
If the SCGI server does not transmit anything within this time,
the connection is closed.

            Syntax:

            scgi_request_buffering on | off;

            Default:

scgi_request_buffering on;

            Context:

            http, server, location

This directive appeared in version 1.7.11.

Enables or disables buffering of a client request body.

When buffering is enabled, the entire request body is
read
from the client before sending the request to an SCGI server.

When buffering is disabled, the request body is sent to the SCGI server
immediately as it is received.
In this case, the request cannot be passed to the
next server
if nginx already started sending the request body.

When HTTP/1.1 chunked transfer encoding is used
to send the original request body,
the request body will be buffered regardless of the directive value.

            Syntax:

            scgi_request_dynamic on | off;

            Default:

scgi_request_dynamic off;

            Context:

            http, server, location

This directive appeared in version 1.29.3.

Enables or disables creation of a separate request instance
for each SCGI server.
By default, a single request is used for all SCGI servers.
If enabled, a separate request instance is created,
allowing per-server request customization.

This directive is available as part of our
commercial subscription.

            Syntax:

            scgi_send_timeout time;

            Default:

scgi_send_timeout 60s;

            Context:

            http, server, location

Sets a timeout for transmitting a request to the SCGI server.
The timeout is set only between two successive write operations,
not for the transmission of the whole request.
If the SCGI server does not receive anything within this time,
the connection is closed.

            Syntax:

            scgi_socket_keepalive on | off;

            Default:

scgi_socket_keepalive off;

            Context:

            http, server, location

This directive appeared in version 1.15.6.

Configures the “TCP keepalive” behavior
for outgoing connections to an SCGI server.
By default, the operating system’s settings are in effect for the socket.
If the directive is set to the value “on”, the
SO_KEEPALIVE socket option is turned on for the socket.

            Syntax:

            scgi_store
    on |
    off |
    string;

            Default:

scgi_store off;

            Context:

            http, server, location

Enables saving of files to a disk.
The on parameter saves files with paths
corresponding to the directives
alias or
root.
The off parameter disables saving of files.
In addition, the file name can be set explicitly using the
string with variables:

scgi_store /data/www$original_uri;

The modification time of files is set according to the received
“Last-Modified” response header field.
The response is first written to a temporary file,
and then the file is renamed.
Starting from version 0.8.9, temporary files and the persistent store
can be put on different file systems.
However, be aware that in this case a file is copied
across two file systems instead of the cheap renaming operation.
It is thus recommended that for any given location both saved files and a
directory holding temporary files, set by the scgi_temp_path
directive, are put on the same file system.

This directive can be used to create local copies of static unchangeable
files, e.g.:

location /images/ {
    root              /data/www;
    error_page        404 = /fetch$uri;
}

location /fetch/ {
    internal;

    scgi_pass         backend:9000;
    ...

    scgi_store        on;
    scgi_store_access user:rw group:rw all:r;
    scgi_temp_path    /data/temp;

    alias             /data/www/;
}

            Syntax:

            scgi_store_access users:permissions ...;

            Default:

scgi_store_access user:rw;

            Context:

            http, server, location

Sets access permissions for newly created files and directories, e.g.:

scgi_store_access user:rw group:rw all:r;

If any group or all access permissions
are specified then user permissions may be omitted:

scgi_store_access group:rw all:r;

            Syntax:

            scgi_temp_file_write_size size;

            Default:

scgi_temp_file_write_size 8k|16k;

            Context:

            http, server, location

Limits the size of data written to a temporary file
at a time, when buffering of responses from the SCGI server
to temporary files is enabled.
By default, size is limited by two buffers set by the
scgi_buffer_size and scgi_buffers directives.
The maximum size of a temporary file is set by the
scgi_max_temp_file_size directive.

            Syntax:

            scgi_temp_path
    path
    [level1
    [level2
    [level3]]];

            Default:

scgi_temp_path scgi_temp;

            Context:

            http, server, location

Defines a directory for storing temporary files
with data received from SCGI servers.
Up to three-level subdirectory hierarchy can be used underneath the specified
directory.
For example, in the following configuration

scgi_temp_path /spool/nginx/scgi_temp 1 2;

a temporary file might look like this:

/spool/nginx/scgi_temp/7/45/00000123457

See also the use_temp_path parameter of the
scgi_cache_path directive.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_secure_link_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_http_secure_link_module

Directives
     secure_link
     secure_link_md5
     secure_link_secret
Embedded Variables

The ngx_http_secure_link_module module (0.7.18)
is used to check authenticity of requested links,
protect resources from unauthorized access,
and limit link lifetime.

The authenticity of a requested link is verified by comparing the
checksum value passed in a request with the value computed
for the request.
If a link has a limited lifetime and the time has expired,
the link is considered outdated.
The status of these checks is made available in the
$secure_link variable.

The module provides two alternative operation modes.
The first mode is enabled by the secure_link_secret
directive and is used to check authenticity of requested links
as well as protect resources from unauthorized access.
The second mode (0.8.50) is enabled by the
secure_link and secure_link_md5
directives and is also used to limit lifetime of links.

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

Directives

            Syntax:

            secure_link expression;

            Default:

            —

            Context:

            http, server, location

Defines a string with variables from which the
checksum value and lifetime of a link will be extracted.

Variables used in an expression are usually associated
with a request; see example below.

The checksum value extracted from the string is compared with
the MD5 hash value of the expression defined by the
secure_link_md5 directive.
If the checksums are different, the $secure_link variable
is set to an empty string.
If the checksums are the same, the link lifetime is checked.
If the link has a limited lifetime and the time has expired,
the $secure_link variable is set to “0”.
Otherwise, it is set to “1”.
The MD5 hash value passed in a request is encoded in
base64url.

If a link has a limited lifetime, the expiration time
is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT).
The value is specified in the expression after the MD5 hash,
and is separated by a comma.
The expiration time passed in a request is available through
the $secure_link_expires variable for a use in
the secure_link_md5 directive.
If the expiration time is not specified, a link has the unlimited
lifetime.

            Syntax:

            secure_link_md5 expression;

            Default:

            —

            Context:

            http, server, location

Defines an expression for which the MD5 hash value will
be computed and compared with the value passed in a request.

The expression should contain the secured part of a link (resource)
and a secret ingredient.
If the link has a limited lifetime,
the expression should also contain $secure_link_expires.

To prevent unauthorized access, the expression may contain some
information about the client, such as its address and browser version.

Example:

location /s/ {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;
    }

    ...
}

The
“/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647”
link
restricts access to “/s/link” for the client with the
IP address 127.0.0.1.
The link also has the limited lifetime until January 19, 2038 (GMT).

On UNIX, the md5 request argument value can be obtained as:

echo -n '2147483647/s/link127.0.0.1 secret' | \
    openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =

            Syntax:

            secure_link_secret word;

            Default:

            —

            Context:

            location

Defines a secret word used to check authenticity
of requested links.

The full URI of a requested link looks as follows:

/prefix/hash/link

where hash is a hexadecimal representation of the
MD5 hash computed for the concatenation of the link and secret word,
and prefix is an arbitrary string without slashes.

If the requested link passes the authenticity check,
the $secure_link variable is set to the link
extracted from the request URI.
Otherwise, the $secure_link variable
is set to an empty string.

Example:

location /p/ {
    secure_link_secret secret;

    if ($secure_link = "") {
        return 403;
    }

    rewrite ^ /secure/$secure_link;
}

location /secure/ {
    internal;
}

A request of “/p/5e814704a28d9bc1914ff19fa0c4a00a/link”
will be internally redirected to
“/secure/link”.

On UNIX, the hash value for this example can be obtained as:

echo -n 'linksecret' | openssl md5 -hex

Embedded Variables

$secure_link

The status of a link check.
The specific value depends on the selected operation mode.

$secure_link_expires

The lifetime of a link passed in a request;
intended to be used only in the
secure_link_md5 directive.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_session_log_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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).


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_slice_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_split_clients_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

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).


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_ssi_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_http_ssi_module

Example Configuration
Directives
     ssi
     ssi_last_modified
     ssi_min_file_chunk
     ssi_silent_errors
     ssi_types
     ssi_value_length
SSI Commands
Embedded Variables

The ngx_http_ssi_module module is a filter
that processes SSI (Server Side Includes) commands in responses
passing through it.
Currently, the list of supported SSI commands is incomplete.

Example Configuration

location / {
    ssi on;
    ...
}

Directives

            Syntax:

            ssi on | off;

            Default:

ssi off;

            Context:

            http, server, location, if in location

Enables or disables processing of SSI commands in responses.

            Syntax:

            ssi_last_modified on | off;

            Default:

ssi_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 SSI processing
to facilitate response caching.

By default, the header field is removed as contents of the response
are modified during processing and may contain dynamically generated elements
or parts that are changed independently of the original response.

            Syntax:

            ssi_min_file_chunk size;

            Default:

ssi_min_file_chunk 1k;

            Context:

            http, server, location

Sets the minimum size for parts of a response stored on disk,
starting from which it makes sense to send them using
sendfile.

            Syntax:

            ssi_silent_errors on | off;

            Default:

ssi_silent_errors off;

            Context:

            http, server, location

If enabled, suppresses the output of the
“[an error occurred while processing the directive]”
string if an error occurred during SSI processing.

            Syntax:

            ssi_types mime-type ...;

            Default:

ssi_types text/html;

            Context:

            http, server, location

Enables processing of SSI commands in responses with the specified MIME types
in addition to “text/html”.
The special value “*” matches any MIME type (0.8.29).

            Syntax:

            ssi_value_length length;

            Default:

ssi_value_length 256;

            Context:

            http, server, location

Sets the maximum length of parameter values in SSI commands.

SSI Commands

SSI commands have the following generic format:

<!--# command parameter1=value1 parameter2=value2 ... -->

The following commands are supported:

block

Defines a block that can be used as a stub
in the include command.
The block can contain other SSI commands.
The command has the following parameter:

name

block name.

Example:

<!--# block name="one" -->
stub
<!--# endblock -->

config

Sets some parameters used during SSI processing, namely:

errmsg

a string that is output if an error occurs during SSI processing.
By default, the following string is output:

[an error occurred while processing the directive]

timefmt

a format string passed to the strftime() function
used to output date and time.
By default, the following format is used:

"%A, %d-%b-%Y %H:%M:%S %Z"

The “%s” format is suitable to output time in seconds.

echo

Outputs the value of a variable.
The command has the following parameters:

var

the variable name.

encoding

the encoding method.
Possible values include none, url, and
entity.
By default, entity is used.

default

a non-standard parameter that sets a string to be output
if a variable is undefined.
By default, “(none)” is output.
The command

<!--# echo var="name" default="no" -->

replaces the following sequence of commands:

<!--# if expr="$name" --><!--# echo var="name" --><!--#
       else -->no<!--# endif -->

if

Performs a conditional inclusion.
The following commands are supported:

<!--# if expr="..." -->
...
<!--# elif expr="..." -->
...
<!--# else -->
...
<!--# endif -->

Only one level of nesting is currently supported.
The command has the following parameter:

expr

expression.
An expression can be:

variable existence check:

<!--# if expr="$name" -->

comparison of a variable with a text:

<!--# if expr="$name = text" -->
<!--# if expr="$name != text" -->

comparison of a variable with a regular expression:

<!--# if expr="$name = /text/" -->
<!--# if expr="$name != /text/" -->

If a text contains variables,
their values are substituted.
A regular expression can contain positional and named captures
that can later be used through variables, for example:

<!--# if expr="$name = /(.+)@(?P<domain>.+)/" -->
    <!--# echo var="1" -->
    <!--# echo var="domain" -->
<!--# endif -->

include

Includes the result of another request into a response.
The command has the following parameters:

file

specifies an included file, for example:

<!--# include file="footer.html" -->

virtual

specifies an included request, for example:

<!--# include virtual="/remote/body.php?argument=value" -->

Several requests specified on one page and processed by proxied or
FastCGI/uwsgi/SCGI/gRPC servers run in parallel.
If sequential processing is desired, the wait
parameter should be used.

stub

a non-standard parameter that names the block whose
content will be output if the included request results in an empty
body or if an error occurs during the request processing, for example:

<!--# block name="one" -->&nbsp;<!--# endblock -->
<!--# include virtual="/remote/body.php?argument=value" stub="one" -->

The replacement block content is processed in the included request context.

wait

a non-standard parameter that instructs to wait for a request to fully
complete before continuing with SSI processing, for example:

<!--# include virtual="/remote/body.php?argument=value" wait="yes" -->

set

a non-standard parameter that instructs to write a successful result
of request processing to the specified variable,
for example:

<!--# include virtual="/remote/body.php?argument=value" set="one" -->

The maximum size of the response is set by the
subrequest_output_buffer_size
directive (1.13.10):

location /remote/ {
    subrequest_output_buffer_size 64k;
    ...
}

Prior to version 1.13.10, only the results of responses obtained using the
ngx_http_proxy_module,
ngx_http_memcached_module,
ngx_http_fastcgi_module (1.5.6),
ngx_http_uwsgi_module (1.5.6),
and ngx_http_scgi_module (1.5.6)
modules could be written into variables.
The maximum size of the response was set with the
proxy_buffer_size,
memcached_buffer_size,
fastcgi_buffer_size,
uwsgi_buffer_size,
and scgi_buffer_size
directives.

set

Sets a value of a variable.
The command has the following parameters:

var

the variable name.

value

the variable value.
If an assigned value contains variables,
their values are substituted.

Embedded Variables

The ngx_http_ssi_module module supports
two embedded variables:

$date_local

current time in the local time zone.
The format is set by the config command
with the timefmt parameter.

$date_gmt

current time in GMT.
The format is set by the config command
with the timefmt parameter.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_ssl_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_http_ssl_module

Example Configuration
Directives
     ssl
     ssl_buffer_size
     ssl_certificate
     ssl_certificate_cache
     ssl_certificate_compression
     ssl_certificate_key
     ssl_ciphers
     ssl_client_certificate
     ssl_conf_command
     ssl_crl
     ssl_dhparam
     ssl_early_data
     ssl_ecdh_curve
     ssl_ech_file
     ssl_key_log
     ssl_ocsp
     ssl_ocsp_cache
     ssl_ocsp_responder
     ssl_password_file
     ssl_prefer_server_ciphers
     ssl_protocols
     ssl_reject_handshake
     ssl_session_cache
     ssl_session_ticket_key
     ssl_session_tickets
     ssl_session_timeout
     ssl_stapling
     ssl_stapling_file
     ssl_stapling_responder
     ssl_stapling_verify
     ssl_trusted_certificate
     ssl_verify_client
     ssl_verify_depth
Error Processing
Embedded Variables

The ngx_http_ssl_module module provides the
necessary support for HTTPS.

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

This module requires the
OpenSSL library.

Example Configuration

To reduce the processor load, it is recommended to

set the number of
worker processes
equal to the number of processors,

enable
keep-alive
connections,

enable the shared session cache,

disable the built-in session cache,

and possibly increase the session lifetime
(by default, 5 minutes):

worker_processes auto;

http {

    ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

Directives

            Syntax:

            ssl on | off;

            Default:

ssl off;

            Context:

            http, server

This directive was made obsolete in version 1.15.0
and was removed in version 1.25.1.
The ssl parameter
of the listen directive
should be used instead.

            Syntax:

            ssl_buffer_size size;

            Default:

ssl_buffer_size 16k;

            Context:

            http, server

This directive appeared in version 1.5.9.

Sets the size of the buffer used for sending data.

By default, the buffer size is 16k, which corresponds to minimal
overhead when sending big responses.
To minimize Time To First Byte it may be beneficial to use smaller values,
for example:

ssl_buffer_size 4k;

            Syntax:

            ssl_certificate file;

            Default:

            —

            Context:

            http, server

Specifies a file with the certificate in the PEM format
for the given virtual server.
If intermediate certificates should be specified in addition to a primary
certificate, they should be specified in the same file in the following
order: the primary certificate comes first, then the intermediate certificates.
A secret key in the PEM format may be placed in the same file.

Since version 1.11.0,
this directive can be specified multiple times
to load certificates of different types, for example, RSA and ECDSA:

server {
    listen              443 ssl;
    server_name         example.com;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    ...
}

Only OpenSSL 1.0.2 or higher supports separate
certificate chains
for different certificates.
With older versions, only one certificate chain can be used.

Since version 1.15.9, variables can be used in the file name
when using OpenSSL 1.0.2 or higher:

ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;

Note that using variables implies that
a certificate will be loaded for each SSL handshake,
and this may have a negative impact on performance.

The value
data:$variable
can be specified instead of the file (1.15.10),
which loads a certificate from a variable
without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
error log.

It should be kept in mind that due to the SSL/TLS protocol limitations,
for maximum interoperability with clients that do not use
SNI,
virtual servers with different certificates should listen on
different
IP addresses.

            Syntax:

            ssl_certificate_cache off;
ssl_certificate_cache
    max=N
    [inactive=time]
    [valid=time];

            Default:

ssl_certificate_cache off;

            Context:

            http, server

This directive appeared in version 1.27.4.

Defines a cache that stores
SSL certificates and
secret keys
specified with variables.

The directive has the following parameters:

max

sets the maximum number of elements in the cache;
on cache overflow the least recently used (LRU) elements are removed;

inactive

defines a time after which an element is removed from the cache
if it has not been accessed during this time;
by default, it is 10 seconds;

valid

defines a time during which
an element in the cache is considered valid
and can be reused;
by default, it is 60 seconds.
Certificates that exceed this time will be reloaded or revalidated;

off

disables the cache.

Example:

ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;

            Syntax:

            ssl_certificate_compression on | off;

            Default:

ssl_certificate_compression off;

            Context:

            http, server

This directive appeared in version 1.29.1.

Enables TLS 1.3
compression
of server certificates.

The directive is supported when using OpenSSL 3.2 or higher;
the list of supported compression algorithms is provided by the library.

The directive is supported when using BoringSSL;
the list of supported compression algorithms includes
zlib (1.29.3).

            Syntax:

            ssl_certificate_key file;

            Default:

            —

            Context:

            http, server

Specifies a file with the secret key in the PEM format
for the given virtual server.

The value
engine:name:id
can be specified instead of the file (1.7.9),
which loads a secret key with a specified id
from the OpenSSL engine name.

The value
store:scheme:id
can be specified instead of the file (1.29.0),
which is used to load a secret key with a specified id
and OpenSSL provider registered URI scheme, such as
pkcs11.

The value
data:$variable
can be specified instead of the file (1.15.10),
which loads a secret key from a variable without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
error log.

Since version 1.15.9, variables can be used in the file name
when using OpenSSL 1.0.2 or higher.

            Syntax:

            ssl_ciphers ciphers;

            Default:

ssl_ciphers HIGH:!aNULL:!MD5;

            Context:

            http, server

Specifies the enabled ciphers.
The ciphers are specified in the format understood by the
OpenSSL library, for example:

ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

The full list can be viewed using the
“openssl ciphers” command.

The previous versions of nginx used
different
ciphers by default.

            Syntax:

            ssl_client_certificate file;

            Default:

            —

            Context:

            http, server

Specifies a file with trusted CA certificates in the PEM format
used to verify client certificates and
OCSP responses if ssl_stapling is enabled.

The list of certificates will be sent to clients.
If this is not desired, the ssl_trusted_certificate
directive can be used.

            Syntax:

            ssl_conf_command name value;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration
commands.

The directive is supported when using OpenSSL 1.0.2 or higher.

Several ssl_conf_command directives
can be specified on the same level:

ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;

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

Note that configuring OpenSSL directly
might result in unexpected behavior.

            Syntax:

            ssl_crl file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 0.8.7.

Specifies a file with revoked certificates (CRL)
in the PEM format used to verify
client certificates.
When using intermediate certificates, their CRLs should be
specified in the same file.

            Syntax:

            ssl_dhparam file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 0.7.2.

Specifies a file with DH parameters for DHE ciphers.

By default no parameters are set,
and therefore DHE ciphers will not be used.

Prior to version 1.11.0, builtin parameters were used by default.

            Syntax:

            ssl_early_data on | off;

            Default:

ssl_early_data off;

            Context:

            http, server

This directive appeared in version 1.15.3.

Enables or disables TLS 1.3
early data.

The directive is supported when using OpenSSL 1.1.1 or higher (1.15.4) and
BoringSSL.

Requests sent within early data are subject to
replay attacks.
To protect against such attacks at the application layer,
the $ssl_early_data variable
should be used.

proxy_set_header Early-Data $ssl_early_data;

OpenSSL built-in replay protection is disabled,
because it interferes with session resumption.
It can be turned back if deemed necessary.

ssl_conf_command Options AntiReplay;

            Syntax:

            ssl_ecdh_curve curve;

            Default:

ssl_ecdh_curve auto;

            Context:

            http, server

                    This directive appeared in versions 1.1.0 and 1.0.6.

Specifies a curve for ECDHE ciphers.

When using OpenSSL 1.0.2 or higher,
it is possible to specify multiple curves (1.11.0), for example:

ssl_ecdh_curve prime256v1:secp384r1;

The special value auto (1.11.0) instructs nginx to use
a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,
or prime256v1 with older versions.

Prior to version 1.11.0,
the prime256v1 curve was used by default.

When using OpenSSL 1.0.2 or higher,
this directive sets the list of curves supported by the server.
Thus, in order for ECDSA certificates to work,
it is important to include the curves used in the certificates.

            Syntax:

            ssl_ech_file file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.29.4.

Specifies a file with encrypted ClientHello configuration
(ECHConfig) in the
PEM
format used to enable TLS 1.3
ECH
in shared mode.

The directive is currently supported only when using OpenSSL
ECH
feature branch.

            Syntax:

            ssl_key_log path;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.27.2.

Enables logging of client connection SSL keys
and specifies the path to the key log file.
Keys are logged in the
SSLKEYLOGFILE
format compatible with Wireshark.

This directive is available as part of our
commercial subscription.

            Syntax:

            ssl_ocsp on |
        off |
        leaf;

            Default:

ssl_ocsp off;

            Context:

            http, server

This directive appeared in version 1.19.0.

Enables OCSP validation of the client certificate chain.
The leaf parameter
enables validation of the client certificate only.

For the OCSP validation to work,
the ssl_verify_client directive should be set to
on or optional.

To resolve the OCSP responder hostname,
the resolver directive
should also be specified.

Example:

ssl_verify_client on;
ssl_ocsp          on;
resolver          192.0.2.1;

            Syntax:

            ssl_ocsp_cache
    off |
    [shared:name:size];

            Default:

ssl_ocsp_cache off;

            Context:

            http, server

This directive appeared in version 1.19.0.

Sets name and size of the cache
that stores client certificates status for OCSP validation.
The cache is shared between all worker processes.
A cache with the same name can be used in several
virtual servers.

The off parameter prohibits the use of the cache.

            Syntax:

            ssl_ocsp_responder url;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.19.0.

Overrides the URL of the OCSP responder specified in the
“Authority
Information Access” certificate extension
for validation of client certificates.

Only “http://” OCSP responders are supported:

ssl_ocsp_responder http://ocsp.example.com/;

            Syntax:

            ssl_password_file file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.7.3.

Specifies a file with passphrases for
secret keys
where each passphrase is specified on a separate line.
Passphrases are tried in turn when loading the key.

Example:

http {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name www1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name www2.example.com;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

            Syntax:

            ssl_prefer_server_ciphers on | off;

            Default:

ssl_prefer_server_ciphers off;

            Context:

            http, server

Specifies that server ciphers should be preferred over client ciphers
when the SSLv3 and TLS protocols are used.

            Syntax:

            ssl_protocols
    [SSLv2]
    [SSLv3]
    [TLSv1]
    [TLSv1.1]
    [TLSv1.2]
    [TLSv1.3];

            Default:

ssl_protocols TLSv1.2 TLSv1.3;

            Context:

            http, server

Enables the specified protocols.

If the directive is specified
on the server level,
the value from the default server can be used.
Details are provided in the
“Virtual
server selection” section.

The TLSv1.1 and TLSv1.2 parameters
(1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.

The TLSv1.3 parameter (1.13.0) works only when
OpenSSL 1.1.1 or higher is used.

The TLSv1.3 parameter is used by default
since 1.23.4.

            Syntax:

            ssl_reject_handshake on | off;

            Default:

ssl_reject_handshake off;

            Context:

            http, server

This directive appeared in version 1.19.4.

If enabled, SSL handshakes in
the server block will be rejected.

For example, in the following configuration, SSL handshakes with
server names other than example.com are rejected:

server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}

            Syntax:

            ssl_session_cache
    off |
    none |
    [builtin[:size]]
    [shared:name:size];

            Default:

ssl_session_cache none;

            Context:

            http, server

Sets the types and sizes of caches that store session parameters.
A cache can be of any of the following types:

off

the use of a session cache is strictly prohibited:
nginx explicitly tells a client that sessions may not be reused.

none

the use of a session cache is gently disallowed:
nginx tells a client that sessions may be reused, but does not
actually store session parameters in the cache.

builtin

a cache built in OpenSSL; used by one worker process only.
The cache size is specified in sessions.
If size is not given, it is equal to 20480 sessions.
Use of the built-in cache can cause memory fragmentation.

shared

a cache shared between all worker processes.
The cache size is specified in bytes; one megabyte can store
about 4000 sessions.
Each shared cache should have an arbitrary name.
A cache with the same name can be used in several
virtual servers.
It is also used to automatically generate, store, and
periodically rotate TLS session ticket keys (1.23.2)
unless configured explicitly
using the ssl_session_ticket_key directive.

Both cache types can be used simultaneously, for example:

ssl_session_cache builtin:1000 shared:SSL:10m;

but using only shared cache without the built-in cache should
be more efficient.

            Syntax:

            ssl_session_ticket_key file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.5.7.

Sets a file with the secret key used to encrypt
and decrypt TLS session tickets.
The directive is necessary if the same key has to be shared between
multiple servers.
By default, a randomly generated key is used.

If several keys are specified, only the first key is
used to encrypt TLS session tickets.
This allows configuring key rotation, for example:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

The file must contain 80 or 48 bytes
of random data and can be created using the following command:

openssl rand 80 > ticket.key

Depending on the file size either AES256 (for 80-byte keys, 1.11.8)
or AES128 (for 48-byte keys) is used for encryption.

            Syntax:

            ssl_session_tickets on | off;

            Default:

ssl_session_tickets on;

            Context:

            http, server

This directive appeared in version 1.5.9.

Enables or disables session resumption through
TLS session tickets.

            Syntax:

            ssl_session_timeout time;

            Default:

ssl_session_timeout 5m;

            Context:

            http, server

Specifies a time during which a client may reuse the
session parameters.

            Syntax:

            ssl_stapling on | off;

            Default:

ssl_stapling off;

            Context:

            http, server

This directive appeared in version 1.3.7.

Enables or disables
stapling
of OCSP responses by the server.
Example:

ssl_stapling on;
resolver 192.0.2.1;

For the OCSP stapling to work, the certificate of the server certificate
issuer should be known.
If the ssl_certificate file does
not contain intermediate certificates,
the certificate of the server certificate issuer should be
present in the
ssl_trusted_certificate file.

For a resolution of the OCSP responder hostname,
the resolver directive
should also be specified.

            Syntax:

            ssl_stapling_file file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.3.7.

When set, the stapled OCSP response will be taken from the
specified file instead of querying
the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the
“openssl ocsp” command.

            Syntax:

            ssl_stapling_responder url;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.3.7.

Overrides the URL of the OCSP responder specified in the
“Authority
Information Access” certificate extension.

Only “http://” OCSP responders are supported:

ssl_stapling_responder http://ocsp.example.com/;

            Syntax:

            ssl_stapling_verify on | off;

            Default:

ssl_stapling_verify off;

            Context:

            http, server

This directive appeared in version 1.3.7.

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificate
issuer, the root certificate, and all intermediate certificates
should be configured as trusted using the
ssl_trusted_certificate directive.

            Syntax:

            ssl_trusted_certificate file;

            Default:

            —

            Context:

            http, server

This directive appeared in version 1.3.7.

Specifies a file with trusted CA certificates in the PEM format
used to verify client certificates and
OCSP responses if ssl_stapling is enabled.

In contrast to the certificate set by ssl_client_certificate,
the list of these certificates will not be sent to clients.

            Syntax:

            ssl_verify_client
    on | off |
    optional | optional_no_ca;

            Default:

ssl_verify_client off;

            Context:

            http, server

Enables verification of client certificates.
The verification result is stored in the
$ssl_client_verify variable.

The optional parameter (0.8.7+) requests the client
certificate and verifies it if the certificate is present.

The optional_no_ca parameter (1.3.8, 1.2.5)
requests the client
certificate but does not require it to be signed by a trusted CA certificate.
This is intended for the use in cases when a service that is external to nginx
performs the actual certificate verification.
The contents of the certificate is accessible through the
$ssl_client_cert variable.

            Syntax:

            ssl_verify_depth number;

            Default:

ssl_verify_depth 1;

            Context:

            http, server

Sets the verification depth in the client certificates chain.

Error Processing

The ngx_http_ssl_module module supports several
non-standard error codes that can be used for redirects using the
error_page directive:

495

an error has occurred during the client certificate verification;

496

a client has not presented the required certificate;

497

a regular request has been sent to the HTTPS port.

The redirection happens after the request is fully parsed and
the variables, such as $request_uri,
$uri, $args and others, are available.

Embedded Variables

The ngx_http_ssl_module module supports
embedded variables:

$ssl_alpn_protocol

returns the protocol selected by ALPN during the SSL handshake,
or an empty string otherwise (1.21.4);

$ssl_cipher

returns the name of the cipher used
for an established SSL connection;

$ssl_ciphers

returns the list of ciphers supported by the client (1.11.7).
Known ciphers are listed by names, unknown are shown in hexadecimal,
for example:

AES128-SHA:AES256-SHA:0x00ff

The variable is fully supported only when using OpenSSL version 1.0.2 or higher.
With older versions, the variable is available
only for new sessions and lists only known ciphers.

$ssl_client_escaped_cert

returns the client certificate in the PEM format (urlencoded)
for an established SSL connection (1.13.5);

$ssl_client_cert

returns the client certificate in the PEM format
for an established SSL connection, with each line except the first
prepended with the tab character;
this is intended for the use in the
proxy_set_header directive;

The variable is deprecated,
the $ssl_client_escaped_cert variable should be used instead.

$ssl_client_fingerprint

returns the SHA1 fingerprint of the client certificate
for an established SSL connection (1.7.1);

$ssl_client_i_dn

returns the “issuer DN” string of the client certificate
for an established SSL connection according to
RFC 2253 (1.11.6);

$ssl_client_i_dn_legacy

returns the “issuer DN” string of the client certificate
for an established SSL connection;

Prior to version 1.11.6, the variable name was $ssl_client_i_dn.

$ssl_client_raw_cert

returns the client certificate in the PEM format
for an established SSL connection;

$ssl_client_s_dn

returns the “subject DN” string of the client certificate
for an established SSL connection according to
RFC 2253 (1.11.6);

$ssl_client_s_dn_legacy

returns the “subject DN” string of the client certificate
for an established SSL connection;

Prior to version 1.11.6, the variable name was $ssl_client_s_dn.

$ssl_client_serial

returns the serial number of the client certificate
for an established SSL connection;

$ssl_client_sigalg

returns the
signature algorithm
for the client certificate for an established SSL connection (1.29.3).

The variable is supported only when using OpenSSL version 3.5 or higher.
With older versions, the variable value will be an empty string.

The variable is available only for new sessions.

$ssl_client_v_end

returns the end date of the client certificate (1.11.7);

$ssl_client_v_remain

returns the number of days
until the client certificate expires (1.11.7);

$ssl_client_v_start

returns the start date of the client certificate (1.11.7);

$ssl_client_verify

returns the result of client certificate verification:
“SUCCESS”, “FAILED:reason”,
and “NONE” if a certificate was not present;

Prior to version 1.11.7, the “FAILED” result
did not contain the reason string.

$ssl_curve

returns the negotiated curve used for
SSL handshake key exchange process (1.21.5).
Known curves are listed by names, unknown are shown in hexadecimal,
for example:

prime256v1

The variable is supported only when using OpenSSL version 3.0 or higher.
With older versions, the variable value will be an empty string.

$ssl_curves

returns the list of curves supported by the client (1.11.7).
Known curves are listed by names, unknown are shown in hexadecimal,
for example:

0x001d:prime256v1:secp521r1:secp384r1

The variable is supported only when using OpenSSL version 1.0.2 or higher.
With older versions, the variable value will be an empty string.

The variable is available only for new sessions.

$ssl_early_data

returns “1” if
TLS 1.3 early data is used
and the handshake is not complete, otherwise “” (1.15.3).

$ssl_ech_outer_server_name

returns the public server name requested through
SNI
if TLS 1.3 ECH was accepted,
otherwise “” (1.29.4);

$ssl_ech_status

returns the result of TLS 1.3 ECH processing:
“FAILED”,
“BACKEND”,
“GREASE”,
“SUCCESS”, or
“NOT_TRIED” (1.29.4);

The variable is currently supported only when using OpenSSL
ECH feature branch
and is therefore subject to change.
The variable value will otherwise be an empty string.

$ssl_protocol

returns the protocol of an established SSL connection;

$ssl_server_name

returns the server name requested through
SNI
(1.7.0);

$ssl_session_id

returns the session identifier of an established SSL connection;

$ssl_session_reused

returns “r” if an SSL session was reused,
or “.” otherwise (1.5.11).

$ssl_sigalg

returns the
signature algorithm
for the server certificate for an established SSL connection (1.29.3).

The variable is supported only when using OpenSSL version 3.5 or higher.
With older versions, the variable value will be an empty string.

The variable is available only for new sessions.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_http_status_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

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

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_http_status_module

Example Configuration
Directives
     status
     status_format
     status_zone
Data
Compatibility

The ngx_http_status_module module provides
access to various status information.

This module was available as part of our
commercial subscription
until 1.13.10.
It was superseded by the
ngx_http_api_module module
in 1.13.3.

Example Configuration

http {
    upstream backend {
        zone http_backend 64k;

        server backend1.example.com weight=5;
        server backend2.example.com;
    }

    proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;

    server {
        server_name backend.example.com;

        location / {
            proxy_pass  http://backend;
            proxy_cache cache_backend;

            health_check;
        }

        status_zone server_backend;
    }

    server {
        listen 127.0.0.1;

        location /upstream_conf {
            upstream_conf;
        }

        location /status {
            status;
        }

        location = /status.html {
        }
    }
}

stream {
    upstream backend {
        zone stream_backend 64k;

        server backend1.example.com:12345 weight=5;
        server backend2.example.com:12345;
    }

    server {
        listen      127.0.0.1:12345;
        proxy_pass  backend;
        status_zone server_backend;
        health_check;
    }
}

Examples of status requests with this configuration:

http://127.0.0.1/status
http://127.0.0.1/status/nginx_version
http://127.0.0.1/status/caches/cache_backend
http://127.0.0.1/status/upstreams
http://127.0.0.1/status/upstreams/backend
http://127.0.0.1/status/upstreams/backend/peers/1
http://127.0.0.1/status/upstreams/backend/peers/1/weight
http://127.0.0.1/status/stream
http://127.0.0.1/status/stream/upstreams
http://127.0.0.1/status/stream/upstreams/backend
http://127.0.0.1/status/stream/upstreams/backend/peers/1
http://127.0.0.1/status/stream/upstreams/backend/peers/1/weight

The simple monitoring page is shipped with this distribution,
accessible as “/status.html” in the default configuration.
It requires the locations “/status” and
“/status.html” to be configured as shown above.

Directives

            Syntax:

            status;

            Default:

            —

            Context:

            location

The status information will be accessible from the surrounding location.
Access to this location should be
limited.

            Syntax:

            status_format json;
status_format jsonp [callback];

            Default:

status_format json;

            Context:

            http, server, location

By default, status information is output in the JSON format.

Alternatively, data may be output as JSONP.
The callback parameter specifies the name of a callback function.
Parameter value can contain variables.
If parameter is omitted, or the computed value is an empty string,
then “ngx_status_jsonp_callback” is used.

            Syntax:

            status_zone zone;

            Default:

            —

            Context:

            server

Enables collection of virtual
http
or
stream
(1.7.11) server status information in the specified zone.
Several servers may share the same zone.

Data

The following status information is provided:

version

Version of the provided data set.
The current version is 8.

nginx_version

Version of nginx.

nginx_build

Name of nginx build.

address

The address of the server that accepted status request.

generation

The total number of configuration
reloads.

load_timestamp

Time of the last reload of configuration, in milliseconds since Epoch.

timestamp

Current time in milliseconds since Epoch.

pid

The ID of the worker process that handled status request.

ppid

The ID of the master process that started
the worker process.

processes

respawned

The total number of abnormally terminated and respawned
child processes.

connections

accepted

The total number of accepted client connections.

dropped

The total number of dropped client connections.

active

The current number of active client connections.

idle

The current number of idle client connections.

ssl

handshakes

The total number of successful SSL handshakes.

handshakes_failed

The total number of failed SSL handshakes.

session_reuses

The total number of session reuses during SSL handshake.

requests

total

The total number of client requests.

current

The current number of client requests.

server_zones

For each status_zone:

processing

The number of
client requests that are currently being processed.

requests

The total number of
client requests received from clients.

responses

total

The total number of
responses sent to clients.

1xx,
2xx,
3xx,
4xx,
5xx

The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx.

discarded

The total number of requests completed without sending a response.

received

The total number of bytes received from clients.

sent

The total number of bytes sent to clients.

slabs

For each shared memory zone that uses slab allocator:

pages

used

The current number of used memory pages.

free

The current number of free memory pages.

slots

For each memory slot size (8, 16, 32, 64, 128, etc.)
the following data are provided:

used

The current number of used memory slots.

free

The current number of free memory slots.

reqs

The total number of attempts to allocate memory of specified size.

fails

The number of unsuccessful attempts to allocate memory of specified size.

upstreams

For each
dynamically
configurable
group,
the following data are provided:

peers

For each
server,
the following data are provided:

id

The ID of the server.

server

An
address
of the server.

name

The name of the server specified in the
server
directive.

service

The service
parameter value of the
server directive.

backup

A boolean value indicating whether the server is a
backup
server.

weight

Weight
of the server.

state

Current state, which may be one of
“up”,
“draining”,
“down”,
“unavail”,
“checking”,
or
“unhealthy”.

active

The current number of active connections.

max_conns

The max_conns limit
for the server.

requests

The total number of
client requests forwarded to this server.

responses

total

The total number of
responses obtained from this server.

1xx,
2xx,
3xx,
4xx,
5xx

The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx.

sent

The total number of bytes sent to this server.

received

The total number of bytes received from this server.

fails

The total number of
unsuccessful attempts to communicate with the server.

unavail

How many times
the server became unavailable for client requests
(state “unavail”)
due to the number of unsuccessful attempts reaching the
max_fails
threshold.

health_checks

checks

The total number of
health check
requests made.

fails

The number of failed health checks.

unhealthy

How many times
the server became unhealthy (state “unhealthy”).

last_passed

Boolean indicating
if the last health check request was successful and passed
tests.

downtime

Total time
the server was in the “unavail”,
“checking”, and “unhealthy” states.

downstart

The time (in milliseconds since Epoch)
when the server became
“unavail”,
“checking”, or “unhealthy”.

selected

The time (in milliseconds since Epoch)
when the server was last selected to process a request (1.7.5).

header_time

The average time to get the
response
header from the server (1.7.10).
Prior to version 1.11.6,
the field was available only when using the
least_time
load balancing method.

response_time

The average time to get the
full
response from the server (1.7.10).
Prior to version 1.11.6,
the field was available only when using the
least_time
load balancing method.

keepalive

The current number of
idle keepalive connections.

zombies

The current number of servers removed
from the group but still processing active client requests.

zone

The name of the shared memory
zone
that keeps the group’s configuration and run-time state.

queue

For the requests queue,
the following data are provided:

size

The current number of requests in the queue.

max_size

The maximum number of requests that can be in the queue at the same time.

overflows

The total number of requests rejected due to the queue overflow.

caches

For each cache (configured by
proxy_cache_path and the likes):

size

The current size of the cache.

max_size

The limit on the maximum size of the cache specified in the configuration.

cold

A boolean value indicating whether the “cache loader” process is still loading
data from disk into the cache.

    hit,
    stale,
    updating,
    revalidated

responses

The total number of responses read from the cache (hits, or stale responses
due to proxy_cache_use_stale
and the likes).

bytes

The total number of bytes read from the cache.

    miss,
    expired,
    bypass

responses

The total number of responses not taken from the cache (misses, expires, or
bypasses due to
proxy_cache_bypass
and the likes).

bytes

The total number of bytes read from the proxied server.

responses_written

The total number of responses written to the cache.

bytes_written

The total number of bytes written to the cache.

stream

server_zones

For each status_zone:

processing

The number of
client connections that are currently being processed.

connections

The total number of
connections accepted from clients.

sessions

total

The total number of completed client sessions.

2xx,
4xx,
5xx

The number of sessions completed with
status codes
2xx, 4xx, or 5xx.

discarded

The total number of connections completed without creating a session.

received

The total number of bytes received from clients.

sent

The total number of bytes sent to clients.

upstreams

For each
dynamically
configurable
group,
the following data are provided:

peers

For each
server
the following data are provided:

id

The ID of the server.

server

An
address
of the server.

name

The name of the server specified in the
server directive.

service

The service
parameter value of the
server directive.

backup

A boolean value indicating whether the server is a
backup
server.

weight

Weight
of the server.

state

Current state, which may be one of
“up”,
“down”,
“unavail”,
“checking”,
or
“unhealthy”.

active

The current number of connections.

max_conns

The max_conns limit
for the server.

connections

The total number of
client connections forwarded to this server.

connect_time

The average time to connect to the upstream server.
Prior to version 1.11.6,
the field was available only when using the
least_time
load balancing method.

first_byte_time

The average time to receive the first byte of data.
Prior to version 1.11.6,
the field was available only when using the
least_time
load balancing method.

response_time

The average time to receive the last byte of data.
Prior to version 1.11.6,
the field was available only when using the
least_time
load balancing method.

sent

The total number of bytes sent to this server.

received

The total number of bytes received from this server.

fails

The total number of
unsuccessful attempts to communicate with the server.

unavail

How many times
the server became unavailable for client connections
(state “unavail”)
due to the number of unsuccessful attempts reaching the
max_fails
threshold.

health_checks

checks

The total number of
health check
requests made.

fails

The number of failed health checks.

unhealthy

How many times
the server became unhealthy (state “unhealthy”).

last_passed

Boolean indicating
if the last health check request was successful and passed
tests.

downtime

Total time
the server was in the “unavail”,
“checking”, and “unhealthy” states.

downstart

The time (in milliseconds since Epoch)
when the server became
“unavail”,
“checking”, or “unhealthy”.

selected

The time (in milliseconds since Epoch)
when the server was last selected to process a connection.

zombies

The current number of servers removed
from the group but still processing active client connections.

zone

The name of the shared memory
zone
that keeps the group’s configuration and run-time state.

Compatibility

The
zone field in
http and stream
upstreams
was added in version 8.

The slabs status data
were added in version 8.

The
checking state
was added in version 8.

The
name and service fields in
http and stream
upstreams
were added in version 8.

The
nginx_build and ppid fields
were added in version 8.

The
sessions status data
and the discarded field in
stream server_zones
were added in version 7.

The zombies field
was moved from nginx debug version
in version 6.

The ssl status data
were added in version 6.

The
discarded field in
server_zones
was added in version 6.

The queue status data
were added in version 6.

The
pid field
was added in version 6.

The list of servers in upstreams
was moved into peers in
version 6.

The keepalive field of an upstream server
was removed in version 5.

The stream status data
were added in version 5.

The
generation field
was added in version 5.

The
respawned field in
processes
was added in version 5.

The
header_time and response_time fields in
upstreams
were added in version 5.

The
selected field in
upstreams
was added in version 4.

The draining state in
upstreams
was added in version 4.

The
id and max_conns fields in
upstreams
were added in version 3.

The revalidated field in
caches
was added in version 3.

The server_zones, caches,
and load_timestamp status data
were added in version 2.