<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_api_module"
        link="/en/docs/http/ngx_http_api_module.html"
        lang="en"
        rev="3">

<section id="summary">

<para>
The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API
for accessing various status information,
configuring upstream server groups on-the-fly, and managing
<link doc="ngx_http_keyval_module.xml">key-value pairs</link>
without the need of reconfiguring nginx.
</para>

<para>
<note>
The module supersedes the
<link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and
<link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link>
modules.
</note>
</para>

<para>
When using the <literal>PATCH</literal> or <literal>POST</literal> methods,
make sure that the payload does not exceed the
<link doc="ngx_http_core_module.xml" id="client_body_buffer_size">buffer size</link>
for reading the client request body, otherwise, the
<http-status code="413" text="Request Entity Too Large"/>
error may be returned.
</para>

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
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;
    }

    keyval_zone zone=one:32k state=one.keyval;
    keyval $arg_text $text zone=one;

    server {
        listen 127.0.0.1;

        location /api {
            <emphasis>api</emphasis> write=on;
            allow 127.0.0.1;
            deny all;
        }
    }
}

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;
    }
}
</example>
All API requests include
a supported API <link id="api_version">version</link> in the URI.
Examples of API requests with this configuration:
<example>
http://127.0.0.1/api/8/
http://127.0.0.1/api/8/nginx
http://127.0.0.1/api/8/connections
http://127.0.0.1/api/8/http/requests
http://127.0.0.1/api/8/http/server_zones/server_backend
http://127.0.0.1/api/8/http/caches/cache_backend
http://127.0.0.1/api/8/http/upstreams/backend
http://127.0.0.1/api/8/http/upstreams/backend/servers/
http://127.0.0.1/api/8/http/upstreams/backend/servers/1
http://127.0.0.1/api/8/http/keyvals/one?key=arg1
http://127.0.0.1/api/8/stream/
http://127.0.0.1/api/8/stream/server_zones/server_backend
http://127.0.0.1/api/8/stream/upstreams/
http://127.0.0.1/api/8/stream/upstreams/backend
http://127.0.0.1/api/8/stream/upstreams/backend/servers/1
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="api">
<syntax>
[<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax>
<default/>
<context>location</context>

<para>
Turns on the REST API interface in the surrounding location.
Access to this location should be
<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>.
</para>

<para>
The <literal>write</literal> parameter determines whether the API
is read-only or read-write.
By default, the API is read-only.
</para>

<para id="api_version">
All API requests should contain a supported API version in the URI.
If the request URI equals the location prefix,
the list of supported API versions is returned.
The current API version is “<literal>8</literal>”.
</para>

<para>
The optional “<literal>fields</literal>” argument in the request line
specifies which fields of the requested objects will be output:
<example>
http://127.0.0.1/api/8/nginx?fields=version,build
</example>
</para>

</directive>


<directive name="status_zone">
<syntax><value>zone</value></syntax>
<default/>
<context>server</context>
<context>location</context>
<context>if in location</context>
<appeared-in>1.13.12</appeared-in>

<para>
Enables collection of virtual
<link doc="ngx_http_core_module.xml" id="server">http</link>
or
<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link>
server status information in the specified <value>zone</value>.
Several servers may share the same zone.
</para>

<para id="status_zone_location">
Starting from 1.17.0, status information can be collected
per <link doc="ngx_http_core_module.xml" id="location"/>.
The special value <literal>off</literal> disables statistics collection
in nested location blocks.
Note that the statistics is collected
in the context of a location where processing ends.
It may be different from the original location, if an
<link doc="ngx_http_core_module.xml" id="internal">internal
redirect</link> happens during request processing.
</para>

</directive>

</section>

<section id="compatibility" name="Compatibility">

<para>
<list type="bullet">

<listitem>
Detailed failure counters were added to SSL statistics
in <link id="api_version">version</link> 8 (1.23.2).
</listitem>

<listitem>
The <literal>ssl</literal> data
for each HTTP
<link id="def_nginx_http_upstream">upstream</link>,
<link id="def_nginx_http_server_zone">server zone</link>,
and stream
<link id="def_nginx_stream_upstream">upstream</link>,
<link id="def_nginx_stream_server_zone">server zone</link>,
were added in <link id="api_version">version</link> 8 (1.21.6).
</listitem>

<listitem>
The <literal>codes</literal> data
in <literal>responses</literal> for each HTTP
<link id="def_nginx_http_upstream">upstream</link>,
<link id="def_nginx_http_server_zone">server zone</link>, and
<link id="def_nginx_http_location_zone">location zone</link>
were added in <link id="api_version">version</link> 7.
</listitem>

<listitem>
The <link id="stream_limit_conns_">/stream/limit_conns/</link> data
were added in <link id="api_version">version</link> 6.
</listitem>

<listitem>
The <link id="http_limit_conns_">/http/limit_conns/</link> data
were added in <link id="api_version">version</link> 6.
</listitem>

<listitem>
The <link id="http_limit_reqs_">/http/limit_reqs/</link> data
were added in <link id="api_version">version</link> 6.
</listitem>

<listitem>
The “<literal>expire</literal>” parameter of a
<link doc="ngx_http_keyval_module.xml">key-value</link> pair can be
<link id="postHttpKeyvalZoneData">set</link> or
<link id="patchHttpKeyvalZoneKeyValue">changed</link>
since <link id="api_version">version</link> 5.
</listitem>

<listitem>
The <link id="resolvers_">/resolvers/</link> data
were added in <link id="api_version">version</link> 5.
</listitem>

<listitem>
The <link id="http_location_zones_">/http/location_zones/</link> data
were added in <link id="api_version">version</link> 5.
</listitem>

<listitem>
The <literal>path</literal> and <literal>method</literal> fields of
<link id="def_nginx_error">nginx error object</link>
were removed in <link id="api_version">version</link> 4.
These fields continue to exist in earlier api versions,
but show an empty value.
</listitem>

<listitem>
The <link id="stream_zone_sync_">/stream/zone_sync/</link> data
were added in <link id="api_version">version</link> 3.
</listitem>

<listitem>
The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter
was added in <link id="api_version">version</link> 2.
</listitem>

<listitem>
The <link id="stream_keyvals_">/stream/keyvals/</link> data
were added in <link id="api_version">version</link> 2.
</listitem>

</list>
</para>

</section>
<section id="endpoints" name="Endpoints">
<para>
<list type="tag">
<tag-name id="root" name="/">
<literal>/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getAPIEndpoints">
<literal>GET</literal> - Return list of root endpoints
<para>Returns a list of root endpoints.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of strings</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="nginx" name="/nginx">
<literal>/nginx</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getNginx">
<literal>GET</literal> - Return status of nginx running instance
<para>Returns nginx version, build name, address, number of configuration reloads, IDs of master and worker processes.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of nginx running instance will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_object">nginx</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="processes" name="/processes">
<literal>/processes</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getProcesses">
<literal>GET</literal> - Return nginx processes status
<para>Returns the number of abnormally terminated and respawned child processes.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_processes">Processes</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteProcesses">
<literal>DELETE</literal> - Reset nginx processes statistics
<para>Resets counters of abnormally terminated and respawned child processes.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="connections" name="/connections">
<literal>/connections</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getConnections">
<literal>GET</literal> - Return client connections statistics
<para>Returns statistics of client connections.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the connections statistics will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_connections">Connections</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteConnections">
<literal>DELETE</literal> - Reset client connections statistics
<para>Resets statistics of accepted and dropped client connections.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="slabs_" name="/slabs/">
<literal>/slabs/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getSlabs">
<literal>GET</literal> - Return status of all slabs
<para>Returns status of slabs for each shared memory zone with slab allocator.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of slab zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link>" objects for all slabs</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="slabs_slab_zone_name" name="/slabs/{slabZoneName}">
<literal>/slabs/{slabZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>slabZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of the shared memory zone with slab allocator.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getSlabZone">
<literal>GET</literal> - Return status of a slab
<para>Returns status of slabs for a particular shared memory zone with slab allocator.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the slab zone will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link></listitem>
<listitem>404 - Slab not found (<literal>SlabNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteSlabZoneStats">
<literal>DELETE</literal> - Reset slab statistics
<para>Resets the “<literal>reqs</literal>” and “<literal>fails</literal>” metrics for each memory slot.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Slab not found (<literal>SlabNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_" name="/http/">
<literal>/http/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttp">
<literal>GET</literal> - Return list of HTTP-related endpoints
<para>Returns a list of first level HTTP endpoints.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of strings</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_requests" name="/http/requests">
<literal>/http/requests</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpRequests">
<literal>GET</literal> - Return HTTP requests statistics
<para>Returns status of client HTTP requests.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of client HTTP requests statistics will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_requests">HTTP Requests</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpRequests">
<literal>DELETE</literal> - Reset HTTP requests statistics
<para>Resets the number of total client HTTP requests.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_server_zones_" name="/http/server_zones/">
<literal>/http/server_zones/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpServerZones">
<literal>GET</literal> - Return status of all HTTP server zones
<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">server zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_server_zone">HTTP Server Zone</link>" objects for all HTTP server zones</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_server_zones_http_server_zone_name" name="/http/server_zones/{httpServerZoneName}">
<literal>/http/server_zones/{httpServerZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpServerZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of an HTTP server zone.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpServerZone">
<literal>GET</literal> - Return status of an HTTP server zone
<para>Returns status of a particular HTTP server zone.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the server zone will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_server_zone">HTTP Server Zone</link></listitem>
<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpServerZoneStat">
<literal>DELETE</literal> - Reset statistics for an HTTP server zone
<para>Resets statistics of accepted and discarded requests, responses, received and sent bytes, counters of SSL handshakes and session reuses in a particular HTTP server zone.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_location_zones_" name="/http/location_zones/">
<literal>/http/location_zones/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpLocationZones">
<literal>GET</literal> - Return status of all HTTP location zones
<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of location zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_location_zone">HTTP Location Zone</link>" objects for all HTTP location zones</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_location_zones_http_location_zone_name" name="/http/location_zones/{httpLocationZoneName}">
<literal>/http/location_zones/{httpLocationZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpLocationZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of an HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpLocationZone">
<literal>GET</literal> - Return status of an HTTP location zone
<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the location zone will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_location_zone">HTTP Location Zone</link></listitem>
<listitem>404 - Location zone not found (<literal>LocationZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpLocationZoneStat">
<literal>DELETE</literal> - Reset statistics for a location zone.
<para>Resets statistics of accepted and discarded requests, responses, received and sent bytes in a particular location zone.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Location zone not found (<literal>LocationZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_caches_" name="/http/caches/">
<literal>/http/caches/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpCaches">
<literal>GET</literal> - Return status of all caches
<para>Returns status of each cache configured by <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path">proxy_cache_path</link> and other “<literal>*_cache_path</literal>” directives.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of cache zones will be output. If the “<literal>fields</literal>” value is empty, then only names of cache zones will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_cache">HTTP Cache</link>" objects for all HTTP caches</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_caches_http_cache_zone_name" name="/http/caches/{httpCacheZoneName}">
<literal>/http/caches/{httpCacheZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpCacheZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of the cache zone.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpCacheZone">
<literal>GET</literal> - Return status of a cache
<para>Returns status of a particular cache.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the cache zone will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_cache">HTTP Cache</link></listitem>
<listitem>404 - Cache not found (<literal>CacheNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpCacheZoneStat">
<literal>DELETE</literal> - Reset cache statistics
<para>Resets statistics of cache hits/misses in a particular cache zone.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Cache not found (<literal>CacheNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_limit_conns_" name="/http/limit_conns/">
<literal>/http/limit_conns/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpLimitConnZones">
<literal>GET</literal> - Return status of all HTTP limit_conn zones
<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link>" objects for all HTTP limit conns</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_limit_conns_http_limit_conn_zone_name" name="/http/limit_conns/{httpLimitConnZoneName}">
<literal>/http/limit_conns/{httpLimitConnZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpLimitConnZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpLimitConnZone">
<literal>GET</literal> - Return status of an HTTP limit_conn zone
<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link></listitem>
<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpLimitConnZoneStat">
<literal>DELETE</literal> - Reset statistics for an HTTP limit_conn zone
<para>Resets the connection limiting statistics.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_limit_reqs_" name="/http/limit_reqs/">
<literal>/http/limit_reqs/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpLimitReqZones">
<literal>GET</literal> - Return status of all HTTP limit_req zones
<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of limit_req zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link>" objects for all HTTP limit reqs</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_limit_reqs_http_limit_req_zone_name" name="/http/limit_reqs/{httpLimitReqZoneName}">
<literal>/http/limit_reqs/{httpLimitReqZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpLimitReqZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpLimitReqZone">
<literal>GET</literal> - Return status of an HTTP limit_req zone
<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link> will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link></listitem>
<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpLimitReqZoneStat">
<literal>DELETE</literal> - Reset statistics for an HTTP limit_req zone
<para>Resets the requests limiting statistics.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_upstreams_" name="/http/upstreams/">
<literal>/http/upstreams/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpUpstreams">
<literal>GET</literal> - Return status of all HTTP upstream server groups
<para>Returns status of each HTTP upstream server group and its servers.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_upstream">HTTP Upstream</link>" objects for all HTTP upstreams</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_upstreams_http_upstream_name_" name="/http/upstreams/{httpUpstreamName}/">
<literal>/http/upstreams/{httpUpstreamName}/</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpUpstreamName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of an HTTP upstream server group.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpUpstreamName">
<literal>GET</literal> - Return status of an HTTP upstream server group
<para>Returns status of a particular HTTP upstream server group and its servers.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the upstream server group will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_upstream">HTTP Upstream</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpUpstreamStat">
<literal>DELETE</literal> - Reset statistics of an HTTP upstream server group
<para>Resets the statistics for each upstream server in an upstream server group and queue statistics.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_upstreams_http_upstream_name_servers_" name="/http/upstreams/{httpUpstreamName}/servers/">
<literal>/http/upstreams/{httpUpstreamName}/servers/</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpUpstreamName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of an upstream server group.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpUpstreamServers">
<literal>GET</literal> - Return configuration of all servers in an HTTP upstream server group
<para>Returns configuration of each server in a particular HTTP upstream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Servers</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="postHttpUpstreamServer">
<literal>POST</literal> - Add a server to an HTTP upstream server group
<para>Adds a new server to an HTTP upstream server group. Server parameters are specified in the JSON format.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>postHttpUpstreamServer</literal>
(<link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link>, required)</tag-name>
<tag-desc>
Address of a new server and other optional parameters in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>201 - Created, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>),
missing “<literal>server</literal>” argument (<literal>UpstreamConfFormatError</literal>),
unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>),
nested object or list (<literal>UpstreamConfFormatError</literal>),
“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>),
service upstream “<literal>host</literal>” may not have port (<literal>UpstreamBadAddress</literal>),
service upstream “<literal>host</literal>” requires domain name (<literal>UpstreamBadAddress</literal>),
invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>),
invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>),
invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>),
invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>),
invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>),
reading request body failed <literal>BodyReadError</literal>),
route is too long (<literal>UpstreamBadRoute</literal>),
“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>),
no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>),
upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>),
upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>409 - Entry exists (<literal>EntryExists</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_upstreams_http_upstream_name_servers_http_upstream_server_id" name="/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}">
<literal>/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpUpstreamName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of the upstream server group.</tag-desc>
<tag-name><literal>httpUpstreamServerId</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The ID of the server.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpUpstreamPeer">
<literal>GET</literal> - Return configuration of a server in an HTTP upstream server group
<para>Returns configuration of a particular server in the HTTP upstream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="patchHttpUpstreamPeer">
<literal>PATCH</literal> - Modify a server in an HTTP upstream server group
<para>Modifies settings of a particular server in an HTTP upstream server group. Server parameters are specified in the JSON format.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>patchHttpUpstreamServer</literal>
(<link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link>, required)</tag-name>
<tag-desc>
Server parameters, specified in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>),
unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>),
nested object or list (<literal>UpstreamConfFormatError</literal>),
“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>),
invalid “<literal>server</literal>” argument (<literal>UpstreamBadAddress</literal>),
invalid server ID (<literal>UpstreamBadServerId</literal>),
invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>),
invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>),
invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>),
invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>),
invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>),
reading request body failed <literal>BodyReadError</literal>),
route is too long (<literal>UpstreamBadRoute</literal>),
“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>),
server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>),
server “<literal>ID</literal>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>),
upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpUpstreamServer">
<literal>DELETE</literal> - Remove a server from an HTTP upstream server group
<para>Removes a server from an HTTP upstream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Servers</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid server ID (<literal>UpstreamBadServerId</literal>),
server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_keyvals_" name="/http/keyvals/">
<literal>/http/keyvals/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpKeyvalZones">
<literal>GET</literal> - Return key-value pairs from all HTTP keyval zones
<para>Returns key-value pairs for each HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
If the “<literal>fields</literal>” value is empty, then only HTTP keyval zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>" objects for all HTTP keyvals</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="http_keyvals_http_keyval_zone_name" name="/http/keyvals/{httpKeyvalZoneName}">
<literal>/http/keyvals/{httpKeyvalZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>httpKeyvalZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of an HTTP keyval shared memory zone.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getHttpKeyvalZoneKeysValues">
<literal>GET</literal> - Return key-value pairs from an HTTP keyval zone
<para>Returns key-value pairs stored in a particular HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>key</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Get a particular key-value pair from the HTTP keyval zone.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link></listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
keyval key not found (<literal>KeyvalKeyNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="postHttpKeyvalZoneData">
<literal>POST</literal> - Add a key-value pair to the HTTP keyval zone
<para>Adds a new key-value pair to the HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>Key-value</literal>
(<link id="def_nginx_http_keyval_zone_post_patch">HTTP Keyval Shared Memory Zone</link>, required)</tag-name>
<tag-desc>
A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</link> directive.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>201 - Created</listitem>
<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>),
invalid key format (<literal>KeyvalFormatError</literal>),
key required (<literal>KeyvalFormatError</literal>),
keyval timeout is not enabled (<literal>KeyvalFormatError</literal>),
only one key can be added (<literal>KeyvalFormatError</literal>),
reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>409 - Entry exists (<literal>EntryExists</literal>),
key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="patchHttpKeyvalZoneKeyValue">
<literal>PATCH</literal> - Modify a key-value or delete a key
<para>Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</link> directive.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>httpKeyvalZoneKeyValue</literal>
(<link id="def_nginx_http_keyval_zone_post_patch">HTTP Keyval Shared Memory Zone</link>, required)</tag-name>
<tag-desc>
A new value for the key is specified in the JSON format.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>),
key required (<literal>KeyvalFormatError</literal>),
keyval timeout is not enabled (<literal>KeyvalFormatError</literal>),
only one key can be updated (<literal>KeyvalFormatError</literal>),
reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
keyval key not found (<literal>KeyvalKeyNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteHttpKeyvalZoneData">
<literal>DELETE</literal> - Empty the HTTP keyval zone
<para>Deletes all key-value pairs from the HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_" name="/stream/">
<literal>/stream/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStream">
<literal>GET</literal> - Return list of stream-related endpoints
<para>Returns a list of first level stream endpoints.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of strings</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_server_zones_" name="/stream/server_zones/">
<literal>/stream/server_zones/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamServerZones">
<literal>GET</literal> - Return status of all stream server zones
<para>Returns status information for each stream <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">server zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_server_zone">Stream Server Zone</link>" objects for all stream server zones</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_server_zones_stream_server_zone_name" name="/stream/server_zones/{streamServerZoneName}">
<literal>/stream/server_zones/{streamServerZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>streamServerZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a stream server zone.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamServerZone">
<literal>GET</literal> - Return status of a stream server zone
<para>Returns status of a particular stream server zone.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the server zone will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_server_zone">Stream Server Zone</link></listitem>
<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteStreamServerZoneStat">
<literal>DELETE</literal> - Reset statistics for a stream server zone
<para>Resets statistics of accepted and discarded connections, sessions, received and sent bytes, counters of SSL handshakes and session reuses in a particular stream server zone.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_limit_conns_" name="/stream/limit_conns/">
<literal>/stream/limit_conns/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamLimitConnZones">
<literal>GET</literal> - Return status of all stream limit_conn zones
<para>Returns status information for each stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link>" objects for all stream limit conns</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_limit_conns_stream_limit_conn_zone_name" name="/stream/limit_conns/{streamLimitConnZoneName}">
<literal>/stream/limit_conns/{streamLimitConnZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>streamLimitConnZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamLimitConnZone">
<literal>GET</literal> - Return status of an stream limit_conn zone
<para>Returns status of a particular stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link></listitem>
<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteStreamLimitConnZoneStat">
<literal>DELETE</literal> - Reset statistics for a stream limit_conn zone
<para>Resets the connection limiting statistics.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_upstreams_" name="/stream/upstreams/">
<literal>/stream/upstreams/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamUpstreams">
<literal>GET</literal> - Return status of all stream upstream server groups
<para>Returns status of each stream upstream server group and its servers.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_upstreams_stream_upstream_name_" name="/stream/upstreams/{streamUpstreamName}/">
<literal>/stream/upstreams/{streamUpstreamName}/</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>streamUpstreamName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a stream upstream server group.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamUpstream">
<literal>GET</literal> - Return status of a stream upstream server group
<para>Returns status of a particular stream upstream server group and its servers.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the upstream server group will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_upstream">Stream Upstream</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteStreamUpstreamStat">
<literal>DELETE</literal> - Reset statistics of a stream upstream server group
<para>Resets the statistics for each upstream server in an upstream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_upstreams_stream_upstream_name_servers_" name="/stream/upstreams/{streamUpstreamName}/servers/">
<literal>/stream/upstreams/{streamUpstreamName}/servers/</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>streamUpstreamName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of an upstream server group.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamUpstreamServers">
<literal>GET</literal> - Return configuration of all servers in a stream upstream server group
<para>Returns configuration of each server in a particular stream upstream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="postStreamUpstreamServer">
<literal>POST</literal> - Add a server to a stream upstream server group
<para>Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>postStreamUpstreamServer</literal>
(<link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link>, required)</tag-name>
<tag-desc>
Address of a new server and other optional parameters in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>201 - Created, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>),
missing “<literal>server</literal>” argument (<literal>UpstreamConfFormatError</literal>),
unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>),
nested object or list (<literal>UpstreamConfFormatError</literal>),
“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>),
no port in server “<literal>host</literal>” (<literal>UpstreamBadAddress</literal>),
service upstream “<literal>host</literal>” may not have port (<literal>UpstreamBadAddress</literal>),
service upstream “<literal>host</literal>” requires domain name (<literal>UpstreamBadAddress</literal>),
invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>),
invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>),
invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>),
invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>),
invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>),
“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>),
no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>),
upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>),
upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>),
reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>409 - Entry exists (<literal>EntryExists</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_upstreams_stream_upstream_name_servers_stream_upstream_server_id" name="/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}">
<literal>/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>streamUpstreamName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of the upstream server group.</tag-desc>
<tag-name><literal>streamUpstreamServerId</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The ID of the server.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamUpstreamServer">
<literal>GET</literal> - Return configuration of a server in a stream upstream server group
<para>Returns configuration of a particular server in the stream upstream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>),
server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="patchStreamUpstreamServer">
<literal>PATCH</literal> - Modify a server in a stream upstream server group
<para>Modifies settings of a particular server in a stream upstream server group. Server parameters are specified in the JSON format.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>patchStreamUpstreamServer</literal>
(<link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link>, required)</tag-name>
<tag-desc>
Server parameters, specified in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>),
unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>),
nested object or list (<literal>UpstreamConfFormatError</literal>),
“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>),
invalid “<literal>server</literal>” argument (<literal>UpstreamBadAddress</literal>),
no port in server “<literal>host</literal>” (<literal>UpstreamBadAddress</literal>),
invalid server ID (<literal>UpstreamBadServerId</literal>),
invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>),
invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>),
invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>),
invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>),
invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>),
reading request body failed <literal>BodyReadError</literal>),
“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>),
server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>),
server “<value>ID</value>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>),
upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteStreamUpstreamServer">
<literal>DELETE</literal> - Remove a server from a stream upstream server group
<para>Removes a server from a stream server group.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem>
<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
invalid server ID (<literal>UpstreamBadServerId</literal>),
server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>),
upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_keyvals_" name="/stream/keyvals/">
<literal>/stream/keyvals/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamKeyvalZones">
<literal>GET</literal> - Return key-value pairs from all stream keyval zones
<para>Returns key-value pairs for each stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
If the “<literal>fields</literal>” value is empty, then only stream keyval zone names will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>" objects for all stream keyvals</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_keyvals_stream_keyval_zone_name" name="/stream/keyvals/{streamKeyvalZoneName}">
<literal>/stream/keyvals/{streamKeyvalZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>streamKeyvalZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a stream keyval shared memory zone.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamKeyvalZoneKeysValues">
<literal>GET</literal> - Return key-value pairs from a stream keyval zone
<para>Returns key-value pairs stored in a particular stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>key</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Get a particular key-value pair from the stream keyval zone.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link></listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
keyval key not found (<literal>KeyvalKeyNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="postStreamKeyvalZoneData">
<literal>POST</literal> - Add a key-value pair to the stream keyval zone
<para>Adds a new key-value pair to the stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the stream keyval shared memory zone is empty.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>Key-value</literal>
(<link id="def_nginx_stream_keyval_zone_post_patch">Stream Keyval Shared Memory Zone</link>, required)</tag-name>
<tag-desc>
A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</link> directive.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>201 - Created</listitem>
<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>),
invalid key format (<literal>KeyvalFormatError</literal>),
key required (<literal>KeyvalFormatError</literal>),
keyval timeout is not enabled (<literal>KeyvalFormatError</literal>),
only one key can be added (<literal>KeyvalFormatError</literal>),
reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>409 - Entry exists (<literal>EntryExists</literal>),
key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="patchStreamKeyvalZoneKeyValue">
<literal>PATCH</literal> - Modify a key-value or delete a key
<para>Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time is specified in milliseconds with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</link> directive.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>streamKeyvalZoneKeyValue</literal>
(<link id="def_nginx_stream_keyval_zone_post_patch">Stream Keyval Shared Memory Zone</link>, required)</tag-name>
<tag-desc>
A new value for the key is specified in the JSON format.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>),
key required (<literal>KeyvalFormatError</literal>),
keyval timeout is not enabled (<literal>KeyvalFormatError</literal>),
only one key can be updated (<literal>KeyvalFormatError</literal>),
reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
keyval key not found (<literal>KeyvalKeyNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem>
<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteStreamKeyvalZoneData">
<literal>DELETE</literal> - Empty the stream keyval zone
<para>Deletes all key-value pairs from the stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="stream_zone_sync_" name="/stream/zone_sync/">
<literal>/stream/zone_sync/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getStreamZoneSync">
<literal>GET</literal> - Return sync status of a node
<para>Returns synchronization status of a cluster node.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_stream_zone_sync">Stream Zone Sync Node</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="resolvers_" name="/resolvers/">
<literal>/resolvers/</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getResolverZones">
<literal>GET</literal> - Return status for all resolver zones
<para>Returns status information for each <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of resolvers statistics will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns a collection of "<link id="def_nginx_resolver_zone">Resolver Zone</link>" objects for all resolvers</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="resolvers_resolver_zone_name" name="/resolvers/{resolverZoneName}">
<literal>/resolvers/{resolverZoneName}</literal>
</tag-name>
<tag-desc>
Parameters common for all methods:
<list type="tag">
<tag-name><literal>resolverZoneName</literal>
(<literal>string</literal>, required)</tag-name>
<tag-desc>
The name of a resolver zone.</tag-desc>
</list>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getResolverZone">
<literal>GET</literal> - Return statistics of a resolver zone
<para>Returns statistics stored in a particular resolver <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">zone</link>.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of the resolver zone will be output (requests, responses, or both).</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_resolver_zone">Resolver Zone</link></listitem>
<listitem>404 - Resolver zone not found (<literal>ResolverZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteResolverZoneStat">
<literal>DELETE</literal> - Reset statistics for a resolver zone.
<para>Resets statistics in a particular resolver zone.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Resolver zone not found (<literal>ResolverZoneNotFound</literal>),
unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
<tag-name id="ssl" name="/ssl">
<literal>/ssl</literal>
</tag-name>
<tag-desc>
<para>Supported methods:</para>
<list type="bullet" compact="yes">
<listitem id="getSsl">
<literal>GET</literal> - Return SSL statistics
<para>Returns SSL statistics.</para>
<para>
Request parameters:
<list type="tag">
<tag-name><literal>fields</literal>
(<literal>string</literal>, optional)</tag-name>
<tag-desc>
Limits which fields of SSL statistics will be output.</tag-desc>
</list>
</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>200 - Success, returns <link id="def_nginx_ssl_object">SSL</link></listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
<listitem id="deleteSslStat">
<literal>DELETE</literal> - Reset SSL statistics
<para>Resets counters of SSL handshakes and session reuses.</para>
<para>
Possible responses:
</para>
<list type="bullet">
<listitem>204 - Success</listitem>
<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
</list>
</listitem>
</list>
</tag-desc>
</list>
</para>
</section>
<section id="definitions" name="Response Objects">
<para>
<list type="bullet">
<listitem id="def_nginx_object">
<para>nginx:</para>
General information about nginx:<list type="tag">
<tag-name>
<literal>version</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Version of nginx.
</tag-desc>
<tag-name>
<literal>build</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Name of nginx build.
</tag-desc>
<tag-name>
<literal>address</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The address of the server that accepted status request.
</tag-desc>
<tag-name>
<literal>generation</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of configuration <link url="https://nginx.org/en/docs/control.html#reconfiguration">reloads</link>.
</tag-desc>
<tag-name>
<literal>load_timestamp</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Time of the last reload of configuration, in the ISO 8601 format with millisecond resolution.
</tag-desc>
<tag-name>
<literal>timestamp</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Current time in the ISO 8601 format with millisecond resolution.
</tag-desc>
<tag-name>
<literal>pid</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The ID of the worker process that handled status request.
</tag-desc>
<tag-name>
<literal>ppid</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The ID of the master process that started the <link url="https://nginx.org/en/docs/http/ngx_http_status_module.html#pid">worker process</link>.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "nginx" : {
    "version" : "1.21.6",
    "build" : "nginx-plus-r27",
    "address" : "206.251.255.64",
    "generation" : 6,
    "load_timestamp" : "2022-06-28T11:15:44.467Z",
    "timestamp" : "2022-06-28T09:26:07.305Z",
    "pid" : 32212,
    "ppid" : 32210
  }
}</example>
</listitem>
<listitem id="def_nginx_processes">
<para>Processes:</para>
<list type="tag">
<tag-name>
<literal>respawned</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of abnormally terminated and respawned child processes.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "respawned" : 0
}</example>
</listitem>
<listitem id="def_nginx_connections">
<para>Connections:</para>
The number of accepted, dropped, active, and idle connections.<list type="tag">
<tag-name>
<literal>accepted</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of accepted client connections.
</tag-desc>
<tag-name>
<literal>dropped</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of dropped client connections.
</tag-desc>
<tag-name>
<literal>active</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of active client connections.
</tag-desc>
<tag-name>
<literal>idle</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of idle client connections.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "accepted" : 4968119,
  "dropped" : 0,
  "active" : 5,
  "idle" : 117
}</example>
</listitem>
<listitem id="def_nginx_ssl_object">
<para>SSL:</para>
<list type="tag">
<tag-name>
<literal>handshakes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of successful SSL handshakes.
</tag-desc>
<tag-name>
<literal>handshakes_failed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of failed SSL handshakes.
</tag-desc>
<tag-name>
<literal>session_reuses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of session reuses during SSL handshake.
</tag-desc>
<tag-name>
<literal>no_common_protocol</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no common protocol.
</tag-desc>
<tag-name>
<literal>no_common_cipher</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no shared cipher.
</tag-desc>
<tag-name>
<literal>handshake_timeout</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of a timeout.
</tag-desc>
<tag-name>
<literal>peer_rejected_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed SSL handshakes when nginx presented the certificate to the client but it was rejected with a corresponding alert message.
</tag-desc>
<tag-name>
<literal>verify_failures</literal></tag-name>
<tag-desc>
SSL certificate verification errors<list type="tag">
<tag-name>
<literal>no_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A client did not provide the required certificate.
</tag-desc>
<tag-name>
<literal>expired_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
An expired or not yet valid certificate was presented by a client.
</tag-desc>
<tag-name>
<literal>revoked_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A revoked certificate was presented by a client.
</tag-desc>
<tag-name>
<literal>hostname_mismatch</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Server's certificate doesn't match the hostname.
</tag-desc>
<tag-name>
<literal>other</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Other SSL certificate verification errors.
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "handshakes" : 79572,
  "handshakes_failed" : 21025,
  "session_reuses" : 15762,
  "no_common_protocol" : 4,
  "no_common_cipher" : 2,
  "handshake_timeout" : 0,
  "peer_rejected_cert" : 0,
  "verify_failures" : {
    "no_cert" : 0,
    "expired_cert" : 2,
    "revoked_cert" : 1,
    "hostname_mismatch" : 2,
    "other" : 1
  }
}</example>
</listitem>
<listitem id="def_nginx_slab_zone">
<para>Shared memory zone with slab allocator:</para>
Shared memory zone with slab allocator<list type="tag">
<tag-name>
<literal>pages</literal></tag-name>
<tag-desc>
The number of free and used memory pages.<list type="tag">
<tag-name>
<literal>used</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of used memory pages.
</tag-desc>
<tag-name>
<literal>free</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of free memory pages.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>slots</literal></tag-name>
<tag-desc>
<para>Status data for memory slots (8, 16, 32, 64, 128, etc.)</para><para>A collection of "<link id="def_nginx_slab_zone_slot">Memory Slot</link>" objects</para>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "pages" : {
    "used" : 1143,
    "free" : 2928
  },
  "slots" : {
    "8" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "16" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "32" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "64" : {
      "used" : 1,
      "free" : 63,
      "reqs" : 1,
      "fails" : 0
    },
    "128" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "256" : {
      "used" : 18078,
      "free" : 178,
      "reqs" : 1635736,
      "fails" : 0
    }
  }
}</example>
</listitem>
<listitem id="def_nginx_slab_zone_slot">
<para>Memory Slot:</para>
<list type="tag">
<tag-name>
<literal>used</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of used memory slots.
</tag-desc>
<tag-name>
<literal>free</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of free memory slots.
</tag-desc>
<tag-name>
<literal>reqs</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of attempts to allocate memory of specified size.
</tag-desc>
<tag-name>
<literal>fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of unsuccessful attempts to allocate memory of specified size.
</tag-desc>
</list>
</listitem>
<listitem id="def_nginx_http_requests">
<para>HTTP Requests:</para>
<list type="tag">
<tag-name>
<literal>total</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of client requests.
</tag-desc>
<tag-name>
<literal>current</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of client requests.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "total" : 10624511,
  "current" : 4
}</example>
</listitem>
<listitem id="def_nginx_http_server_zone">
<para>HTTP Server Zone:</para>
<list type="tag">
<tag-name>
<literal>processing</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of client requests that are currently being processed.
</tag-desc>
<tag-name>
<literal>requests</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of client requests received from clients.
</tag-desc>
<tag-name>
<literal>responses</literal></tag-name>
<tag-desc>
The total number of responses sent to clients, the number of responses with status codes “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, “<literal>4xx</literal>”, and “<literal>5xx</literal>”, and the number of responses per each status code.<list type="tag">
<tag-name>
<literal>1xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>1xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>2xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>2xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>3xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>3xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>4xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>4xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>5xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>5xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>codes</literal></tag-name>
<tag-desc>
The number of responses per each status code.<list type="tag">
<tag-name>
<literal>codeNumber</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with this particular status code.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>total</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses sent to clients.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>discarded</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests completed without sending a response.
</tag-desc>
<tag-name>
<literal>received</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes received from clients.
</tag-desc>
<tag-name>
<literal>sent</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes sent to clients.
</tag-desc>
<tag-name>
<literal>ssl</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>handshakes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of successful SSL handshakes.
</tag-desc>
<tag-name>
<literal>handshakes_failed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of failed SSL handshakes.
</tag-desc>
<tag-name>
<literal>session_reuses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of session reuses during SSL handshake.
</tag-desc>
<tag-name>
<literal>no_common_protocol</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no common protocol.
</tag-desc>
<tag-name>
<literal>no_common_cipher</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no shared cipher.
</tag-desc>
<tag-name>
<literal>handshake_timeout</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of a timeout.
</tag-desc>
<tag-name>
<literal>peer_rejected_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed SSL handshakes when nginx presented the certificate to the client but it was rejected with a corresponding alert message.
</tag-desc>
<tag-name>
<literal>verify_failures</literal></tag-name>
<tag-desc>
SSL certificate verification errors<list type="tag">
<tag-name>
<literal>no_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A client did not provide the required certificate.
</tag-desc>
<tag-name>
<literal>expired_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
An expired or not yet valid certificate was presented by a client.
</tag-desc>
<tag-name>
<literal>revoked_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A revoked certificate was presented by a client.
</tag-desc>
<tag-name>
<literal>other</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Other SSL certificate verification errors.
</tag-desc>
</list>
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "processing" : 1,
  "requests" : 706690,
  "responses" : {
    "1xx" : 0,
    "2xx" : 699482,
    "3xx" : 4522,
    "4xx" : 907,
    "5xx" : 266,
    "codes" : {
      "200" : 699482,
      "301" : 4522,
      "404" : 907,
      "503" : 266
    },
    "total" : 705177
  },
  "discarded" : 1513,
  "received" : 172711587,
  "sent" : 19415530115,
  "ssl" : {
    "handshakes" : 104303,
    "handshakes_failed" : 1421,
    "session_reuses" : 54645,
    "no_common_protocol" : 4,
    "no_common_cipher" : 2,
    "handshake_timeout" : 0,
    "peer_rejected_cert" : 0,
    "verify_failures" : {
      "no_cert" : 0,
      "expired_cert" : 2,
      "revoked_cert" : 1,
      "other" : 1
    }
  }
}</example>
</listitem>
<listitem id="def_nginx_http_location_zone">
<para>HTTP Location Zone:</para>
<list type="tag">
<tag-name>
<literal>requests</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of client requests received from clients.
</tag-desc>
<tag-name>
<literal>responses</literal></tag-name>
<tag-desc>
The total number of responses sent to clients, the number of responses with status codes “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, “<literal>4xx</literal>”, and “<literal>5xx</literal>”, and the number of responses per each status code.<list type="tag">
<tag-name>
<literal>1xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>1xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>2xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>2xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>3xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>3xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>4xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>4xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>5xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>5xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>codes</literal></tag-name>
<tag-desc>
The number of responses per each status code.<list type="tag">
<tag-name>
<literal>codeNumber</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with this particular status code.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>total</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses sent to clients.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>discarded</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests completed without sending a response.
</tag-desc>
<tag-name>
<literal>received</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes received from clients.
</tag-desc>
<tag-name>
<literal>sent</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes sent to clients.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "requests" : 706690,
  "responses" : {
    "1xx" : 0,
    "2xx" : 699482,
    "3xx" : 4522,
    "4xx" : 907,
    "5xx" : 266,
    "codes" : {
      "200" : 112674,
      "301" : 4522,
      "404" : 2504,
      "503" : 266
    },
    "total" : 705177
  },
  "discarded" : 1513,
  "received" : 172711587,
  "sent" : 19415530115
}</example>
</listitem>
<listitem id="def_nginx_http_cache">
<para>HTTP Cache:</para>
<list type="tag">
<tag-name>
<literal>size</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current size of the cache.
</tag-desc>
<tag-name>
<literal>max_size</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The limit on the maximum size of the cache specified in the configuration.
</tag-desc>
<tag-name>
<literal>cold</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
A boolean value indicating whether the “cache loader” process is still loading data from disk into the cache.
</tag-desc>
<tag-name>
<literal>hit</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid">valid</link> responses read from the cache.
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the cache.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>stale</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of expired responses read from the cache (see <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale">proxy_cache_use_stale</link> and other “<literal>*_cache_use_stale</literal>” directives).
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the cache.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>updating</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of expired responses read from the cache while responses were being updated (see <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale_updating">proxy_cache_use_stale</link> and other “<literal>*_cache_use_stale</literal>” directives).
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the cache.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>revalidated</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of expired and revalidated responses read from the cache (see <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_revalidate">proxy_cache_revalidate</link> and other “<literal>*_cache_revalidate</literal>” directives.
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the cache.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>miss</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses not found in the cache.
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the proxied server.
</tag-desc>
<tag-name>
<literal>responses_written</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses written to the cache.
</tag-desc>
<tag-name>
<literal>bytes_written</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes written to the cache.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>expired</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of expired responses not taken from the cache.
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the proxied server.
</tag-desc>
<tag-name>
<literal>responses_written</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses written to the cache.
</tag-desc>
<tag-name>
<literal>bytes_written</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes written to the cache.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>bypass</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>responses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses not looked up in the cache due to the <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_bypass">proxy_cache_bypass</link> and other “<literal>*_cache_bypass</literal>” directives.
</tag-desc>
<tag-name>
<literal>bytes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes read from the proxied server.
</tag-desc>
<tag-name>
<literal>responses_written</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses written to the cache.
</tag-desc>
<tag-name>
<literal>bytes_written</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes written to the cache.
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "size" : 530915328,
  "max_size" : 536870912,
  "cold" : false,
  "hit" : {
    "responses" : 254032,
    "bytes" : 6685627875
  },
  "stale" : {
    "responses" : 0,
    "bytes" : 0
  },
  "updating" : {
    "responses" : 0,
    "bytes" : 0
  },
  "revalidated" : {
    "responses" : 0,
    "bytes" : 0
  },
  "miss" : {
    "responses" : 1619201,
    "bytes" : 53841943822
  },
  "expired" : {
    "responses" : 45859,
    "bytes" : 1656847080,
    "responses_written" : 44992,
    "bytes_written" : 1641825173
  },
  "bypass" : {
    "responses" : 200187,
    "bytes" : 5510647548,
    "responses_written" : 200173,
    "bytes_written" : 44992
  }
}</example>
</listitem>
<listitem id="def_nginx_http_limit_conn_zone">
<para>HTTP Connections Limiting:</para>
<list type="tag">
<tag-name>
<literal>passed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections that were neither limited nor accounted as limited.
</tag-desc>
<tag-name>
<literal>rejected</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections that were rejected.
</tag-desc>
<tag-name>
<literal>rejected_dry_run</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "passed" : 15,
  "rejected" : 0,
  "rejected_dry_run" : 2
}</example>
</listitem>
<listitem id="def_nginx_http_limit_req_zone">
<para>HTTP Requests Rate Limiting:</para>
<list type="tag">
<tag-name>
<literal>passed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests that were neither limited nor accounted as limited.
</tag-desc>
<tag-name>
<literal>delayed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests that were delayed.
</tag-desc>
<tag-name>
<literal>rejected</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests that were rejected.
</tag-desc>
<tag-name>
<literal>delayed_dry_run</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests accounted as delayed in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode.
</tag-desc>
<tag-name>
<literal>rejected_dry_run</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "passed" : 15,
  "delayed" : 4,
  "rejected" : 0,
  "delayed_dry_run" : 1,
  "rejected_dry_run" : 2
}</example>
</listitem>
<listitem id="def_nginx_http_upstream">
<para>HTTP Upstream:</para>
<list type="tag">
<tag-name>
<literal>peers</literal></tag-name>
<tag-desc>
An array of:<list type="tag">
<tag-name>
<literal>id</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The ID of the server.
</tag-desc>
<tag-name>
<literal>server</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
An  <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</link> of the server.
</tag-desc>
<tag-name>
<literal>service</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</link> parameter value of the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link> directive.
</tag-desc>
<tag-name>
<literal>name</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The name of the server specified in the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link> directive.
</tag-desc>
<tag-name>
<literal>backup</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
A boolean value indicating whether the server is a <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</link> server.
</tag-desc>
<tag-name>
<literal>weight</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
<link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</link> of the server.
</tag-desc>
<tag-name>
<literal>state</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Current state, which may be one of “<literal>up</literal>”, “<literal>draining</literal>”, “<literal>down</literal>”, “<literal>unavail</literal>”, “<literal>checking</literal>”, and “<literal>unhealthy</literal>”.
</tag-desc>
<tag-name>
<literal>active</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of active connections.
</tag-desc>
<tag-name>
<literal>ssl</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>handshakes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of successful SSL handshakes.
</tag-desc>
<tag-name>
<literal>handshakes_failed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of failed SSL handshakes.
</tag-desc>
<tag-name>
<literal>session_reuses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of session reuses during SSL handshake.
</tag-desc>
<tag-name>
<literal>no_common_protocol</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no common protocol.
</tag-desc>
<tag-name>
<literal>handshake_timeout</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of a timeout.
</tag-desc>
<tag-name>
<literal>peer_rejected_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message.
</tag-desc>
<tag-name>
<literal>verify_failures</literal></tag-name>
<tag-desc>
SSL certificate verification errors<list type="tag">
<tag-name>
<literal>expired_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
An expired or not yet valid certificate was presented by an upstream server.
</tag-desc>
<tag-name>
<literal>revoked_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A revoked certificate was presented by an upstream server.
</tag-desc>
<tag-name>
<literal>hostname_mismatch</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Server's certificate doesn't match the hostname.
</tag-desc>
<tag-name>
<literal>other</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Other SSL certificate verification errors.
</tag-desc>
</list>
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>max_conns</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> limit for the server.
</tag-desc>
<tag-name>
<literal>requests</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of client requests forwarded to this server.
</tag-desc>
<tag-name>
<literal>responses</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>1xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>1xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>2xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>2xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>3xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>3xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>4xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>4xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>5xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with “<literal>5xx</literal>” status codes.
</tag-desc>
<tag-name>
<literal>codes</literal></tag-name>
<tag-desc>
The number of responses per each status code.<list type="tag">
<tag-name>
<literal>codeNumber</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of responses with this particular status code.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>total</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of responses obtained from this server.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>sent</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes sent to this server.
</tag-desc>
<tag-name>
<literal>received</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes received from this server.
</tag-desc>
<tag-name>
<literal>fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of unsuccessful attempts to communicate with the server.
</tag-desc>
<tag-name>
<literal>unavail</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
How many times the server became unavailable for client requests (state “<literal>unavail</literal>”) due to the number of unsuccessful attempts reaching the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</link> threshold.
</tag-desc>
<tag-name>
<literal>health_checks</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>checks</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of <link url="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</link> requests made.
</tag-desc>
<tag-name>
<literal>fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed health checks.
</tag-desc>
<tag-name>
<literal>unhealthy</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
How many times the server became unhealthy (state “<literal>unhealthy</literal>”).
</tag-desc>
<tag-name>
<literal>last_passed</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
Boolean indicating if the last health check request was successful and passed <link url="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</link>.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>downtime</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Total time the server was in the “<literal>unavail</literal>”, “<literal>checking</literal>”, and “<literal>unhealthy</literal>” states.
</tag-desc>
<tag-name>
<literal>downstart</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The time when the server became “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”, in the ISO 8601 format with millisecond resolution.
</tag-desc>
<tag-name>
<literal>selected</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The time when the server was last selected to process a request, in the ISO 8601 format with millisecond resolution.
</tag-desc>
<tag-name>
<literal>header_time</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The average time to get the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</link> from the server.
</tag-desc>
<tag-name>
<literal>response_time</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The average time to get the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</link> from the server.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>keepalive</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of idle <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</link> connections.
</tag-desc>
<tag-name>
<literal>zombies</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of servers removed from the group but still processing active client requests.
</tag-desc>
<tag-name>
<literal>zone</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The name of the shared memory <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</link> that keeps the group’s configuration and run-time state.
</tag-desc>
<tag-name>
<literal>queue</literal></tag-name>
<tag-desc>
For the requests <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</link>, the following data are provided:<list type="tag">
<tag-name>
<literal>size</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of requests in the queue.
</tag-desc>
<tag-name>
<literal>max_size</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The maximum number of requests that can be in the queue at the same time.
</tag-desc>
<tag-name>
<literal>overflows</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests rejected due to the queue overflow.
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "upstream_backend" : {
    "peers" : [
      {
        "id" : 0,
        "server" : "10.0.0.1:8088",
        "name" : "10.0.0.1:8088",
        "backup" : false,
        "weight" : 5,
        "state" : "up",
        "active" : 0,
        "ssl" : {
          "handshakes" : 620311,
          "handshakes_failed" : 3432,
          "session_reuses" : 36442,
          "no_common_protocol" : 4,
          "handshake_timeout" : 0,
          "peer_rejected_cert" : 0,
          "verify_failures" : {
            "expired_cert" : 2,
            "revoked_cert" : 1,
            "hostname_mismatch" : 2,
            "other" : 1
          }
        },
        "max_conns" : 20,
        "requests" : 667231,
        "header_time" : 20,
        "response_time" : 36,
        "responses" : {
          "1xx" : 0,
          "2xx" : 666310,
          "3xx" : 0,
          "4xx" : 915,
          "5xx" : 6,
          "codes" : {
            "200" : 666310,
            "404" : 915,
            "503" : 6
          },
          "total" : 667231
        },
        "sent" : 251946292,
        "received" : 19222475454,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26214,
          "fails" : 0,
          "unhealthy" : 0,
          "last_passed" : true
        },
        "downtime" : 0,
        "downstart" : "2022-06-28T11:09:21.602Z",
        "selected" : "2022-06-28T15:01:25.000Z"
      },
      {
        "id" : 1,
        "server" : "10.0.0.1:8089",
        "name" : "10.0.0.1:8089",
        "backup" : true,
        "weight" : 1,
        "state" : "unhealthy",
        "active" : 0,
        "max_conns" : 20,
        "requests" : 0,
        "responses" : {
          "1xx" : 0,
          "2xx" : 0,
          "3xx" : 0,
          "4xx" : 0,
          "5xx" : 0,
          "codes" : {
          },
          "total" : 0
        },
        "sent" : 0,
        "received" : 0,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26284,
          "fails" : 26284,
          "unhealthy" : 1,
          "last_passed" : false
        },
        "downtime" : 262925617,
        "downstart" : "2022-06-28T11:09:21.602Z",
        "selected" : "2022-06-28T15:01:25.000Z"
      }
    ],
    "keepalive" : 0,
    "zombies" : 0,
    "zone" : "upstream_backend"
  }
}</example>
</listitem>
<listitem id="def_nginx_http_upstream_conf_server">
<para>HTTP Upstream Server:</para>
Dynamically configurable parameters of an HTTP upstream
<link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link>:<list type="tag">
<tag-name>
<literal>id</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The ID of the HTTP upstream server. The ID is assigned automatically and cannot be changed.
</tag-desc>
<tag-name>
<literal>server</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</link> parameter of the HTTP upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</link> directive in the “<literal>http</literal>” block. See also the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>service</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</link> parameter of the HTTP upstream server. This parameter cannot be changed.
</tag-desc>
<tag-name>
<literal>weight</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">weight</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>max_conns</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>max_fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>fail_timeout</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout">fail_timeout</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>slow_start</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start">slow_start</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>route</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#route">route</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>backup</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
When <literal>true</literal>, adds a <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</link> server. This parameter cannot be changed.
</tag-desc>
<tag-name>
<literal>down</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>drain</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#drain">drain</link> parameter of the HTTP upstream server.
</tag-desc>
<tag-name>
<literal>parent</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
</tag-desc>
<tag-name>
<literal>host</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "id" : 1,
  "server" : "10.0.0.1:8089",
  "weight" : 4,
  "max_conns" : 0,
  "max_fails" : 0,
  "fail_timeout" : "10s",
  "slow_start" : "10s",
  "route" : "",
  "backup" : true,
  "down" : true
}</example>
</listitem>
<listitem id="def_nginx_http_keyval_zone">
<para>HTTP Keyval Shared Memory Zone:</para>
Contents of an HTTP keyval shared memory zone
when using the GET method.<para>Example:</para>
<example>
{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : "value3"
}</example>
</listitem>
<listitem id="def_nginx_http_keyval_zone_post_patch">
<para>HTTP Keyval Shared Memory Zone:</para>
Contents of an HTTP keyval shared memory zone
when using the POST or PATCH methods.<para>Example:</para>
<example>
{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : {
    "value" : "value3",
    "expire" : 30000
  }
}</example>
</listitem>
<listitem id="def_nginx_stream_server_zone">
<para>Stream Server Zone:</para>
<list type="tag">
<tag-name>
<literal>processing</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of client connections that are currently being processed.
</tag-desc>
<tag-name>
<literal>connections</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections accepted from clients.
</tag-desc>
<tag-name>
<literal>sessions</literal></tag-name>
<tag-desc>
The total number of completed sessions, and the number of sessions completed with status codes “<literal>2xx</literal>”, “<literal>4xx</literal>”, or “<literal>5xx</literal>”.<list type="tag">
<tag-name>
<literal>2xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of sessions completed with <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> “<literal>2xx</literal>”.
</tag-desc>
<tag-name>
<literal>4xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of sessions completed with <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> “<literal>4xx</literal>”.
</tag-desc>
<tag-name>
<literal>5xx</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of sessions completed with <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> “<literal>5xx</literal>”.
</tag-desc>
<tag-name>
<literal>total</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of completed client sessions.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>discarded</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections completed without creating a session.
</tag-desc>
<tag-name>
<literal>received</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes received from clients.
</tag-desc>
<tag-name>
<literal>sent</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes sent to clients.
</tag-desc>
<tag-name>
<literal>ssl</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>handshakes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of successful SSL handshakes.
</tag-desc>
<tag-name>
<literal>handshakes_failed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of failed SSL handshakes.
</tag-desc>
<tag-name>
<literal>session_reuses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of session reuses during SSL handshake.
</tag-desc>
<tag-name>
<literal>no_common_protocol</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no common protocol.
</tag-desc>
<tag-name>
<literal>no_common_cipher</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no shared cipher.
</tag-desc>
<tag-name>
<literal>handshake_timeout</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of a timeout.
</tag-desc>
<tag-name>
<literal>peer_rejected_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed SSL handshakes when nginx presented the certificate to the client but it was rejected with a corresponding alert message.
</tag-desc>
<tag-name>
<literal>verify_failures</literal></tag-name>
<tag-desc>
SSL certificate verification errors<list type="tag">
<tag-name>
<literal>no_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A client did not provide the required certificate.
</tag-desc>
<tag-name>
<literal>expired_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
An expired or not yet valid certificate was presented by a client.
</tag-desc>
<tag-name>
<literal>revoked_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A revoked certificate was presented by a client.
</tag-desc>
<tag-name>
<literal>other</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Other SSL certificate verification errors.
</tag-desc>
</list>
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "dns" : {
    "processing" : 1,
    "connections" : 155569,
    "sessions" : {
      "2xx" : 155564,
      "4xx" : 0,
      "5xx" : 0,
      "total" : 155569
    },
    "discarded" : 0,
    "received" : 4200363,
    "sent" : 20489184,
    "ssl" : {
      "handshakes" : 76455,
      "handshakes_failed" : 432,
      "session_reuses" : 28770,
      "no_common_protocol" : 4,
      "no_common_cipher" : 2,
      "handshake_timeout" : 0,
      "peer_rejected_cert" : 0,
      "verify_failures" : {
        "no_cert" : 0,
        "expired_cert" : 2,
        "revoked_cert" : 1,
        "other" : 1
      }
    }
  }
}</example>
</listitem>
<listitem id="def_nginx_stream_limit_conn_zone">
<para>Stream Connections Limiting:</para>
<list type="tag">
<tag-name>
<literal>passed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections that were neither limited nor accounted as limited.
</tag-desc>
<tag-name>
<literal>rejected</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections that were rejected.
</tag-desc>
<tag-name>
<literal>rejected_dry_run</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "passed" : 15,
  "rejected" : 0,
  "rejected_dry_run" : 2
}</example>
</listitem>
<listitem id="def_nginx_stream_upstream">
<para>Stream Upstream:</para>
<list type="tag">
<tag-name>
<literal>peers</literal></tag-name>
<tag-desc>
An array of:<list type="tag">
<tag-name>
<literal>id</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The ID of the server.
</tag-desc>
<tag-name>
<literal>server</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
An <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</link> of the server.
</tag-desc>
<tag-name>
<literal>service</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</link> parameter value of the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link> directive.
</tag-desc>
<tag-name>
<literal>name</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The name of the server specified in the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link> directive.
</tag-desc>
<tag-name>
<literal>backup</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
A boolean value indicating whether the server is a <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</link> server.
</tag-desc>
<tag-name>
<literal>weight</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
<link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</link> of the server.
</tag-desc>
<tag-name>
<literal>state</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Current state, which may be one of “<literal>up</literal>”, “<literal>down</literal>”, “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”.
</tag-desc>
<tag-name>
<literal>active</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of connections.
</tag-desc>
<tag-name>
<literal>ssl</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>handshakes</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of successful SSL handshakes.
</tag-desc>
<tag-name>
<literal>handshakes_failed</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of failed SSL handshakes.
</tag-desc>
<tag-name>
<literal>session_reuses</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of session reuses during SSL handshake.
</tag-desc>
<tag-name>
<literal>no_common_protocol</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of no common protocol.
</tag-desc>
<tag-name>
<literal>handshake_timeout</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of SSL handshakes failed because of a timeout.
</tag-desc>
<tag-name>
<literal>peer_rejected_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message.
</tag-desc>
<tag-name>
<literal>verify_failures</literal></tag-name>
<tag-desc>
SSL certificate verification errors<list type="tag">
<tag-name>
<literal>expired_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
An expired or not yet valid certificate was presented by an upstream server.
</tag-desc>
<tag-name>
<literal>revoked_cert</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
A revoked certificate was presented by an upstream server.
</tag-desc>
<tag-name>
<literal>hostname_mismatch</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Server's certificate doesn't match the hostname.
</tag-desc>
<tag-name>
<literal>other</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Other SSL certificate verification errors.
</tag-desc>
</list>
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>max_conns</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</link> limit for the server.
</tag-desc>
<tag-name>
<literal>connections</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of client connections forwarded to this server.
</tag-desc>
<tag-name>
<literal>connect_time</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The average time to connect to the upstream server.
</tag-desc>
<tag-name>
<literal>first_byte_time</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The average time to receive the first byte of data.
</tag-desc>
<tag-name>
<literal>response_time</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The average time to receive the last byte of data.
</tag-desc>
<tag-name>
<literal>sent</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes sent to this server.
</tag-desc>
<tag-name>
<literal>received</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of bytes received from this server.
</tag-desc>
<tag-name>
<literal>fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of unsuccessful attempts to communicate with the server.
</tag-desc>
<tag-name>
<literal>unavail</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
How many times the server became unavailable for client connections (state “<literal>unavail</literal>”) due to the number of unsuccessful attempts reaching the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</link> threshold.
</tag-desc>
<tag-name>
<literal>health_checks</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>checks</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check">health check</link> requests made.
</tag-desc>
<tag-name>
<literal>fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of failed health checks.
</tag-desc>
<tag-name>
<literal>unhealthy</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
How many times the server became unhealthy (state “<literal>unhealthy</literal>”).
</tag-desc>
<tag-name>
<literal>last_passed</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
Boolean indicating whether the last health check request was successful and passed <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match">tests</link>.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>downtime</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Total time the server was in the “<literal>unavail</literal>”, “<literal>checking</literal>”, and “<literal>unhealthy</literal>” states.
</tag-desc>
<tag-name>
<literal>downstart</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The time when the server became “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”, in the ISO 8601 format with millisecond resolution.
</tag-desc>
<tag-name>
<literal>selected</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The time when the server was last selected to process a connection, in the ISO 8601 format with millisecond resolution.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>zombies</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The current number of servers removed from the group but still processing active client connections.
</tag-desc>
<tag-name>
<literal>zone</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The name of the shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone">zone</link> that keeps the group’s configuration and run-time state.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "dns" : {
    "peers" : [
      {
        "id" : 0,
        "server" : "10.0.0.1:12347",
        "name" : "10.0.0.1:12347",
        "backup" : false,
        "weight" : 5,
        "state" : "up",
        "active" : 0,
        "ssl" : {
          "handshakes" : 200,
          "handshakes_failed" : 4,
          "session_reuses" : 189,
          "no_common_protocol" : 4,
          "handshake_timeout" : 0,
          "peer_rejected_cert" : 0,
          "verify_failures" : {
            "expired_cert" : 2,
            "revoked_cert" : 1,
            "hostname_mismatch" : 2,
            "other" : 1
          }
        },
        "max_conns" : 50,
        "connections" : 667231,
        "sent" : 251946292,
        "received" : 19222475454,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26214,
          "fails" : 0,
          "unhealthy" : 0,
          "last_passed" : true
        },
        "downtime" : 0,
        "downstart" : "2022-06-28T11:09:21.602Z",
        "selected" : "2022-06-28T15:01:25.000Z"
      },
      {
        "id" : 1,
        "server" : "10.0.0.1:12348",
        "name" : "10.0.0.1:12348",
        "backup" : true,
        "weight" : 1,
        "state" : "unhealthy",
        "active" : 0,
        "max_conns" : 50,
        "connections" : 0,
        "sent" : 0,
        "received" : 0,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26284,
          "fails" : 26284,
          "unhealthy" : 1,
          "last_passed" : false
        },
        "downtime" : 262925617,
        "downstart" : "2022-06-28T11:09:21.602Z",
        "selected" : "2022-06-28T15:01:25.000Z"
      }
    ],
    "zombies" : 0,
    "zone" : "dns"
  }
}</example>
</listitem>
<listitem id="def_nginx_stream_upstream_conf_server">
<para>Stream Upstream Server:</para>
Dynamically configurable parameters of a stream upstream
<link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link>:<list type="tag">
<tag-name>
<literal>id</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The ID of the stream upstream server. The ID is assigned automatically and cannot be changed.
</tag-desc>
<tag-name>
<literal>server</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</link> parameter of the stream upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</link> directive in the “<literal>stream</literal>” block. See also the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>service</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</link> parameter of the stream upstream server. This parameter cannot be changed.
</tag-desc>
<tag-name>
<literal>weight</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>max_conns</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>max_fails</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>fail_timeout</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>slow_start</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>backup</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
When <literal>true</literal>, adds a <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</link> server. This parameter cannot be changed.
</tag-desc>
<tag-name>
<literal>down</literal> (<literal>boolean</literal>)
</tag-name>
<tag-desc>
Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</link> parameter of the stream upstream server.
</tag-desc>
<tag-name>
<literal>parent</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
</tag-desc>
<tag-name>
<literal>host</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "id" : 0,
  "server" : "10.0.0.1:12348",
  "weight" : 1,
  "max_conns" : 0,
  "max_fails" : 1,
  "fail_timeout" : "10s",
  "slow_start" : 0,
  "backup" : false,
  "down" : false
}</example>
</listitem>
<listitem id="def_nginx_stream_keyval_zone">
<para>Stream Keyval Shared Memory Zone:</para>
Contents of a stream keyval shared memory zone when using the GET method.<para>Example:</para>
<example>
{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : "value3"
}</example>
</listitem>
<listitem id="def_nginx_stream_keyval_zone_post_patch">
<para>Stream Keyval Shared Memory Zone:</para>
Contents of a stream keyval shared memory zone
when using the POST or PATCH methods.<para>Example:</para>
<example>
{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : {
    "value" : "value3",
    "expire" : 30000
  }
}</example>
</listitem>
<listitem id="def_nginx_stream_zone_sync">
<para>Stream Zone Sync Node:</para>
<list type="tag">
<tag-name>
<literal>zones</literal></tag-name>
<tag-desc>
<para>Synchronization information per each shared memory zone.</para><para>A collection of "<link id="def_nginx_stream_zone_sync_zone">Sync Zone</link>" objects</para>
</tag-desc>
<tag-name>
<literal>status</literal></tag-name>
<tag-desc>
Synchronization information per node in a cluster.<list type="tag">
<tag-name>
<literal>bytes_in</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of bytes received by this node.
</tag-desc>
<tag-name>
<literal>msgs_in</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of messages received by this node.
</tag-desc>
<tag-name>
<literal>msgs_out</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of messages sent by this node.
</tag-desc>
<tag-name>
<literal>bytes_out</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of bytes sent by this node.
</tag-desc>
<tag-name>
<literal>nodes_online</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of peers this node is connected to.
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "zones" : {
    "zone1" : {
      "records_pending" : 2061,
      "records_total" : 260575
    },
    "zone2" : {
      "records_pending" : 0,
      "records_total" : 14749
    }
  },
  "status" : {
    "bytes_in" : 1364923761,
    "msgs_in" : 337236,
    "msgs_out" : 346717,
    "bytes_out" : 1402765472,
    "nodes_online" : 15
  }
}</example>
</listitem>
<listitem id="def_nginx_stream_zone_sync_zone">
<para>Sync Zone:</para>
Synchronization status of a shared memory zone.<list type="tag">
<tag-name>
<literal>records_pending</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The number of records that need to be sent to the cluster.
</tag-desc>
<tag-name>
<literal>records_total</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of records stored in the shared memory zone.
</tag-desc>
</list>
</listitem>
<listitem id="def_nginx_resolver_zone">
<para>Resolver Zone:</para>
Statistics of DNS requests and responses per particular
<link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</link>.<list type="tag">
<tag-name>
<literal>requests</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>name</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests to resolve names to addresses.
</tag-desc>
<tag-name>
<literal>srv</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests to resolve SRV records.
</tag-desc>
<tag-name>
<literal>addr</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests to resolve addresses to names.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>responses</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>noerror</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of successful responses.
</tag-desc>
<tag-name>
<literal>formerr</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of FORMERR (<literal>Format error</literal>) responses.
</tag-desc>
<tag-name>
<literal>servfail</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of SERVFAIL (<literal>Server failure</literal>) responses.
</tag-desc>
<tag-name>
<literal>nxdomain</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of NXDOMAIN (<literal>Host not found</literal>) responses.
</tag-desc>
<tag-name>
<literal>notimp</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of NOTIMP (<literal>Unimplemented</literal>) responses.
</tag-desc>
<tag-name>
<literal>refused</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of REFUSED (<literal>Operation refused</literal>) responses.
</tag-desc>
<tag-name>
<literal>timedout</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of timed out requests.
</tag-desc>
<tag-name>
<literal>unknown</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
The total number of requests completed with an unknown error.
</tag-desc>
</list>
</tag-desc>
</list>
<para>Example:</para>
<example>
{
  "resolver_zone1" : {
    "requests" : {
      "name" : 25460,
      "srv" : 130,
      "addr" : 2580
    },
    "responses" : {
      "noerror" : 26499,
      "formerr" : 0,
      "servfail" : 3,
      "nxdomain" : 0,
      "notimp" : 0,
      "refused" : 0,
      "timedout" : 243,
      "unknown" : 478
    }
  }
}</example>
</listitem>
<listitem id="def_nginx_error">
<para>Error:</para>
nginx error object.<list type="tag">
<tag-name>
<literal>error</literal></tag-name>
<tag-desc>
<list type="tag">
<tag-name>
<literal>status</literal> (<literal>integer</literal>)
</tag-name>
<tag-desc>
HTTP error code.
</tag-desc>
<tag-name>
<literal>text</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Error description.
</tag-desc>
<tag-name>
<literal>code</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Internal nginx error code.
</tag-desc>
</list>
</tag-desc>
<tag-name>
<literal>request_id</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
The ID of the request, equals the value of the <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</link> variable.
</tag-desc>
<tag-name>
<literal>href</literal> (<literal>string</literal>)
</tag-name>
<tag-desc>
Link to reference documentation.
</tag-desc>
</list>
</listitem>
</list>
</para>
</section>

</module>