Mercurial > hg > nginx-site
changeset 2469:98fd810c13e0
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 02 Dec 2019 13:23:05 +0300 |
parents | 409e1f755037 |
children | 504536999408 |
files | xml/en/docs/http/ngx_http_api_module.xml xml/en/docs/http/ngx_http_api_module_head.xml xml/en/docs/http/ngx_http_keyval_module.xml xml/en/docs/http/ngx_http_upstream_module.xml xml/en/docs/stream/ngx_stream_keyval_module.xml xml/en/docs/stream/ngx_stream_upstream_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/stream/ngx_stream_upstream_module.xml yaml/nginx_api.yaml |
diffstat | 9 files changed, 1064 insertions(+), 44 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_api_module.xml +++ b/xml/en/docs/http/ngx_http_api_module.xml @@ -101,21 +101,21 @@ All API requests include a supported API <link id="api_version">version</link> in the URI. Examples of API requests with this configuration: <example> -http://127.0.0.1/api/5/ -http://127.0.0.1/api/5/nginx -http://127.0.0.1/api/5/connections -http://127.0.0.1/api/5/http/requests -http://127.0.0.1/api/5/http/server_zones/server_backend -http://127.0.0.1/api/5/http/caches/cache_backend -http://127.0.0.1/api/5/http/upstreams/backend -http://127.0.0.1/api/5/http/upstreams/backend/servers/ -http://127.0.0.1/api/5/http/upstreams/backend/servers/1 -http://127.0.0.1/api/5/http/keyvals/one?key=arg1 -http://127.0.0.1/api/5/stream/ -http://127.0.0.1/api/5/stream/server_zones/server_backend -http://127.0.0.1/api/5/stream/upstreams/ -http://127.0.0.1/api/5/stream/upstreams/backend -http://127.0.0.1/api/5/stream/upstreams/backend/servers/1 +http://127.0.0.1/api/6/ +http://127.0.0.1/api/6/nginx +http://127.0.0.1/api/6/connections +http://127.0.0.1/api/6/http/requests +http://127.0.0.1/api/6/http/server_zones/server_backend +http://127.0.0.1/api/6/http/caches/cache_backend +http://127.0.0.1/api/6/http/upstreams/backend +http://127.0.0.1/api/6/http/upstreams/backend/servers/ +http://127.0.0.1/api/6/http/upstreams/backend/servers/1 +http://127.0.0.1/api/6/http/keyvals/one?key=arg1 +http://127.0.0.1/api/6/stream/ +http://127.0.0.1/api/6/stream/server_zones/server_backend +http://127.0.0.1/api/6/stream/upstreams/ +http://127.0.0.1/api/6/stream/upstreams/backend +http://127.0.0.1/api/6/stream/upstreams/backend/servers/1 </example> </para> @@ -146,14 +146,14 @@ By default, the API is read-only. All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. -The current API version is “<literal>5</literal>”. +The current API version is “<literal>6</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/5/nginx?fields=version,build +http://127.0.0.1/api/6/nginx?fields=version,build </example> </para> @@ -199,6 +199,21 @@ redirect</link> happens during request p <list type="bullet"> <listitem> +The <link id="stream_limit_conns_">/stream/limit_conns/</link> data +were added in <link id="api_version">version</link> 6. +</listitem> + +<listitem> +The <link id="http_limit_conns_">/http/limit_conns/</link> data +were added in <link id="api_version">version</link> 6. +</listitem> + +<listitem> +The <link id="http_limit_reqs_">/http/limit_reqs/</link> data +were added in <link id="api_version">version</link> 6. +</listitem> + +<listitem> The “<literal>expire</literal>” parameter of a <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be <link id="postHttpKeyvalZoneData">set</link> or @@ -708,6 +723,154 @@ Possible responses: </listitem> </list> </tag-desc> +<tag-name id="http_limit_conns_" name="/http/limit_conns/"> +<literal>/http/limit_conns/</literal> +</tag-name> +<tag-desc> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getHttpLimitConnZones"> +<literal>GET</literal> - Return status of all HTTP limit_conn zones +<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link>" objects for all HTTP limit conns</listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="http_limit_conns_http_limit_conn_zone_name" name="/http/limit_conns/{httpLimitConnZoneName}"> +<literal>/http/limit_conns/{httpLimitConnZoneName}</literal> +</tag-name> +<tag-desc> +Parameters common for all methods: +<list type="tag"> +<tag-name><literal>httpLimitConnZoneName</literal> +(<literal>string</literal>, required)</tag-name> +<tag-desc> +The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc> +</list> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getHttpLimitConnZone"> +<literal>GET</literal> - Return status of an HTTP limit_conn zone +<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns <link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link></listitem> +<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="deleteHttpLimitConnZoneStat"> +<literal>DELETE</literal> - Reset statistics for an HTTP limit_conn zone +<para>Resets the connection limiting statistics.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="http_limit_reqs_" name="/http/limit_reqs/"> +<literal>/http/limit_reqs/</literal> +</tag-name> +<tag-desc> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getHttpLimitReqZones"> +<literal>GET</literal> - Return status of all HTTP limit_req zones +<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of limit_req zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link>" objects for all HTTP limit reqs</listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="http_limit_reqs_http_limit_req_zone_name" name="/http/limit_reqs/{httpLimitReqZoneName}"> +<literal>/http/limit_reqs/{httpLimitReqZoneName}</literal> +</tag-name> +<tag-desc> +Parameters common for all methods: +<list type="tag"> +<tag-name><literal>httpLimitReqZoneName</literal> +(<literal>string</literal>, required)</tag-name> +<tag-desc> +The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</tag-desc> +</list> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getHttpLimitReqZone"> +<literal>GET</literal> - Return status of an HTTP limit_req zone +<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link> will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns <link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link></listitem> +<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="deleteHttpLimitReqZoneStat"> +<literal>DELETE</literal> - Reset statistics for an HTTP limit_req zone +<para>Resets the requests limiting statistics.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +</list> +</tag-desc> <tag-name id="http_upstreams_" name="/http/upstreams/"> <literal>/http/upstreams/</literal> </tag-name> @@ -1162,6 +1325,80 @@ Possible responses: </listitem> </list> </tag-desc> +<tag-name id="stream_limit_conns_" name="/stream/limit_conns/"> +<literal>/stream/limit_conns/</literal> +</tag-name> +<tag-desc> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getStreamLimitConnZones"> +<literal>GET</literal> - Return status of all stream limit_conn zones +<para>Returns status information for each stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link>" objects for all stream limit conns</listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="stream_limit_conns_stream_limit_conn_zone_name" name="/stream/limit_conns/{streamLimitConnZoneName}"> +<literal>/stream/limit_conns/{streamLimitConnZoneName}</literal> +</tag-name> +<tag-desc> +Parameters common for all methods: +<list type="tag"> +<tag-name><literal>streamLimitConnZoneName</literal> +(<literal>string</literal>, required)</tag-name> +<tag-desc> +The name of a <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc> +</list> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getStreamLimitConnZone"> +<literal>GET</literal> - Return status of an stream limit_conn zone +<para>Returns status of a particular stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns <link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link></listitem> +<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="deleteStreamLimitConnZoneStat"> +<literal>DELETE</literal> - Reset statistics for a stream limit_conn zone +<para>Resets the connection limiting statistics.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +</list> +</tag-desc> <tag-name id="stream_upstreams_" name="/stream/upstreams/"> <literal>/stream/upstreams/</literal> </tag-name> @@ -2340,6 +2577,80 @@ The total number of bytes written to the } }</example> </listitem> +<listitem id="def_nginx_http_limit_conn_zone"> +<para>HTTP Connections Limiting:</para> +<list type="tag"> +<tag-name> +<literal>passed</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of connections that were neither limited nor accounted as limited. +</tag-desc> +<tag-name> +<literal>rejected</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of connections that were rejected. +</tag-desc> +<tag-name> +<literal>rejected_dry_run</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode. +</tag-desc> +</list> +<para>Example:</para> +<example> +{ + "passed" : 15, + "rejected" : 0, + "rejected_dry_run" : 2 +}</example> +</listitem> +<listitem id="def_nginx_http_limit_req_zone"> +<para>HTTP Requests Rate Limiting:</para> +<list type="tag"> +<tag-name> +<literal>passed</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests that were neither limited nor accounted as limited. +</tag-desc> +<tag-name> +<literal>delayed</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests that were delayed. +</tag-desc> +<tag-name> +<literal>rejected</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests that were rejected. +</tag-desc> +<tag-name> +<literal>delayed_dry_run</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests accounted as delayed in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode. +</tag-desc> +<tag-name> +<literal>rejected_dry_run</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode. +</tag-desc> +</list> +<para>Example:</para> +<example> +{ + "passed" : 15, + "delayed" : 4, + "rejected" : 0, + "delayed_dry_run" : 1, + "rejected_dry_run" : 2 +}</example> +</listitem> <listitem id="def_nginx_http_upstream"> <para>HTTP Upstream:</para> <list type="tag"> @@ -2867,6 +3178,36 @@ The total number of bytes sent to client } }</example> </listitem> +<listitem id="def_nginx_stream_limit_conn_zone"> +<para>Stream Connections Limiting:</para> +<list type="tag"> +<tag-name> +<literal>passed</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of connections that were neither limited nor accounted as limited. +</tag-desc> +<tag-name> +<literal>rejected</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of connections that were rejected. +</tag-desc> +<tag-name> +<literal>rejected_dry_run</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode. +</tag-desc> +</list> +<para>Example:</para> +<example> +{ + "passed" : 15, + "rejected" : 0, + "rejected_dry_run" : 2 +}</example> +</listitem> <listitem id="def_nginx_stream_upstream"> <para>Stream Upstream:</para> <list type="tag">
--- a/xml/en/docs/http/ngx_http_api_module_head.xml +++ b/xml/en/docs/http/ngx_http_api_module_head.xml @@ -101,21 +101,21 @@ All API requests include a supported API <link id="api_version">version</link> in the URI. Examples of API requests with this configuration: <example> -http://127.0.0.1/api/5/ -http://127.0.0.1/api/5/nginx -http://127.0.0.1/api/5/connections -http://127.0.0.1/api/5/http/requests -http://127.0.0.1/api/5/http/server_zones/server_backend -http://127.0.0.1/api/5/http/caches/cache_backend -http://127.0.0.1/api/5/http/upstreams/backend -http://127.0.0.1/api/5/http/upstreams/backend/servers/ -http://127.0.0.1/api/5/http/upstreams/backend/servers/1 -http://127.0.0.1/api/5/http/keyvals/one?key=arg1 -http://127.0.0.1/api/5/stream/ -http://127.0.0.1/api/5/stream/server_zones/server_backend -http://127.0.0.1/api/5/stream/upstreams/ -http://127.0.0.1/api/5/stream/upstreams/backend -http://127.0.0.1/api/5/stream/upstreams/backend/servers/1 +http://127.0.0.1/api/6/ +http://127.0.0.1/api/6/nginx +http://127.0.0.1/api/6/connections +http://127.0.0.1/api/6/http/requests +http://127.0.0.1/api/6/http/server_zones/server_backend +http://127.0.0.1/api/6/http/caches/cache_backend +http://127.0.0.1/api/6/http/upstreams/backend +http://127.0.0.1/api/6/http/upstreams/backend/servers/ +http://127.0.0.1/api/6/http/upstreams/backend/servers/1 +http://127.0.0.1/api/6/http/keyvals/one?key=arg1 +http://127.0.0.1/api/6/stream/ +http://127.0.0.1/api/6/stream/server_zones/server_backend +http://127.0.0.1/api/6/stream/upstreams/ +http://127.0.0.1/api/6/stream/upstreams/backend +http://127.0.0.1/api/6/stream/upstreams/backend/servers/1 </example> </para> @@ -146,14 +146,14 @@ By default, the API is read-only. All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. -The current API version is “<literal>5</literal>”. +The current API version is “<literal>6</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/5/nginx?fields=version,build +http://127.0.0.1/api/6/nginx?fields=version,build </example> </para> @@ -199,6 +199,21 @@ redirect</link> happens during request p <list type="bullet"> <listitem> +The <link id="stream_limit_conns_">/stream/limit_conns/</link> data +were added in <link id="api_version">version</link> 6. +</listitem> + +<listitem> +The <link id="http_limit_conns_">/http/limit_conns/</link> data +were added in <link id="api_version">version</link> 6. +</listitem> + +<listitem> +The <link id="http_limit_reqs_">/http/limit_reqs/</link> data +were added in <link id="api_version">version</link> 6. +</listitem> + +<listitem> The “<literal>expire</literal>” parameter of a <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be <link id="postHttpKeyvalZoneData">set</link> or
--- a/xml/en/docs/http/ngx_http_keyval_module.xml +++ b/xml/en/docs/http/ngx_http_keyval_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_http_keyval_module" link="/en/docs/http/ngx_http_keyval_module.html" lang="en" - rev="7"> + rev="8"> <section id="summary"> @@ -86,7 +86,7 @@ specified by the <literal>zone</literal> <literal>zone</literal>=<value>name</value>:<value>size</value> [<literal>state</literal>=<value>file</value>] [<literal>timeout</literal>=<value>time</value>] - [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>] + [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>|<literal>prefix</literal>] [<literal>sync</literal>]</syntax> <default/> <context>http</context> @@ -136,6 +136,13 @@ to match a record key, the search key mu specified by a record key or exactly match an IP address </tag-desc> +<tag-name id="keyval_type_prefix"><literal>type=prefix</literal></tag-name> +<tag-desc> +variable lookup is performed using prefix match +of a record key and a search key (1.17.5); +to match a record key, the record key must be a prefix of the search key +</tag-desc> + </list> </para>
--- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="82"> + rev="83"> <section id="summary"> @@ -885,6 +885,87 @@ The <literal>least_time</literal> method </directive> +<directive name="resolver"> +<syntax> + <value>address</value> ... + [<literal>valid</literal>=<value>time</value>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>zone</value>]</syntax> +<default/> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Configures name servers used to resolve names of upstream servers +into addresses, for example: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +The address can be specified as a domain name or IP address, +with an optional port. +If port is not specified, the port 53 is used. +Name servers are queried in a round-robin fashion. +</para> + +<para id="resolver_ipv6"> +By default, nginx will look up both IPv4 and IPv6 addresses while resolving. +If looking up of IPv6 addresses is not desired, +the <literal>ipv6=off</literal> parameter can be specified. +</para> + +<para id="resolver_valid"> +By default, nginx caches answers using the TTL value of a response. +An optional <literal>valid</literal> parameter allows overriding it: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +<note> +To prevent DNS spoofing, it is recommended +configuring DNS servers in a properly secured trusted local network. +</note> +</para> + +<para id="resolver_status_zone"> +The optional <literal>status_zone</literal> parameter +enables +<link doc="ngx_http_api_module.xml" id="resolvers_">collection</link> +of DNS server statistics of requests and responses +in the specified <value>zone</value>. +</para> + +<para> +<note> +This directive is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Sets a timeout for name resolution, for example: +<example> +resolver_timeout 5s; +</example> +</para> + +<para> +<note> +This directive is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</directive> + + <directive name="sticky"> <syntax> <literal>cookie</literal> <value>name</value>
--- a/xml/en/docs/stream/ngx_stream_keyval_module.xml +++ b/xml/en/docs/stream/ngx_stream_keyval_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_keyval_module" link="/en/docs/stream/ngx_stream_keyval_module.html" lang="en" - rev="6"> + rev="7"> <section id="summary"> @@ -90,7 +90,7 @@ specified by the <literal>zone</literal> <literal>zone</literal>=<value>name</value>:<value>size</value> [<literal>state</literal>=<value>file</value>] [<literal>timeout</literal>=<value>time</value>] - [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>] + [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>|<literal>prefix</literal>] [<literal>sync</literal>]</syntax> <default/> <context>stream</context> @@ -140,6 +140,13 @@ to match a record key, the search key mu specified by a record key or exactly match an IP address </tag-desc> +<tag-name id="keyval_type_prefix"><literal>type=prefix</literal></tag-name> +<tag-desc> +variable lookup is performed using prefix match +of a record key and a search key (1.17.5); +to match a record key, the record key must be a prefix of the search key +</tag-desc> + </list> </para>
--- a/xml/en/docs/stream/ngx_stream_upstream_module.xml +++ b/xml/en/docs/stream/ngx_stream_upstream_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_upstream_module" link="/en/docs/stream/ngx_stream_upstream_module.html" lang="en" - rev="37"> + rev="38"> <section id="summary"> @@ -549,6 +549,87 @@ The <literal>least_time</literal> method </directive> + +<directive name="resolver"> +<syntax> + <value>address</value> ... + [<literal>valid</literal>=<value>time</value>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>zone</value>]</syntax> +<default/> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Configures name servers used to resolve names of upstream servers +into addresses, for example: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +The address can be specified as a domain name or IP address, +with an optional port. +If port is not specified, the port 53 is used. +Name servers are queried in a round-robin fashion. +</para> + +<para id="resolver_ipv6"> +By default, nginx will look up both IPv4 and IPv6 addresses while resolving. +If looking up of IPv6 addresses is not desired, +the <literal>ipv6=off</literal> parameter can be specified. +</para> + +<para id="resolver_valid"> +By default, nginx caches answers using the TTL value of a response. +The optional <literal>valid</literal> parameter allows overriding it: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +<note> +To prevent DNS spoofing, it is recommended +configuring DNS servers in a properly secured trusted local network. +</note> +</para> + +<para id="resolver_status_zone"> +The optional <literal>status_zone</literal> parameter +enables +<link doc="../http/ngx_http_api_module.xml" id="resolvers_">collection</link> +of DNS server statistics of requests and responses +in the specified <value>zone</value>. +</para> + +<para> +<note> +This directive is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Sets a timeout for name resolution, for example: +<example> +resolver_timeout 5s; +</example> +</para> + +<para> +<note> +This directive is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</directive> + </section>
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_upstream_module" link="/ru/docs/http/ngx_http_upstream_module.html" lang="ru" - rev="82"> + rev="83"> <section id="summary"> @@ -893,6 +893,89 @@ server { </directive> +<directive name="resolver"> +<syntax> + <value>адрес</value> ... + [<literal>valid</literal>=<value>время</value>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>зона</value>]</syntax> +<default/> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов +в адреса, например: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +Адрес может быть указан в виде доменного имени или IP-адреса, +и необязательного порта. +Если порт не указан, используется порт 53. +Серверы DNS опрашиваются циклически. +</para> + +<para id="resolver_ipv6"> +По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса +при преобразовании имён в адреса. +Если поиск IPv6-адресов нежелателен, +можно указать параметр <literal>ipv6=off</literal>. +</para> + +<para id="resolver_valid"> +По умолчанию nginx кэширует ответы, используя значение TTL из ответа. +Необязательный параметр <literal>valid</literal> позволяет это +переопределить: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +<note> +Для предотвращения DNS-спуфинга рекомендуется +использовать DNS-серверы в защищённой доверенной локальной сети. +</note> +</para> + +<para id="resolver_status_zone"> +Необязательный параметр <literal>status_zone</literal> +включает +<link doc="ngx_http_api_module.xml" id="resolvers_">сбор информации</link> +о запросах и ответах сервера DNS +в указанной <value>зоне</value>. +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>время</value></syntax> +<default>30s</default> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Задаёт таймаут для преобразования имени в адрес, например: +<example> +resolver_timeout 5s; +</example> +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + + <directive name="sticky"> <syntax> <literal>cookie</literal> <value>имя</value>
--- a/xml/ru/docs/stream/ngx_stream_upstream_module.xml +++ b/xml/ru/docs/stream/ngx_stream_upstream_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_stream_upstream_module" link="/ru/docs/stream/ngx_stream_upstream_module.html" lang="ru" - rev="37"> + rev="38"> <section id="summary"> @@ -550,6 +550,89 @@ hash $remote_addr; </directive> + +<directive name="resolver"> +<syntax> + <value>адрес</value> ... + [<literal>valid</literal>=<value>время</value>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>зона</value>]</syntax> +<default/> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов +в адреса, например: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +Адрес может быть указан в виде доменного имени или IP-адреса, +и необязательного порта. +Если порт не указан, используется порт 53. +Серверы DNS опрашиваются циклически. +</para> + +<para id="resolver_ipv6"> +По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса +при преобразовании имён в адреса. +Если поиск IPv6-адресов нежелателен, +можно указать параметр <literal>ipv6=off</literal>. +</para> + +<para id="resolver_valid"> +По умолчанию nginx кэширует ответы, используя значение TTL из ответа. +Необязательный параметр <literal>valid</literal> позволяет это +переопределить: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +<note> +Для предотвращения DNS-спуфинга рекомендуется +использовать DNS-серверы в защищённой доверенной локальной сети. +</note> +</para> + +<para id="resolver_status_zone"> +Необязательный параметр <literal>status_zone</literal> +включает +<link doc="../http/ngx_http_api_module.xml" id="resolvers_">сбор информации</link> +о запросах и ответах сервера DNS +в указанной <value>зоне</value>. +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>время</value></syntax> +<default>30s</default> +<context>upstream</context> +<appeared-in>1.17.5</appeared-in> + +<para> +Задаёт таймаут для преобразования имени в адрес, например: +<example> +resolver_timeout 5s; +</example> +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + </section>
--- a/yaml/nginx_api.yaml +++ b/yaml/nginx_api.yaml @@ -1,6 +1,6 @@ swagger: '2.0' info: - version: '5.0' + version: '6.0' title: NGINX Plus REST API description: NGINX Plus REST [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) @@ -9,7 +9,7 @@ info: key-value pairs management for [http](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) and [stream](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html). -basePath: /api/5 +basePath: /api/6 tags: - name: General Info - name: Processes @@ -22,10 +22,13 @@ tags: - name: HTTP Server Zones - name: HTTP Location Zones - name: HTTP Caches + - name: HTTP Limit Conns + - name: HTTP Limit Reqs - name: HTTP Keyvals - name: HTTP Upstreams - name: Stream - name: Stream Server Zones + - name: Stream Limit Conns - name: Stream Keyvals - name: Stream Upstreams - name: Stream Zone Sync @@ -470,6 +473,156 @@ paths: description: Method disabled (*MethodDisabled*) schema: $ref: '#/definitions/NginxError' + /http/limit_conns/: + get: + tags: + - HTTP Limit Conns + - Method GET + summary: Return status of all HTTP limit_conn zones + description: Returns status information for each HTTP + [limit_conn zone](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone). + operationId: getHttpLimitConnZones + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: Limits which fields of limit_conn zones will be output. + If the “<literal>fields</literal>” value is empty, + then only zone names will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPLimitConnZonesMap' + '/http/limit_conns/{httpLimitConnZoneName}': + parameters: + - name: httpLimitConnZoneName + in: path + description: The name of a + [limit_conn zone](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone). + type: string + required: true + get: + tags: + - HTTP Limit Conns + - Method GET + summary: Return status of an HTTP limit_conn zone + description: Returns status of a particular HTTP + [limit_conn zone](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone). + operationId: getHttpLimitConnZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: Limits which fields of the + [limit_conn zone](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone) + will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPLimitConnZone' + '404': + description: limit_conn not found (*LimitConnNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Limit Conns + - Method DELETE + summary: Reset statistics for an HTTP limit_conn zone + description: Resets the connection limiting statistics. + operationId: deleteHttpLimitConnZoneStat + responses: + '204': + description: Success + '404': + description: limit_conn not found (*LimitConnNotFound*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' + /http/limit_reqs/: + get: + tags: + - HTTP Limit Reqs + - Method GET + summary: Return status of all HTTP limit_req zones + description: Returns status information for each HTTP + [limit_req zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone). + operationId: getHttpLimitReqZones + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: Limits which fields of limit_req zones will be output. + If the “<literal>fields</literal>” value is empty, + then only zone names will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPLimitReqZonesMap' + '/http/limit_reqs/{httpLimitReqZoneName}': + parameters: + - name: httpLimitReqZoneName + in: path + description: The name of a + [limit_req zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone). + type: string + required: true + get: + tags: + - HTTP Limit Reqs + - Method GET + summary: Return status of an HTTP limit_req zone + description: Returns status of a particular HTTP + [limit_req zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone). + operationId: getHttpLimitReqZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: Limits which fields of the + [limit_req zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) + will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPLimitReqZone' + '404': + description: limit_req not found (*LimitReqNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Limit Reqs + - Method DELETE + summary: Reset statistics for an HTTP limit_req zone + description: Resets the requests limiting statistics. + operationId: deleteHttpLimitReqZoneStat + responses: + '204': + description: Success + '404': + description: limit_req not found (*LimitReqNotFound*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' /http/upstreams/: get: tags: @@ -1046,6 +1199,81 @@ paths: description: Method disabled (*MethodDisabled*) schema: $ref: '#/definitions/NginxError' + /stream/limit_conns/: + get: + tags: + - Stream Limit Conns + - Method GET + summary: Return status of all stream limit_conn zones + description: Returns status information for each stream + [limit_conn zone](https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone). + operationId: getStreamLimitConnZones + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: Limits which fields of limit_conn zones will be output. + If the “<literal>fields</literal>” value is empty, + then only zone names will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamLimitConnZonesMap' + '/stream/limit_conns/{streamLimitConnZoneName}': + parameters: + - name: streamLimitConnZoneName + in: path + description: The name of a + [limit_conn zone](https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone). + type: string + required: true + get: + tags: + - Stream Limit Conns + - Method GET + summary: Return status of an stream limit_conn zone + description: Returns status of a particular stream + [limit_conn zone](https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone). + operationId: getStreamLimitConnZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: Limits which fields of the + [limit_conn zone](https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone) + will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamLimitConnZone' + '404': + description: limit_conn not found (*LimitConnNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - Stream Limit Conns + - Method DELETE + summary: Reset statistics for a stream limit_conn zone + description: Resets the connection limiting statistics. + operationId: deleteStreamLimitConnZoneStat + responses: + '204': + description: Success + '404': + description: limit_conn not found (*LimitConnNotFound*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' /stream/upstreams/: get: tags: @@ -2324,6 +2552,72 @@ definitions: bytes: 5510647548 responses_written: 200173 bytes_written: 44992 + NginxHTTPLimitConnZonesMap: + title: HTTP limit_conns + description: | + Status data for all HTTP + <a href="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPLimitConnZone' + NginxHTTPLimitConnZone: + title: HTTP Connections Limiting + type: object + properties: + passed: + type: integer + description: The total number of connections that were neither limited + nor accounted as limited. + rejected: + type: integer + description: The total number of connections that were rejected. + rejected_dry_run: + type: integer + description: The total number of connections accounted as rejected in the + <a href="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_dry_run">dry run</a> + mode. + example: + passed: 15 + rejected: 0 + rejected_dry_run: 2 + NginxHTTPLimitReqZonesMap: + title: HTTP limit_reqs + description: | + Status data for all HTTP + <a href="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPLimitReqZone' + NginxHTTPLimitReqZone: + title: HTTP Requests Rate Limiting + type: object + properties: + passed: + type: integer + description: The total number of requests that were neither limited + nor accounted as limited. + delayed: + type: integer + description: The total number of requests that were delayed. + rejected: + type: integer + description: The total number of requests that were rejected. + delayed_dry_run: + type: integer + description: The total number of requests accounted as delayed in the + <a href="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</a> + mode. + rejected_dry_run: + type: integer + description: The total number of requests accounted as rejected in the + <a href="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</a> + mode. + example: + passed: 15 + delayed: 4 + rejected: 0 + delayed_dry_run: 1 + rejected_dry_run: 2 NginxHTTPUpstreamMap: title: HTTP Upstreams description: | @@ -2982,6 +3276,34 @@ definitions: discarded: 0 received: 4200363 sent: 20489184 + NginxStreamLimitConnZonesMap: + title: Stream limit_conns + description: | + Status data for all stream + <a href="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxStreamLimitConnZone' + NginxStreamLimitConnZone: + title: Stream Connections Limiting + type: object + properties: + passed: + type: integer + description: The total number of connections that were neither limited + nor accounted as limited. + rejected: + type: integer + description: The total number of connections that were rejected. + rejected_dry_run: + type: integer + description: The total number of connections accounted as rejected in the + <a href="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_dry_run">dry run</a> + mode. + example: + passed: 15 + rejected: 0 + rejected_dry_run: 2 NginxStreamUpstreamMap: title: Stream Upstreams description: Status information of stream upstream server groups.