Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_api_module.xml @ 2034:7e7edf832099
Added the generated ngx_http_api_module and separate target for it.
This avoids unnecessary build steps and dependencies. The separate
'genapi' target is added to regenerate the ngx_http_api_module from
yaml source. The generated file is not removed during 'clean' step.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Fri, 08 Sep 2017 13:58:41 +0300 |
parents | |
children | a810103f8a75 |
line wrap: on
line source
<?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="1"> <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> <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 version in the URI. Examples of API requests with this configuration: <example> http://127.0.0.1/api/1/ http://127.0.0.1/api/1/nginx http://127.0.0.1/api/1/connections http://127.0.0.1/api/1/http/requests http://127.0.0.1/api/1/http/server_zones/server_backend http://127.0.0.1/api/1/http/caches/cache_backend http://127.0.0.1/api/1/http/upstreams/backend http://127.0.0.1/api/1/http/upstreams/backend/servers/ http://127.0.0.1/api/1/http/upstreams/backend/servers/1 http://127.0.0.1/api/1/http/keyvals/one?key=arg1 http://127.0.0.1/api/1/stream/ http://127.0.0.1/api/1/stream/server_zones/server_backend http://127.0.0.1/api/1/stream/upstreams/ http://127.0.0.1/api/1/stream/upstreams/backend http://127.0.0.1/api/1/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> 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 and the only API version is “<literal>1</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/1/nginx?fields=version,build </example> </para> </directive> </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> </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> </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> </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> </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> </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> </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> </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> </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 are 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> </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>), 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>), 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> </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> </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> </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_status_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 are 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> </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>), 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 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>), 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 are 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> </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>), 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>), 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 are 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> </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 - 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 - Upstream not found (<literal>UpstreamNotFound</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 - 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>), 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 - Upstream not found (<literal>UpstreamNotFound</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 - 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="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>), 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 - 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> <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 - 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> </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 keyval zones <para>Returns key-value pairs for each 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 keyval zone names are 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">Keyval Shared Memory Zone</link>" objects for all http keyvals </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 a 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 a keyval zone <para>Returns key-value pairs stored in a particular 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 keyval zone.</tag-desc> </list> </para> <para> Possible responses: </para> <list type="bullet"> <listitem>200 - Success, returns <link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link></listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), keyval key not found (<literal>KeyvalKeyNotFound</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 keyval zone <para>Adds a new key-value pair to the 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 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">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 keyval shared memory zone is empty.</tag-desc> </list> </para> <para> Possible responses: </para> <list type="bullet"> <listitem>201 - Created</listitem> <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), only one key can be added (<literal>KeyvalFormatError</literal>), nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>409 - Key already exists (<literal>KeyvalKeyExists</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="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 or deletes a key by setting the key value to <literal>null</literal>.</para> <para> Request parameters: <list type="tag"> <tag-name><literal>httpKeyvalZoneKeyValue</literal> (<link id="def_nginx_http_keyval_zone">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 - Key required (<literal>KeyvalFormatError</literal>), only one key can be updated (<literal>KeyvalFormatError</literal>), nested object or list (<literal>KeyvalFormatError</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>), 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 keyval zone <para>Deletes all key-value pairs from the keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> <para> Possible responses: </para> <list type="bullet"> <listitem>204 - Success</listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</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> </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_status_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 are 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 - <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 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>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 are 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 - <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 - Upstream not found (<literal>UpstreamNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 - Upstream not found (<literal>UpstreamNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 - Upstream not found (<literal>UpstreamNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 - Upstream not found (<literal>UpstreamNotFound</literal>), server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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>), “<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 - Upstream not found (<literal>UpstreamNotFound</literal>), server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 - Upstream not found (<literal>UpstreamNotFound</literal>), server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</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 milliseconds since Epoch. </tag-desc> <tag-name> <literal>timestamp</literal> (<literal>string</literal>) </tag-name> <tag-desc> Current time in milliseconds since Epoch. </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.13.3", "build" : "nginx-plus-r12-p3", "address" : "206.251.255.64", "generation" : 2, "load_timestamp" : "2017-07-07T11:09:21.594Z", "timestamp" : "2017-07-11T09:31:13.477Z", "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> </list> <para>Example:</para> <example> { "handshakes" : 79572, "handshakes_failed" : 21025, "session_reuses" : 15762 }</example> </listitem> <listitem id="def_nginx_slab_zone"> <para>Shared memory zone with slab allocator:</para> <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 and the number of responses with status codes “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, “<literal>4xx</literal>”, and “<literal>5xx</literal>”.<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>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> { "processing" : 1, "requests" : 706690, "responses" : { "1xx" : 0, "2xx" : 699482, "3xx" : 4522, "4xx" : 907, "5xx" : 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_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>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>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 (in milliseconds since Epoch) when the server became “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”. </tag-desc> <tag-name> <literal>selected</literal> (<literal>string</literal>) </tag-name> <tag-desc> The time (in milliseconds since Epoch) when the server was last selected to process a request. </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, "max_conns" : 20, "requests" : 667231, "header_time" : 20, "response_time" : 36, "responses" : { "1xx" : 0, "2xx" : 666310, "3xx" : 0, "4xx" : 915, "5xx" : 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" : "2017-07-07T11:09:21.602Z", "selected" : "2017-07-17T15: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, "total" : 0 }, "sent" : 0, "received" : 0, "fails" : 0, "unavail" : 0, "health_checks" : { "checks" : 26284, "fails" : 26284, "unhealthy" : 1, "last_passed" : false }, "downtime" : 262925617, "downstart" : "2017-07-07T11:09:21.602Z", "selected" : "2017-07-17T15: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#address">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>integer</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>integer</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>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> <tag-name> <literal>drain</literal> (<literal>string</literal>) </tag-name> <tag-desc> Puts the HTTP upstream server into the “draining” mode. In this mode, only requests <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</link> to the server will be proxied to it. The parameter cannot be initially set, it can only be changed with the <literal>PATCH</literal> method. </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>Keyval Shared Memory Zone:</para> Contents of a keyval shared memory zone.<para>Example:</para> <example> { "key1" : "value1", "key2" : "value2", "key3" : "value3" }</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> 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> </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 } }</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>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 (in milliseconds since Epoch) when the server became “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”. </tag-desc> <tag-name> <literal>selected</literal> (<literal>string</literal>) </tag-name> <tag-desc> The time (in milliseconds since Epoch) when the server was last selected to process a connection. </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, "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" : "2017-07-07T11:09:21.602Z", "selected" : "2017-07-17T15: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" : "2017-07-07T11:09:21.602Z", "selected" : "2017-07-17T15: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>integer</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>integer</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_error"> <para>Error:</para> nginx error object.<list type="tag"> <tag-name> <literal>path</literal> (<literal>string</literal>) </tag-name> <tag-desc> API path. </tag-desc> <tag-name> <literal>method</literal> (<literal>string</literal>) </tag-name> <tag-desc> HTTP method. </tag-desc> <tag-name> <literal>error</literal></tag-name> <tag-desc> <list type="tag"> <tag-name> <literal>status</literal> (<literal>string</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>