Mercurial > hg > nginx-site
changeset 3043:9eadb98ec770
Free nginx: removed commercial version documentation.
line wrap: on
line diff
--- a/GNUmakefile +++ b/GNUmakefile @@ -170,10 +170,6 @@ xslt/%.xslt: xsls/%.xsls $(call XSLScript, $<, $@) -genapi: - $(MAKE) -C yaml - - images: \ binary/books/nginx_cookbook.jpg \ binary/books/nginx_http_server_3rd_ed.jpg \
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -39,9 +39,7 @@ REFS = \ ngx_core_module \ http/ngx_http_access_module \ http/ngx_http_addition_module \ - http/ngx_http_api_module \ http/ngx_http_auth_basic_module \ - http/ngx_http_auth_jwt_module \ http/ngx_http_auth_request_module \ http/ngx_http_autoindex_module \ http/ngx_http_browser_module \ @@ -50,7 +48,6 @@ REFS = \ http/ngx_http_dav_module \ http/ngx_http_empty_gif_module \ http/ngx_http_fastcgi_module \ - http/ngx_http_f4f_module \ http/ngx_http_flv_module \ http/ngx_http_geo_module \ http/ngx_http_geoip_module \ @@ -59,12 +56,9 @@ REFS = \ http/ngx_http_gzip_module \ http/ngx_http_gzip_static_module \ http/ngx_http_headers_module \ - http/ngx_http_hls_module \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \ - http/ngx_http_internal_redirect_module \ http/ngx_http_js_module \ - http/ngx_http_keyval_module \ http/ngx_http_limit_conn_module \ http/ngx_http_limit_req_module \ http/ngx_http_log_module \ @@ -74,7 +68,6 @@ REFS = \ http/ngx_http_mp4_module \ http/ngx_http_perl_module \ http/ngx_http_proxy_module \ - http/ngx_http_proxy_protocol_vendor_module \ http/ngx_http_random_index_module \ http/ngx_http_realip_module \ http/ngx_http_referer_module \ @@ -83,16 +76,12 @@ REFS = \ http/ngx_http_secure_link_module \ http/ngx_http_slice_module \ http/ngx_http_spdy_module \ - http/ngx_http_session_log_module \ http/ngx_http_split_clients_module \ http/ngx_http_ssi_module \ http/ngx_http_ssl_module \ - http/ngx_http_status_module \ http/ngx_http_stub_status_module \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ - http/ngx_http_upstream_conf_module \ - http/ngx_http_upstream_hc_module \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_v2_module \ @@ -111,14 +100,10 @@ REFS = \ stream/ngx_stream_geo_module \ stream/ngx_stream_geoip_module \ stream/ngx_stream_js_module \ - stream/ngx_stream_keyval_module \ stream/ngx_stream_limit_conn_module \ stream/ngx_stream_log_module \ stream/ngx_stream_map_module \ - stream/ngx_stream_mqtt_filter_module \ - stream/ngx_stream_mqtt_preread_module \ stream/ngx_stream_proxy_module \ - stream/ngx_stream_proxy_protocol_vendor_module \ stream/ngx_stream_realip_module \ stream/ngx_stream_return_module \ stream/ngx_stream_set_module \ @@ -126,12 +111,8 @@ REFS = \ stream/ngx_stream_ssl_module \ stream/ngx_stream_ssl_preread_module \ stream/ngx_stream_upstream_module \ - stream/ngx_stream_upstream_hc_module \ - stream/ngx_stream_zone_sync_module \ stream/stream_processing \ ngx_google_perftools_module \ - ngx_mgmt_module \ - ngx_otel_module \ dev/development_guide \ njs/index \ njs/changes \
--- a/xml/en/docs/http/ngx_http_access_module.xml +++ b/xml/en/docs/http/ngx_http_access_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_access_module" link="/en/docs/http/ngx_http_access_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -21,9 +21,8 @@ limiting access to certain client addres <para> Access can also be limited by -<link doc="ngx_http_auth_basic_module.xml">password</link>, by the -<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>, -or by <link doc="ngx_http_auth_jwt_module.xml">JWT</link>. +<link doc="ngx_http_auth_basic_module.xml">password</link> or by the +<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>. Simultaneous limitation of access by address and by password is controlled by the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive. </para>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_api_module.xml +++ /dev/null @@ -1,4587 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_api_module" - link="/en/docs/http/ngx_http_api_module.html" - lang="en" - rev="3"> - -<section id="summary"> - -<para> -The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API -for accessing various status information, -configuring upstream server groups on-the-fly, and managing -<link doc="ngx_http_keyval_module.xml">key-value pairs</link> -without the need of reconfiguring nginx. -</para> - -<para> -<note> -The module supersedes the -<link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and -<link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link> -modules. -</note> -</para> - -<para> -When using the <literal>PATCH</literal> or <literal>POST</literal> methods, -make sure that the payload does not exceed the -<link doc="ngx_http_core_module.xml" id="client_body_buffer_size">buffer size</link> -for reading the client request body, otherwise, the -<http-status code="413" text="Request Entity Too Large"/> -error may be returned. -</para> - -<para> -<note> -This module is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -http { - upstream backend { - zone http_backend 64k; - - server backend1.example.com weight=5; - server backend2.example.com; - } - - proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m; - - server { - server_name backend.example.com; - - location / { - proxy_pass http://backend; - proxy_cache cache_backend; - - health_check; - } - - status_zone server_backend; - } - - keyval_zone zone=one:32k state=one.keyval; - keyval $arg_text $text zone=one; - - server { - listen 127.0.0.1; - - location /api { - <emphasis>api</emphasis> write=on; - allow 127.0.0.1; - deny all; - } - } -} - -stream { - upstream backend { - zone stream_backend 64k; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345; - } - - server { - listen 127.0.0.1:12345; - proxy_pass backend; - status_zone server_backend; - health_check; - } -} -</example> -All API requests include -a supported API <link id="api_version">version</link> in the URI. -Examples of API requests with this configuration: -<example> -http://127.0.0.1/api/9/ -http://127.0.0.1/api/9/nginx -http://127.0.0.1/api/9/connections -http://127.0.0.1/api/9/workers -http://127.0.0.1/api/9/http/requests -http://127.0.0.1/api/9/http/server_zones/server_backend -http://127.0.0.1/api/9/http/caches/cache_backend -http://127.0.0.1/api/9/http/upstreams/backend -http://127.0.0.1/api/9/http/upstreams/backend/servers/ -http://127.0.0.1/api/9/http/upstreams/backend/servers/1 -http://127.0.0.1/api/9/http/keyvals/one?key=arg1 -http://127.0.0.1/api/9/stream/ -http://127.0.0.1/api/9/stream/server_zones/server_backend -http://127.0.0.1/api/9/stream/upstreams/ -http://127.0.0.1/api/9/stream/upstreams/backend -http://127.0.0.1/api/9/stream/upstreams/backend/servers/1 -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="api"> -<syntax> -[<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> -<default/> -<context>location</context> - -<para> -Turns on the REST API interface in the surrounding location. -Access to this location should be -<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. -</para> - -<para> -The <literal>write</literal> parameter determines whether the API -is read-only or read-write. -By default, the API is read-only. -</para> - -<para id="api_version"> -All API requests should contain a supported API version in the URI. -If the request URI equals the location prefix, -the list of supported API versions is returned. -The current API version is “<literal>9</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/9/nginx?fields=version,build -</example> -</para> - -</directive> - - -<directive name="status_zone"> -<syntax><value>zone</value></syntax> -<default/> -<context>server</context> -<context>location</context> -<context>if in location</context> -<appeared-in>1.13.12</appeared-in> - -<para> -Enables collection of virtual -<link doc="ngx_http_core_module.xml" id="server">http</link> -or -<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> -server status information in the specified <value>zone</value>. -Several servers may share the same zone. -</para> - -<para id="status_zone_location"> -Starting from 1.17.0, status information can be collected -per <link doc="ngx_http_core_module.xml" id="location"/>. -The special value <literal>off</literal> disables statistics collection -in nested location blocks. -Note that the statistics is collected -in the context of a location where processing ends. -It may be different from the original location, if an -<link doc="ngx_http_core_module.xml" id="internal">internal -redirect</link> happens during request processing. -</para> - -</directive> - -</section> - -<section id="compatibility" name="Compatibility"> - -<para> -<list type="bullet"> - -<listitem> -The <link id="workers_">/workers/</link> data -were added in <link id="api_version">version</link> 9. -</listitem> - -<listitem> -Detailed failure counters were added to SSL statistics -in <link id="api_version">version</link> 8 (1.23.2). -</listitem> - -<listitem> -The <literal>ssl</literal> data -for each HTTP -<link id="def_nginx_http_upstream">upstream</link>, -<link id="def_nginx_http_server_zone">server zone</link>, -and stream -<link id="def_nginx_stream_upstream">upstream</link>, -<link id="def_nginx_stream_server_zone">server zone</link>, -were added in <link id="api_version">version</link> 8 (1.21.6). -</listitem> - -<listitem> -The <literal>codes</literal> data -in <literal>responses</literal> for each HTTP -<link id="def_nginx_http_upstream">upstream</link>, -<link id="def_nginx_http_server_zone">server zone</link>, and -<link id="def_nginx_http_location_zone">location zone</link> -were added in <link id="api_version">version</link> 7. -</listitem> - -<listitem> -The <link id="stream_limit_conns_">/stream/limit_conns/</link> data -were added in <link id="api_version">version</link> 6. -</listitem> - -<listitem> -The <link id="http_limit_conns_">/http/limit_conns/</link> data -were added in <link id="api_version">version</link> 6. -</listitem> - -<listitem> -The <link id="http_limit_reqs_">/http/limit_reqs/</link> data -were added in <link id="api_version">version</link> 6. -</listitem> - -<listitem> -The “<literal>expire</literal>” parameter of a -<link doc="ngx_http_keyval_module.xml">key-value</link> pair can be -<link id="postHttpKeyvalZoneData">set</link> or -<link id="patchHttpKeyvalZoneKeyValue">changed</link> -since <link id="api_version">version</link> 5. -</listitem> - -<listitem> -The <link id="resolvers_">/resolvers/</link> data -were added in <link id="api_version">version</link> 5. -</listitem> - -<listitem> -The <link id="http_location_zones_">/http/location_zones/</link> data -were added in <link id="api_version">version</link> 5. -</listitem> - -<listitem> -The <literal>path</literal> and <literal>method</literal> fields of -<link id="def_nginx_error">nginx error object</link> -were removed in <link id="api_version">version</link> 4. -These fields continue to exist in earlier api versions, -but show an empty value. -</listitem> - -<listitem> -The <link id="stream_zone_sync_">/stream/zone_sync/</link> data -were added in <link id="api_version">version</link> 3. -</listitem> - -<listitem> -The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter -was added in <link id="api_version">version</link> 2. -</listitem> - -<listitem> -The <link id="stream_keyvals_">/stream/keyvals/</link> data -were added in <link id="api_version">version</link> 2. -</listitem> - -</list> -</para> - -</section> -<section id="endpoints" name="Endpoints"> -<para> -<list type="tag"> -<tag-name id="root" name="/"> -<literal>/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getAPIEndpoints"> -<literal>GET</literal> - Return list of root endpoints -<para>Returns a list of root endpoints.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of strings</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="nginx" name="/nginx"> -<literal>/nginx</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getNginx"> -<literal>GET</literal> - Return status of nginx running instance -<para>Returns nginx version, build name, address, number of configuration reloads, IDs of master and worker processes.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of nginx running instance will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_object">nginx</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="processes" name="/processes"> -<literal>/processes</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getProcesses"> -<literal>GET</literal> - Return nginx processes status -<para>Returns the number of abnormally terminated and respawned child processes.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_processes">Processes</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteProcesses"> -<literal>DELETE</literal> - Reset nginx processes statistics -<para>Resets counters of abnormally terminated and respawned child processes.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="connections" name="/connections"> -<literal>/connections</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getConnections"> -<literal>GET</literal> - Return client connections statistics -<para>Returns statistics of client connections.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the connections statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_connections">Connections</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteConnections"> -<literal>DELETE</literal> - Reset client connections statistics -<para>Resets statistics of accepted and dropped client connections.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="slabs_" name="/slabs/"> -<literal>/slabs/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getSlabs"> -<literal>GET</literal> - Return status of all slabs -<para>Returns status of slabs for each shared memory zone with slab allocator.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of slab zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link>" objects for all slabs</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="slabs_slab_zone_name" name="/slabs/{slabZoneName}"> -<literal>/slabs/{slabZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>slabZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of the shared memory zone with slab allocator.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getSlabZone"> -<literal>GET</literal> - Return status of a slab -<para>Returns status of slabs for a particular shared memory zone with slab allocator.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the slab zone will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link></listitem> -<listitem>404 - Slab not found (<literal>SlabNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteSlabZoneStats"> -<literal>DELETE</literal> - Reset slab statistics -<para>Resets the “<literal>reqs</literal>” and “<literal>fails</literal>” metrics for each memory slot.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Slab not found (<literal>SlabNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_" name="/http/"> -<literal>/http/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttp"> -<literal>GET</literal> - Return list of HTTP-related endpoints -<para>Returns a list of first level HTTP endpoints.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of strings</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_requests" name="/http/requests"> -<literal>/http/requests</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpRequests"> -<literal>GET</literal> - Return HTTP requests statistics -<para>Returns status of client HTTP requests.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of client HTTP requests statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_requests">HTTP Requests</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpRequests"> -<literal>DELETE</literal> - Reset HTTP requests statistics -<para>Resets the number of total client HTTP requests.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_server_zones_" name="/http/server_zones/"> -<literal>/http/server_zones/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpServerZones"> -<literal>GET</literal> - Return status of all HTTP server zones -<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">server zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_server_zone">HTTP Server Zone</link>" objects for all HTTP server zones</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_server_zones_http_server_zone_name" name="/http/server_zones/{httpServerZoneName}"> -<literal>/http/server_zones/{httpServerZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpServerZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of an HTTP server zone.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpServerZone"> -<literal>GET</literal> - Return status of an HTTP server zone -<para>Returns status of a particular HTTP server zone.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the server zone will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_server_zone">HTTP Server Zone</link></listitem> -<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpServerZoneStat"> -<literal>DELETE</literal> - Reset statistics for an HTTP server zone -<para>Resets statistics of accepted and discarded requests, responses, received and sent bytes, counters of SSL handshakes and session reuses in a particular HTTP server zone.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_location_zones_" name="/http/location_zones/"> -<literal>/http/location_zones/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpLocationZones"> -<literal>GET</literal> - Return status of all HTTP location zones -<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of location zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_location_zone">HTTP Location Zone</link>" objects for all HTTP location zones</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_location_zones_http_location_zone_name" name="/http/location_zones/{httpLocationZoneName}"> -<literal>/http/location_zones/{httpLocationZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpLocationZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of an HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpLocationZone"> -<literal>GET</literal> - Return status of an HTTP location zone -<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the location zone will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_location_zone">HTTP Location Zone</link></listitem> -<listitem>404 - Location zone not found (<literal>LocationZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpLocationZoneStat"> -<literal>DELETE</literal> - Reset statistics for a location zone. -<para>Resets statistics of accepted and discarded requests, responses, received and sent bytes in a particular location zone.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Location zone not found (<literal>LocationZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_caches_" name="/http/caches/"> -<literal>/http/caches/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpCaches"> -<literal>GET</literal> - Return status of all caches -<para>Returns status of each cache configured by <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path">proxy_cache_path</link> and other “<literal>*_cache_path</literal>” directives.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of cache zones will be output. If the “<literal>fields</literal>” value is empty, then only names of cache zones will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_cache">HTTP Cache</link>" objects for all HTTP caches</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_caches_http_cache_zone_name" name="/http/caches/{httpCacheZoneName}"> -<literal>/http/caches/{httpCacheZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpCacheZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of the cache zone.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpCacheZone"> -<literal>GET</literal> - Return status of a cache -<para>Returns status of a particular cache.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the cache zone will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_cache">HTTP Cache</link></listitem> -<listitem>404 - Cache not found (<literal>CacheNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpCacheZoneStat"> -<literal>DELETE</literal> - Reset cache statistics -<para>Resets statistics of cache hits/misses in a particular cache zone.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Cache not found (<literal>CacheNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_limit_conns_" name="/http/limit_conns/"> -<literal>/http/limit_conns/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpLimitConnZones"> -<literal>GET</literal> - Return status of all HTTP limit_conn zones -<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link>" objects for all HTTP limit conns</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_limit_conns_http_limit_conn_zone_name" name="/http/limit_conns/{httpLimitConnZoneName}"> -<literal>/http/limit_conns/{httpLimitConnZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpLimitConnZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpLimitConnZone"> -<literal>GET</literal> - Return status of an HTTP limit_conn zone -<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link></listitem> -<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpLimitConnZoneStat"> -<literal>DELETE</literal> - Reset statistics for an HTTP limit_conn zone -<para>Resets the connection limiting statistics.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_limit_reqs_" name="/http/limit_reqs/"> -<literal>/http/limit_reqs/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpLimitReqZones"> -<literal>GET</literal> - Return status of all HTTP limit_req zones -<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of limit_req zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link>" objects for all HTTP limit reqs</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_limit_reqs_http_limit_req_zone_name" name="/http/limit_reqs/{httpLimitReqZoneName}"> -<literal>/http/limit_reqs/{httpLimitReqZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpLimitReqZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpLimitReqZone"> -<literal>GET</literal> - Return status of an HTTP limit_req zone -<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link> will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link></listitem> -<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpLimitReqZoneStat"> -<literal>DELETE</literal> - Reset statistics for an HTTP limit_req zone -<para>Resets the requests limiting statistics.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_upstreams_" name="/http/upstreams/"> -<literal>/http/upstreams/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpUpstreams"> -<literal>GET</literal> - Return status of all HTTP upstream server groups -<para>Returns status of each HTTP upstream server group and its servers.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_upstream">HTTP Upstream</link>" objects for all HTTP upstreams</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_upstreams_http_upstream_name_" name="/http/upstreams/{httpUpstreamName}/"> -<literal>/http/upstreams/{httpUpstreamName}/</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpUpstreamName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of an HTTP upstream server group.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpUpstreamName"> -<literal>GET</literal> - Return status of an HTTP upstream server group -<para>Returns status of a particular HTTP upstream server group and its servers.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the upstream server group will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_upstream">HTTP Upstream</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpUpstreamStat"> -<literal>DELETE</literal> - Reset statistics of an HTTP upstream server group -<para>Resets the statistics for each upstream server in an upstream server group and queue statistics.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_upstreams_http_upstream_name_servers_" name="/http/upstreams/{httpUpstreamName}/servers/"> -<literal>/http/upstreams/{httpUpstreamName}/servers/</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpUpstreamName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of an upstream server group.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpUpstreamServers"> -<literal>GET</literal> - Return configuration of all servers in an HTTP upstream server group -<para>Returns configuration of each server in a particular HTTP upstream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Servers</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="postHttpUpstreamServer"> -<literal>POST</literal> - Add a server to an HTTP upstream server group -<para>Adds a new server to an HTTP upstream server group. Server parameters are specified in the JSON format.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>postHttpUpstreamServer</literal> -(<link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link>, required)</tag-name> -<tag-desc> -Address of a new server and other optional parameters in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>201 - Created, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), -missing “<literal>server</literal>” argument (<literal>UpstreamConfFormatError</literal>), -unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), -nested object or list (<literal>UpstreamConfFormatError</literal>), -“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), -service upstream “<literal>host</literal>” may not have port (<literal>UpstreamBadAddress</literal>), -service upstream “<literal>host</literal>” requires domain name (<literal>UpstreamBadAddress</literal>), -invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), -invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), -invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), -invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), -invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), -reading request body failed <literal>BodyReadError</literal>), -route is too long (<literal>UpstreamBadRoute</literal>), -“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), -no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>), -upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>), -upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>409 - Entry exists (<literal>EntryExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_upstreams_http_upstream_name_servers_http_upstream_server_id" name="/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}"> -<literal>/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpUpstreamName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of the upstream server group.</tag-desc> -<tag-name><literal>httpUpstreamServerId</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The ID of the server.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpUpstreamPeer"> -<literal>GET</literal> - Return configuration of a server in an HTTP upstream server group -<para>Returns configuration of a particular server in the HTTP upstream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="patchHttpUpstreamPeer"> -<literal>PATCH</literal> - Modify a server in an HTTP upstream server group -<para>Modifies settings of a particular server in an HTTP upstream server group. Server parameters are specified in the JSON format.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>patchHttpUpstreamServer</literal> -(<link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link>, required)</tag-name> -<tag-desc> -Server parameters, specified in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Server</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), -unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), -nested object or list (<literal>UpstreamConfFormatError</literal>), -“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), -invalid “<literal>server</literal>” argument (<literal>UpstreamBadAddress</literal>), -invalid server ID (<literal>UpstreamBadServerId</literal>), -invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), -invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), -invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), -invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), -invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), -reading request body failed <literal>BodyReadError</literal>), -route is too long (<literal>UpstreamBadRoute</literal>), -“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), -server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>), -server “<literal>ID</literal>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>), -upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpUpstreamServer"> -<literal>DELETE</literal> - Remove a server from an HTTP upstream server group -<para>Removes a server from an HTTP upstream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of <link id="def_nginx_http_upstream_conf_server">HTTP Upstream Servers</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid server ID (<literal>UpstreamBadServerId</literal>), -server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_keyvals_" name="/http/keyvals/"> -<literal>/http/keyvals/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpKeyvalZones"> -<literal>GET</literal> - Return key-value pairs from all HTTP keyval zones -<para>Returns key-value pairs for each HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -If the “<literal>fields</literal>” value is empty, then only HTTP keyval zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>" objects for all HTTP keyvals</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="http_keyvals_http_keyval_zone_name" name="/http/keyvals/{httpKeyvalZoneName}"> -<literal>/http/keyvals/{httpKeyvalZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>httpKeyvalZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of an HTTP keyval shared memory zone.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getHttpKeyvalZoneKeysValues"> -<literal>GET</literal> - Return key-value pairs from an HTTP keyval zone -<para>Returns key-value pairs stored in a particular HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>key</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Get a particular key-value pair from the HTTP keyval zone.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link></listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -keyval key not found (<literal>KeyvalKeyNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="postHttpKeyvalZoneData"> -<literal>POST</literal> - Add a key-value pair to the HTTP keyval zone -<para>Adds a new key-value pair to the HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>Key-value</literal> -(<link id="def_nginx_http_keyval_zone_post_patch">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> -<tag-desc> -A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</link> directive.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>201 - Created</listitem> -<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), -invalid key format (<literal>KeyvalFormatError</literal>), -key required (<literal>KeyvalFormatError</literal>), -keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), -only one key can be added (<literal>KeyvalFormatError</literal>), -reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>409 - Entry exists (<literal>EntryExists</literal>), -key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="patchHttpKeyvalZoneKeyValue"> -<literal>PATCH</literal> - Modify a key-value or delete a key -<para>Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</link> directive.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>httpKeyvalZoneKeyValue</literal> -(<link id="def_nginx_http_keyval_zone_post_patch">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> -<tag-desc> -A new value for the key is specified in the JSON format.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), -key required (<literal>KeyvalFormatError</literal>), -keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), -only one key can be updated (<literal>KeyvalFormatError</literal>), -reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -keyval key not found (<literal>KeyvalKeyNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteHttpKeyvalZoneData"> -<literal>DELETE</literal> - Empty the HTTP keyval zone -<para>Deletes all key-value pairs from the HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_" name="/stream/"> -<literal>/stream/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStream"> -<literal>GET</literal> - Return list of stream-related endpoints -<para>Returns a list of first level stream endpoints.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of strings</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_server_zones_" name="/stream/server_zones/"> -<literal>/stream/server_zones/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamServerZones"> -<literal>GET</literal> - Return status of all stream server zones -<para>Returns status information for each stream <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">server zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_server_zone">Stream Server Zone</link>" objects for all stream server zones</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_server_zones_stream_server_zone_name" name="/stream/server_zones/{streamServerZoneName}"> -<literal>/stream/server_zones/{streamServerZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>streamServerZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a stream server zone.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamServerZone"> -<literal>GET</literal> - Return status of a stream server zone -<para>Returns status of a particular stream server zone.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the server zone will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_server_zone">Stream Server Zone</link></listitem> -<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteStreamServerZoneStat"> -<literal>DELETE</literal> - Reset statistics for a stream server zone -<para>Resets statistics of accepted and discarded connections, sessions, received and sent bytes, counters of SSL handshakes and session reuses in a particular stream server zone.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_limit_conns_" name="/stream/limit_conns/"> -<literal>/stream/limit_conns/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamLimitConnZones"> -<literal>GET</literal> - Return status of all stream limit_conn zones -<para>Returns status information for each stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link>" objects for all stream limit conns</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_limit_conns_stream_limit_conn_zone_name" name="/stream/limit_conns/{streamLimitConnZoneName}"> -<literal>/stream/limit_conns/{streamLimitConnZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>streamLimitConnZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamLimitConnZone"> -<literal>GET</literal> - Return status of an stream limit_conn zone -<para>Returns status of a particular stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link></listitem> -<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteStreamLimitConnZoneStat"> -<literal>DELETE</literal> - Reset statistics for a stream limit_conn zone -<para>Resets the connection limiting statistics.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_upstreams_" name="/stream/upstreams/"> -<literal>/stream/upstreams/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamUpstreams"> -<literal>GET</literal> - Return status of all stream upstream server groups -<para>Returns status of each stream upstream server group and its servers.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_upstreams_stream_upstream_name_" name="/stream/upstreams/{streamUpstreamName}/"> -<literal>/stream/upstreams/{streamUpstreamName}/</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>streamUpstreamName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a stream upstream server group.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamUpstream"> -<literal>GET</literal> - Return status of a stream upstream server group -<para>Returns status of a particular stream upstream server group and its servers.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the upstream server group will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_upstream">Stream Upstream</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteStreamUpstreamStat"> -<literal>DELETE</literal> - Reset statistics of a stream upstream server group -<para>Resets the statistics for each upstream server in an upstream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_upstreams_stream_upstream_name_servers_" name="/stream/upstreams/{streamUpstreamName}/servers/"> -<literal>/stream/upstreams/{streamUpstreamName}/servers/</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>streamUpstreamName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of an upstream server group.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamUpstreamServers"> -<literal>GET</literal> - Return configuration of all servers in a stream upstream server group -<para>Returns configuration of each server in a particular stream upstream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="postStreamUpstreamServer"> -<literal>POST</literal> - Add a server to a stream upstream server group -<para>Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>postStreamUpstreamServer</literal> -(<link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link>, required)</tag-name> -<tag-desc> -Address of a new server and other optional parameters in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>201 - Created, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), -missing “<literal>server</literal>” argument (<literal>UpstreamConfFormatError</literal>), -unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), -nested object or list (<literal>UpstreamConfFormatError</literal>), -“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), -no port in server “<literal>host</literal>” (<literal>UpstreamBadAddress</literal>), -service upstream “<literal>host</literal>” may not have port (<literal>UpstreamBadAddress</literal>), -service upstream “<literal>host</literal>” requires domain name (<literal>UpstreamBadAddress</literal>), -invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), -invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), -invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), -invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), -invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), -“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), -no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>), -upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>), -upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), -reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>409 - Entry exists (<literal>EntryExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_upstreams_stream_upstream_name_servers_stream_upstream_server_id" name="/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}"> -<literal>/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>streamUpstreamName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of the upstream server group.</tag-desc> -<tag-name><literal>streamUpstreamServerId</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The ID of the server.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamUpstreamServer"> -<literal>GET</literal> - Return configuration of a server in a stream upstream server group -<para>Returns configuration of a particular server in the stream upstream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), -server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="patchStreamUpstreamServer"> -<literal>PATCH</literal> - Modify a server in a stream upstream server group -<para>Modifies settings of a particular server in a stream upstream server group. Server parameters are specified in the JSON format.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>patchStreamUpstreamServer</literal> -(<link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link>, required)</tag-name> -<tag-desc> -Server parameters, specified in the JSON format. The “<literal>ID</literal>”, “<literal>backup</literal>”, and “<literal>service</literal>” parameters cannot be changed.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid “<value>parameter</value>” value (<literal>UpstreamConfFormatError</literal>), -unknown parameter “<value>name</value>” (<literal>UpstreamConfFormatError</literal>), -nested object or list (<literal>UpstreamConfFormatError</literal>), -“<literal>error</literal>” while parsing (<literal>UpstreamBadAddress</literal>), -invalid “<literal>server</literal>” argument (<literal>UpstreamBadAddress</literal>), -no port in server “<literal>host</literal>” (<literal>UpstreamBadAddress</literal>), -invalid server ID (<literal>UpstreamBadServerId</literal>), -invalid “<literal>weight</literal>” (<literal>UpstreamBadWeight</literal>), -invalid “<literal>max_conns</literal>” (<literal>UpstreamBadMaxConns</literal>), -invalid “<literal>max_fails</literal>” (<literal>UpstreamBadMaxFails</literal>), -invalid “<literal>fail_timeout</literal>” (<literal>UpstreamBadFailTimeout</literal>), -invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), -reading request body failed <literal>BodyReadError</literal>), -“<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), -server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>), -server “<value>ID</value>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>), -upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteStreamUpstreamServer"> -<literal>DELETE</literal> - Remove a server from a stream upstream server group -<para>Removes a server from a stream server group.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> -<listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), -invalid server ID (<literal>UpstreamBadServerId</literal>), -server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), -upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_keyvals_" name="/stream/keyvals/"> -<literal>/stream/keyvals/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamKeyvalZones"> -<literal>GET</literal> - Return key-value pairs from all stream keyval zones -<para>Returns key-value pairs for each stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -If the “<literal>fields</literal>” value is empty, then only stream keyval zone names will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>" objects for all stream keyvals</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_keyvals_stream_keyval_zone_name" name="/stream/keyvals/{streamKeyvalZoneName}"> -<literal>/stream/keyvals/{streamKeyvalZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>streamKeyvalZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a stream keyval shared memory zone.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamKeyvalZoneKeysValues"> -<literal>GET</literal> - Return key-value pairs from a stream keyval zone -<para>Returns key-value pairs stored in a particular stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>key</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Get a particular key-value pair from the stream keyval zone.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link></listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -keyval key not found (<literal>KeyvalKeyNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="postStreamKeyvalZoneData"> -<literal>POST</literal> - Add a key-value pair to the stream keyval zone -<para>Adds a new key-value pair to the stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the stream keyval shared memory zone is empty.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>Key-value</literal> -(<link id="def_nginx_stream_keyval_zone_post_patch">Stream Keyval Shared Memory Zone</link>, required)</tag-name> -<tag-desc> -A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</link> directive.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>201 - Created</listitem> -<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), -invalid key format (<literal>KeyvalFormatError</literal>), -key required (<literal>KeyvalFormatError</literal>), -keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), -only one key can be added (<literal>KeyvalFormatError</literal>), -reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>409 - Entry exists (<literal>EntryExists</literal>), -key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="patchStreamKeyvalZoneKeyValue"> -<literal>PATCH</literal> - Modify a key-value or delete a key -<para>Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time is specified in milliseconds with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</link> directive.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>streamKeyvalZoneKeyValue</literal> -(<link id="def_nginx_stream_keyval_zone_post_patch">Stream Keyval Shared Memory Zone</link>, required)</tag-name> -<tag-desc> -A new value for the key is specified in the JSON format.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), -key required (<literal>KeyvalFormatError</literal>), -keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), -only one key can be updated (<literal>KeyvalFormatError</literal>), -reading request body failed <literal>BodyReadError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -keyval key not found (<literal>KeyvalKeyNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>413 - Request Entity Too Large, returns <link id="def_nginx_error">Error</link></listitem> -<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteStreamKeyvalZoneData"> -<literal>DELETE</literal> - Empty the stream keyval zone -<para>Deletes all key-value pairs from the stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="stream_zone_sync_" name="/stream/zone_sync/"> -<literal>/stream/zone_sync/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getStreamZoneSync"> -<literal>GET</literal> - Return sync status of a node -<para>Returns synchronization status of a cluster node.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_stream_zone_sync">Stream Zone Sync Node</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="resolvers_" name="/resolvers/"> -<literal>/resolvers/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getResolverZones"> -<literal>GET</literal> - Return status for all resolver zones -<para>Returns status information for each <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of resolvers statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_resolver_zone">Resolver Zone</link>" objects for all resolvers</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="resolvers_resolver_zone_name" name="/resolvers/{resolverZoneName}"> -<literal>/resolvers/{resolverZoneName}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>resolverZoneName</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The name of a resolver zone.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getResolverZone"> -<literal>GET</literal> - Return statistics of a resolver zone -<para>Returns statistics stored in a particular resolver <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">zone</link>.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of the resolver zone will be output (requests, responses, or both).</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_resolver_zone">Resolver Zone</link></listitem> -<listitem>404 - Resolver zone not found (<literal>ResolverZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteResolverZoneStat"> -<literal>DELETE</literal> - Reset statistics for a resolver zone. -<para>Resets statistics in a particular resolver zone.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Resolver zone not found (<literal>ResolverZoneNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="ssl" name="/ssl"> -<literal>/ssl</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getSsl"> -<literal>GET</literal> - Return SSL statistics -<para>Returns SSL statistics.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of SSL statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_ssl_object">SSL</link></listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteSslStat"> -<literal>DELETE</literal> - Reset SSL statistics -<para>Resets counters of SSL handshakes and session reuses.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="workers_" name="/workers/"> -<literal>/workers/</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getWorkers"> -<literal>GET</literal> - Return statistics for all worker processes -<para>Returns statistics for all worker processes such as accepted, dropped, active, idle connections, total and current 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 worker process statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_worker">Worker process</link>" objects for all workers</listitem> -<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteWorkersStat"> -<literal>DELETE</literal> - Reset statistics for all worker processes. -<para>Resets statistics for all worker processes such as -accepted, dropped, active, idle connections, total and current requests.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -<tag-name id="workers_worker_id" name="/workers/{workerId}"> -<literal>/workers/{workerId}</literal> -</tag-name> -<tag-desc> -Parameters common for all methods: -<list type="tag"> -<tag-name><literal>workerId</literal> -(<literal>string</literal>, required)</tag-name> -<tag-desc> -The ID of the worker process.</tag-desc> -</list> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getWorker"> -<literal>GET</literal> - Return status of a worker process -<para>Returns status of a particular worker process.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of worker process statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_worker">Worker process</link></listitem> -<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -<listitem id="deleteWorkerStat"> -<literal>DELETE</literal> - Reset statistics for a worker process. -<para>Resets statistics of accepted, dropped, active, idle connections, -as well as total and current requests.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>), -unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> -<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> -</list> -</listitem> -</list> -</tag-desc> -</list> -</para> -</section> -<section id="definitions" name="Response Objects"> -<para> -<list type="bullet"> -<listitem id="def_nginx_object"> -<para>nginx:</para> -General information about nginx:<list type="tag"> -<tag-name> -<literal>version</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Version of nginx. -</tag-desc> -<tag-name> -<literal>build</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Name of nginx build. -</tag-desc> -<tag-name> -<literal>address</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The address of the server that accepted status request. -</tag-desc> -<tag-name> -<literal>generation</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of configuration <link url="https://nginx.org/en/docs/control.html#reconfiguration">reloads</link>. -</tag-desc> -<tag-name> -<literal>load_timestamp</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Time of the last reload of configuration, in the ISO 8601 format with millisecond resolution. -</tag-desc> -<tag-name> -<literal>timestamp</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Current time in the ISO 8601 format with millisecond resolution. -</tag-desc> -<tag-name> -<literal>pid</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the worker process that handled status request. -</tag-desc> -<tag-name> -<literal>ppid</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the master process that started the <link url="https://nginx.org/en/docs/http/ngx_http_status_module.html#pid">worker process</link>. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "nginx" : { - "version" : "1.21.6", - "build" : "nginx-plus-r27", - "address" : "206.251.255.64", - "generation" : 6, - "load_timestamp" : "2022-06-28T11:15:44.467Z", - "timestamp" : "2022-06-28T09:26:07.305Z", - "pid" : 32212, - "ppid" : 32210 - } -}</example> -</listitem> -<listitem id="def_nginx_processes"> -<para>Processes:</para> -<list type="tag"> -<tag-name> -<literal>respawned</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of abnormally terminated and respawned child processes. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "respawned" : 0 -}</example> -</listitem> -<listitem id="def_nginx_connections"> -<para>Connections:</para> -The number of accepted, dropped, active, and idle connections.<list type="tag"> -<tag-name> -<literal>accepted</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of accepted client connections. -</tag-desc> -<tag-name> -<literal>dropped</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of dropped client connections. -</tag-desc> -<tag-name> -<literal>active</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of active client connections. -</tag-desc> -<tag-name> -<literal>idle</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of idle client connections. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "accepted" : 4968119, - "dropped" : 0, - "active" : 5, - "idle" : 117 -}</example> -</listitem> -<listitem id="def_nginx_ssl_object"> -<para>SSL:</para> -<list type="tag"> -<tag-name> -<literal>handshakes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of successful SSL handshakes. -</tag-desc> -<tag-name> -<literal>handshakes_failed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of failed SSL handshakes. -</tag-desc> -<tag-name> -<literal>session_reuses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of session reuses during SSL handshake. -</tag-desc> -<tag-name> -<literal>no_common_protocol</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no common protocol. -</tag-desc> -<tag-name> -<literal>no_common_cipher</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no shared cipher. -</tag-desc> -<tag-name> -<literal>handshake_timeout</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of a timeout. -</tag-desc> -<tag-name> -<literal>peer_rejected_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed SSL handshakes when nginx presented the certificate to the client but it was rejected with a corresponding alert message. -</tag-desc> -<tag-name> -<literal>verify_failures</literal></tag-name> -<tag-desc> -SSL certificate verification errors<list type="tag"> -<tag-name> -<literal>no_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A client did not provide the required certificate. -</tag-desc> -<tag-name> -<literal>expired_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -An expired or not yet valid certificate was presented by a client. -</tag-desc> -<tag-name> -<literal>revoked_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A revoked certificate was presented by a client. -</tag-desc> -<tag-name> -<literal>hostname_mismatch</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Server's certificate doesn't match the hostname. -</tag-desc> -<tag-name> -<literal>other</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Other SSL certificate verification errors. -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "handshakes" : 79572, - "handshakes_failed" : 21025, - "session_reuses" : 15762, - "no_common_protocol" : 4, - "no_common_cipher" : 2, - "handshake_timeout" : 0, - "peer_rejected_cert" : 0, - "verify_failures" : { - "no_cert" : 0, - "expired_cert" : 2, - "revoked_cert" : 1, - "hostname_mismatch" : 2, - "other" : 1 - } -}</example> -</listitem> -<listitem id="def_nginx_slab_zone"> -<para>Shared memory zone with slab allocator:</para> -Shared memory zone with slab allocator<list type="tag"> -<tag-name> -<literal>pages</literal></tag-name> -<tag-desc> -The number of free and used memory pages.<list type="tag"> -<tag-name> -<literal>used</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of used memory pages. -</tag-desc> -<tag-name> -<literal>free</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of free memory pages. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>slots</literal></tag-name> -<tag-desc> -<para>Status data for memory slots (8, 16, 32, 64, 128, etc.)</para><para>A collection of "<link id="def_nginx_slab_zone_slot">Memory Slot</link>" objects</para> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "pages" : { - "used" : 1143, - "free" : 2928 - }, - "slots" : { - "8" : { - "used" : 0, - "free" : 0, - "reqs" : 0, - "fails" : 0 - }, - "16" : { - "used" : 0, - "free" : 0, - "reqs" : 0, - "fails" : 0 - }, - "32" : { - "used" : 0, - "free" : 0, - "reqs" : 0, - "fails" : 0 - }, - "64" : { - "used" : 1, - "free" : 63, - "reqs" : 1, - "fails" : 0 - }, - "128" : { - "used" : 0, - "free" : 0, - "reqs" : 0, - "fails" : 0 - }, - "256" : { - "used" : 18078, - "free" : 178, - "reqs" : 1635736, - "fails" : 0 - } - } -}</example> -</listitem> -<listitem id="def_nginx_slab_zone_slot"> -<para>Memory Slot:</para> -<list type="tag"> -<tag-name> -<literal>used</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of used memory slots. -</tag-desc> -<tag-name> -<literal>free</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of free memory slots. -</tag-desc> -<tag-name> -<literal>reqs</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of attempts to allocate memory of specified size. -</tag-desc> -<tag-name> -<literal>fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of unsuccessful attempts to allocate memory of specified size. -</tag-desc> -</list> -</listitem> -<listitem id="def_nginx_http_requests"> -<para>HTTP Requests:</para> -<list type="tag"> -<tag-name> -<literal>total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client requests. -</tag-desc> -<tag-name> -<literal>current</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of client requests. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "total" : 10624511, - "current" : 4 -}</example> -</listitem> -<listitem id="def_nginx_http_server_zone"> -<para>HTTP Server Zone:</para> -<list type="tag"> -<tag-name> -<literal>processing</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of client requests that are currently being processed. -</tag-desc> -<tag-name> -<literal>requests</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client requests received from clients. -</tag-desc> -<tag-name> -<literal>responses</literal></tag-name> -<tag-desc> -The total number of responses sent to clients, the number of responses with status codes “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, “<literal>4xx</literal>”, and “<literal>5xx</literal>”, and the number of responses per each status code.<list type="tag"> -<tag-name> -<literal>1xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>1xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>2xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>2xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>3xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>3xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>4xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>4xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>5xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>5xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>codes</literal></tag-name> -<tag-desc> -The number of responses per each status code.<list type="tag"> -<tag-name> -<literal>codeNumber</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with this particular status code. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses sent to clients. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>discarded</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests completed without sending a response. -</tag-desc> -<tag-name> -<literal>received</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes received from clients. -</tag-desc> -<tag-name> -<literal>sent</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes sent to clients. -</tag-desc> -<tag-name> -<literal>ssl</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>handshakes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of successful SSL handshakes. -</tag-desc> -<tag-name> -<literal>handshakes_failed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of failed SSL handshakes. -</tag-desc> -<tag-name> -<literal>session_reuses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of session reuses during SSL handshake. -</tag-desc> -<tag-name> -<literal>no_common_protocol</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no common protocol. -</tag-desc> -<tag-name> -<literal>no_common_cipher</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no shared cipher. -</tag-desc> -<tag-name> -<literal>handshake_timeout</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of a timeout. -</tag-desc> -<tag-name> -<literal>peer_rejected_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed SSL handshakes when nginx presented the certificate to the client but it was rejected with a corresponding alert message. -</tag-desc> -<tag-name> -<literal>verify_failures</literal></tag-name> -<tag-desc> -SSL certificate verification errors<list type="tag"> -<tag-name> -<literal>no_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A client did not provide the required certificate. -</tag-desc> -<tag-name> -<literal>expired_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -An expired or not yet valid certificate was presented by a client. -</tag-desc> -<tag-name> -<literal>revoked_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A revoked certificate was presented by a client. -</tag-desc> -<tag-name> -<literal>other</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Other SSL certificate verification errors. -</tag-desc> -</list> -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "processing" : 1, - "requests" : 706690, - "responses" : { - "1xx" : 0, - "2xx" : 699482, - "3xx" : 4522, - "4xx" : 907, - "5xx" : 266, - "codes" : { - "200" : 699482, - "301" : 4522, - "404" : 907, - "503" : 266 - }, - "total" : 705177 - }, - "discarded" : 1513, - "received" : 172711587, - "sent" : 19415530115, - "ssl" : { - "handshakes" : 104303, - "handshakes_failed" : 1421, - "session_reuses" : 54645, - "no_common_protocol" : 4, - "no_common_cipher" : 2, - "handshake_timeout" : 0, - "peer_rejected_cert" : 0, - "verify_failures" : { - "no_cert" : 0, - "expired_cert" : 2, - "revoked_cert" : 1, - "other" : 1 - } - } -}</example> -</listitem> -<listitem id="def_nginx_http_location_zone"> -<para>HTTP Location Zone:</para> -<list type="tag"> -<tag-name> -<literal>requests</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client requests received from clients. -</tag-desc> -<tag-name> -<literal>responses</literal></tag-name> -<tag-desc> -The total number of responses sent to clients, the number of responses with status codes “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, “<literal>4xx</literal>”, and “<literal>5xx</literal>”, and the number of responses per each status code.<list type="tag"> -<tag-name> -<literal>1xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>1xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>2xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>2xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>3xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>3xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>4xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>4xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>5xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>5xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>codes</literal></tag-name> -<tag-desc> -The number of responses per each status code.<list type="tag"> -<tag-name> -<literal>codeNumber</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with this particular status code. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses sent to clients. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>discarded</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests completed without sending a response. -</tag-desc> -<tag-name> -<literal>received</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes received from clients. -</tag-desc> -<tag-name> -<literal>sent</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes sent to clients. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "requests" : 706690, - "responses" : { - "1xx" : 0, - "2xx" : 699482, - "3xx" : 4522, - "4xx" : 907, - "5xx" : 266, - "codes" : { - "200" : 112674, - "301" : 4522, - "404" : 2504, - "503" : 266 - }, - "total" : 705177 - }, - "discarded" : 1513, - "received" : 172711587, - "sent" : 19415530115 -}</example> -</listitem> -<listitem id="def_nginx_http_cache"> -<para>HTTP Cache:</para> -<list type="tag"> -<tag-name> -<literal>size</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current size of the cache. -</tag-desc> -<tag-name> -<literal>max_size</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The limit on the maximum size of the cache specified in the configuration. -</tag-desc> -<tag-name> -<literal>cold</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -A boolean value indicating whether the “cache loader” process is still loading data from disk into the cache. -</tag-desc> -<tag-name> -<literal>hit</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid">valid</link> responses read from the cache. -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the cache. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>stale</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of expired responses read from the cache (see <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale">proxy_cache_use_stale</link> and other “<literal>*_cache_use_stale</literal>” directives). -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the cache. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>updating</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of expired responses read from the cache while responses were being updated (see <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale_updating">proxy_cache_use_stale</link> and other “<literal>*_cache_use_stale</literal>” directives). -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the cache. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>revalidated</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of expired and revalidated responses read from the cache (see <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_revalidate">proxy_cache_revalidate</link> and other “<literal>*_cache_revalidate</literal>” directives. -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the cache. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>miss</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses not found in the cache. -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the proxied server. -</tag-desc> -<tag-name> -<literal>responses_written</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses written to the cache. -</tag-desc> -<tag-name> -<literal>bytes_written</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes written to the cache. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>expired</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of expired responses not taken from the cache. -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the proxied server. -</tag-desc> -<tag-name> -<literal>responses_written</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses written to the cache. -</tag-desc> -<tag-name> -<literal>bytes_written</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes written to the cache. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>bypass</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>responses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses not looked up in the cache due to the <link url="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_bypass">proxy_cache_bypass</link> and other “<literal>*_cache_bypass</literal>” directives. -</tag-desc> -<tag-name> -<literal>bytes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes read from the proxied server. -</tag-desc> -<tag-name> -<literal>responses_written</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses written to the cache. -</tag-desc> -<tag-name> -<literal>bytes_written</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes written to the cache. -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "size" : 530915328, - "max_size" : 536870912, - "cold" : false, - "hit" : { - "responses" : 254032, - "bytes" : 6685627875 - }, - "stale" : { - "responses" : 0, - "bytes" : 0 - }, - "updating" : { - "responses" : 0, - "bytes" : 0 - }, - "revalidated" : { - "responses" : 0, - "bytes" : 0 - }, - "miss" : { - "responses" : 1619201, - "bytes" : 53841943822 - }, - "expired" : { - "responses" : 45859, - "bytes" : 1656847080, - "responses_written" : 44992, - "bytes_written" : 1641825173 - }, - "bypass" : { - "responses" : 200187, - "bytes" : 5510647548, - "responses_written" : 200173, - "bytes_written" : 44992 - } -}</example> -</listitem> -<listitem id="def_nginx_http_limit_conn_zone"> -<para>HTTP Connections Limiting:</para> -<list type="tag"> -<tag-name> -<literal>passed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections that were neither limited nor accounted as limited. -</tag-desc> -<tag-name> -<literal>rejected</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections that were rejected. -</tag-desc> -<tag-name> -<literal>rejected_dry_run</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "passed" : 15, - "rejected" : 0, - "rejected_dry_run" : 2 -}</example> -</listitem> -<listitem id="def_nginx_http_limit_req_zone"> -<para>HTTP Requests Rate Limiting:</para> -<list type="tag"> -<tag-name> -<literal>passed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests that were neither limited nor accounted as limited. -</tag-desc> -<tag-name> -<literal>delayed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests that were delayed. -</tag-desc> -<tag-name> -<literal>rejected</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests that were rejected. -</tag-desc> -<tag-name> -<literal>delayed_dry_run</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests accounted as delayed in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode. -</tag-desc> -<tag-name> -<literal>rejected_dry_run</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "passed" : 15, - "delayed" : 4, - "rejected" : 0, - "delayed_dry_run" : 1, - "rejected_dry_run" : 2 -}</example> -</listitem> -<listitem id="def_nginx_http_upstream"> -<para>HTTP Upstream:</para> -<list type="tag"> -<tag-name> -<literal>peers</literal></tag-name> -<tag-desc> -An array of:<list type="tag"> -<tag-name> -<literal>id</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the server. -</tag-desc> -<tag-name> -<literal>server</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -An <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</link> of the server. -</tag-desc> -<tag-name> -<literal>service</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</link> parameter value of the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link> directive. -</tag-desc> -<tag-name> -<literal>name</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The name of the server specified in the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link> directive. -</tag-desc> -<tag-name> -<literal>backup</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -A boolean value indicating whether the server is a <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</link> server. -</tag-desc> -<tag-name> -<literal>weight</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -<link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</link> of the server. -</tag-desc> -<tag-name> -<literal>state</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Current state, which may be one of “<literal>up</literal>”, “<literal>draining</literal>”, “<literal>down</literal>”, “<literal>unavail</literal>”, “<literal>checking</literal>”, and “<literal>unhealthy</literal>”. -</tag-desc> -<tag-name> -<literal>active</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of active connections. -</tag-desc> -<tag-name> -<literal>ssl</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>handshakes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of successful SSL handshakes. -</tag-desc> -<tag-name> -<literal>handshakes_failed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of failed SSL handshakes. -</tag-desc> -<tag-name> -<literal>session_reuses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of session reuses during SSL handshake. -</tag-desc> -<tag-name> -<literal>no_common_protocol</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no common protocol. -</tag-desc> -<tag-name> -<literal>handshake_timeout</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of a timeout. -</tag-desc> -<tag-name> -<literal>peer_rejected_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message. -</tag-desc> -<tag-name> -<literal>verify_failures</literal></tag-name> -<tag-desc> -SSL certificate verification errors<list type="tag"> -<tag-name> -<literal>expired_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -An expired or not yet valid certificate was presented by an upstream server. -</tag-desc> -<tag-name> -<literal>revoked_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A revoked certificate was presented by an upstream server. -</tag-desc> -<tag-name> -<literal>hostname_mismatch</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Server's certificate doesn't match the hostname. -</tag-desc> -<tag-name> -<literal>other</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Other SSL certificate verification errors. -</tag-desc> -</list> -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>max_conns</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> limit for the server. -</tag-desc> -<tag-name> -<literal>requests</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client requests forwarded to this server. -</tag-desc> -<tag-name> -<literal>responses</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>1xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>1xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>2xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>2xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>3xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>3xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>4xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>4xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>5xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with “<literal>5xx</literal>” status codes. -</tag-desc> -<tag-name> -<literal>codes</literal></tag-name> -<tag-desc> -The number of responses per each status code.<list type="tag"> -<tag-name> -<literal>codeNumber</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of responses with this particular status code. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of responses obtained from this server. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>sent</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes sent to this server. -</tag-desc> -<tag-name> -<literal>received</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes received from this server. -</tag-desc> -<tag-name> -<literal>fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of unsuccessful attempts to communicate with the server. -</tag-desc> -<tag-name> -<literal>unavail</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -How many times the server became unavailable for client requests (state “<literal>unavail</literal>”) due to the number of unsuccessful attempts reaching the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</link> threshold. -</tag-desc> -<tag-name> -<literal>health_checks</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>checks</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of <link url="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</link> requests made. -</tag-desc> -<tag-name> -<literal>fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed health checks. -</tag-desc> -<tag-name> -<literal>unhealthy</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -How many times the server became unhealthy (state “<literal>unhealthy</literal>”). -</tag-desc> -<tag-name> -<literal>last_passed</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -Boolean indicating if the last health check request was successful and passed <link url="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</link>. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>downtime</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Total time the server was in the “<literal>unavail</literal>”, “<literal>checking</literal>”, and “<literal>unhealthy</literal>” states. -</tag-desc> -<tag-name> -<literal>downstart</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The time when the server became “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”, in the ISO 8601 format with millisecond resolution. -</tag-desc> -<tag-name> -<literal>selected</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The time when the server was last selected to process a request, in the ISO 8601 format with millisecond resolution. -</tag-desc> -<tag-name> -<literal>header_time</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The average time to get the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</link> from the server. -</tag-desc> -<tag-name> -<literal>response_time</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The average time to get the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</link> from the server. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>keepalive</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of idle <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</link> connections. -</tag-desc> -<tag-name> -<literal>zombies</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of servers removed from the group but still processing active client requests. -</tag-desc> -<tag-name> -<literal>zone</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The name of the shared memory <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</link> that keeps the group’s configuration and run-time state. -</tag-desc> -<tag-name> -<literal>queue</literal></tag-name> -<tag-desc> -For the requests <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</link>, the following data are provided:<list type="tag"> -<tag-name> -<literal>size</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of requests in the queue. -</tag-desc> -<tag-name> -<literal>max_size</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The maximum number of requests that can be in the queue at the same time. -</tag-desc> -<tag-name> -<literal>overflows</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests rejected due to the queue overflow. -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "upstream_backend" : { - "peers" : [ - { - "id" : 0, - "server" : "10.0.0.1:8088", - "name" : "10.0.0.1:8088", - "backup" : false, - "weight" : 5, - "state" : "up", - "active" : 0, - "ssl" : { - "handshakes" : 620311, - "handshakes_failed" : 3432, - "session_reuses" : 36442, - "no_common_protocol" : 4, - "handshake_timeout" : 0, - "peer_rejected_cert" : 0, - "verify_failures" : { - "expired_cert" : 2, - "revoked_cert" : 1, - "hostname_mismatch" : 2, - "other" : 1 - } - }, - "max_conns" : 20, - "requests" : 667231, - "header_time" : 20, - "response_time" : 36, - "responses" : { - "1xx" : 0, - "2xx" : 666310, - "3xx" : 0, - "4xx" : 915, - "5xx" : 6, - "codes" : { - "200" : 666310, - "404" : 915, - "503" : 6 - }, - "total" : 667231 - }, - "sent" : 251946292, - "received" : 19222475454, - "fails" : 0, - "unavail" : 0, - "health_checks" : { - "checks" : 26214, - "fails" : 0, - "unhealthy" : 0, - "last_passed" : true - }, - "downtime" : 0, - "downstart" : "2022-06-28T11:09:21.602Z", - "selected" : "2022-06-28T15:01:25.000Z" - }, - { - "id" : 1, - "server" : "10.0.0.1:8089", - "name" : "10.0.0.1:8089", - "backup" : true, - "weight" : 1, - "state" : "unhealthy", - "active" : 0, - "max_conns" : 20, - "requests" : 0, - "responses" : { - "1xx" : 0, - "2xx" : 0, - "3xx" : 0, - "4xx" : 0, - "5xx" : 0, - "codes" : { - }, - "total" : 0 - }, - "sent" : 0, - "received" : 0, - "fails" : 0, - "unavail" : 0, - "health_checks" : { - "checks" : 26284, - "fails" : 26284, - "unhealthy" : 1, - "last_passed" : false - }, - "downtime" : 262925617, - "downstart" : "2022-06-28T11:09:21.602Z", - "selected" : "2022-06-28T15:01:25.000Z" - } - ], - "keepalive" : 0, - "zombies" : 0, - "zone" : "upstream_backend" - } -}</example> -</listitem> -<listitem id="def_nginx_http_upstream_conf_server"> -<para>HTTP Upstream Server:</para> -Dynamically configurable parameters of an HTTP upstream -<link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</link>:<list type="tag"> -<tag-name> -<literal>id</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the HTTP upstream server. The ID is assigned automatically and cannot be changed. -</tag-desc> -<tag-name> -<literal>server</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</link> parameter of the HTTP upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</link> directive in the “<literal>http</literal>” block. See also the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>service</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</link> parameter of the HTTP upstream server. This parameter cannot be changed. -</tag-desc> -<tag-name> -<literal>weight</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">weight</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>max_conns</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>max_fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>fail_timeout</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout">fail_timeout</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>slow_start</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start">slow_start</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>route</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#route">route</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>backup</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -When <literal>true</literal>, adds a <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</link> server. This parameter cannot be changed. -</tag-desc> -<tag-name> -<literal>down</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>drain</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#drain">drain</link> parameter of the HTTP upstream server. -</tag-desc> -<tag-name> -<literal>parent</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed. -</tag-desc> -<tag-name> -<literal>host</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Hostname of the resolved server. The hostname is assigned automatically and cannot be changed. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "id" : 1, - "server" : "10.0.0.1:8089", - "weight" : 4, - "max_conns" : 0, - "max_fails" : 0, - "fail_timeout" : "10s", - "slow_start" : "10s", - "route" : "", - "backup" : true, - "down" : true -}</example> -</listitem> -<listitem id="def_nginx_http_keyval_zone"> -<para>HTTP Keyval Shared Memory Zone:</para> -Contents of an HTTP keyval shared memory zone -when using the GET method.<para>Example:</para> -<example> -{ - "key1" : "value1", - "key2" : "value2", - "key3" : "value3" -}</example> -</listitem> -<listitem id="def_nginx_http_keyval_zone_post_patch"> -<para>HTTP Keyval Shared Memory Zone:</para> -Contents of an HTTP keyval shared memory zone -when using the POST or PATCH methods.<para>Example:</para> -<example> -{ - "key1" : "value1", - "key2" : "value2", - "key3" : { - "value" : "value3", - "expire" : 30000 - } -}</example> -</listitem> -<listitem id="def_nginx_stream_server_zone"> -<para>Stream Server Zone:</para> -<list type="tag"> -<tag-name> -<literal>processing</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of client connections that are currently being processed. -</tag-desc> -<tag-name> -<literal>connections</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections accepted from clients. -</tag-desc> -<tag-name> -<literal>sessions</literal></tag-name> -<tag-desc> -The total number of completed sessions, and the number of sessions completed with status codes “<literal>2xx</literal>”, “<literal>4xx</literal>”, or “<literal>5xx</literal>”.<list type="tag"> -<tag-name> -<literal>2xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of sessions completed with <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> “<literal>2xx</literal>”. -</tag-desc> -<tag-name> -<literal>4xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of sessions completed with <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> “<literal>4xx</literal>”. -</tag-desc> -<tag-name> -<literal>5xx</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of sessions completed with <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</link> “<literal>5xx</literal>”. -</tag-desc> -<tag-name> -<literal>total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of completed client sessions. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>discarded</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections completed without creating a session. -</tag-desc> -<tag-name> -<literal>received</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes received from clients. -</tag-desc> -<tag-name> -<literal>sent</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes sent to clients. -</tag-desc> -<tag-name> -<literal>ssl</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>handshakes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of successful SSL handshakes. -</tag-desc> -<tag-name> -<literal>handshakes_failed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of failed SSL handshakes. -</tag-desc> -<tag-name> -<literal>session_reuses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of session reuses during SSL handshake. -</tag-desc> -<tag-name> -<literal>no_common_protocol</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no common protocol. -</tag-desc> -<tag-name> -<literal>no_common_cipher</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no shared cipher. -</tag-desc> -<tag-name> -<literal>handshake_timeout</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of a timeout. -</tag-desc> -<tag-name> -<literal>peer_rejected_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed SSL handshakes when nginx presented the certificate to the client but it was rejected with a corresponding alert message. -</tag-desc> -<tag-name> -<literal>verify_failures</literal></tag-name> -<tag-desc> -SSL certificate verification errors<list type="tag"> -<tag-name> -<literal>no_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A client did not provide the required certificate. -</tag-desc> -<tag-name> -<literal>expired_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -An expired or not yet valid certificate was presented by a client. -</tag-desc> -<tag-name> -<literal>revoked_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A revoked certificate was presented by a client. -</tag-desc> -<tag-name> -<literal>other</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Other SSL certificate verification errors. -</tag-desc> -</list> -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "dns" : { - "processing" : 1, - "connections" : 155569, - "sessions" : { - "2xx" : 155564, - "4xx" : 0, - "5xx" : 0, - "total" : 155569 - }, - "discarded" : 0, - "received" : 4200363, - "sent" : 20489184, - "ssl" : { - "handshakes" : 76455, - "handshakes_failed" : 432, - "session_reuses" : 28770, - "no_common_protocol" : 4, - "no_common_cipher" : 2, - "handshake_timeout" : 0, - "peer_rejected_cert" : 0, - "verify_failures" : { - "no_cert" : 0, - "expired_cert" : 2, - "revoked_cert" : 1, - "other" : 1 - } - } - } -}</example> -</listitem> -<listitem id="def_nginx_stream_limit_conn_zone"> -<para>Stream Connections Limiting:</para> -<list type="tag"> -<tag-name> -<literal>passed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections that were neither limited nor accounted as limited. -</tag-desc> -<tag-name> -<literal>rejected</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections that were rejected. -</tag-desc> -<tag-name> -<literal>rejected_dry_run</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "passed" : 15, - "rejected" : 0, - "rejected_dry_run" : 2 -}</example> -</listitem> -<listitem id="def_nginx_stream_upstream"> -<para>Stream Upstream:</para> -<list type="tag"> -<tag-name> -<literal>peers</literal></tag-name> -<tag-desc> -An array of:<list type="tag"> -<tag-name> -<literal>id</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the server. -</tag-desc> -<tag-name> -<literal>server</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -An <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</link> of the server. -</tag-desc> -<tag-name> -<literal>service</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</link> parameter value of the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link> directive. -</tag-desc> -<tag-name> -<literal>name</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The name of the server specified in the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link> directive. -</tag-desc> -<tag-name> -<literal>backup</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -A boolean value indicating whether the server is a <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</link> server. -</tag-desc> -<tag-name> -<literal>weight</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -<link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</link> of the server. -</tag-desc> -<tag-name> -<literal>state</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Current state, which may be one of “<literal>up</literal>”, “<literal>down</literal>”, “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”. -</tag-desc> -<tag-name> -<literal>active</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of connections. -</tag-desc> -<tag-name> -<literal>ssl</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>handshakes</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of successful SSL handshakes. -</tag-desc> -<tag-name> -<literal>handshakes_failed</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of failed SSL handshakes. -</tag-desc> -<tag-name> -<literal>session_reuses</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of session reuses during SSL handshake. -</tag-desc> -<tag-name> -<literal>no_common_protocol</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of no common protocol. -</tag-desc> -<tag-name> -<literal>handshake_timeout</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of SSL handshakes failed because of a timeout. -</tag-desc> -<tag-name> -<literal>peer_rejected_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message. -</tag-desc> -<tag-name> -<literal>verify_failures</literal></tag-name> -<tag-desc> -SSL certificate verification errors<list type="tag"> -<tag-name> -<literal>expired_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -An expired or not yet valid certificate was presented by an upstream server. -</tag-desc> -<tag-name> -<literal>revoked_cert</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -A revoked certificate was presented by an upstream server. -</tag-desc> -<tag-name> -<literal>hostname_mismatch</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Server's certificate doesn't match the hostname. -</tag-desc> -<tag-name> -<literal>other</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Other SSL certificate verification errors. -</tag-desc> -</list> -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>max_conns</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</link> limit for the server. -</tag-desc> -<tag-name> -<literal>connections</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client connections forwarded to this server. -</tag-desc> -<tag-name> -<literal>connect_time</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The average time to connect to the upstream server. -</tag-desc> -<tag-name> -<literal>first_byte_time</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The average time to receive the first byte of data. -</tag-desc> -<tag-name> -<literal>response_time</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The average time to receive the last byte of data. -</tag-desc> -<tag-name> -<literal>sent</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes sent to this server. -</tag-desc> -<tag-name> -<literal>received</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of bytes received from this server. -</tag-desc> -<tag-name> -<literal>fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of unsuccessful attempts to communicate with the server. -</tag-desc> -<tag-name> -<literal>unavail</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -How many times the server became unavailable for client connections (state “<literal>unavail</literal>”) due to the number of unsuccessful attempts reaching the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</link> threshold. -</tag-desc> -<tag-name> -<literal>health_checks</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>checks</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check">health check</link> requests made. -</tag-desc> -<tag-name> -<literal>fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of failed health checks. -</tag-desc> -<tag-name> -<literal>unhealthy</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -How many times the server became unhealthy (state “<literal>unhealthy</literal>”). -</tag-desc> -<tag-name> -<literal>last_passed</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -Boolean indicating whether the last health check request was successful and passed <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match">tests</link>. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>downtime</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Total time the server was in the “<literal>unavail</literal>”, “<literal>checking</literal>”, and “<literal>unhealthy</literal>” states. -</tag-desc> -<tag-name> -<literal>downstart</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The time when the server became “<literal>unavail</literal>”, “<literal>checking</literal>”, or “<literal>unhealthy</literal>”, in the ISO 8601 format with millisecond resolution. -</tag-desc> -<tag-name> -<literal>selected</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The time when the server was last selected to process a connection, in the ISO 8601 format with millisecond resolution. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>zombies</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of servers removed from the group but still processing active client connections. -</tag-desc> -<tag-name> -<literal>zone</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The name of the shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone">zone</link> that keeps the group’s configuration and run-time state. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "dns" : { - "peers" : [ - { - "id" : 0, - "server" : "10.0.0.1:12347", - "name" : "10.0.0.1:12347", - "backup" : false, - "weight" : 5, - "state" : "up", - "active" : 0, - "ssl" : { - "handshakes" : 200, - "handshakes_failed" : 4, - "session_reuses" : 189, - "no_common_protocol" : 4, - "handshake_timeout" : 0, - "peer_rejected_cert" : 0, - "verify_failures" : { - "expired_cert" : 2, - "revoked_cert" : 1, - "hostname_mismatch" : 2, - "other" : 1 - } - }, - "max_conns" : 50, - "connections" : 667231, - "sent" : 251946292, - "received" : 19222475454, - "fails" : 0, - "unavail" : 0, - "health_checks" : { - "checks" : 26214, - "fails" : 0, - "unhealthy" : 0, - "last_passed" : true - }, - "downtime" : 0, - "downstart" : "2022-06-28T11:09:21.602Z", - "selected" : "2022-06-28T15:01:25.000Z" - }, - { - "id" : 1, - "server" : "10.0.0.1:12348", - "name" : "10.0.0.1:12348", - "backup" : true, - "weight" : 1, - "state" : "unhealthy", - "active" : 0, - "max_conns" : 50, - "connections" : 0, - "sent" : 0, - "received" : 0, - "fails" : 0, - "unavail" : 0, - "health_checks" : { - "checks" : 26284, - "fails" : 26284, - "unhealthy" : 1, - "last_passed" : false - }, - "downtime" : 262925617, - "downstart" : "2022-06-28T11:09:21.602Z", - "selected" : "2022-06-28T15:01:25.000Z" - } - ], - "zombies" : 0, - "zone" : "dns" - } -}</example> -</listitem> -<listitem id="def_nginx_stream_upstream_conf_server"> -<para>Stream Upstream Server:</para> -Dynamically configurable parameters of a stream upstream -<link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</link>:<list type="tag"> -<tag-name> -<literal>id</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the stream upstream server. The ID is assigned automatically and cannot be changed. -</tag-desc> -<tag-name> -<literal>server</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</link> parameter of the stream upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</link> directive in the “<literal>stream</literal>” block. See also the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>service</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</link> parameter of the stream upstream server. This parameter cannot be changed. -</tag-desc> -<tag-name> -<literal>weight</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>max_conns</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>max_fails</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>fail_timeout</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>slow_start</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>backup</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -When <literal>true</literal>, adds a <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</link> server. This parameter cannot be changed. -</tag-desc> -<tag-name> -<literal>down</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -Same as the <link url="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</link> parameter of the stream upstream server. -</tag-desc> -<tag-name> -<literal>parent</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed. -</tag-desc> -<tag-name> -<literal>host</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Hostname of the resolved server. The hostname is assigned automatically and cannot be changed. -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "id" : 0, - "server" : "10.0.0.1:12348", - "weight" : 1, - "max_conns" : 0, - "max_fails" : 1, - "fail_timeout" : "10s", - "slow_start" : 0, - "backup" : false, - "down" : false -}</example> -</listitem> -<listitem id="def_nginx_stream_keyval_zone"> -<para>Stream Keyval Shared Memory Zone:</para> -Contents of a stream keyval shared memory zone when using the GET method.<para>Example:</para> -<example> -{ - "key1" : "value1", - "key2" : "value2", - "key3" : "value3" -}</example> -</listitem> -<listitem id="def_nginx_stream_keyval_zone_post_patch"> -<para>Stream Keyval Shared Memory Zone:</para> -Contents of a stream keyval shared memory zone -when using the POST or PATCH methods.<para>Example:</para> -<example> -{ - "key1" : "value1", - "key2" : "value2", - "key3" : { - "value" : "value3", - "expire" : 30000 - } -}</example> -</listitem> -<listitem id="def_nginx_stream_zone_sync"> -<para>Stream Zone Sync Node:</para> -<list type="tag"> -<tag-name> -<literal>zones</literal></tag-name> -<tag-desc> -<para>Synchronization information per each shared memory zone.</para><para>A collection of "<link id="def_nginx_stream_zone_sync_zone">Sync Zone</link>" objects</para> -</tag-desc> -<tag-name> -<literal>status</literal></tag-name> -<tag-desc> -Synchronization information per node in a cluster.<list type="tag"> -<tag-name> -<literal>bytes_in</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of bytes received by this node. -</tag-desc> -<tag-name> -<literal>msgs_in</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of messages received by this node. -</tag-desc> -<tag-name> -<literal>msgs_out</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of messages sent by this node. -</tag-desc> -<tag-name> -<literal>bytes_out</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of bytes sent by this node. -</tag-desc> -<tag-name> -<literal>nodes_online</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of peers this node is connected to. -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "zones" : { - "zone1" : { - "records_pending" : 2061, - "records_total" : 260575 - }, - "zone2" : { - "records_pending" : 0, - "records_total" : 14749 - } - }, - "status" : { - "bytes_in" : 1364923761, - "msgs_in" : 337236, - "msgs_out" : 346717, - "bytes_out" : 1402765472, - "nodes_online" : 15 - } -}</example> -</listitem> -<listitem id="def_nginx_stream_zone_sync_zone"> -<para>Sync Zone:</para> -Synchronization status of a shared memory zone.<list type="tag"> -<tag-name> -<literal>records_pending</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of records that need to be sent to the cluster. -</tag-desc> -<tag-name> -<literal>records_total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of records stored in the shared memory zone. -</tag-desc> -</list> -</listitem> -<listitem id="def_nginx_resolver_zone"> -<para>Resolver Zone:</para> -Statistics of DNS requests and responses per particular -<link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</link>.<list type="tag"> -<tag-name> -<literal>requests</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>name</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests to resolve names to addresses. -</tag-desc> -<tag-name> -<literal>srv</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests to resolve SRV records. -</tag-desc> -<tag-name> -<literal>addr</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests to resolve addresses to names. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>responses</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>noerror</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of successful responses. -</tag-desc> -<tag-name> -<literal>formerr</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of FORMERR (<literal>Format error</literal>) responses. -</tag-desc> -<tag-name> -<literal>servfail</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of SERVFAIL (<literal>Server failure</literal>) responses. -</tag-desc> -<tag-name> -<literal>nxdomain</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of NXDOMAIN (<literal>Host not found</literal>) responses. -</tag-desc> -<tag-name> -<literal>notimp</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of NOTIMP (<literal>Unimplemented</literal>) responses. -</tag-desc> -<tag-name> -<literal>refused</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of REFUSED (<literal>Operation refused</literal>) responses. -</tag-desc> -<tag-name> -<literal>timedout</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of timed out requests. -</tag-desc> -<tag-name> -<literal>unknown</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of requests completed with an unknown error. -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "resolver_zone1" : { - "requests" : { - "name" : 25460, - "srv" : 130, - "addr" : 2580 - }, - "responses" : { - "noerror" : 26499, - "formerr" : 0, - "servfail" : 3, - "nxdomain" : 0, - "notimp" : 0, - "refused" : 0, - "timedout" : 243, - "unknown" : 478 - } - } -}</example> -</listitem> -<listitem id="def_nginx_worker"> -<para>Worker process:</para> -Statistics per each worker process.<list type="tag"> -<tag-name> -<literal>id</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The ID of the worker process. -</tag-desc> -<tag-name> -<literal>pid</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The PID identifier of the worker process used by the operating system. -</tag-desc> -<tag-name> -<literal>connections</literal></tag-name> -<tag-desc> -The number of accepted, dropped, active, and idle connections -per worker process.<list type="tag"> -<tag-name> -<literal>accepted</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client connections -accepted by the worker process. -</tag-desc> -<tag-name> -<literal>dropped</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client connections -dropped by the worker process. -</tag-desc> -<tag-name> -<literal>active</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of active client connections -that are currently being handled by the worker process. -</tag-desc> -<tag-name> -<literal>idle</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The number of idle client connections -that are currently being handled by the worker process. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>http</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>requests</literal></tag-name> -<tag-desc> -The total number of client requests handled by the worker process.<list type="tag"> -<tag-name> -<literal>total</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The total number of client requests received by the worker process. -</tag-desc> -<tag-name> -<literal>current</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -The current number of client requests that are currently being processed by the worker process. -</tag-desc> -</list> -</tag-desc> -</list> -</tag-desc> -</list> -<para>Example:</para> -<example> -{ - "id" : 0, - "pid" : 32212, - "connections" : { - "accepted" : 1, - "dropped" : 0, - "active" : 1, - "idle" : 0 - }, - "http" : { - "requests" : { - "total" : 15, - "current" : 1 - } - } -}</example> -</listitem> -<listitem id="def_nginx_error"> -<para>Error:</para> -nginx error object.<list type="tag"> -<tag-name> -<literal>error</literal></tag-name> -<tag-desc> -<list type="tag"> -<tag-name> -<literal>status</literal> (<literal>integer</literal>) -</tag-name> -<tag-desc> -HTTP error code. -</tag-desc> -<tag-name> -<literal>text</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Error description. -</tag-desc> -<tag-name> -<literal>code</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Internal nginx error code. -</tag-desc> -</list> -</tag-desc> -<tag-name> -<literal>request_id</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -The ID of the request, equals the value of the <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</link> variable. -</tag-desc> -<tag-name> -<literal>href</literal> (<literal>string</literal>) -</tag-name> -<tag-desc> -Link to reference documentation. -</tag-desc> -</list> -</listitem> -</list> -</para> -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_api_module_head.xml +++ /dev/null @@ -1,302 +0,0 @@ -<?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="4"> - -<section id="summary"> - -<para> -The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API -for accessing various status information, -configuring upstream server groups on-the-fly, and managing -<link doc="ngx_http_keyval_module.xml">key-value pairs</link> -without the need of reconfiguring nginx. -</para> - -<para> -<note> -The module supersedes the -<link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and -<link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link> -modules. -</note> -</para> - -<para> -When using the <literal>PATCH</literal> or <literal>POST</literal> methods, -make sure that the payload does not exceed the -<link doc="ngx_http_core_module.xml" id="client_body_buffer_size">buffer size</link> -for reading the client request body, otherwise, the -<http-status code="413" text="Request Entity Too Large"/> -error may be returned. -</para> - -<para> -<note> -This module is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -http { - upstream backend { - zone http_backend 64k; - - server backend1.example.com weight=5; - server backend2.example.com; - } - - proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m; - - server { - server_name backend.example.com; - - location / { - proxy_pass http://backend; - proxy_cache cache_backend; - - health_check; - } - - status_zone server_backend; - } - - keyval_zone zone=one:32k state=one.keyval; - keyval $arg_text $text zone=one; - - server { - listen 127.0.0.1; - - location /api { - <emphasis>api</emphasis> write=on; - allow 127.0.0.1; - deny all; - } - } -} - -stream { - upstream backend { - zone stream_backend 64k; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345; - } - - server { - listen 127.0.0.1:12345; - proxy_pass backend; - status_zone server_backend; - health_check; - } -} -</example> -All API requests include -a supported API <link id="api_version">version</link> in the URI. -Examples of API requests with this configuration: -<example> -http://127.0.0.1/api/9/ -http://127.0.0.1/api/9/nginx -http://127.0.0.1/api/9/connections -http://127.0.0.1/api/9/workers -http://127.0.0.1/api/9/http/requests -http://127.0.0.1/api/9/http/server_zones/server_backend -http://127.0.0.1/api/9/http/caches/cache_backend -http://127.0.0.1/api/9/http/upstreams/backend -http://127.0.0.1/api/9/http/upstreams/backend/servers/ -http://127.0.0.1/api/9/http/upstreams/backend/servers/1 -http://127.0.0.1/api/9/http/keyvals/one?key=arg1 -http://127.0.0.1/api/9/stream/ -http://127.0.0.1/api/9/stream/server_zones/server_backend -http://127.0.0.1/api/9/stream/upstreams/ -http://127.0.0.1/api/9/stream/upstreams/backend -http://127.0.0.1/api/9/stream/upstreams/backend/servers/1 -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="api"> -<syntax> -[<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> -<default/> -<context>location</context> - -<para> -Turns on the REST API interface in the surrounding location. -Access to this location should be -<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. -</para> - -<para> -The <literal>write</literal> parameter determines whether the API -is read-only or read-write. -By default, the API is read-only. -</para> - -<para id="api_version"> -All API requests should contain a supported API version in the URI. -If the request URI equals the location prefix, -the list of supported API versions is returned. -The current API version is “<literal>9</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/9/nginx?fields=version,build -</example> -</para> - -</directive> - - -<directive name="status_zone"> -<syntax><value>zone</value></syntax> -<default/> -<context>server</context> -<context>location</context> -<context>if in location</context> -<appeared-in>1.13.12</appeared-in> - -<para> -Enables collection of virtual -<link doc="ngx_http_core_module.xml" id="server">http</link> -or -<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> -server status information in the specified <value>zone</value>. -Several servers may share the same zone. -</para> - -<para id="status_zone_location"> -Starting from 1.17.0, status information can be collected -per <link doc="ngx_http_core_module.xml" id="location"/>. -The special value <literal>off</literal> disables statistics collection -in nested location blocks. -Note that the statistics is collected -in the context of a location where processing ends. -It may be different from the original location, if an -<link doc="ngx_http_core_module.xml" id="internal">internal -redirect</link> happens during request processing. -</para> - -</directive> - -</section> - -<section id="compatibility" name="Compatibility"> - -<para> -<list type="bullet"> - -<listitem> -The <link id="workers_">/workers/</link> data -were added in <link id="api_version">version</link> 9. -</listitem> - -<listitem> -Detailed failure counters were added to SSL statistics -in <link id="api_version">version</link> 8 (1.23.2). -</listitem> - -<listitem> -The <literal>ssl</literal> data -for each HTTP -<link id="def_nginx_http_upstream">upstream</link>, -<link id="def_nginx_http_server_zone">server zone</link>, -and stream -<link id="def_nginx_stream_upstream">upstream</link>, -<link id="def_nginx_stream_server_zone">server zone</link>, -were added in <link id="api_version">version</link> 8 (1.21.6). -</listitem> - -<listitem> -The <literal>codes</literal> data -in <literal>responses</literal> for each HTTP -<link id="def_nginx_http_upstream">upstream</link>, -<link id="def_nginx_http_server_zone">server zone</link>, and -<link id="def_nginx_http_location_zone">location zone</link> -were added in <link id="api_version">version</link> 7. -</listitem> - -<listitem> -The <link id="stream_limit_conns_">/stream/limit_conns/</link> data -were added in <link id="api_version">version</link> 6. -</listitem> - -<listitem> -The <link id="http_limit_conns_">/http/limit_conns/</link> data -were added in <link id="api_version">version</link> 6. -</listitem> - -<listitem> -The <link id="http_limit_reqs_">/http/limit_reqs/</link> data -were added in <link id="api_version">version</link> 6. -</listitem> - -<listitem> -The “<literal>expire</literal>” parameter of a -<link doc="ngx_http_keyval_module.xml">key-value</link> pair can be -<link id="postHttpKeyvalZoneData">set</link> or -<link id="patchHttpKeyvalZoneKeyValue">changed</link> -since <link id="api_version">version</link> 5. -</listitem> - -<listitem> -The <link id="resolvers_">/resolvers/</link> data -were added in <link id="api_version">version</link> 5. -</listitem> - -<listitem> -The <link id="http_location_zones_">/http/location_zones/</link> data -were added in <link id="api_version">version</link> 5. -</listitem> - -<listitem> -The <literal>path</literal> and <literal>method</literal> fields of -<link id="def_nginx_error">nginx error object</link> -were removed in <link id="api_version">version</link> 4. -These fields continue to exist in earlier api versions, -but show an empty value. -</listitem> - -<listitem> -The <link id="stream_zone_sync_">/stream/zone_sync/</link> data -were added in <link id="api_version">version</link> 3. -</listitem> - -<listitem> -The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter -was added in <link id="api_version">version</link> 2. -</listitem> - -<listitem> -The <link id="stream_keyvals_">/stream/keyvals/</link> data -were added in <link id="api_version">version</link> 2. -</listitem> - -</list> -</para> - -</section> - -</module>
--- a/xml/en/docs/http/ngx_http_auth_basic_module.xml +++ b/xml/en/docs/http/ngx_http_auth_basic_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_auth_basic_module" link="/en/docs/http/ngx_http_auth_basic_module.html" lang="en" - rev="10"> + rev="11"> <section id="summary"> @@ -22,9 +22,8 @@ using the “HTTP Basic Authentication” protocol. <para> Access can also be limited by -<link doc="ngx_http_access_module.xml">address</link>, by the -<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>, -or by <link doc="ngx_http_auth_jwt_module.xml">JWT</link>. +<link doc="ngx_http_access_module.xml">address</link> or by the +<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>. Simultaneous limitation of access by address and by password is controlled by the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive. </para>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_auth_jwt_module.xml +++ /dev/null @@ -1,461 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_auth_jwt_module" - link="/en/docs/http/ngx_http_auth_jwt_module.html" - lang="en" - rev="12"> - -<section id="summary"> - -<para> -The <literal>ngx_http_auth_jwt_module</literal> module (1.11.3) -implements client authorization by validating the provided -<link url="https://datatracker.ietf.org/doc/html/rfc7519">JSON Web Token</link> (JWT) -using the specified keys. -The module supports -<link url="https://datatracker.ietf.org/doc/html/rfc7515">JSON Web Signature</link> (JWS), -<link url="https://datatracker.ietf.org/doc/html/rfc7516">JSON Web Encryption</link> (JWE) -(1.19.7), and Nested JWT (1.21.0). -The module can be used for -<link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link> -authentication. -</para> - -<para> -The module may be combined with -other access modules, such as -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, -and -<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>, -via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive. -</para> - -<para> -<note> -This module is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</section> - - -<section id="algorithms" name="Supported Algorithms"> - -<para> -The module supports the following JSON Web -<link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">Algorithms</link>. -</para> - -<para> -JWS algorithms: -<list type="bullet"> - -<listitem> -HS256, HS384, HS512 -</listitem> - -<listitem> -RS256, RS384, RS512 -</listitem> - -<listitem> -ES256, ES384, ES512 -</listitem> - -<listitem> -EdDSA (Ed25519 and Ed448 signatures) (1.15.7) -</listitem> - -</list> - -<note> -Prior to version 1.13.7, -only HS256, RS256, ES256 algorithms were supported. -</note> -</para> - -<para> -JWE content encryption algorithms (1.19.7): -<list type="bullet"> - -<listitem> -A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 -</listitem> - -<listitem> -A128GCM, A192GCM, A256GCM -</listitem> - -</list> -</para> - -<para> -JWE key management algorithms (1.19.9): -<list type="bullet"> - -<listitem> -A128KW, A192KW, A256KW -</listitem> - -<listitem> -A128GCMKW, A192GCMKW, A256GCMKW -</listitem> - -<listitem> -dir—direct use of a shared symmetric key as the content encryption key -</listitem> - -<listitem> -RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0) -</listitem> - -</list> -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -location / { - auth_jwt "closed site"; - auth_jwt_key_file conf/keys.json; -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="auth_jwt"> -<syntax> - <value>string</value> - [<literal>token=</literal><value>$variable</value>] | - <literal>off</literal></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> - -<para> -Enables validation of JSON Web Token. -The specified <value>string</value> is used as a <literal>realm</literal>. -Parameter value can contain variables. -</para> - -<para> -The optional <literal>token</literal> parameter specifies a variable -that contains JSON Web Token. -By default, JWT is passed in the <header>Authorization</header> header -as a -<link url="https://datatracker.ietf.org/doc/html/rfc6750">Bearer Token</link>. -JWT may be also passed as a cookie or a part of a query string: -<example> -auth_jwt "closed site" token=$cookie_auth_token; -</example> -</para> - -<para> -The special value <literal>off</literal> cancels the effect -of the <literal>auth_jwt</literal> directive -inherited from the previous configuration level. -</para> - -</directive> - - -<directive name="auth_jwt_claim_set"> -<syntax><value>$variable</value> <value>name</value> ...</syntax> -<default/> -<context>http</context> -<appeared-in>1.11.10</appeared-in> - -<para> -Sets the <value>variable</value> to a JWT claim parameter -identified by key names. -Name matching starts from the top level of the JSON tree. -For arrays, the variable keeps a list of array elements separated by commas. -<example> -auth_jwt_claim_set $email info e-mail; -auth_jwt_claim_set $job info "job title"; -</example> -<note> -Prior to version 1.13.7, only one key name could be specified, -and the result was undefined for arrays. -</note> -</para> - -<para> -<note> -Variable values for tokens encrypted with JWE -are available only after decryption which occurs during the -<link doc="../dev/development_guide.xml" id="http_phases">Access</link> phase. -</note> -</para> - -</directive> - - -<directive name="auth_jwt_header_set"> -<syntax><value>$variable</value> <value>name</value> ...</syntax> -<default/> -<context>http</context> -<appeared-in>1.11.10</appeared-in> - -<para> -Sets the <value>variable</value> to a JOSE header parameter -identified by key names. -Name matching starts from the top level of the JSON tree. -For arrays, the variable keeps a list of array elements separated by commas. -<note> -Prior to version 1.13.7, only one key name could be specified, -and the result was undefined for arrays. -</note> -</para> - -</directive> - - -<directive name="auth_jwt_key_cache"> -<syntax><value>time</value></syntax> -<default>0</default> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.21.4</appeared-in> - -<para> -Enables or disables caching of keys -obtained from a <link id="auth_jwt_key_file">file</link> -or from a <link id="auth_jwt_key_request">subrequest</link>, -and sets caching time for them. -Caching of keys obtained from variables is not supported. -By default, caching of keys is disabled. -</para> - -</directive> - - -<directive name="auth_jwt_key_file"> -<syntax><value>file</value></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> - -<para> -Specifies a <value>file</value> in -<link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> -format for validating JWT signature. -Parameter value can contain variables. -</para> - -<para> -Several <literal>auth_jwt_key_file</literal> directives -can be specified on the same level (1.21.1): -<example> -auth_jwt_key_file conf/keys.json; -auth_jwt_key_file conf/key.jwk; -</example> -If at least one of the specified keys cannot be loaded or processed, -nginx will return the -<http-status code="500" text="Internal Server Error"/> error. -</para> - -</directive> - - -<directive name="auth_jwt_key_request"> -<syntax><value>uri</value></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> -<appeared-in>1.15.6</appeared-in> - -<para> -Allows retrieving a -<link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> -file from a subrequest for validating JWT signature and -sets the URI where the subrequest will be sent to. -Parameter value can contain variables. -To avoid validation overhead, -it is recommended to cache the key file: -<example> -proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m; - -server { - ... - - location / { - auth_jwt "closed site"; - auth_jwt_key_request /jwks_uri; - } - - location = /jwks_uri { - internal; - proxy_cache foo; - proxy_pass http://idp.example.com/keys; - } -} -</example> -Several <literal>auth_jwt_key_request</literal> directives -can be specified on the same level (1.21.1): -<example> -auth_jwt_key_request /jwks_uri; -auth_jwt_key_request /jwks2_uri; -</example> -If at least one of the specified keys cannot be loaded or processed, -nginx will return the -<http-status code="500" text="Internal Server Error"/> error. -</para> - -</directive> - - -<directive name="auth_jwt_leeway"> -<syntax><value>time</value></syntax> -<default>0s</default> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.13.10</appeared-in> - -<para> -Sets the maximum allowable leeway to compensate -clock skew when verifying the -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4">exp</link> -and -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5">nbf</link> -JWT claims. -</para> - -</directive> - - -<directive name="auth_jwt_type"> -<syntax><value>signed</value> | - <value>encrypted</value> | - <value>nested</value></syntax> -<default>signed</default> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> -<appeared-in>1.19.7</appeared-in> - -<para> -Specifies which type of JSON Web Token to expect: -JWS (<literal>signed</literal>), -JWE (<literal>encrypted</literal>), -or signed and then encrypted -Nested JWT (<literal>nested</literal>) (1.21.0). -</para> - -</directive> - - -<directive name="auth_jwt_require"> -<syntax> - <value>$value</value> ... - [<literal>error</literal>=<literal>401</literal> | - <literal>403</literal>] -</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> -<appeared-in>1.21.2</appeared-in> - -<para> -Specifies additional checks for JWT validation. -The value can contain text, variables, and their combination, -and must start with a variable (1.21.7). -The authentication will succeed only -if all the values are not empty and are not equal to “0”. -<example> -map $jwt_claim_iss $valid_jwt_iss { - "good" 1; -} -... - -auth_jwt_require $valid_jwt_iss; -</example> -</para> - -<para> -If any of the checks fails, -the <literal>401</literal> error code is returned. -The optional <literal>error</literal> parameter (1.21.7) -allows redefining the error code to <literal>403</literal>. -</para> - -</directive> - -</section> - - -<section id="variables" name="Embedded Variables"> - -<para> -The <literal>ngx_http_auth_jwt_module</literal> module -supports embedded variables: -</para> - -<para> -<list type="tag" compact="yes"> -<tag-name id="var_jwt_header_"><var>$jwt_header_</var><value>name</value></tag-name> -<tag-desc> -returns the value of a specified -<link url="https://datatracker.ietf.org/doc/html/rfc7515#section-4">JOSE header</link> -</tag-desc> - -<tag-name id="var_jwt_claim_"><var>$jwt_claim_</var><value>name</value></tag-name> -<tag-desc> -returns the value of a specified -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4">JWT claim</link> - -<para> -For nested claims and claims including a dot (“.”), -the value of the variable cannot be evaluated; -the <link id="auth_jwt_claim_set"/> directive should be used instead. -</para> - -<para> -Variable values for tokens encrypted with JWE -are available only after decryption which occurs during the -<link doc="../dev/development_guide.xml" id="http_phases">Access</link> phase. -</para> -</tag-desc> - -<tag-name id="var_jwt_payload"><var>$jwt_payload</var></tag-name> -<tag-desc> -returns the decrypted top-level payload -of <literal>nested</literal> -or <literal>encrypted</literal> tokens (1.21.2). -For nested tokens returns the enclosed JWS token. -For encrypted tokens returns JSON with claims. -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/en/docs/http/ngx_http_auth_request_module.xml +++ b/xml/en/docs/http/ngx_http_auth_request_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_auth_request_module" link="/en/docs/http/ngx_http_auth_request_module.html" lang="en" - rev="5"> + rev="6"> <section id="summary"> @@ -37,10 +37,8 @@ configuration parameter. <para> The module may be combined with other access modules, such as -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, +<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> and <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, -and -<link doc="ngx_http_auth_jwt_module.xml">ngx_http_auth_jwt_module</link>, via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive. <note> Before version 1.7.3, responses to authorization subrequests could not be cached
--- a/xml/en/docs/http/ngx_http_core_module.xml +++ b/xml/en/docs/http/ngx_http_core_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_core_module" link="/en/docs/http/ngx_http_core_module.html" lang="en" - rev="106"> + rev="107"> <section id="directives" name="Directives"> @@ -260,9 +260,8 @@ location /images/ { <para> Delays processing of unauthorized requests with 401 response code to prevent timing attacks when access is limited by -<link doc="ngx_http_auth_basic_module.xml">password</link>, by the -<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>, -or by <link doc="ngx_http_auth_jwt_module.xml">JWT</link>. +<link doc="ngx_http_auth_basic_module.xml">password</link> or by the +<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>. </para> </directive> @@ -855,7 +854,6 @@ Internal requests are the following: requests redirected by the <link id="error_page"/>, <link doc="ngx_http_index_module.xml" id="index"/>, -<link doc="ngx_http_internal_redirect_module.xml" id="internal_redirect"/>, <link doc="ngx_http_random_index_module.xml" id="random_index"/>, and <link id="try_files"/> directives; </listitem> @@ -1070,11 +1068,8 @@ or Allowing the <literal>GET</literal> method makes the <literal>HEAD</literal> method also allowed. Access to other methods can be limited using the -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, -and -<link doc="ngx_http_auth_jwt_module.xml">ngx_http_auth_jwt_module</link> -(1.13.10) +<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> and +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> modules directives: <example> limit_except GET { @@ -2186,8 +2181,7 @@ closed normally. <value>address</value> ... [<literal>valid</literal>=<value>time</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>zone</value>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <default/> <context>http</context> <context>server</context> @@ -2237,16 +2231,6 @@ configuring DNS servers in a properly se </note> </para> -<para id="resolver_status_zone"> -The optional <literal>status_zone</literal> parameter (1.17.1) -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>. -The parameter is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</para> - </directive> @@ -2314,9 +2298,8 @@ Allows access if all (<literal>all</lite (<literal>any</literal>) of the <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, -<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>, or -<link doc="ngx_http_auth_jwt_module.xml">ngx_http_auth_jwt_module</link> +<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link> modules allow access. </para> @@ -2667,8 +2650,7 @@ The details of setting up hash tables ar <syntax> <literal>on</literal> | <literal>off</literal> | - <literal>build</literal> | - <value>string</value></syntax> + <literal>build</literal></syntax> <default>on</default> <context>http</context> <context>server</context> @@ -2685,16 +2667,6 @@ a <link doc="../configure.xml" id="build along with nginx version. </para> -<para> -Additionally, as part of our -<commercial_version>commercial subscription</commercial_version>, -starting from version 1.9.13 -the signature on error pages and -the <header>Server</header> response header field value -can be set explicitly using the <value>string</value> with variables. -An empty string disables the emission of the <header>Server</header> field. -</para> - </directive>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_f4f_module.xml +++ /dev/null @@ -1,89 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_f4f_module" - link="/en/docs/http/ngx_http_f4f_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_http_f4f_module</literal> module provides -server-side support for Adobe HTTP Dynamic Streaming (HDS). -</para> - -<para> -This module implements handling of HTTP Dynamic Streaming requests in the -“<literal>/videoSeg1-Frag1</literal>” form — extracting the needed fragment -from the <path>videoSeg1.f4f</path> file using the <path>videoSeg1.f4x</path> -index file. -This module is an alternative to the Adobe’s f4f module (HTTP Origin Module) -for Apache. -</para> - -<para> -Usual pre-processing with Adobe’s f4fpackager is required, see relevant -documentation for details. -</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> -location /video/ { - f4f; - ... -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="f4f"> -<syntax/> -<default/> -<context>location</context> - -<para> -Turns on module processing in the surrounding location. -</para> - -</directive> - - -<directive name="f4f_buffer_size"> -<syntax><value>size</value></syntax> -<default>512k</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the <value>size</value> of the buffer used for -reading the <path>.f4x</path> index file. -</para> - -</directive> - -</section> - -</module>
--- a/xml/en/docs/http/ngx_http_fastcgi_module.xml +++ b/xml/en/docs/http/ngx_http_fastcgi_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_fastcgi_module" link="/en/docs/http/ngx_http_fastcgi_module.html" lang="en" - rev="53"> + rev="54"> <section id="summary"> @@ -392,11 +392,7 @@ will be cached. [<literal>manager_threshold</literal>=<value>time</value>] [<literal>loader_files</literal>=<value>number</value>] [<literal>loader_sleep</literal>=<value>time</value>] - [<literal>loader_threshold</literal>=<value>time</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>number</value>] - [<literal>purger_sleep</literal>=<value>time</value>] - [<literal>purger_threshold</literal>=<value>time</value>]</syntax> + [<literal>loader_threshold</literal>=<value>time</value>]</syntax> <default/> <context>http</context> @@ -442,15 +438,6 @@ In addition, all active keys and informa in a shared memory zone, whose <value>name</value> and <value>size</value> are configured by the <literal>keys_zone</literal> parameter. One megabyte zone can store about 8 thousand keys. -<note> -As part of -<commercial_version>commercial subscription</commercial_version>, -the shared memory zone also stores extended -cache <link doc="ngx_http_api_module.xml" id="http_caches_">information</link>, -thus, it is required to specify a larger zone size for the same number of keys. -For example, -one megabyte zone can store about 4 thousand keys. -</note> </para> <para> @@ -494,56 +481,6 @@ parameter (by default, 50 milliseconds) </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Instructs whether cache entries that match a -<link id="fastcgi_cache_purge">wildcard key</link> -will be removed from the disk by the cache purger (1.7.12). -Setting the parameter to <literal>on</literal> -(default is <literal>off</literal>) -will activate the “cache purger” process that -permanently iterates through all cache entries -and deletes the entries that match the wildcard key. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the number of items that will be scanned during one iteration (1.7.12). -By default, <literal>purger_files</literal> is set to 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the duration of one iteration (1.7.12). -By default, <literal>purger_threshold</literal> is set to 50 milliseconds. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets a pause between iterations (1.7.12). -By default, <literal>purger_sleep</literal> is set to 50 milliseconds. -</tag-desc> - -</list> -</para> - -<para> <note> In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid @@ -554,63 +491,6 @@ after upgrading to a newer nginx version </directive> -<directive name="fastcgi_cache_purge"> -<syntax>string ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Defines conditions under which the request will be considered a cache -purge request. -If at least one value of the string parameters is not empty and is not equal -to “0” then the cache entry with a corresponding -<link id="fastcgi_cache_key">cache key</link> is removed. -The result of successful operation is indicated by returning -the <http-status code="204" text="No Content"/> response. -</para> - -<para> -If the <link id="fastcgi_cache_key">cache key</link> of a purge request ends -with an asterisk (“<literal>*</literal>”), all cache entries matching the -wildcard key will be removed from the cache. -However, these entries will remain on the disk until they are deleted -for either <link id="fastcgi_cache_path">inactivity</link>, -or processed by the <link id="purger">cache purger</link> (1.7.12), -or a client attempts to access them. -</para> - -<para> -Example configuration: -<example> -fastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - fastcgi_pass backend; - fastcgi_cache cache_zone; - fastcgi_cache_key $uri; - fastcgi_cache_purge $purge_method; - } -} -</example> -<note> -This functionality is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="fastcgi_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_hls_module.xml +++ /dev/null @@ -1,278 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_hls_module" - link="/en/docs/http/ngx_http_hls_module.html" - lang="en" - rev="7"> - -<section id="summary"> - -<para> -The <literal>ngx_http_hls_module</literal> module provides HTTP Live Streaming -(HLS) server-side support for MP4 and MOV media files. -Such files typically have the <path>.mp4</path>, <path>.m4v</path>, -<path>.m4a</path>, <path>.mov</path>, or <path>.qt</path> filename extensions. -The module supports H.264 video codec, AAC and MP3 audio codecs. -</para> - -<para> -For each media file, two URIs are supported: -<list type="bullet"> - -<listitem> -A playlist URI with the “<literal>.m3u8</literal>” filename extension. -The URI can accept optional arguments: -<list type="bullet"> - -<listitem> -“<literal>start</literal>” and “<literal>end</literal>” -define playlist boundaries in seconds (1.9.0). -</listitem> - -<listitem> -“<literal>offset</literal>” shifts an initial playback position -to the time offset in seconds (1.9.0). -A positive value sets a time offset from the beginning of the playlist. -A negative value sets a time offset -from the end of the last fragment in the playlist. -</listitem> - -<listitem> -“<literal>len</literal>” defines the fragment length in seconds. -</listitem> -</list> - -</listitem> - -<listitem> -A fragment URI with the “<literal>.ts</literal>” filename extension. -The URI can accept optional arguments: -<list type="bullet"> - -<listitem> -“<literal>start</literal>” and “<literal>end</literal>” -define fragment boundaries in seconds. -</listitem> - -</list> -</listitem> - -</list> -</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> -location / { - hls; - hls_fragment 5s; - hls_buffers 10 10m; - hls_mp4_buffer_size 1m; - hls_mp4_max_buffer_size 5m; - root /var/video/; -} -</example> -With this configuration, the following URIs are supported for -the “<path>/var/video/test.mp4</path>” file: -<example> -http://hls.example.com/test.mp4.m3u8?offset=1.000&start=1.000&end=2.200 -http://hls.example.com/test.mp4.m3u8?len=8.000 -http://hls.example.com/test.mp4.ts?start=1.000&end=2.200 -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="hls"> -<syntax/> -<default/> -<context>location</context> - -<para> -Turns on HLS streaming in the surrounding location. -</para> - -</directive> - - -<directive name="hls_buffers"> -<syntax><value>number</value> <value>size</value></syntax> -<default>8 2m</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the maximum <value>number</value> and <value>size</value> of buffers -that are used for reading and writing data frames. -</para> - -</directive> - - -<directive name="hls_forward_args"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.12</appeared-in> - -<para> -Adds arguments from a playlist request to URIs of fragments. -This may be useful for performing client authorization at the moment of -requesting a fragment, or when protecting an HLS stream with the -<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link> -module. -</para> - -<para> -For example, if a client requests a playlist -<literal>http://example.com/hls/test.mp4.m3u8?a=1&b=2</literal>, -the arguments <literal>a=1</literal> and <literal>b=2</literal> -will be added to URIs of fragments after the arguments -<literal>start</literal> and <literal>end</literal>: -<example> -#EXTM3U -#EXT-X-VERSION:3 -#EXT-X-TARGETDURATION:15 -#EXT-X-PLAYLIST-TYPE:VOD - -#EXTINF:9.333, -test.mp4.ts?start=0.000&end=9.333&a=1&b=2 -#EXTINF:7.167, -test.mp4.ts?start=9.333&end=16.500&a=1&b=2 -#EXTINF:5.416, -test.mp4.ts?start=16.500&end=21.916&a=1&b=2 -#EXTINF:5.500, -test.mp4.ts?start=21.916&end=27.416&a=1&b=2 -#EXTINF:15.167, -test.mp4.ts?start=27.416&end=42.583&a=1&b=2 -#EXTINF:9.626, -test.mp4.ts?start=42.583&end=52.209&a=1&b=2 - -#EXT-X-ENDLIST -</example> -</para> - -<para> -If an HLS stream is protected with the -<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link> -module, <var>$uri</var> should not be used in the -<link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/> -expression because this will cause errors when requesting the fragments. -<link doc="ngx_http_map_module.xml" id="map">Base URI</link> should be used -instead of <var>$uri</var> -(<var>$hls_uri</var> in the example): -<example> -http { - ... - - map $uri $hls_uri { - ~^(?<base_uri>.*).m3u8$ $base_uri; - ~^(?<base_uri>.*).ts$ $base_uri; - default $uri; - } - - server { - ... - - location /hls/ { - hls; - hls_forward_args on; - - alias /var/videos/; - - secure_link $arg_md5,$arg_expires; - secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret"; - - if ($secure_link = "") { - return 403; - } - - if ($secure_link = "0") { - return 410; - } - } - } -} -</example> -</para> - -</directive> - - -<directive name="hls_fragment"> -<syntax><value>time</value></syntax> -<default>5s</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Defines the default fragment length for playlist URIs requested without the -“<literal>len</literal>” argument. -</para> - -</directive> - - -<directive name="hls_mp4_buffer_size"> -<syntax><value>size</value></syntax> -<default>512k</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the initial <value>size</value> of the buffer used for -processing MP4 and MOV files. -</para> - -</directive> - - -<directive name="hls_mp4_max_buffer_size"> -<syntax><value>size</value></syntax> -<default>10m</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -During metadata processing, a larger buffer may become necessary. -Its size cannot exceed the specified <value>size</value>, -or else nginx will return the server error -<http-status code="500" text="Internal Server Error"/>, -and log the following message: -<example> -"/some/movie/file.mp4" mp4 moov atom is too large: -12583268, you may want to increase hls_mp4_max_buffer_size -</example> -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_internal_redirect_module.xml +++ /dev/null @@ -1,97 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_internal_redirect_module" - link="/en/docs/http/ngx_http_internal_redirect_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_http_internal_redirect_module</literal> module (1.23.4) allows -making an internal redirect. -In contrast to -<link doc="ngx_http_rewrite_module.xml">rewriting URIs</link>, -the redirection is made after checking -<link doc="ngx_http_limit_req_module.xml">request</link> and -<link doc="ngx_http_limit_conn_module.xml">connection</link> processing limits, -and <link doc="ngx_http_access_module.xml">access</link> limits. -</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> -limit_req_zone $jwt_claim_sub zone=jwt_sub:10m rate=1r/s; - -server { - location / { - auth_jwt "realm"; - auth_jwt_key_file key.jwk; - - internal_redirect @rate_limited; - } - - location @rate_limited { - internal; - - limit_req zone=jwt_sub burst=10; - proxy_pass http://backend; - } -} -</example> -The example implements -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2">per-user</link> -<link doc="ngx_http_limit_req_module.xml">rate limiting</link>. -Implementation without <link id="internal_redirect">internal_redirect</link> -is vulnerable to DoS attacks by unsigned JWTs, as normally the -<link doc="ngx_http_limit_req_module.xml" id="limit_req">limit_req</link> -check is performed -<link doc="../dev/development_guide.xml" id="http_phases">before</link> -<link doc="ngx_http_auth_jwt_module.xml" id="auth_jwt">auth_jwt</link> check. -Using <link id="internal_redirect">internal_redirect</link> -allows reordering these checks. -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="internal_redirect"> -<syntax><value>uri</value></syntax> -<default/> -<context>server</context> -<context>location</context> - -<para> -Sets the URI for internal redirection of the request. -It is also possible to use a -<link doc="ngx_http_core_module.xml" id="location_named">named location</link> -instead of the URI. -The <value>uri</value> value can contain variables. -If the <value>uri</value> value is empty, -then the redirect will not be made. -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_keyval_module.xml +++ /dev/null @@ -1,178 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_keyval_module" - link="/en/docs/http/ngx_http_keyval_module.html" - lang="en" - rev="11"> - -<section id="summary"> - -<para> -The <literal>ngx_http_keyval_module</literal> module (1.13.3) creates variables -with values taken from key-value pairs managed by the -<link doc="ngx_http_api_module.xml" id="http_keyvals_">API</link> -or a variable (1.15.10) that can also be set with -<link url="https://github.com/nginx/njs-examples/#logging-the-number-of-requests-per-client-http-logging-num-requests">njs</link>. -</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 { - - keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; - keyval $arg_text $text zone=one; - ... - server { - ... - location / { - return 200 $text; - } - - location /api { - api write=on; - } - } -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="keyval"> -<syntax> - <value>key</value> - <value>$variable</value> - <literal>zone</literal>=<value>name</value></syntax> -<default/> -<context>http</context> - -<para> -Creates a new <value>$variable</value> whose value -is looked up by the <value>key</value> in the key-value database. -Matching rules are defined by the -<link id="keyval_type"><literal>type</literal></link> parameter of the -<link id="keyval_zone"><literal>keyval_zone</literal></link> directive. -The database is stored in a shared memory zone -specified by the <literal>zone</literal> parameter. -</para> - -</directive> - - -<directive name="keyval_zone"> -<syntax> - <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>prefix</literal>] - [<literal>sync</literal>]</syntax> -<default/> -<context>http</context> - -<para> -Sets the <value>name</value> and <value>size</value> of the shared memory zone -that keeps the key-value database. -Key-value pairs are managed by the -<link doc="ngx_http_api_module.xml" id="http_keyvals_">API</link>. -</para> - -<para id="keyval_state"> -The optional <literal>state</literal> parameter specifies a <value>file</value> -that keeps the current state of the key-value database in the JSON format -and makes it persistent across nginx restarts. -Changing the file content directly should be avoided. -</para> - -<para> -Examples: -<example> -keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; # path for Linux -keyval_zone zone=one:32k state=/var/db/nginx/state/one.keyval; # path for FreeBSD -</example> -</para> - -<para id="keyval_timeout"> -The optional <literal>timeout</literal> parameter (1.15.0) sets -the time after which key-value pairs are removed from the zone. -</para> - -<para id="keyval_type"> -The optional <literal>type</literal> parameter (1.17.1) activates -an extra index optimized for matching the key of a certain type -and defines matching rules when evaluating -a <link id="keyval">keyval</link> <literal>$variable</literal>. -<note> -The index is stored in the same shared memory zone -and thus requires additional storage. -</note> - -<list type="tag"> - -<tag-name id="keyval_type_string"><literal>type=string</literal></tag-name> -<tag-desc> -default, no index is enabled; -variable lookup is performed using exact match -of the record key and a search key -</tag-desc> - -<tag-name id="keyval_type_ip"><literal>type=ip</literal></tag-name> -<tag-desc> -the search key is the textual representation of IPv4 or IPv6 address -or CIDR range; -to match a record key, the search key must belong to a subnet -specified by a record key or exactly match an IP address -</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> - -<para id="keyval_sync"> -The optional <literal>sync</literal> parameter (1.15.0) enables -<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link> -of the shared memory zone. -The synchronization requires the -<literal>timeout</literal> parameter to be set. -<note> -If the synchronization is enabled, removal of key-value pairs (no matter -<link doc="ngx_http_api_module.xml" id="patchHttpKeyvalZoneKeyValue">one</link> -or -<link doc="ngx_http_api_module.xml" id="deleteHttpKeyvalZoneData">all</link>) -will be performed only on a target cluster node. -The same key-value pairs on other cluster nodes -will be removed upon <literal>timeout</literal>. -</note> -</para> - -</directive> - -</section> - -</module>
--- a/xml/en/docs/http/ngx_http_limit_conn_module.xml +++ b/xml/en/docs/http/ngx_http_limit_conn_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_limit_conn_module" link="/en/docs/http/ngx_http_limit_conn_module.html" lang="en" - rev="14"> + rev="15"> <section id="summary"> @@ -201,19 +201,6 @@ If the zone storage is exhausted, the se to all further requests. </para> -<para> -<note> -Additionally, as part of our -<commercial_version>commercial subscription</commercial_version>, -the -<link doc="ngx_http_api_module.xml" id="http_limit_conns_">status information</link> -for each such shared memory zone can be -<link doc="ngx_http_api_module.xml" id="getHttpLimitConnZone">obtained</link> or -<link doc="ngx_http_api_module.xml" id="deleteHttpLimitConnZoneStat">reset</link> -with the <link doc="ngx_http_api_module.xml">API</link> since 1.17.7. -</note> -</para> - </directive>
--- a/xml/en/docs/http/ngx_http_limit_req_module.xml +++ b/xml/en/docs/http/ngx_http_limit_req_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_limit_req_module" link="/en/docs/http/ngx_http_limit_req_module.html" lang="en" - rev="16"> + rev="17"> <section id="summary"> @@ -187,8 +187,7 @@ Sets the status code to return in respon <syntax> <value>key</value> <literal>zone</literal>=<value>name</value>:<value>size</value> - <literal>rate</literal>=<value>rate</value> - [<literal>sync</literal>]</syntax> + <literal>rate</literal>=<value>rate</value></syntax> <default/> <context>http</context> @@ -238,29 +237,6 @@ it is specified in request per minute (r For example, half-request per second is 30r/m. </para> -<para id="limit_req_zone_sync"> -The <literal>sync</literal> parameter (1.15.3) enables -<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link> -of the shared memory zone. -<note> -The <literal>sync</literal> parameter is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -<para> -<note> -Additionally, as part of our -<commercial_version>commercial subscription</commercial_version>, -the -<link doc="ngx_http_api_module.xml" id="http_limit_reqs_">status information</link> -for each such shared memory zone can be -<link doc="ngx_http_api_module.xml" id="getHttpLimitReqZone">obtained</link> or -<link doc="ngx_http_api_module.xml" id="deleteHttpLimitReqZoneStat">reset</link> -with the <link doc="ngx_http_api_module.xml">API</link> since 1.17.7. -</note> -</para> - </directive> </section>
--- a/xml/en/docs/http/ngx_http_mp4_module.xml +++ b/xml/en/docs/http/ngx_http_mp4_module.xml @@ -188,62 +188,6 @@ 12583268, you may want to increase mp4_m </directive> -<directive name="mp4_limit_rate"> -<syntax> - <literal>on</literal> | - <literal>off</literal> | - <value>factor</value></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Limits the rate of response transmission to a client. -The rate is limited based on the average bitrate of the -MP4 file served. -To calculate the rate, the bitrate is multiplied by the specified -<value>factor</value>. -The special value “<literal>on</literal>” corresponds to the factor of 1.1. -The special value “<literal>off</literal>” disables rate limiting. -The limit is set per a request, and so if a client simultaneously opens -two connections, the overall rate will be twice as much -as the specified limit. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="mp4_limit_rate_after"> -<syntax><value>time</value></syntax> -<default>60s</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Sets the initial amount of media data (measured in playback time) -after which the further transmission of the response to a client -will be rate limited. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="mp4_start_key_frame"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
--- a/xml/en/docs/http/ngx_http_proxy_module.xml +++ b/xml/en/docs/http/ngx_http_proxy_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_proxy_module" link="/en/docs/http/ngx_http_proxy_module.html" lang="en" - rev="76"> + rev="77"> <section id="summary"> @@ -408,11 +408,7 @@ will be cached. [<literal>manager_threshold</literal>=<value>time</value>] [<literal>loader_files</literal>=<value>number</value>] [<literal>loader_sleep</literal>=<value>time</value>] - [<literal>loader_threshold</literal>=<value>time</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>number</value>] - [<literal>purger_sleep</literal>=<value>time</value>] - [<literal>purger_threshold</literal>=<value>time</value>]</syntax> + [<literal>loader_threshold</literal>=<value>time</value>]</syntax> <default/> <context>http</context> @@ -458,15 +454,6 @@ In addition, all active keys and informa in a shared memory zone, whose <value>name</value> and <value>size</value> are configured by the <literal>keys_zone</literal> parameter. One megabyte zone can store about 8 thousand keys. -<note> -As part of -<commercial_version>commercial subscription</commercial_version>, -the shared memory zone also stores extended -cache <link doc="ngx_http_api_module.xml" id="http_caches_">information</link>, -thus, it is required to specify a larger zone size for the same number of keys. -For example, -one megabyte zone can store about 4 thousand keys. -</note> </para> <para> @@ -510,56 +497,6 @@ parameter (by default, 50 milliseconds) </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Instructs whether cache entries that match a -<link id="proxy_cache_purge">wildcard key</link> -will be removed from the disk by the cache purger (1.7.12). -Setting the parameter to <literal>on</literal> -(default is <literal>off</literal>) -will activate the “cache purger” process that -permanently iterates through all cache entries -and deletes the entries that match the wildcard key. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the number of items that will be scanned during one iteration (1.7.12). -By default, <literal>purger_files</literal> is set to 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the duration of one iteration (1.7.12). -By default, <literal>purger_threshold</literal> is set to 50 milliseconds. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets a pause between iterations (1.7.12). -By default, <literal>purger_sleep</literal> is set to 50 milliseconds. -</tag-desc> - -</list> -</para> - -<para> <note> In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid @@ -570,63 +507,6 @@ after upgrading to a newer nginx version </directive> -<directive name="proxy_cache_purge"> -<syntax>string ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Defines conditions under which the request will be considered a cache -purge request. -If at least one value of the string parameters is not empty and is not equal -to “0” then the cache entry with a corresponding -<link id="proxy_cache_key">cache key</link> is removed. -The result of successful operation is indicated by returning -the <http-status code="204" text="No Content"/> response. -</para> - -<para> -If the <link id="proxy_cache_key">cache key</link> of a purge request ends -with an asterisk (“<literal>*</literal>”), all cache entries matching the -wildcard key will be removed from the cache. -However, these entries will remain on the disk until they are deleted -for either <link id="proxy_cache_path">inactivity</link>, -or processed by the <link id="purger">cache purger</link> (1.7.12), -or a client attempts to access them. -</para> - -<para> -Example configuration: -<example> -proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - proxy_pass http://backend; - proxy_cache cache_zone; - proxy_cache_key $uri; - proxy_cache_purge $purge_method; - } -} -</example> -<note> -This functionality is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="proxy_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_proxy_protocol_vendor_module.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_proxy_protocol_vendor_module" - link="/en/docs/http/ngx_http_proxy_protocol_vendor_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_http_proxy_protocol_vendor_module</literal> module (1.23.3) -allows obtaining additional information about a connection in -cloud platforms from application-specific TLVs of the -<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">PROXY -protocol</link> -header. -</para> - -<para> -Supported cloud platforms: -<list type="bullet"> - -<listitem> -Amazon Web Services -</listitem> - -<listitem> -Google Cloud Platform -</listitem> - -<listitem> -Microsoft Azure -</listitem> - -</list> -</para> - -<para> -The PROXY protocol must be previously enabled by setting the -<literal>proxy_protocol</literal> parameter -in the <link doc="ngx_http_core_module.xml" id="listen"/> directive. -</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> -proxy_set_header X-Conn-ID $proxy_protocol_tlv_gcp_conn_id; - -server { - listen 80 proxy_protocol; - listen 443 ssl proxy_protocol; - ... -} -</example> -</para> - -</section> - - -<section id="variables" name="Embedded Variables"> - -<para> -<list type="tag"> - -<tag-name id="var_proxy_protocol_tlv_aws_vpce_id"><var>$proxy_protocol_tlv_aws_vpce_id</var></tag-name> -<tag-desc> -TLV value from the PROXY Protocol header representing the -<link url="https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol">ID -of AWS VPC endpoint</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_azure_pel_id"><var>$proxy_protocol_tlv_azure_pel_id</var></tag-name> -<tag-desc> -TLV value from the PROXY Protocol header representing the -<link url="https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview#getting-connection-information-using-tcp-proxy-v2">LinkID -of Azure private endpoint</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_gcp_conn_id"><var>$proxy_protocol_tlv_gcp_conn_id</var></tag-name> -<tag-desc> -TLV value from the PROXY Protocol header representing -<link url="https://cloud.google.com/vpc/docs/configure-private-service-connect-producer#proxy-protocol">Google Cloud PSC -connection ID</link> -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/en/docs/http/ngx_http_scgi_module.xml +++ b/xml/en/docs/http/ngx_http_scgi_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_scgi_module" link="/en/docs/http/ngx_http_scgi_module.html" lang="en" - rev="41"> + rev="42"> <section id="summary"> @@ -383,11 +383,7 @@ will be cached. [<literal>manager_threshold</literal>=<value>time</value>] [<literal>loader_files</literal>=<value>number</value>] [<literal>loader_sleep</literal>=<value>time</value>] - [<literal>loader_threshold</literal>=<value>time</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>number</value>] - [<literal>purger_sleep</literal>=<value>time</value>] - [<literal>purger_threshold</literal>=<value>time</value>]</syntax> + [<literal>loader_threshold</literal>=<value>time</value>]</syntax> <default/> <context>http</context> @@ -433,15 +429,6 @@ In addition, all active keys and informa in a shared memory zone, whose <value>name</value> and <value>size</value> are configured by the <literal>keys_zone</literal> parameter. One megabyte zone can store about 8 thousand keys. -<note> -As part of -<commercial_version>commercial subscription</commercial_version>, -the shared memory zone also stores extended -cache <link doc="ngx_http_api_module.xml" id="http_caches_">information</link>, -thus, it is required to specify a larger zone size for the same number of keys. -For example, -one megabyte zone can store about 4 thousand keys. -</note> </para> <para> @@ -485,56 +472,6 @@ parameter (by default, 50 milliseconds) </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Instructs whether cache entries that match a -<link id="scgi_cache_purge">wildcard key</link> -will be removed from the disk by the cache purger (1.7.12). -Setting the parameter to <literal>on</literal> -(default is <literal>off</literal>) -will activate the “cache purger” process that -permanently iterates through all cache entries -and deletes the entries that match the wildcard key. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the number of items that will be scanned during one iteration (1.7.12). -By default, <literal>purger_files</literal> is set to 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the duration of one iteration (1.7.12). -By default, <literal>purger_threshold</literal> is set to 50 milliseconds. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets a pause between iterations (1.7.12). -By default, <literal>purger_sleep</literal> is set to 50 milliseconds. -</tag-desc> - -</list> -</para> - -<para> <note> In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid @@ -545,63 +482,6 @@ after upgrading to a newer nginx version </directive> -<directive name="scgi_cache_purge"> -<syntax>string ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Defines conditions under which the request will be considered a cache -purge request. -If at least one value of the string parameters is not empty and is not equal -to “0” then the cache entry with a corresponding -<link id="scgi_cache_key">cache key</link> is removed. -The result of successful operation is indicated by returning -the <http-status code="204" text="No Content"/> response. -</para> - -<para> -If the <link id="scgi_cache_key">cache key</link> of a purge request ends -with an asterisk (“<literal>*</literal>”), all cache entries matching the -wildcard key will be removed from the cache. -However, these entries will remain on the disk until they are deleted -for either <link id="scgi_cache_path">inactivity</link>, -or processed by the <link id="purger">cache purger</link> (1.7.12), -or a client attempts to access them. -</para> - -<para> -Example configuration: -<example> -scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - scgi_pass backend; - scgi_cache cache_zone; - scgi_cache_key $uri; - scgi_cache_purge $purge_method; - } -} -</example> -<note> -This functionality is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="scgi_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_session_log_module.xml +++ /dev/null @@ -1,161 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_session_log_module" - link="/en/docs/http/ngx_http_session_log_module.html" - lang="en" - rev="3"> - -<section id="summary"> - -<para> -The <literal>ngx_http_session_log_module</literal> module enables logging -sessions (that is, aggregates of multiple HTTP requests) instead of -individual HTTP requests. -</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> -The following configuration sets up a session log and maps requests to -sessions according to the request client address and <header>User-Agent</header> -request header field: -<example> - session_log_zone /path/to/log format=combined - zone=one:1m timeout=30s - md5=$binary_remote_addr$http_user_agent; - - location /media/ { - session_log one; - } -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="session_log"> -<syntax><value>name</value> | <literal>off</literal></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables the use of the specified session log. -The special value <literal>off</literal> cancels the effect -of the <literal>session_log</literal> directives -inherited from the previous configuration level. -</para> - -</directive> - - -<directive name="session_log_format"> -<syntax> - <value>name</value> - <value>string</value> ...</syntax> -<default>combined "..."</default> -<context>http</context> - -<para> -Specifies the output format of a log. -The value of the <var>$body_bytes_sent</var> variable is aggregated across -all requests in a session. -The values of all other variables available for logging correspond to the -first request in a session. -</para> - -</directive> - - -<directive name="session_log_zone"> -<syntax> - <value>path</value> - <literal>zone</literal>=<value>name</value>:<value>size</value> - [<literal>format</literal>=<value>format</value>] - [<literal>timeout</literal>=<value>time</value>] - [<literal>id</literal>=<value>id</value>] - [<literal>md5</literal>=<value>md5</value>] -</syntax> -<default/> -<context>http</context> - -<para> -Sets the path to a log file and configures the shared memory zone that is used -to store currently active sessions. -</para> - -<para> -A session is considered active for as long as the time elapsed since -the last request in the session does not exceed the specified -<literal>timeout</literal> (by default, 30 seconds). -Once a session is no longer active, it is written to the log. -</para> - -<para> -The <literal>id</literal> parameter identifies the -session to which a request is mapped. -The <literal>id</literal> parameter is set to the hexadecimal representation -of an MD5 hash (for example, obtained from a cookie using variables). -If this parameter is not specified or does not represent the valid -MD5 hash, nginx computes the MD5 hash from the value of -the <literal>md5</literal> parameter and creates a new session using this hash. -Both the <literal>id</literal> and <literal>md5</literal> parameters -can contain variables. -</para> - -<para> -The <literal>format</literal> parameter sets the custom session log -format configured by the <link id="session_log_format"/> directive. -If <literal>format</literal> is not specified, the predefined -“<literal>combined</literal>” format is used. -</para> - -</directive> - -</section> - - -<section id="variables" name="Embedded Variables"> - -<para> -The <literal>ngx_http_session_log_module</literal> module supports -two embedded variables: - -<list type="tag"> - -<tag-name id="var_session_log_id"><var>$session_log_id</var></tag-name> -<tag-desc> -current session ID; -</tag-desc> - -<tag-name id="var_session_log_binary_id"><var>$session_log_binary_id</var> -</tag-name> -<tag-desc> -current session ID in binary form (16 bytes). -</tag-desc> - -</list> -</para> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_status_module.xml +++ /dev/null @@ -1,1192 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_status_module" - link="/en/docs/http/ngx_http_status_module.html" - lang="en" - rev="19"> - -<section id="summary"> - -<para> -The <literal>ngx_http_status_module</literal> module provides -access to various status information. -<note> -This module was available as part of our -<commercial_version>commercial subscription</commercial_version> -until 1.13.10. -It was superseded by the -<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> module -in 1.13.3. -</note> -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -http { - upstream <emphasis>backend</emphasis> { - <emphasis>zone</emphasis> http_backend 64k; - - server backend1.example.com weight=5; - server backend2.example.com; - } - - proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m; - - server { - server_name backend.example.com; - - location / { - proxy_pass http://backend; - proxy_cache cache_backend; - - health_check; - } - - <emphasis>status_zone server_backend;</emphasis> - } - - server { - listen 127.0.0.1; - - location /upstream_conf { - upstream_conf; - } - - location /status { - status; - } - - location = /status.html { - } - } -} - -stream { - upstream <emphasis>backend</emphasis> { - <emphasis>zone</emphasis> 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; - <emphasis>status_zone server_backend;</emphasis> - health_check; - } -} -</example> -</para> - -<para> -Examples of status requests with this configuration: -<example> -http://127.0.0.1/status -http://127.0.0.1/status/nginx_version -http://127.0.0.1/status/caches/cache_backend -http://127.0.0.1/status/upstreams -http://127.0.0.1/status/upstreams/backend -http://127.0.0.1/status/upstreams/backend/peers/1 -http://127.0.0.1/status/upstreams/backend/peers/1/weight -http://127.0.0.1/status/stream -http://127.0.0.1/status/stream/upstreams -http://127.0.0.1/status/stream/upstreams/backend -http://127.0.0.1/status/stream/upstreams/backend/peers/1 -http://127.0.0.1/status/stream/upstreams/backend/peers/1/weight -</example> -</para> - -<para> -The simple monitoring page is shipped with this distribution, -accessible as “<literal>/status.html</literal>” in the default configuration. -It requires the locations “<literal>/status</literal>” and -“<literal>/status.html</literal>” to be configured as shown above. -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="status"> -<syntax/> -<default/> -<context>location</context> - -<para> -The status information will be accessible from the surrounding location. -Access to this location should be -<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. -</para> - -</directive> - - -<directive name="status_format"> -<syntax><literal>json</literal></syntax> -<syntax><literal>jsonp</literal> [<value>callback</value>]</syntax> -<default>json</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -By default, status information is output in the JSON format. -</para> - -<para> -Alternatively, data may be output as JSONP. -The <value>callback</value> parameter specifies the name of a callback function. -Parameter value can contain variables. -If parameter is omitted, or the computed value is an empty string, -then “<literal>ngx_status_jsonp_callback</literal>” is used. -</para> - -</directive> - - -<directive name="status_zone"> -<syntax><value>zone</value></syntax> -<default/> -<context>server</context> - -<para> -Enables collection of virtual -<link doc="ngx_http_core_module.xml" id="server">http</link> -or -<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> -(1.7.11) server status information in the specified <value>zone</value>. -Several servers may share the same zone. -</para> - -</directive> - -</section> - - -<section id="data" name="Data"> - -<para> -The following status information is provided: -<list type="tag"> - -<tag-name id="version"><literal>version</literal></tag-name> -<tag-desc> -Version of the provided data set. -The current version is 8. -</tag-desc> - -<tag-name><literal>nginx_version</literal></tag-name> -<tag-desc> -Version of nginx. -</tag-desc> - -<tag-name id="nginx_build"><literal>nginx_build</literal></tag-name> -<tag-desc> -Name of nginx build. -</tag-desc> - -<tag-name><literal>address</literal></tag-name> -<tag-desc> -The address of the server that accepted status request. -</tag-desc> - -<tag-name id="generation"><literal>generation</literal></tag-name> -<tag-desc> -The total number of configuration -<link doc="../control.xml" id="reconfiguration">reloads</link>. -</tag-desc> - -<tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name> -<tag-desc> -Time of the last reload of configuration, in milliseconds since Epoch. -</tag-desc> - -<tag-name><literal>timestamp</literal></tag-name> -<tag-desc> -Current time in milliseconds since Epoch. -</tag-desc> - -<tag-name id="pid"><literal>pid</literal></tag-name> -<tag-desc> -The ID of the worker process that handled status request. -</tag-desc> - -<tag-name id="ppid"><literal>ppid</literal></tag-name> -<tag-desc> -The ID of the master process that started -the <link id="pid">worker process</link>. -</tag-desc> - -<tag-name id="processes"><literal>processes</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name id="respawned"><literal>respawned</literal></tag-name> -<tag-desc> -The total number of abnormally terminated and respawned -child processes. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>connections</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>accepted</literal></tag-name> -<tag-desc> -The total number of accepted client connections. -</tag-desc> - -<tag-name><literal>dropped</literal></tag-name> -<tag-desc> -The total number of dropped client connections. -</tag-desc> - -<tag-name><literal>active</literal></tag-name> -<tag-desc> -The current number of active client connections. -</tag-desc> - -<tag-name><literal>idle</literal></tag-name> -<tag-desc> -The current number of idle client connections. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="ssl"><literal>ssl</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>handshakes</literal></tag-name> -<tag-desc> -The total number of successful SSL handshakes. -</tag-desc> - -<tag-name><literal>handshakes_failed</literal></tag-name> -<tag-desc> -The total number of failed SSL handshakes. -</tag-desc> - -<tag-name><literal>session_reuses</literal></tag-name> -<tag-desc> -The total number of session reuses during SSL handshake. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>requests</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -The total number of client requests. -</tag-desc> - -<tag-name><literal>current</literal></tag-name> -<tag-desc> -The current number of client requests. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="server_zones"><literal>server_zones</literal></tag-name> -<tag-desc> -For each <link id="status_zone"/>: -<list type="tag"> - -<tag-name><literal>processing</literal></tag-name> -<tag-desc> -The number of -client requests that are currently being processed. -</tag-desc> - -<tag-name><literal>requests</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> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -The total number of -responses sent to clients. -</tag-desc> - -<tag-name> -<literal>1xx</literal>, -<literal>2xx</literal>, -<literal>3xx</literal>, -<literal>4xx</literal>, -<literal>5xx</literal> -</tag-name> -<tag-desc> -The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="discarded"><literal>discarded</literal></tag-name> -<tag-desc> -The total number of requests completed without sending a response. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -The total number of bytes received from clients. -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -The total number of bytes sent to clients. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="slabs"><literal>slabs</literal></tag-name> -<tag-desc> -For each shared memory zone that uses slab allocator: -<list type="tag"> - -<tag-name><literal>pages</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>used</literal></tag-name> -<tag-desc> -The current number of used memory pages. -</tag-desc> - -<tag-name><literal>free</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> -For each memory slot size (8, 16, 32, 64, 128, etc.) -the following data are provided: -<list type="tag"> - -<tag-name><literal>used</literal></tag-name> -<tag-desc> -The current number of used memory slots. -</tag-desc> - -<tag-name><literal>free</literal></tag-name> -<tag-desc> -The current number of free memory slots. -</tag-desc> - -<tag-name><literal>reqs</literal></tag-name> -<tag-desc> -The total number of attempts to allocate memory of specified size. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -The number of unsuccessful attempts to allocate memory of specified size. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="upstreams"><literal>upstreams</literal></tag-name> -<tag-desc> -For each -<link doc="ngx_http_upstream_module.xml" id="zone">dynamically -configurable</link> -<link doc="ngx_http_upstream_module.xml" id="upstream">group</link>, -the following data are provided: -<list type="tag"> - -<tag-name id="peers"><literal>peers</literal></tag-name> -<tag-desc> -For each -<link doc="ngx_http_upstream_module.xml" id="server"/>, -the following data are provided: -<list type="tag"> - -<tag-name id="id"><literal>id</literal></tag-name> -<tag-desc> -The ID of the server. -</tag-desc> - -<tag-name><literal>server</literal></tag-name> -<tag-desc> -An -<link doc="ngx_http_upstream_module.xml" id="server">address</link> -of the server. -</tag-desc> - -<tag-name id="name"><literal>name</literal></tag-name> -<tag-desc> -The name of the server specified in the -<link doc="ngx_http_upstream_module.xml" id="server"/> -directive. -</tag-desc> - -<tag-name id="service"><literal>service</literal></tag-name> -<tag-desc> -The <link doc="ngx_http_upstream_module.xml" id="service"/> -parameter value of the -<link doc="ngx_http_upstream_module.xml" id="server"/> directive. -</tag-desc> - -<tag-name><literal>backup</literal></tag-name> -<tag-desc> -A boolean value indicating whether the server is a -<link doc="ngx_http_upstream_module.xml" id="backup"/> -server. -</tag-desc> - -<tag-name><literal>weight</literal></tag-name> -<tag-desc> -<link doc="ngx_http_upstream_module.xml" id="weight">Weight</link> -of the server. -</tag-desc> - -<tag-name id="state"><literal>state</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>”, -or -“<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name><literal>active</literal></tag-name> -<tag-desc> -The current number of active connections. -</tag-desc> - -<tag-name id="max_conns"><literal>max_conns</literal></tag-name> -<tag-desc> -The <link doc="ngx_http_upstream_module.xml" id="max_conns"/> limit -for the server. -</tag-desc> - -<tag-name><literal>requests</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>total</literal></tag-name> -<tag-desc> -The total number of -responses obtained from this server. -</tag-desc> - -<tag-name> -<literal>1xx</literal>, -<literal>2xx</literal>, -<literal>3xx</literal>, -<literal>4xx</literal>, -<literal>5xx</literal> -</tag-name> -<tag-desc> -The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -The total number of bytes sent to this server. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -The total number of bytes received from this server. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -The total number of -unsuccessful attempts to communicate with the server. -</tag-desc> - -<tag-name><literal>unavail</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 doc="ngx_http_upstream_module.xml" id="max_fails"/> -threshold. -</tag-desc> - -<tag-name><literal>health_checks</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>checks</literal></tag-name> -<tag-desc> -The total number of -<link doc="ngx_http_upstream_hc_module.xml" id="health_check">health check</link> -requests made. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -The number of failed health checks. -</tag-desc> - -<tag-name><literal>unhealthy</literal></tag-name> -<tag-desc> -How many times -the server became unhealthy (state “<literal>unhealthy</literal>”). -</tag-desc> - -<tag-name><literal>last_passed</literal></tag-name> -<tag-desc> -Boolean indicating -if the last health check request was successful and passed -<link doc="ngx_http_upstream_hc_module.xml" id="match">tests</link>. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>downtime</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></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 id="selected"><literal>selected</literal></tag-name> -<tag-desc> -The time (in milliseconds since Epoch) -when the server was last selected to process a request (1.7.5). -</tag-desc> - -<tag-name id="header_time"><literal>header_time</literal></tag-name> -<tag-desc> -The average time to get the -<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">response -header</link> from the server (1.7.10). -Prior to version 1.11.6, -the field was available only when using the -<link doc="ngx_http_upstream_module.xml" id="least_time"/> -load balancing method. -</tag-desc> - -<tag-name id="response_time"><literal>response_time</literal></tag-name> -<tag-desc> -The average time to get the -<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">full -response</link> from the server (1.7.10). -Prior to version 1.11.6, -the field was available only when using the -<link doc="ngx_http_upstream_module.xml" id="least_time"/> -load balancing method. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>keepalive</literal></tag-name> -<tag-desc> -The current number of -idle <link doc="ngx_http_upstream_module.xml" id="keepalive"/> connections. -</tag-desc> - -<tag-name id="zombies"><literal>zombies</literal></tag-name> -<tag-desc> -The current number of servers removed -from the group but still processing active client requests. -</tag-desc> - -<tag-name id="zone"><literal>zone</literal></tag-name> -<tag-desc> -The name of the shared memory -<link doc="ngx_http_upstream_module.xml" id="zone"/> -that keeps the group’s configuration and run-time state. -</tag-desc> - -<tag-name id="queue"><literal>queue</literal></tag-name> -<tag-desc> -For the requests <link doc="ngx_http_upstream_module.xml" id="queue"/>, -the following data are provided: -<list type="tag"> - -<tag-name><literal>size</literal></tag-name> -<tag-desc> -The current number of requests in the queue. -</tag-desc> - -<tag-name id="max_size"><literal>max_size</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></tag-name> -<tag-desc> -The total number of requests rejected due to the queue overflow. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="caches"><literal>caches</literal></tag-name> -<tag-desc> -For each cache (configured by -<link doc="ngx_http_proxy_module.xml" id="proxy_cache_path"/> and the likes): -<list type="tag"> - -<tag-name><literal>size</literal></tag-name> -<tag-desc> -The current size of the cache. -</tag-desc> - -<tag-name><literal>max_size</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></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>, - <literal>stale</literal>, - <literal>updating</literal>, - <literal>revalidated</literal> -</tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>responses</literal></tag-name> -<tag-desc> -The total number of responses read from the cache (hits, or stale responses -due to <link doc="ngx_http_proxy_module.xml" id="proxy_cache_use_stale"/> -and the likes). -</tag-desc> - -<tag-name><literal>bytes</literal></tag-name> -<tag-desc> -The total number of bytes read from the cache. -</tag-desc> - -</list> -</tag-desc> - -<tag-name> - <literal>miss</literal>, - <literal>expired</literal>, - <literal>bypass</literal> -</tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>responses</literal></tag-name> -<tag-desc> -The total number of responses not taken from the cache (misses, expires, or -bypasses due to -<link doc="ngx_http_proxy_module.xml" id="proxy_cache_bypass"/> -and the likes). -</tag-desc> - -<tag-name><literal>bytes</literal></tag-name> -<tag-desc> -The total number of bytes read from the proxied server. -</tag-desc> - -<tag-name><literal>responses_written</literal></tag-name> -<tag-desc> -The total number of responses written to the cache. -</tag-desc> - -<tag-name><literal>bytes_written</literal></tag-name> -<tag-desc> -The total number of bytes written to the cache. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="stream"><literal>stream</literal></tag-name> -<tag-desc> - -<list type="tag"> -<tag-name id="stream_server_zones"><literal>server_zones</literal></tag-name> -<tag-desc> -For each <link id="status_zone"/>: -<list type="tag"> - -<tag-name><literal>processing</literal></tag-name> -<tag-desc> -The number of -client connections that are currently being processed. -</tag-desc> - -<tag-name><literal>connections</literal></tag-name> -<tag-desc> -The total number of -connections accepted from clients. -</tag-desc> - -<tag-name id="sessions"><literal>sessions</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -The total number of completed client sessions. -</tag-desc> - -<tag-name> -<literal>2xx</literal>, -<literal>4xx</literal>, -<literal>5xx</literal> -</tag-name> -<tag-desc> -The number of sessions completed with -<link doc="../stream/ngx_stream_core_module.xml" id="var_status">status codes</link> -2xx, 4xx, or 5xx. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="stream_discarded"><literal>discarded</literal></tag-name> -<tag-desc> -The total number of connections completed without creating a session. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -The total number of bytes received from clients. -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -The total number of bytes sent to clients. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="stream_upstreams"><literal>upstreams</literal></tag-name> -<tag-desc> -For each -<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">dynamically -configurable</link> -<link doc="../stream/ngx_stream_upstream_module.xml" id="upstream">group</link>, -the following data are provided: -<list type="tag"> - -<tag-name><literal>peers</literal></tag-name> -<tag-desc> -For each -<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/> -the following data are provided: -<list type="tag"> - -<tag-name><literal>id</literal></tag-name> -<tag-desc> -The ID of the server. -</tag-desc> - -<tag-name><literal>server</literal></tag-name> -<tag-desc> -An -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">address</link> -of the server. -</tag-desc> - - -<tag-name id="stream_name"><literal>name</literal></tag-name> -<tag-desc> -The name of the server specified in the -<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/> directive. -</tag-desc> - -<tag-name id="stream_service"><literal>service</literal></tag-name> -<tag-desc> -The <link doc="../stream/ngx_stream_upstream_module.xml" id="service"/> -parameter value of the -<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/> directive. -</tag-desc> - -<tag-name><literal>backup</literal></tag-name> -<tag-desc> -A boolean value indicating whether the server is a -<link doc="../stream/ngx_stream_upstream_module.xml" id="backup"/> -server. -</tag-desc> - -<tag-name><literal>weight</literal></tag-name> -<tag-desc> -<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">Weight</link> -of the server. -</tag-desc> - -<tag-name><literal>state</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></tag-name> -<tag-desc> -The current number of connections. -</tag-desc> - -<tag-name><literal>max_conns</literal></tag-name> -<tag-desc> -The <link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns"/> limit -for the server. -</tag-desc> - -<tag-name><literal>connections</literal></tag-name> -<tag-desc> -The total number of -client connections forwarded to this server. -</tag-desc> - -<tag-name><literal>connect_time</literal></tag-name> -<tag-desc> -The average time to connect to the upstream server. -Prior to version 1.11.6, -the field was available only when using the -<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> -load balancing method. -</tag-desc> - -<tag-name><literal>first_byte_time</literal></tag-name> -<tag-desc> -The average time to receive the first byte of data. -Prior to version 1.11.6, -the field was available only when using the -<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> -load balancing method. -</tag-desc> - -<tag-name><literal>response_time</literal></tag-name> -<tag-desc> -The average time to receive the last byte of data. -Prior to version 1.11.6, -the field was available only when using the -<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> -load balancing method. -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -The total number of bytes sent to this server. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -The total number of bytes received from this server. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -The total number of -unsuccessful attempts to communicate with the server. -</tag-desc> - -<tag-name><literal>unavail</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 doc="../stream/ngx_stream_upstream_module.xml" id="max_fails"/> -threshold. -</tag-desc> - -<tag-name><literal>health_checks</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>checks</literal></tag-name> -<tag-desc> -The total number of -<link doc="../stream/ngx_stream_upstream_hc_module.xml" id="health_check">health check</link> -requests made. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -The number of failed health checks. -</tag-desc> - -<tag-name><literal>unhealthy</literal></tag-name> -<tag-desc> -How many times -the server became unhealthy (state “<literal>unhealthy</literal>”). -</tag-desc> - -<tag-name><literal>last_passed</literal></tag-name> -<tag-desc> -Boolean indicating -if the last health check request was successful and passed -<link doc="../stream/ngx_stream_upstream_hc_module.xml" id="match">tests</link>. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>downtime</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></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></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></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></tag-name> -<tag-desc> -The name of the shared memory -<link doc="../stream/ngx_stream_upstream_module.xml" id="zone"/> -that keeps the group’s configuration and run-time state. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -</list> -</para> - -</section> - -<section id="compatibility" name="Compatibility"> - -<para> -<list type="bullet"> - -<listitem> -The -<link id="zone"/> field in -<link id="upstreams">http</link> and <link id="stream_upstreams">stream</link> -upstreams -was added in <link id="version"/> 8. -</listitem> - -<listitem> -The <link id="slabs"/> status data -were added in <link id="version"/> 8. -</listitem> - -<listitem> -The -<link id="state">checking</link> state -was added in <link id="version"/> 8. -</listitem> - -<listitem> -The -<link id="name"/> and <link id="service"/> fields in -<link id="upstreams">http</link> and <link id="stream_upstreams">stream</link> -upstreams -were added in <link id="version"/> 8. -</listitem> - -<listitem> -The -<link id="nginx_build"/> and <link id="ppid"/> fields -were added in <link id="version"/> 8. -</listitem> - -<listitem> -The -<link id="sessions"/> status data -and the <link id="stream_discarded">discarded</link> field in -stream <link id="stream_server_zones">server_zones</link> -were added in <link id="version"/> 7. -</listitem> - -<listitem> -The <link id="zombies"/> field -was moved from nginx <link doc="../debugging_log.xml">debug</link> version -in <link id="version"/> 6. -</listitem> - -<listitem> -The <link id="ssl"/> status data -were added in <link id="version"/> 6. -</listitem> - -<listitem> -The -<link id="discarded"/> field in -<link id="server_zones"/> -was added in <link id="version"/> 6. -</listitem> - -<listitem> -The <link id="queue"/> status data -were added in <link id="version"/> 6. -</listitem> - -<listitem> -The -<link id="pid"/> field -was added in <link id="version"/> 6. -</listitem> - -<listitem> -The list of servers in <link id="upstreams"/> -was moved into <link id="peers"/> in -<link id="version"/> 6. -</listitem> - -<listitem> -The <literal>keepalive</literal> field of an upstream server -was removed in <link id="version"/> 5. -</listitem> - -<listitem> -The <link id="stream">stream</link> status data -were added in <link id="version"/> 5. -</listitem> - -<listitem> -The -<link id="generation"/> field -was added in <link id="version"/> 5. -</listitem> - -<listitem> -The -<link id="respawned"/> field in -<link id="processes"/> -was added in <link id="version"/> 5. -</listitem> - -<listitem> -The -<link id="header_time"/> and <link id="response_time"/> fields in -<link id="upstreams"/> -were added in <link id="version"/> 5. -</listitem> - -<listitem> -The -<link id="selected"/> field in -<link id="upstreams"/> -was added in <link id="version"/> 4. -</listitem> - -<listitem> -The <link id="state">draining</link> state in -<link id="upstreams"/> -was added in <link id="version"/> 4. -</listitem> - -<listitem> -The -<link id="id"/> and <link id="max_conns"/> fields in -<link id="upstreams"/> -were added in <link id="version"/> 3. -</listitem> - -<listitem> -The <literal>revalidated</literal> field in -<link id="caches"/> -was added in <link id="version"/> 3. -</listitem> - -<listitem> -The <link id="server_zones"/>, <link id="caches"/>, -and <link id="load_timestamp"/> status data -were added in <link id="version"/> 2. -</listitem> - -</list> -</para> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_upstream_conf_module.xml +++ /dev/null @@ -1,369 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_upstream_conf_module" - link="/en/docs/http/ngx_http_upstream_conf_module.html" - lang="en" - rev="6"> - -<section id="summary"> - -<para> -The <literal>ngx_http_upstream_conf_module</literal> module -allows configuring upstream server groups on-the-fly -via a simple HTTP interface without the need of restarting nginx. -The -<link doc="ngx_http_upstream_module.xml" id="zone">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> -server group must reside in the shared memory. -<note> -This module was available as part of our -<commercial_version>commercial subscription</commercial_version> -until 1.13.10. -It was superseded by the -<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> module -in 1.13.3. -</note> -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -upstream backend { - zone upstream_backend 64k; - - ... -} - -server { - location /upstream_conf { - <emphasis>upstream_conf</emphasis>; - allow 127.0.0.1; - deny all; - } -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="upstream_conf"> -<syntax/> -<default/> -<context>location</context> - -<para> -Turns on the HTTP interface of upstream configuration in the surrounding -location. -Access to this location should be -<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. -</para> - -<para> -Configuration commands can be used to: -<list type="bullet"> - -<listitem>view the group configuration;</listitem> - -<listitem>view, modify, or remove a server;</listitem> - -<listitem>add a new server.</listitem> - -</list> -<note> -Since addresses in a group are not required to be unique, specific -servers in a group are referenced by their IDs. -IDs are assigned automatically and shown when adding a new server -or viewing the group configuration. -</note> -</para> - -<para> -A configuration command consists of parameters passed as request arguments, -for example: -<example> -http://127.0.0.1/upstream_conf?upstream=backend -</example> -</para> - -<para> -The following parameters are supported: - -<list type="tag" compact="no"> - -<tag-name> -<literal>stream=</literal></tag-name> -<tag-desc> -Selects a -<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> -upstream server group. -Without this parameter, selects an -<link doc="ngx_http_upstream_module.xml">http</link> -upstream server group. -</tag-desc> - -<tag-name> -<literal>upstream=</literal><value>name</value></tag-name> -<tag-desc> -Selects a group to work with. -This parameter is mandatory. -</tag-desc> - -<tag-name> -<literal>id=</literal><value>number</value></tag-name> -<tag-desc> -Selects a server for viewing, modifying, or removing. -</tag-desc> - -<tag-name> -<literal>remove=</literal></tag-name> -<tag-desc> -Removes a server from the group. -</tag-desc> - -<tag-name> -<literal>add=</literal></tag-name> -<tag-desc> -Adds a new server to the group. -</tag-desc> - -<tag-name> -<literal>backup=</literal></tag-name> -<tag-desc> -Required to add a backup server. -<note> -Before version 1.7.2, <literal>backup=</literal> -was also required to view, modify, or remove existing backup servers. -</note> -</tag-desc> - -<tag-name> -<literal>server=</literal><value>address</value></tag-name> -<tag-desc> -Same as the “<literal>address</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="server">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> -upstream server. -<para> -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 (1.7.2). -This requires the “<literal>resolver</literal>” directive in the -<link doc="ngx_http_core_module.xml" id="resolver">http</link> -or -<link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> -block. -See also the “<literal>resolve</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="resolve">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link> -upstream server. -</para> -</tag-desc> - -<tag-name> -<literal>service=</literal><value>name</value></tag-name> -<tag-desc> -Same as the “<literal>service</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="service">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="service">stream</link> -upstream server (1.9.13). -</tag-desc> - -<tag-name> -<literal>weight=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>weight</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="weight">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link> -upstream server. -</tag-desc> - -<tag-name> -<literal>max_conns=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>max_conns</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link> -upstream server. -</tag-desc> - -<tag-name> -<literal>max_fails=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>max_fails</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link> -upstream server. -</tag-desc> - -<tag-name> -<literal>fail_timeout=</literal><value>time</value></tag-name> -<tag-desc> -Same as the “<literal>fail_timeout</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link> -upstream server. -</tag-desc> - -<tag-name> -<literal>slow_start=</literal><value>time</value></tag-name> -<tag-desc> -Same as the “<literal>slow_start</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link> -upstream server. -</tag-desc> - -<tag-name> -<literal>down=</literal></tag-name> -<tag-desc> -Same as the “<literal>down</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="down">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> -upstream server. -</tag-desc> - -<tag-name id="drain"><literal>drain=</literal></tag-name> -<tag-desc> -Puts the -<link doc="ngx_http_upstream_module.xml">http</link> -upstream server into the “draining” mode (1.7.5). -In this mode, only requests -<link doc="ngx_http_upstream_module.xml" id="sticky">bound</link> to the server -will be proxied to it. -</tag-desc> - -<tag-name> -<literal>up=</literal></tag-name> -<tag-desc> -The opposite of the “<literal>down</literal>” parameter -of the -<link doc="ngx_http_upstream_module.xml" id="down">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> -upstream server. -</tag-desc> - -<tag-name> -<literal>route=</literal><value>string</value></tag-name> -<tag-desc> -Same as the “<literal>route</literal>” parameter of the -<link doc="ngx_http_upstream_module.xml" id="route">http</link> -upstream server. -</tag-desc> - -</list> - -The first three parameters select an object. -This can be either the whole http or stream upstream server group, -or a specific server. -Without other parameters, the configuration of the selected -group or server is shown. -</para> - -<para> -For example, to view the configuration of the whole group, send: -<example> -http://127.0.0.1/upstream_conf?upstream=backend -</example> - -To view the configuration of a specific server, also specify its ID: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42 -</example> -</para> - -<para> -To add a new server, -specify its address in the “<literal>server=</literal>” parameter. -Without other parameters specified, a server will be added with other -parameters set to their default values (see the -<link doc="ngx_http_upstream_module.xml" id="server">http</link> -or -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> -“<literal>server</literal>” directive). -</para> - -<para> -For example, to add a new primary server, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 -</example> - -To add a new backup server, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 -</example> - -To add a new primary server, -set its parameters to non-default values -and mark it as “<literal>down</literal>”, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= -</example> - -To remove a server, specify its ID: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 -</example> - -To mark an existing server as “<literal>down</literal>”, send: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= -</example> - -To modify the address of an existing server, send: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 -</example> - -To modify other parameters of an existing server, send: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 -</example> - -The above examples are for an -<link doc="ngx_http_upstream_module.xml">http</link> -upstream server group. -Similar examples for a -<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> -upstream server group require the “<literal>stream=</literal>” parameter. -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/http/ngx_http_upstream_hc_module.xml +++ /dev/null @@ -1,409 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_upstream_hc_module" - link="/en/docs/http/ngx_http_upstream_hc_module.html" - lang="en" - rev="5"> - -<section id="summary"> - -<para> -The <literal>ngx_http_upstream_hc_module</literal> module -allows enabling periodic health checks of the servers in a -<link doc="ngx_http_upstream_module.xml" id="upstream">group</link> -referenced in the surrounding location. -The server group must reside in the -<link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>. -</para> - -<para> -If a health check fails, -the server will be considered unhealthy. -If several health checks are defined for the same group of servers, -a single failure of any check will make the corresponding server be -considered unhealthy. -Client requests are not passed to unhealthy servers -and servers in the “checking” state. -</para> - -<para> -<note> -Please note that most of the variables will have empty values -when used with health checks. -</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> -upstream dynamic { - zone upstream_dynamic 64k; - - server backend1.example.com weight=5; - server backend2.example.com:8080 fail_timeout=5s slow_start=30s; - server 192.0.2.1 max_fails=3; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://dynamic; - health_check; - } -} -</example> -With this configuration, nginx will send “<literal>/</literal>” requests to each -server in the <literal>backend</literal> group every five seconds. -If any communication error or timeout occurs, or a -proxied server responds with the status code other than -2xx or 3xx, the health check will fail, and the server will -be considered unhealthy. -</para> - -<para> -Health checks can be configured to test the status code of a response, -presence of certain header fields and their values, -and the body contents. -Tests are configured separately using the <link id="match"/> directive -and referenced in the <literal>match</literal> parameter -of the <link id="health_check"/> directive: -<example> -http { - server { - ... - location / { - proxy_pass http://backend; - health_check match=welcome; - } - } - - match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; - } -} -</example> -This configuration shows that in order for a health check to pass, the response -to a health check request should succeed, have status 200, -and contain “<literal>Welcome to nginx!</literal>” in the body. -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="health_check"> -<syntax>[<value>parameters</value>]</syntax> -<default/> -<context>location</context> - -<para> -Enables periodic health checks of the servers in a -<link doc="ngx_http_upstream_module.xml" id="upstream">group</link> -referenced in the surrounding location. -</para> - -<para> -The following optional parameters are supported: -<list type="tag"> - -<tag-name id="health_check_interval"> -<literal>interval</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the interval between two consecutive health checks, -by default, 5 seconds. -</tag-desc> - -<tag-name id="health_check_jitter"> -<literal>jitter</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the time within which -each health check will be randomly delayed, -by default, there is no delay. -</tag-desc> - -<tag-name id="health_check_fails"> -<literal>fails</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of consecutive failed health checks of a particular server -after which this server will be considered unhealthy, -by default, 1. -</tag-desc> - -<tag-name id="health_check_passes"> -<literal>passes</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of consecutive passed health checks of a particular server -after which the server will be considered healthy, -by default, 1. -</tag-desc> - -<tag-name id="health_check_uri"> -<literal>uri</literal>=<value>uri</value> -</tag-name> -<tag-desc> -defines the URI used in health check requests, -by default, “<literal>/</literal>”. -</tag-desc> - -<tag-name id="health_check_mandatory"> -<literal>mandatory</literal> [<literal>persistent</literal>] -</tag-name> -<tag-desc> -<para> -sets the initial “checking” state for a server -until the first health check is completed (1.11.7). -Client requests are not passed to servers in the “checking” state. -If the parameter is not specified, -the server will be initially considered healthy. -</para> - -<para id="health_check_persistent"> -The <literal>persistent</literal> parameter (1.19.7) -sets the initial “up” state for a server after reload -if the server was considered healthy before reload. -</para> - -</tag-desc> - -<tag-name id="health_check_match"> -<literal>match</literal>=<value>name</value> -</tag-name> -<tag-desc> -specifies the <literal>match</literal> block configuring the tests that a -response should pass in order for a health check to pass. -By default, the response should have status code 2xx or 3xx. -</tag-desc> - -<tag-name id="health_check_port"> -<literal>port</literal>=<value>number</value> -</tag-name> -<tag-desc> -defines the port used when connecting to a server -to perform a health check (1.9.7). -By default, equals the -<link doc="ngx_http_upstream_module.xml" id="server"/> port. -</tag-desc> - -<tag-name id="health_check_grpc"> -<literal>type</literal>=<literal>grpc</literal> -[<literal>grpc_service</literal>=<value>name</value>] -[<literal>grpc_status</literal>=<value>code</value>] -</tag-name> -<tag-desc> -enables periodic -<link url="https://github.com/grpc/grpc/blob/master/doc/health-checking.md#grpc-health-checking-protocol">health -checks</link> of a gRPC server -or a particular gRPC service specified with the optional -<literal>grpc_service</literal> parameter (1.19.5). -If the server does not support the gRPC Health Checking Protocol, -the optional <literal>grpc_status</literal> parameter can be used -to specify non-zero gRPC -<link url="https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc">status</link> -(for example, -status code “<literal>12</literal>” / “<literal>UNIMPLEMENTED</literal>”) -that will be treated as healthy: -<example> -health_check mandatory type=grpc grpc_status=12; -</example> -The <literal>type</literal>=<literal>grpc</literal> parameter -must be specified after all other directive parameters, -<literal>grpc_service</literal> and <literal>grpc_status</literal> -must follow <literal>type</literal>=<literal>grpc</literal>. -The parameter is not compatible with -<link id="health_check_uri"><literal>uri</literal></link> or -<link id="health_check_match"><literal>match</literal></link> parameters. -</tag-desc> - -<tag-name id="health_check_keepalive_time"> -<literal>keepalive_time</literal>=<value>time</value> -</tag-name> -<tag-desc> -enables <link doc="ngx_http_upstream_module.xml" id="keepalive">keepalive</link> -connections for health checks and specifies the time during which -requests can be processed through one keepalive connection (1.21.7). -By default keepalive connections are disabled. -</tag-desc> - -</list> -</para> - -</directive> - - -<directive name="match"> -<syntax block="yes"><value>name</value></syntax> -<default/> -<context>http</context> - -<para> -Defines the named test set used to verify responses to health check requests. -</para> - -<para> -The following items can be tested in a response: -<list type="tag"> - -<tag-name><literal>status 200;</literal></tag-name> -<tag-desc>status is 200</tag-desc> - -<tag-name><literal>status ! 500;</literal></tag-name> -<tag-desc>status is not 500</tag-desc> - -<tag-name><literal>status 200 204;</literal></tag-name> -<tag-desc>status is 200 or 204</tag-desc> - -<tag-name><literal>status ! 301 302;</literal></tag-name> -<tag-desc>status is neither 301 nor 302</tag-desc> - -<tag-name><literal>status 200-399;</literal></tag-name> -<tag-desc>status is in the range from 200 to 399</tag-desc> - -<tag-name><literal>status ! 400-599;</literal></tag-name> -<tag-desc>status is not in the range from 400 to 599</tag-desc> - -<tag-name><literal>status 301-303 307;</literal></tag-name> -<tag-desc>status is either 301, 302, 303, or 307</tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>header Content-Type = text/html;</literal></tag-name> -<tag-desc> -header contains <header>Content-Type</header> -with value <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Content-Type != text/html;</literal></tag-name> -<tag-desc> -header contains <header>Content-Type</header> -with value other than <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Connection ~ close;</literal></tag-name> -<tag-desc> -header contains <header>Connection</header> -with value matching regular expression <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Connection !~ close;</literal></tag-name> -<tag-desc> -header contains <header>Connection</header> -with value not matching regular expression <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Host;</literal></tag-name> -<tag-desc>header contains <header>Host</header></tag-desc> - -<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name> -<tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -body matches regular expression “<literal>Welcome to nginx!</literal>” -</tag-desc> - -<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -body does not match regular expression “<literal>Welcome to nginx!</literal>” -</tag-desc> - -</list> - -<list type="tag"> - -<tag-name id="match_require"><literal>require</literal> - <value>$variable</value> - <literal>...;</literal></tag-name> -<tag-desc> -all specified variables are not empty and not equal to “0” (1.15.9). -</tag-desc> - -</list> -</para> - -<para> -If several tests are specified, -the response matches only if it matches all tests. -<note> -Only the first 256k of the response body are examined. -</note> -</para> - -<para> -Examples: -<example> -# status is 200, content type is "text/html", -# and body contains "Welcome to nginx!" -match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; -} -</example> - -<example> -# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:" -match not_redirect { - status ! 301-303 307; - header ! Refresh; -} -</example> - -<example> -# status ok and not in maintenance mode -match server_ok { - status 200-399; - body !~ "maintenance mode"; -} -</example> - -<example> -# status is 200 or 204 -map $upstream_status $good_status { - 200 1; - 204 1; -} - -match server_ok { - require $good_status; -} -</example> - -</para> - -</directive> - -</section> - -</module>
--- 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="88"> + rev="89"> <section id="summary"> @@ -49,36 +49,6 @@ server { </example> </para> -<para> -Dynamically configurable group with -periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is -available as part of our -<commercial_version>commercial subscription</commercial_version>: -<example> -resolver 10.0.0.1; - -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; - - server backend1.example.com weight=5; - server backend2.example.com:8080 fail_timeout=5s slow_start=30s; - server 192.0.2.1 max_fails=3; - server backend3.example.com resolve; - server backend4.example.com service=http resolve; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://<emphasis>dynamic</emphasis>; - health_check; - } -} -</example> -</para> - </section> @@ -168,11 +138,6 @@ and the <link id="zone">shared memory</l the total number of active and idle connections to the proxied server may exceed the <literal>max_conns</literal> value. </note> -<note> -Since version 1.5.9 and prior to version 1.11.5, -this parameter was available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> </tag-desc> <tag-name id="max_fails"> @@ -239,117 +204,9 @@ marks the server as permanently unavaila </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -<list type="tag"> - -<tag-name id="resolve"> -<literal>resolve</literal> -</tag-name> -<tag-desc> -monitors changes of the IP addresses -that correspond to a domain name of the server, -and automatically modifies the upstream configuration -without the need of restarting nginx (1.5.12). -The server group must reside in the <link id="zone">shared memory</link>. -<para> -In order for this parameter to work, -the <literal>resolver</literal> directive -must be specified in the -<link doc="ngx_http_core_module.xml" id="resolver">http</link> block -or in the corresponding <link id="resolver">upstream</link> block. -</para> -</tag-desc> - -<tag-name id="route"> -<literal>route</literal>=<value>string</value> -</tag-name> -<tag-desc> -sets the server route name. -</tag-desc> - -<tag-name id="service"> -<literal>service</literal>=<value>name</value> -</tag-name> -<tag-desc> -enables resolving of DNS -<link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link> -records and sets the service <value>name</value> (1.9.13). -In order for this parameter to work, it is necessary to specify -the <link id="resolve"/> parameter for the server -and specify a hostname without a port number. -<para> -If the service name does not contain a dot (“<literal>.</literal>”), then -the <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>-compliant name -is constructed -and the TCP protocol is added to the service prefix. -For example, to look up the -<literal>_http._tcp.backend.example.com</literal> SRV record, -it is necessary to specify the directive: -<example> -server backend.example.com service=http resolve; -</example> -If the service name contains one or more dots, then the name is constructed -by joining the service prefix and the server name. -For example, to look up the <literal>_http._tcp.backend.example.com</literal> -and <literal>server1.backend.example.com</literal> SRV records, -it is necessary to specify the directives: -<example> -server backend.example.com service=_http._tcp resolve; -server example.com service=server1.backend resolve; -</example> -</para> - -<para> -Highest-priority SRV records -(records with the same lowest-number priority value) -are resolved as primary servers, -the rest of SRV records are resolved as backup servers. -If the <link id="backup"/> parameter is specified for the server, -high-priority SRV records are resolved as backup servers, -the rest of SRV records are ignored. -</para> -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the <value>time</value> during which the server will recover its weight -from zero to a nominal value, when unhealthy server becomes -<link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>, -or when the server becomes available after a period of time -it was considered <link id="fail_timeout">unavailable</link>. -Default value is zero, i.e. slow start is disabled. <note> -The parameter cannot be used along with the -<link id="hash"/>, <link id="ip_hash"/>, and <link id="random"/> -load balancing methods. -</note> -</tag-desc> - -<tag-name id="drain"> -<literal>drain</literal> -</tag-name> -<tag-desc> -puts the server into the “draining” mode (1.13.6). -In this mode, only requests <link id="sticky">bound</link> to the server -will be proxied to it. -<note> -Prior to version 1.13.6, -the parameter could be changed only with the -<link doc="ngx_http_api_module.xml">API</link> module. -</note> -</tag-desc> - -</list> -</para> - -<para> -<note> -If there is only a single server in a group, <literal>max_fails</literal>, -<literal>fail_timeout</literal> and <literal>slow_start</literal> parameters +If there is only a single server in a group, +<literal>max_fails</literal> and <literal>fail_timeout</literal> parameters are ignored, and such a server will never be considered unavailable. </note> </para> @@ -371,70 +228,6 @@ Several groups may share the same zone. In this case, it is enough to specify the <value>size</value> only once. </para> -<para> -Additionally, -as part of our <commercial_version>commercial subscription</commercial_version>, -such groups allow changing the group membership -or modifying the settings of a particular server -without the need of restarting nginx. -The configuration is accessible via the -<link doc="ngx_http_api_module.xml">API</link> module (1.13.3). -<note> -Prior to version 1.13.3, -the configuration was accessible only via a special location -handled by -<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. -</note> -</para> - -</directive> - - -<directive name="state"> -<syntax><value>file</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.9.7</appeared-in> - -<para> -Specifies a <value>file</value> that keeps the state -of the dynamically configurable group. -</para> - -<para> -Examples: -<example> -state /var/lib/nginx/state/servers.conf; # path for Linux -state /var/db/nginx/state/servers.conf; # path for FreeBSD -</example> -</para> - -<para> -The state is currently limited to the list of servers with their parameters. -The file is read when parsing the configuration and is updated each time -the upstream configuration is -<link doc="ngx_http_api_module.xml" id="http_upstreams_http_upstream_name_servers_">changed</link>. -Changing the file content directly should be avoided. -The directive cannot be used -along with the <link id="server"/> directive. -</para> - -<para> -<note> -Changes made during -<link doc="../control.xml" id="reconfiguration">configuration reload</link> -or <link doc="../control.xml" id="upgrade">binary upgrade</link> -can be lost. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> @@ -695,68 +488,6 @@ connection to an upstream server will st </directive> -<directive name="ntlm"> -<syntax/> -<default/> -<context>upstream</context> -<appeared-in>1.9.2</appeared-in> - -<para> -Allows proxying requests with -<link url="https://en.wikipedia.org/wiki/Integrated_Windows_Authentication">NTLM -Authentication</link>. -The upstream connection is bound to the client connection -once the client sends a request with the <header>Authorization</header> -header field value -starting with “<literal>Negotiate</literal>” or “<literal>NTLM</literal>”. -Further client requests will be proxied through the same upstream connection, -keeping the authentication context. -</para> - -<para> -In order for NTLM authentication to work, -it is necessary to enable keepalive connections to upstream servers. -The <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/> -directive should be set to “<literal>1.1</literal>” -and the <header>Connection</header> header field should be cleared: -<example> -upstream http_backend { - server 127.0.0.1:8080; - - ntlm; -} - -server { - ... - - location /http/ { - proxy_pass http://http_backend; - proxy_http_version 1.1; - proxy_set_header Connection ""; - ... - } -} -</example> -</para> - -<para> -<note> -When using load balancer methods other than the default -round-robin method, it is necessary to activate them before -the <literal>ntlm</literal> directive. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="least_conn"> <syntax/> <default/> @@ -775,88 +506,6 @@ weighted round-robin balancing method. </directive> -<directive name="least_time"> -<syntax> - <literal>header</literal> | - <literal>last_byte</literal> - [<literal>inflight</literal>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.7.10</appeared-in> - -<para> -Specifies that a group should use a load balancing method where a request -is passed to the server with the least average response time and -least number of active connections, taking into account weights of servers. -If there are several such servers, they are tried in turn using a -weighted round-robin balancing method. -</para> - -<para> -If the <literal>header</literal> parameter is specified, -time to receive the -<link id="var_upstream_header_time">response header</link> is used. -If the <literal>last_byte</literal> parameter is specified, -time to receive the <link id="var_upstream_response_time">full response</link> -is used. -If the <literal>inflight</literal> parameter is specified (1.11.6), -incomplete requests are also taken into account. -<note> -Prior to version 1.11.6, incomplete requests were taken into account by default. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="queue"> -<syntax> -<value>number</value> -[<literal>timeout</literal>=<value>time</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.12</appeared-in> - -<para> -If an upstream server cannot be selected immediately -while processing a request, -the request will be placed into the queue. -The directive specifies the maximum <value>number</value> of requests -that can be in the queue at the same time. -If the queue is filled up, -or the server to pass the request to cannot be selected within -the time period specified in the <literal>timeout</literal> parameter, -the <http-status code="502" text="Bad Gateway"/> -error will be returned to the client. -</para> - -<para> -The default value of the <literal>timeout</literal> parameter is 60 seconds. -</para> - -<para> -<note> -When using load balancer methods other than the default -round-robin method, it is necessary to activate them before -the <literal>queue</literal> directive. -</note> - -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="random"> <syntax>[<literal>two</literal> [<value>method</value>]]</syntax> <default/> @@ -880,379 +529,6 @@ which passes a request to a server with the least number of active connections. </para> -<para id="random_least_time"> -The <literal>least_time</literal> method passes a request to a server -with the least average response time and least number of active connections. -If <literal>least_time=header</literal> is specified, the time to receive the -<link id="var_upstream_header_time">response header</link> is used. -If <literal>least_time=last_byte</literal> is specified, the time to receive the -<link id="var_upstream_response_time">full response</link> is used. -<note> -The <literal>least_time</literal> method is available as a part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="resolver"> -<syntax> - <value>address</value> ... - [<literal>valid</literal>=<value>time</value>] - [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<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 IPv4 or IPv6 addresses is not desired, -the <literal>ipv4=off</literal> (1.23.1) or -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> - [<literal>expires=</literal><value>time</value>] - [<literal>domain=</literal><value>domain</value>] - [<literal>httponly</literal>] - [<literal>samesite=</literal><literal>strict</literal>|<literal>lax</literal>|<literal>none</literal>|<value>$variable</value>] - [<literal>secure</literal>] - [<literal>path=</literal><value>path</value>]</syntax> -<syntax> - <literal>route</literal> <value>$variable</value> ...</syntax> -<syntax> - <literal>learn</literal> - <literal>create=</literal><value>$variable</value> - <literal>lookup=</literal><value>$variable</value> - <literal>zone=</literal><value>name</value>:<value>size</value> - [<literal>timeout=</literal><value>time</value>] - [<literal>header</literal>] - [<literal>sync</literal>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Enables session affinity, which causes requests from the same client to be -passed to the same server in a group of servers. -Three methods are available: -<list type="tag"> -<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name> -<tag-desc> - -<para> -When the <literal>cookie</literal> method is used, information about the -designated server is passed in an HTTP cookie generated by nginx: -<example> -upstream backend { - server backend1.example.com; - server backend2.example.com; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -</para> - -<para> -A request that comes from a client not yet bound to a particular server -is passed to the server selected by the configured balancing method. -Further requests with this cookie will be passed to the designated server. -If the designated server cannot process a request, the new server is -selected as if the client has not been bound yet. - -<note> -As a load balancing method always tries to evenly distribute the load -considering already bound requests, -the server with a higher number of active bound requests -has less possibility of getting new unbound requests. -</note> -</para> - -<para> -The first parameter sets the name of the cookie to be set or inspected. -The cookie value is -a hexadecimal representation of the MD5 hash of the IP address and port, -or of the UNIX-domain socket path. -However, if the “<literal>route</literal>” parameter of the -<link id="server"/> directive is specified, the cookie value will be -the value of the “<literal>route</literal>” parameter: -<example> -upstream backend { - server backend1.example.com route=<emphasis>a</emphasis>; - server backend2.example.com route=<emphasis>b</emphasis>; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -In this case, the value of the “<literal>srv_id</literal>” cookie will be -either <value>a</value> or <value>b</value>. -</para> - -<para> -Additional parameters may be as follows: -<list type="tag"> - -<tag-name><literal>expires=</literal><value>time</value></tag-name> -<tag-desc> -Sets the <value>time</value> for which a browser should keep the cookie. -The special value <literal>max</literal> will cause the cookie to expire on -“<literal>31 Dec 2037 23:55:55 GMT</literal>”. -If the parameter is not specified, it will cause the cookie to expire at -the end of a browser session. -</tag-desc> - -<tag-name><literal>domain=</literal><value>domain</value></tag-name> -<tag-desc> -Defines the <value>domain</value> for which the cookie is set. -Parameter value can contain variables (1.11.5). -</tag-desc> - -<tag-name><literal>httponly</literal></tag-name> -<tag-desc> -Adds the <literal>HttpOnly</literal> attribute to the cookie (1.7.11). -</tag-desc> - -<tag-name id="sticky_samesite"><literal>samesite=</literal><literal>strict</literal> | -<literal>lax</literal> | <literal>none</literal> | <value>$variable</value></tag-name> -<tag-desc> -Adds the <literal>SameSite</literal> (1.19.4) attribute to the cookie -with one of the following values: -<literal>Strict</literal>, -<literal>Lax</literal>, -<literal>None</literal>, or -using variables (1.23.3). -In the latter case, if the variable value is empty, -the <literal>SameSite</literal> attribute will not be added to the cookie, -if the value is resolved to -<literal>Strict</literal>, -<literal>Lax</literal>, or -<literal>None</literal>, -the corresponding value will be assigned, -otherwise the <literal>Strict</literal> value will be assigned. -</tag-desc> - -<tag-name><literal>secure</literal></tag-name> -<tag-desc> -Adds the <literal>Secure</literal> attribute to the cookie (1.7.11). -</tag-desc> - -<tag-name><literal>path=</literal><value>path</value></tag-name> -<tag-desc> -Defines the <value>path</value> for which the cookie is set. -</tag-desc> - -</list> -If any parameters are omitted, the corresponding cookie fields are not set. -</para> -</tag-desc> - -<tag-name id="sticky_route"><literal>route</literal></tag-name> -<tag-desc> - -<para> -When the <literal>route</literal> method is used, proxied server assigns -client a route on receipt of the first request. -All subsequent requests from this client will carry routing information -in a cookie or URI. -This information is compared with the “<literal>route</literal>” parameter -of the <link id="server"/> directive to identify the server to which the -request should be proxied. -If the “<literal>route</literal>” parameter is not specified, the route name -will be a hexadecimal representation of the MD5 hash of the IP address and port, -or of the UNIX-domain socket path. -If the designated server cannot process a request, the new server is -selected by the configured balancing method as if there is no routing -information in the request. -</para> - -<para> -The parameters of the <literal>route</literal> method specify variables that -may contain routing information. -The first non-empty variable is used to find the matching server. -</para> - -<para> -Example: -<example> -map $cookie_jsessionid $route_cookie { - ~.+\.(?P<route>\w+)$ $route; -} - -map $request_uri $route_uri { - ~jsessionid=.+\.(?P<route>\w+)$ $route; -} - -upstream backend { - server backend1.example.com route=a; - server backend2.example.com route=b; - - sticky route $route_cookie $route_uri; -} -</example> -Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie -if present in a request. -Otherwise, the route from the URI is used. -</para> - -</tag-desc> - -<tag-name id="sticky_learn"><literal>learn</literal></tag-name> -<tag-desc> -<para> -When the <literal>learn</literal> method (1.7.1) is used, nginx -analyzes upstream server responses and learns server-initiated sessions -usually passed in an HTTP cookie. -<example> -upstream backend { - server backend1.example.com:8080; - server backend2.example.com:8081; - - sticky learn - create=$upstream_cookie_examplecookie - lookup=$cookie_examplecookie - zone=client_sessions:1m; -} -</example> - -In the example, the upstream server creates a session by setting the -cookie “<literal>EXAMPLECOOKIE</literal>” in the response. -Further requests with this cookie will be passed to the same server. -If the server cannot process the request, the new server is -selected as if the client has not been bound yet. -</para> - -<para> -The parameters <literal>create</literal> and <literal>lookup</literal> -specify variables that indicate how new sessions are created and existing -sessions are searched, respectively. -Both parameters may be specified more than once, in which case the first -non-empty variable is used. -</para> - -<para> -Sessions are stored in a shared memory zone, whose <value>name</value> and -<value>size</value> are configured by the <literal>zone</literal> parameter. -One megabyte zone can store about 4000 sessions on the 64-bit platform. -The sessions that are not accessed during the time specified by the -<literal>timeout</literal> parameter get removed from the zone. -By default, <literal>timeout</literal> is set to 10 minutes. -</para> - -<para id="sticky_learn_header"> -The <literal>header</literal> parameter (1.13.1) allows creating a session -right after receiving response headers from the upstream server. -</para> - -<para id="sticky_learn_sync"> -The <literal>sync</literal> parameter (1.13.8) enables -<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link> -of the shared memory zone. -</para> - -</tag-desc> -</list> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky_cookie_insert"> -<syntax><value>name</value> -[<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>domain</value>] -[<literal>path=</literal><value>path</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -This directive is obsolete since version 1.5.7. -An equivalent -<link id="sticky"/> directive with a new syntax should be used instead: -<note> -<literal>sticky cookie</literal> <value>name</value> -[<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>domain</value>] -[<literal>path=</literal><value>path</value>]; -</note> -</para> - </directive> </section> @@ -1349,25 +625,6 @@ as for the variables that start with the Only the header fields from the response of the last server are saved. </tag-desc> -<tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name> -<tag-desc> -keeps the name of last selected upstream server (1.25.3); -allows passing it -<link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">through SNI</link>: -<example> -proxy_ssl_server_name on; -proxy_ssl_name $upstream_last_server_name; -</example> - -<para> -<note> -This variable is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</tag-desc> - <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> <tag-desc> keeps time the request spent in the upstream <link id="queue">queue</link>
--- a/xml/en/docs/http/ngx_http_uwsgi_module.xml +++ b/xml/en/docs/http/ngx_http_uwsgi_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_uwsgi_module" link="/en/docs/http/ngx_http_uwsgi_module.html" lang="en" - rev="50"> + rev="51"> <section id="summary"> @@ -383,11 +383,7 @@ will be cached. [<literal>manager_threshold</literal>=<value>time</value>] [<literal>loader_files</literal>=<value>number</value>] [<literal>loader_sleep</literal>=<value>time</value>] - [<literal>loader_threshold</literal>=<value>time</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>number</value>] - [<literal>purger_sleep</literal>=<value>time</value>] - [<literal>purger_threshold</literal>=<value>time</value>]</syntax> + [<literal>loader_threshold</literal>=<value>time</value>]</syntax> <default/> <context>http</context> @@ -433,15 +429,6 @@ In addition, all active keys and informa in a shared memory zone, whose <value>name</value> and <value>size</value> are configured by the <literal>keys_zone</literal> parameter. One megabyte zone can store about 8 thousand keys. -<note> -As part of -<commercial_version>commercial subscription</commercial_version>, -the shared memory zone also stores extended -cache <link doc="ngx_http_api_module.xml" id="http_caches_">information</link>, -thus, it is required to specify a larger zone size for the same number of keys. -For example, -one megabyte zone can store about 4 thousand keys. -</note> </para> <para> @@ -485,56 +472,6 @@ parameter (by default, 50 milliseconds) </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Instructs whether cache entries that match a -<link id="uwsgi_cache_purge">wildcard key</link> -will be removed from the disk by the cache purger (1.7.12). -Setting the parameter to <literal>on</literal> -(default is <literal>off</literal>) -will activate the “cache purger” process that -permanently iterates through all cache entries -and deletes the entries that match the wildcard key. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the number of items that will be scanned during one iteration (1.7.12). -By default, <literal>purger_files</literal> is set to 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets the duration of one iteration (1.7.12). -By default, <literal>purger_threshold</literal> is set to 50 milliseconds. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>number</value> -</tag-name> -<tag-desc> -Sets a pause between iterations (1.7.12). -By default, <literal>purger_sleep</literal> is set to 50 milliseconds. -</tag-desc> - -</list> -</para> - -<para> <note> In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid @@ -545,63 +482,6 @@ after upgrading to a newer nginx version </directive> -<directive name="uwsgi_cache_purge"> -<syntax>string ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Defines conditions under which the request will be considered a cache -purge request. -If at least one value of the string parameters is not empty and is not equal -to “0” then the cache entry with a corresponding -<link id="uwsgi_cache_key">cache key</link> is removed. -The result of successful operation is indicated by returning -the <http-status code="204" text="No Content"/> response. -</para> - -<para> -If the <link id="uwsgi_cache_key">cache key</link> of a purge request ends -with an asterisk (“<literal>*</literal>”), all cache entries matching the -wildcard key will be removed from the cache. -However, these entries will remain on the disk until they are deleted -for either <link id="uwsgi_cache_path">inactivity</link>, -or processed by the <link id="purger">cache purger</link> (1.7.12), -or a client attempts to access them. -</para> - -<para> -Example configuration: -<example> -uwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - uwsgi_pass backend; - uwsgi_cache cache_zone; - uwsgi_cache_key $uri; - uwsgi_cache_purge $purge_method; - } -} -</example> -<note> -This functionality is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="uwsgi_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="49" + rev="50" toc="no"> @@ -219,21 +219,11 @@ ngx_http_addition_module</link> </listitem> <listitem> -<link doc="http/ngx_http_api_module.xml"> -ngx_http_api_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_auth_basic_module.xml"> ngx_http_auth_basic_module</link> </listitem> <listitem> -<link doc="http/ngx_http_auth_jwt_module.xml"> -ngx_http_auth_jwt_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_auth_request_module.xml"> ngx_http_auth_request_module</link> </listitem> @@ -264,11 +254,6 @@ ngx_http_empty_gif_module</link> </listitem> <listitem> -<link doc="http/ngx_http_f4f_module.xml"> -ngx_http_f4f_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_fastcgi_module.xml"> ngx_http_fastcgi_module</link> </listitem> @@ -314,11 +299,6 @@ ngx_http_headers_module</link> </listitem> <listitem> -<link doc="http/ngx_http_hls_module.xml"> -ngx_http_hls_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_image_filter_module.xml"> ngx_http_image_filter_module</link> </listitem> @@ -329,21 +309,11 @@ ngx_http_index_module</link> </listitem> <listitem> -<link doc="http/ngx_http_internal_redirect_module.xml"> -ngx_http_internal_redirect_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_js_module.xml"> ngx_http_js_module</link> </listitem> <listitem> -<link doc="http/ngx_http_keyval_module.xml"> -ngx_http_keyval_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_limit_conn_module.xml"> ngx_http_limit_conn_module</link> </listitem> @@ -389,11 +359,6 @@ ngx_http_proxy_module</link> </listitem> <listitem> -<link doc="http/ngx_http_proxy_protocol_vendor_module.xml"> -ngx_http_proxy_protocol_vendor_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_random_index_module.xml"> ngx_http_random_index_module</link> </listitem> @@ -424,11 +389,6 @@ ngx_http_secure_link_module</link> </listitem> <listitem> -<link doc="http/ngx_http_session_log_module.xml"> -ngx_http_session_log_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_slice_module.xml"> ngx_http_slice_module</link> </listitem> @@ -449,11 +409,6 @@ ngx_http_ssl_module</link> </listitem> <listitem> -<link doc="http/ngx_http_status_module.xml"> -ngx_http_status_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_stub_status_module.xml"> ngx_http_stub_status_module</link> </listitem> @@ -469,16 +424,6 @@ ngx_http_upstream_module</link> </listitem> <listitem> -<link doc="http/ngx_http_upstream_conf_module.xml"> -ngx_http_upstream_conf_module</link> -</listitem> - -<listitem> -<link doc="http/ngx_http_upstream_hc_module.xml"> -ngx_http_upstream_hc_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_userid_module.xml"> ngx_http_userid_module</link> </listitem> @@ -581,11 +526,6 @@ ngx_stream_js_module</link> </listitem> <listitem> -<link doc="stream/ngx_stream_keyval_module.xml"> -ngx_stream_keyval_module</link> -</listitem> - -<listitem> <link doc="stream/ngx_stream_limit_conn_module.xml"> ngx_stream_limit_conn_module</link> </listitem> @@ -601,26 +541,11 @@ ngx_stream_map_module</link> </listitem> <listitem> -<link doc="stream/ngx_stream_mqtt_preread_module.xml"> -ngx_stream_mqtt_preread_module</link> -</listitem> - -<listitem> -<link doc="stream/ngx_stream_mqtt_filter_module.xml"> -ngx_stream_mqtt_filter_module</link> -</listitem> - -<listitem> <link doc="stream/ngx_stream_proxy_module.xml"> ngx_stream_proxy_module</link> </listitem> <listitem> -<link doc="stream/ngx_stream_proxy_protocol_vendor_module.xml"> -ngx_stream_proxy_protocol_vendor_module</link> -</listitem> - -<listitem> <link doc="stream/ngx_stream_realip_module.xml"> ngx_stream_realip_module</link> </listitem> @@ -655,16 +580,6 @@ ngx_stream_ssl_preread_module</link> ngx_stream_upstream_module</link> </listitem> -<listitem> -<link doc="stream/ngx_stream_upstream_hc_module.xml"> -ngx_stream_upstream_hc_module</link> -</listitem> - -<listitem> -<link doc="stream/ngx_stream_zone_sync_module.xml"> -ngx_stream_zone_sync_module</link> -</listitem> - </list> </para> @@ -676,16 +591,6 @@ ngx_stream_zone_sync_module</link> ngx_google_perftools_module</link> </listitem> -<listitem> -<link doc="ngx_mgmt_module.xml"> -ngx_mgmt_module</link> -</listitem> - -<listitem> -<link doc="ngx_otel_module.xml"> -ngx_otel_module</link> -</listitem> - </list> </para>
--- a/xml/en/docs/mail/ngx_mail_core_module.xml +++ b/xml/en/docs/mail/ngx_mail_core_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_mail_core_module" link="/en/docs/mail/ngx_mail_core_module.html" lang="en" - rev="21"> + rev="22"> <section id="summary"> @@ -314,8 +314,7 @@ parameters <literal>--without-mail_imap_ <value>address</value> ... [<literal>valid</literal>=<value>time</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>zone</value>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <syntax><literal>off</literal></syntax> <default>off</default> <context>mail</context> @@ -370,16 +369,6 @@ configuring DNS servers in a properly se </note> </para> -<para id="resolver_status_zone"> -The optional <literal>status_zone</literal> parameter (1.17.1) -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>. -The parameter is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</para> - <para id="resolver_off"> The special value <literal>off</literal> disables resolving. </para>
deleted file mode 100644 --- a/xml/en/docs/ngx_mgmt_module.xml +++ /dev/null @@ -1,407 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../dtd/module.dtd"> - -<module name="Module ngx_mgmt_module" - link="/en/docs/ngx_mgmt_module.html" - lang="en" - rev="2"> - -<section id="summary"> - -<para> -The <literal>ngx_mgmt_module</literal> module enables reporting of -current nginx installation to -<link url="https://docs.nginx.com/nginx-management-suite/about/">NGINX -Management Suite Instance Manager</link> (1.25.3). -By default, nginx sends usage info -to the Instance Manager located at <literal>nginx-mgmt.local</literal> -every 30 minutes using the SSL connection. -The system resolver is used unless -a <link id="resolver">custom resolver</link> is configured -and is invoked only once when the -configuration is <link doc="beginners_guide.xml" id="control">loaded</link>. -</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> -mgmt { - usage_report endpoint=nginx-mgmt.local interval=30m; - resolver DNS_IP; - - uuid_file /var/lib/nginx/nginx.id; - - ssl_protocols TLSv1.2 TLSv1.3; - ssl_ciphers DEFAULT; - - ssl_certificate client_cert.pem; - ssl_certificate_key client_cert.key; - - # configure server certificate verification - # to validate the authenticity of NMS - ssl_trusted_certificate trusted_ca_cert.crt; - ssl_verify on; - ssl_verify_depth 2; -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="connect_timeout"> -<syntax><value>time</value></syntax> -<default>15s</default> -<context>mgmt</context> - -<para> -Defines a timeout for establishing a connection with the Instance Manager. -</para> - -</directive> - - -<directive name="mgmt"> -<syntax block="yes"/> -<default/> -<context>main</context> - -<para> -Provides the configuration file context -in which the management server directives are specified. -</para> - -</directive> - - -<directive name="read_timeout"> -<syntax><value>time</value></syntax> -<default>60s</default> -<context>mgmt</context> - -<para> -Defines a timeout for reading a response from the Instance Manager. -The timeout is set only between two successive read operations, -not for the transmission of the whole response. -If the Instance Manager does not transmit anything within this time, -the connection is closed. -</para> - -</directive> - - -<directive name="resolver"> -<syntax> - <value>address</value> ... - [<literal>valid</literal>=<value>time</value>] - [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>zone</value>]</syntax> -<default/> -<context>mgmt</context> - -<para> -Configures name servers used to resolve names of the Instance Manager -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 IPv4 or IPv6 addresses is not desired, -the <literal>ipv4=off</literal> or -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> - -</directive> - - -<directive name="resolver_timeout"> -<syntax><value>time</value></syntax> -<default>30s</default> -<context>mgmt</context> - -<para> -Sets a timeout for name resolution. -</para> - -</directive> - - -<directive name="send_timeout"> -<syntax><value>time</value></syntax> -<default>60s</default> -<context>mgmt</context> - -<para> -Sets a timeout for transmitting a request to the Instance Manager. -The timeout is set only between two successive write operations, -not for the transmission of the whole request. -If the Instance Manager does not receive anything within this time, -the connection is closed. -</para> - -</directive> - - -<directive name="ssl"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>on</default> -<context>mgmt</context> - -<para> -Enables the HTTPS protocol for all -connections to the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_certificate"> -<syntax><value>file</value></syntax> -<default/> -<context>mgmt</context> - -<para> -Specifies a <value>file</value> with the certificate in the PEM format -used for authentication to the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_certificate_key"> -<syntax><value>file</value></syntax> -<default/> -<context>mgmt</context> - -<para> -Specifies a <value>file</value> with the secret key in the PEM format -used for authentication to the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_ciphers"> -<syntax><value>ciphers</value></syntax> -<default>DEFAULT</default> -<context>mgmt</context> - -<para> -Specifies the enabled ciphers for requests to the Instance Manager. -The ciphers are specified in the format understood by the OpenSSL library. -</para> - -<para> -The full list can be viewed using the -“<command>openssl ciphers</command>” command. -</para> - -</directive> - - -<directive name="ssl_crl"> -<syntax><value>file</value></syntax> -<default/> -<context>mgmt</context> - -<para> -Specifies a <value>file</value> with revoked certificates (CRL) -in the PEM format used to <link id="ssl_verify">verify</link> -the certificate of the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_name"> -<syntax><value>name</value></syntax> -<default>ssl_name host</default> -<context>mgmt</context> - -<para> -Allows overriding the server name used to -<link id="ssl_verify">verify</link> -the certificate of the Instance Manager and to be -<link id="ssl_server_name">passed through SNI</link> -when establishing a connection with the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_password_file"> -<syntax><value>file</value></syntax> -<default/> -<context>mgmt</context> - -<para> -Specifies a <value>file</value> with passphrases for -<link id="ssl_certificate_key">secret keys</link> -where each passphrase is specified on a separate line. -Passphrases are tried in turn when loading the key. -</para> - -</directive> - - -<directive name="ssl_protocols"> -<syntax> - [<literal>SSLv2</literal>] - [<literal>SSLv3</literal>] - [<literal>TLSv1</literal>] - [<literal>TLSv1.1</literal>] - [<literal>TLSv1.2</literal>] - [<literal>TLSv1.3</literal>]</syntax> -<default>TLSv1 TLSv1.1 TLSv1.2 TLSv1.3</default> -<context>mgmt</context> - -<para> -Enables the specified protocols for requests to the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_server_name"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>mgmt</context> - -<para> -Enables or disables passing of the server name through -<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS -Server Name Indication extension</link> (SNI, RFC 6066) -when establishing a connection with the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_trusted_certificate"> -<syntax><value>file</value></syntax> -<default/> -<context>mgmt</context> - -<para> -Specifies a <value>file</value> with trusted CA certificates in the PEM format -used to <link id="ssl_verify">verify</link> -the certificate of the Instance Manager. -</para> - -</directive> - - -<directive name="ssl_verify"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>mgmt</context> - -<para> -Enables or disables verification of the Instance Manager certificate. -</para> - -</directive> - - -<directive name="ssl_verify_depth"> -<syntax><value>number</value></syntax> -<default>1</default> -<context>mgmt</context> - -<para> -Sets the verification depth in the Instance Manager certificates chain. -</para> - -</directive> - - -<directive name="usage_report"> -<syntax> [<literal>endpoint</literal>=<value>address</value>] - [<literal>interval</literal>=<value>time</value>]</syntax> -<default/> -<context>mgmt</context> - -<para> -Sets the <value>address</value> and <value>port</value> for IP, -or the <value>path</value> for a UNIX-domain socket on which -the Instance Manager is installed, -by default <literal>nginx-mgmt.local</literal>. -The <literal>interval</literal> sets an interval between reports -to the Instance Manager, by default 30m. -</para> - -</directive> - - -<directive name="uuid_file"> -<syntax><value>file</value></syntax> -<default>logs/uuid</default> -<context>mgmt</context> - -<para> -Specifies a <value>file</value> that keeps the ID of nginx instance. -</para> - -<para> -Examples: -<example> -uuid_file /var/lib/nginx/nginx.id; # path for Linux -uuid_file /var/db/nginx/nginx.id; # path for FreeBSD -</example> -</para> - -<para> -Changing the file content directly should be avoided. -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/ngx_otel_module.xml +++ /dev/null @@ -1,347 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../dtd/module.dtd"> - -<module name="Module ngx_otel_module" - link="/en/docs/ngx_otel_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_otel_module</literal> module (1.23.4) provides -<link url="https://opentelemetry.io">OpenTelemetry</link> -distributed tracing support. -The module supports -<link url="https://w3c.github.io/trace-context">W3C</link> -context propagation and OTLP/gRPC export protocol. -</para> - -<para> -<note> -This module is available as part of our -<commercial_version>commercial subscription</commercial_version> -in <literal>nginx-plus-module-otel</literal> package. -After installation, the module can be loaded -<link doc="ngx_core_module.xml" id="load_module">dynamically</link>. -</note> -</para> - -</section> - - -<section id="example" name="Example Configuration"> - -<para> -<example> -load_module modules/ngx_otel_module.so; - -events { -} - -http { - - otel_exporter { - endpoint localhost:4317; - } - - server { - listen 127.0.0.1:8080; - - location / { - otel_trace on; - otel_trace_context inject; - - proxy_pass http://backend; - } - } -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="otel_exporter"> -<syntax block="yes"/> -<default/> -<context>http</context> - -<para> -Specifies OTel data export parameters: - -<list type="tag"> - -<tag-name id="endpoint"><literal>endpoint</literal></tag-name> -<tag-desc> -the address of OTLP/gRPC endpoint that will accept telemetry data. -</tag-desc> - -<tag-name id="interval"><literal>interval</literal></tag-name> -<tag-desc> -the maximum interval between two exports, -by default is <literal>5</literal> seconds. -</tag-desc> - -<tag-name id="batch_size"><literal>batch_size</literal></tag-name> -<tag-desc> -the maximum number of spans to be sent in one batch per worker, -by default is <literal>512</literal>. -</tag-desc> - -<tag-name id="batch_count"><literal>batch_count</literal></tag-name> -<tag-desc> -the number of pending batches per worker, -spans exceeding the limit are dropped, -by default is <literal>4</literal>. -</tag-desc> - -</list> -Example: -<example> -otel_exporter { - endpoint localhost:4317; - interval 5s; - batch_size 512; - batch_count 4; -} -</example> -</para> - -</directive> - - -<directive name="otel_service_name"> -<syntax><value>name</value></syntax> -<default>unknown_service:nginx</default> -<context>http</context> - -<para> -Sets the -“<link url="https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service"><literal>service.name</literal></link>” -attribute of the OTel resource. -</para> - -</directive> - - -<directive name="otel_trace"> -<syntax><literal>on</literal> | - <literal>off</literal> | - <literal>$variable</literal></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Enables or disables OpenTelemetry tracing. -The directive can also be enabled by specifying a variable: -<example> -split_clients "$otel_trace_id" $ratio_sampler { - 10% on; - * off; -} - -server { - location / { - otel_trace $ratio_sampler; - otel_trace_context inject; - proxy_pass http://backend; - } -} -</example> -</para> - -</directive> - - -<directive name="otel_trace_context"> -<syntax><literal>extract</literal> | - <literal>inject</literal> | - <literal>propagate</literal> | - <literal>ignore</literal></syntax> -<default>ignore</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Specifies how to propagate -<link url="https://www.w3.org/TR/trace-context/#design-overview">traceparent/tracestate</link> headers: - -<list type="tag"> - -<tag-name id="extract"><literal>extract</literal></tag-name> -<tag-desc> -uses an existing trace context from the request, -so that the identifiers of -a <link id="var_otel_trace_id">trace</link> and -the <link id="var_otel_parent_id">parent span</link> -are inherited from the incoming request. -</tag-desc> - -<tag-name id="inject"><literal>inject</literal></tag-name> -<tag-desc> -adds a new context to the request, overwriting existing headers, if any. -</tag-desc> - -<tag-name id="propagate"><literal>propagate</literal></tag-name> -<tag-desc> -updates the existing context -(combines <link id="extract"/> and <link id="inject"/>). -</tag-desc> - -<tag-name id="ignore"><literal>ignore</literal></tag-name> -<tag-desc> -skips context headers processing. -</tag-desc> - -</list> -</para> - -</directive> - - -<directive name="otel_span_name"> -<syntax><value>name</value></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Defines the name of the OTel -<link url="https://opentelemetry.io/docs/concepts/observability-primer/#spans">span</link>. -By default, it is a name of the location for a request. -The name can contain variables. -</para> - -</directive> - - -<directive name="otel_span_attr"> -<syntax><value>name</value> <value>value</value></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Adds a custom OTel span attribute. -The value can contain variables. -</para> - -</directive> - -</section> - - -<section id="span" name="Default span attributes"> - -<para> -The following <link url="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md">span attributes</link> -are added automatically: - -<list type="bullet"> - -<listitem> -<literal>http.method</literal> -</listitem> - -<listitem> -<literal>http.target</literal> -</listitem> - -<listitem> -<literal>http.route</literal> -</listitem> - -<listitem> -<literal>http.scheme</literal> -</listitem> - -<listitem> -<literal>http.flavor</literal> -</listitem> - -<listitem> -<literal>http.user_agent</literal> -</listitem> - -<listitem> -<literal>http.request_content_length</literal> -</listitem> - -<listitem> -<literal>http.response_content_length</literal> -</listitem> - -<listitem> -<literal>http.status_code</literal> -</listitem> - -<listitem> -<literal>net.host.name</literal> -</listitem> - -<listitem> -<literal>net.host.port</literal> -</listitem> - -<listitem> -<literal>net.sock.peer.addr</literal> -</listitem> - -<listitem> -<literal>net.sock.peer.port</literal> -</listitem> - -</list> -</para> - -</section> - - -<section id="variables" name="Embedded Variables"> - -<para> -<list type="tag"> - -<tag-name id="var_otel_trace_id"><var>$otel_trace_id</var></tag-name> -<tag-desc> -the identifier of the trace the current span belongs to, -for example, <literal>56552bc4daa3bf39c08362527e1dd6c4</literal> -</tag-desc> - -<tag-name id="var_otel_span_id"><var>$otel_span_id</var></tag-name> -<tag-desc> -the identifier of the current span, -for example, <literal>4c0b8531ec38ca59</literal> -</tag-desc> - -<tag-name id="var_otel_parent_id"><var>$otel_parent_id</var></tag-name> -<tag-desc> -the identifier of the parent span, -for example, <literal>dc94d281b0f884ea</literal> -</tag-desc> - -<tag-name id="var_otel_parent_sampled"><var>$otel_parent_sampled</var></tag-name> -<tag-desc> -the “<literal>sampled</literal>” flag of the parent span, -can be “<literal>1</literal>” or “<literal>0</literal>” -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/en/docs/njs/examples.xml +++ b/xml/en/docs/njs/examples.xml @@ -9,7 +9,7 @@ <article name="Examples" link="/en/docs/njs/examples.html" lang="en" - rev="21"> + rev="22"> <section id="summary"> @@ -198,72 +198,6 @@ export default {jwt_payload_sub}; <section id="http_proxying" name="HTTP Proxying"> -<section id="subrequest" name="Accessing API from a Subrequest"> - -<para> -<path>nginx.conf</path>: -<example> -js_import http.js; - -keyval_zone zone=foo:10m; -#... - -location /keyval { - js_content http.set_keyval; -} - -location /version { - js_content http.version; -} - -location /api { - api write=on; -} -</example> -</para> - -<para> -<path>http.js</path>: -<example> -async function set_keyval(r) { - let res = await r.subrequest('/api/7/http/keyvals/foo', - { method: 'POST', - body: JSON.stringify({ foo: 789, bar: "ss dd 00" })}); - - if (res.status >= 300) { - r.return(res.status, res.responseBody); - return; - } - - r.return(200); -} - -async function version(r) { - let res = await r.subrequest('/api/7/nginx', { method: 'GET' }); - - if (res.status != 200) { - r.return(res.status); - return; - } - - var json = JSON.parse(res.responseBody); - r.return(200, json.version); -} - -export default {set_keyval, version}; -</example> -<note> -The <link doc="../http/ngx_http_keyval_module.xml" id="keyval"/>, -<link doc="../http/ngx_http_keyval_module.xml" id="keyval_zone"/>, -and <link doc="../http/ngx_http_api_module.xml" id="api"/> directives -are available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</section> - - <section id="fast_response" name="Returning Fastest Response from Proxy"> <para> @@ -393,56 +327,6 @@ export default {redirect}; </section> - -<section id="requests" name="Logging the Number of Requests Per Client"> - -<para> -<path>nginx.conf</path>: -<example> -js_import http.js; - -js_set $num_requests http.num_requests; - -keyval_zone zone=foo:10m; - -keyval $remote_addr $foo zone=foo; - -log_format bar '$remote_addr [$time_local] $num_requests'; -access_log logs/access.log bar; - -server { - listen 8000; - - location / { - root html; - } -} -</example> -</para> - -<para> -<path>http.js</path>: -<example> -function num_requests(r) -{ - var n = r.variables.foo; - n = n ? Number(n) + 1 : 1; - r.variables.foo = n; - return n; -} - -export default {num_requests}; -</example> -<note> -The <link doc="../http/ngx_http_keyval_module.xml" id="keyval"/> and -<link doc="../http/ngx_http_keyval_module.xml" id="keyval_zone"/> directives -are available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</section> - </section> </article>
--- a/xml/en/docs/stream/ngx_stream_core_module.xml +++ b/xml/en/docs/stream/ngx_stream_core_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_core_module" link="/en/docs/stream/ngx_stream_core_module.html" lang="en" - rev="37"> + rev="38"> <section id="summary"> @@ -342,8 +342,7 @@ the connection is closed. <value>address</value> ... [<literal>valid</literal>=<value>time</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>zone</value>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <default/> <context>stream</context> <context>server</context> @@ -380,23 +379,6 @@ configuring DNS servers in a properly se </note> </para> -<para id="resolver_status_zone"> -The optional <literal>status_zone</literal> parameter (1.17.1) -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>. -The parameter is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</para> - -<para> -<note> -Before version 1.11.3, this directive was available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> @@ -412,10 +394,6 @@ Sets a timeout for name resolution, for <example> resolver_timeout 5s; </example> -<note> -Before version 1.11.3, this directive was available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> </para> </directive>
deleted file mode 100644 --- a/xml/en/docs/stream/ngx_stream_keyval_module.xml +++ /dev/null @@ -1,184 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_stream_keyval_module" - link="/en/docs/stream/ngx_stream_keyval_module.html" - lang="en" - rev="11"> - -<section id="summary"> - -<para> -The <literal>ngx_stream_keyval_module</literal> module (1.13.7) creates variables -with values taken from key-value pairs managed by the -<link doc="../http/ngx_http_api_module.xml" id="stream_keyvals_">API</link> -or a variable that can also be set with -<link url="https://github.com/nginx/njs-examples/">njs</link>. -</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 { - - server { - ... - location /api { - api write=on; - } - } -} - -stream { - - keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; - keyval $ssl_server_name $name zone=one; - - server { - listen 12345 ssl; - proxy_pass $name; - ssl_certificate /usr/local/nginx/conf/cert.pem; - ssl_certificate_key /usr/local/nginx/conf/cert.key; - } -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="keyval"> -<syntax> - <value>key</value> - <value>$variable</value> - <literal>zone</literal>=<value>name</value></syntax> -<default/> -<context>stream</context> - -<para> -Creates a new <value>$variable</value> whose value -is looked up by the <value>key</value> in the key-value database. -Matching rules are defined by the -<link id="keyval_type"><literal>type</literal></link> parameter of the -<link id="keyval_zone"><literal>keyval_zone</literal></link> directive. -The database is stored in a shared memory zone -specified by the <literal>zone</literal> parameter. -</para> - -</directive> - - -<directive name="keyval_zone"> -<syntax> - <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>prefix</literal>] - [<literal>sync</literal>]</syntax> -<default/> -<context>stream</context> - -<para> -Sets the <value>name</value> and <value>size</value> of the shared memory zone -that keeps the key-value database. -Key-value pairs are managed by the -<link doc="../http/ngx_http_api_module.xml" id="stream_keyvals_">API</link>. -</para> - -<para id="keyval_state"> -The optional <literal>state</literal> parameter specifies a <value>file</value> -that keeps the current state of the key-value database in the JSON format -and makes it persistent across nginx restarts. -Changing the file content directly should be avoided. -</para> - -<para> -Examples: -<example> -keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; # path for Linux -keyval_zone zone=one:32k state=/var/db/nginx/state/one.keyval; # path for FreeBSD -</example> -</para> - -<para id="keyval_timeout"> -The optional <literal>timeout</literal> parameter (1.15.0) sets -the time after which key-value pairs are removed from the zone. -</para> - -<para id="keyval_type"> -The optional <literal>type</literal> parameter (1.17.1) activates -an extra index optimized for matching the key of a certain type -and defines matching rules when evaluating -a <link id="keyval">keyval</link> <literal>$variable</literal>. -<note> -The index is stored in the same shared memory zone -and thus requires additional storage. -</note> - -<list type="tag"> - -<tag-name id="keyval_type_string"><literal>type=string</literal></tag-name> -<tag-desc> -default, no index is enabled; -variable lookup is performed using exact match -of the record key and a search key -</tag-desc> - -<tag-name id="keyval_type_ip"><literal>type=ip</literal></tag-name> -<tag-desc> -the search key is the textual representation of IPv4 or IPv6 address -or CIDR range; -to match a record key, the search key must belong to a subnet -specified by a record key or exactly match an IP address -</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> - -<para id="keyval_sync"> -The optional <literal>sync</literal> parameter (1.15.0) enables -<link doc="ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link> -of the shared memory zone. -The synchronization requires the -<literal>timeout</literal> parameter to be set. -<note> -If the synchronization is enabled, removal of key-value pairs (no matter -<link doc="../http/ngx_http_api_module.xml" id="patchStreamKeyvalZoneKeyValue">one</link> -or -<link doc="../http/ngx_http_api_module.xml" id="deleteStreamKeyvalZoneData">all</link>) -will be performed only on a target cluster node. -The same key-value pairs on other cluster nodes -will be removed upon <literal>timeout</literal>. -</note> -</para> - -</directive> - -</section> - -</module>
--- a/xml/en/docs/stream/ngx_stream_limit_conn_module.xml +++ b/xml/en/docs/stream/ngx_stream_limit_conn_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_stream_limit_conn_module" link="/en/docs/stream/ngx_stream_limit_conn_module.html" lang="en" - rev="7"> + rev="8"> <section id="summary"> @@ -148,19 +148,6 @@ or about 16 thousand 64-byte states. If the zone storage is exhausted, the server will close the connection. </para> -<para> -<note> -Additionally, as part of our -<commercial_version>commercial subscription</commercial_version>, -the -<link doc="../http/ngx_http_api_module.xml" id="stream_limit_conns_">status information</link> -for each such shared memory zone can be -<link doc="../http/ngx_http_api_module.xml" id="getStreamLimitConnZone">obtained</link> or -<link doc="../http/ngx_http_api_module.xml" id="deleteStreamLimitConnZoneStat">reset</link> -with the <link doc="../http/ngx_http_api_module.xml">API</link> since 1.17.7. -</note> -</para> - </directive> </section>
deleted file mode 100644 --- a/xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml +++ /dev/null @@ -1,134 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_stream_mqtt_filter_module" - link="/en/docs/http/ngx_stream_mqtt_filter_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_stream_mqtt_filter_module</literal> module (1.23.4) provides -support for Message Queuing Telemetry Transport protocol (MQTT) versions -<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> -and -<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>. -</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> -listen 127.0.0.1:18883; -proxy_pass backend; -proxy_buffer_size 16k; - -mqtt on; -mqtt_set_connect clientid "$client"; -mqtt_set_connect username "$name"; -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="mqtt"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> - -<para> -Enables the MQTT protocol for the given virtual server. -</para> - -</directive> - - -<directive name="mqtt_buffers"> -<syntax><value>number</value> <value>size</value></syntax> -<default>100 1k</default> -<context>stream</context> -<context>server</context> -<appeared-in>1.25.1</appeared-in> - -<para> -Sets the <value>number</value> and <value>size</value> of the buffers -used for handling MQTT messages, -for a single connection. -</para> - -</directive> - - -<directive name="mqtt_rewrite_buffer_size"> -<syntax><value>size</value></syntax> -<default>4k|8k</default> -<context>server</context> - -<para> -<note> -This directive is obsolete since version 1.25.1. -The <link id="mqtt_buffers"/> -directive should be used instead. -</note> -</para> - -<para> -Sets the <value>size</value> of the buffer -used for writing a modified message. -By default, the buffer size is equal to one memory page. -This is either 4K or 8K, depending on a platform. -It can be made smaller, however. -</para> - -</directive> - - -<directive name="mqtt_set_connect"> -<syntax><literal>field</literal> <value>value</value></syntax> -<default/> -<context>server</context> - -<para> -Sets the message <literal>field</literal> -to the given <literal>value</literal> for CONNECT message. -The following fields are supported: -<literal>clientid</literal>, -<literal>username</literal>, and -<literal>password</literal>. -The value can contain text, variables, and their combination. -</para> - -<para> -Several <literal>mqtt_set_connect</literal> directives -can be specified on the same level: -<example> -mqtt_set_connect clientid "$client"; -mqtt_set_connect username "$name"; -</example> -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/stream/ngx_stream_mqtt_preread_module.xml +++ /dev/null @@ -1,86 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_stream_mqtt_preread_module" - link="/en/docs/http/ngx_stream_mqtt_preread_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_stream_mqtt_preread_module</literal> module (1.23.4) allows -extracting information from the CONNECT message -of the Message Queuing Telemetry Transport protocol (MQTT) versions -<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> -and -<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>, -for example, a username or a client ID. -</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> -mqtt_preread on; -return $mqtt_preread_clientid; -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="mqtt_preread"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> - -<para> -Enables extracting information from the MQTT CONNECT message at -the <link doc="stream_processing.xml" id="preread_phase">preread</link> phase. -</para> - -</directive> - -</section> - - -<section id="variables" name="Embedded Variables"> - -<para> -<list type="tag"> - -<tag-name id="var_mqtt_preread_clientid"><var>$mqtt_preread_clientid</var></tag-name> -<tag-desc> -the <literal>clientid</literal> value from the CONNECT message -</tag-desc> - -<tag-name id="var_mqtt_preread_username"><var>$mqtt_preread_username</var></tag-name> -<tag-desc> -the <literal>username</literal> value from the CONNECT message -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/en/docs/stream/ngx_stream_proxy_module.xml +++ b/xml/en/docs/stream/ngx_stream_proxy_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_proxy_module" link="/en/docs/stream/ngx_stream_proxy_module.html" lang="en" - rev="32"> + rev="33"> <section id="summary"> @@ -327,40 +327,6 @@ session is still not finished, the respo </directive> -<directive name="proxy_session_drop"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> -<appeared-in>1.15.8</appeared-in> - -<para> -Enables terminating all sessions to a proxied server -after it was removed from the group or marked as permanently unavailable. -This can occur because of -<link doc="ngx_stream_core_module.xml" id="resolver">re-resolve</link> -or with the API -<link doc="../http/ngx_http_api_module.xml" id="deleteStreamUpstreamServer"><literal>DELETE</literal></link> -command. -A server can be marked as permanently unavailable if it is considered -<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">unhealthy</link> -or with the API -<link doc="../http/ngx_http_api_module.xml" id="patchStreamUpstreamServer"><literal>PATCH</literal></link> -command. -Each session is terminated when the next -read or write event is processed for the client or proxied server. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="proxy_socket_keepalive"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/en/docs/stream/ngx_stream_proxy_protocol_vendor_module.xml +++ /dev/null @@ -1,105 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_stream_proxy_protocol_vendor_module" - link="/en/docs/stream/ngx_stream_proxy_protocol_vendor_module.html" - lang="en" - rev="1"> - -<section id="summary"> - -<para> -The <literal>ngx_stream_proxy_protocol_vendor_module</literal> module (1.23.3) -allows obtaining additional information about a connection in -cloud platforms from application-specific TLVs of the -<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">PROXY -protocol</link> -header. -</para> - -<para> -Supported cloud platforms: -<list type="bullet"> - -<listitem> -Amazon Web Services -</listitem> - -<listitem> -Google Cloud Platform -</listitem> - -<listitem> -Microsoft Azure -</listitem> - -</list> -</para> - -<para> -The PROXY protocol must be previously enabled by setting the -<literal>proxy_protocol</literal> parameter -in the <link doc="ngx_stream_core_module.xml" id="listen"/> directive. -</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> -server { - listen 12345 proxy_protocol; - return $proxy_protocol_tlv_gcp_conn_id; -} -</example> -</para> - -</section> - - -<section id="variables" name="Embedded Variables"> - -<para> -<list type="tag"> - -<tag-name id="var_proxy_protocol_tlv_aws_vpce_id"><var>$proxy_protocol_tlv_aws_vpce_id</var></tag-name> -<tag-desc> -TLV value from the PROXY Protocol header representing the -<link url="https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol">ID -of AWS VPC endpoint</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_azure_pel_id"><var>$proxy_protocol_tlv_azure_pel_id</var></tag-name> -<tag-desc> -TLV value from the PROXY Protocol header representing the -<link url="https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview#getting-connection-information-using-tcp-proxy-v2">LinkID -of Azure private endpoint</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_gcp_conn_id"><var>$proxy_protocol_tlv_gcp_conn_id</var></tag-name> -<tag-desc> -TLV value from the PROXY Protocol header representing -<link url="https://cloud.google.com/vpc/docs/configure-private-service-connect-producer#proxy-protocol">Google Cloud PSC -connection ID</link> -</tag-desc> - -</list> -</para> - -</section> - -</module>
deleted file mode 100644 --- a/xml/en/docs/stream/ngx_stream_upstream_hc_module.xml +++ /dev/null @@ -1,330 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_stream_upstream_hc_module" - link="/en/docs/stream/ngx_stream_upstream_hc_module.html" - lang="en" - rev="6"> - -<section id="summary"> - -<para> -The <literal>ngx_stream_upstream_hc_module</literal> module (1.9.0) -allows enabling periodic health checks of the servers in a -<link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>. -The server group must reside in the -<link doc="ngx_stream_upstream_module.xml" id="zone">shared memory</link>. -</para> - -<para> -If a health check fails, the server will be considered unhealthy. -If several health checks are defined for the same group of servers, -a single failure of any check will make the corresponding server be -considered unhealthy. -Client connections are not passed to unhealthy servers -and servers in the “checking” state. -</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> -upstream tcp { - zone upstream_tcp 64k; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345 fail_timeout=5s slow_start=30s; - server 192.0.2.1:12345 max_fails=3; - - server backup1.example.com:12345 backup; - server backup2.example.com:12345 backup; -} - -server { - listen 12346; - proxy_pass tcp; - health_check; -} -</example> -With this configuration, nginx -will check the ability to establish a TCP connection to each server -in the <literal>tcp</literal> group every five seconds. -When a connection to the server cannot be established, -the health check will fail, and the server will -be considered unhealthy. -</para> - -<para> -Health checks can be configured for the UDP protocol: -<example> -upstream dns_upstream { - - zone dns_zone 64k; - - server dns1.example.com:53; - server dns2.example.com:53; - server dns3.example.com:53; -} - -server { - listen 53 udp; - proxy_pass dns_upstream; - health_check udp; -} -</example> -In this case, the absence of -ICMP “<literal>Destination Unreachable</literal>” message is expected -in reply to the sent string “<literal>nginx health check</literal>”. -</para> - -<para> -Health checks can also be configured to test data obtained from the server. -Tests are configured separately using the <link id="match"/> directive -and referenced in the <literal>match</literal> parameter -of the <link id="health_check"/> directive. -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="health_check"> -<syntax>[<value>parameters</value>]</syntax> -<default/> -<context>server</context> - -<para> -Enables periodic health checks of the servers in a -<link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>. -</para> - -<para> -The following optional parameters are supported: -<list type="tag"> - -<tag-name id="health_check_interval"> -<literal>interval</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the interval between two consecutive health checks, -by default, 5 seconds. -</tag-desc> - -<tag-name id="health_check_jitter"> -<literal>jitter</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the time within which -each health check will be randomly delayed, -by default, there is no delay. -</tag-desc> - -<tag-name id="health_check_fails"> -<literal>fails</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of consecutive failed health checks of a particular server -after which this server will be considered unhealthy, -by default, 1. -</tag-desc> - -<tag-name id="health_check_passes"> -<literal>passes</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of consecutive passed health checks of a particular server -after which the server will be considered healthy, -by default, 1. -</tag-desc> - -<tag-name id="health_check_mandatory"> -<literal>mandatory</literal> [<literal>persistent</literal>] -</tag-name> -<tag-desc> -<para> -sets the initial “checking” state for a server -until the first health check is completed (1.11.7). -Client connections are not passed to servers in the “checking” state. -If the parameter is not specified, -the server will be initially considered healthy. -</para> - -<para id="health_check_persistent"> -The <literal>persistent</literal> parameter (1.21.1) -sets the initial “up” state for a server after reload -if the server was considered healthy before reload. -</para> - -</tag-desc> - -<tag-name id="health_check_match"> -<literal>match</literal>=<value>name</value> -</tag-name> -<tag-desc> -specifies the <literal>match</literal> block configuring the tests that a -successful connection should pass in order for a health check to pass. -By default, for TCP, only the ability -to establish a TCP connection with the server is checked. -For <link id="health_check_udp">UDP</link>, the absence of -ICMP “<literal>Destination Unreachable</literal>” message is expected -in reply to the sent string “<literal>nginx health check</literal>”. -<note> -Prior to version 1.11.7, by default, UDP health check -required a <link id="hc_match">match</link> block with the -<link id="match_send">send</link> and <link id="match_expect">expect</link> -parameters. -</note> -</tag-desc> - -<tag-name id="health_check_port"> -<literal>port</literal>=<value>number</value> -</tag-name> -<tag-desc> -defines the port used when connecting to a server -to perform a health check (1.9.7). -By default, equals the -<link doc="ngx_stream_upstream_module.xml" id="server"/> port. -</tag-desc> - -<tag-name id="health_check_udp"> -<literal>udp</literal> -</tag-name> -<tag-desc> -specifies that the <literal>UDP</literal> protocol should be used for -health checks instead of the default <literal>TCP</literal> protocol (1.9.13). -</tag-desc> - -</list> -</para> - -</directive> - - -<directive name="health_check_timeout"> -<syntax><value>timeout</value></syntax> -<default>5s</default> -<context>stream</context> -<context>server</context> - -<para> -Overrides the -<link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> -value for health checks. -</para> - -</directive> - - -<directive name="match"> -<syntax block="yes"><value>name</value> </syntax> -<default/> -<context>stream</context> - -<para> -Defines the named test set used to verify server responses to health checks. -</para> - -<para> -The following parameters can be configured: -<list type="tag"> - -<tag-name id="match_send"> -<literal>send</literal> <value>string</value>; -</tag-name> -<tag-desc> -sends a <value>string</value> to the server; -</tag-desc> - -<tag-name id="match_expect"> -<literal>expect</literal> <value>string</value> | -<literal>~</literal> <value>regex</value>; -</tag-name> -<tag-desc> -a literal string (1.9.12) or a regular expression -that the data obtained from the server should match. -The regular expression is specified with the preceding -“<literal>~*</literal>” modifier (for case-insensitive matching), or the -“<literal>~</literal>” modifier (for case-sensitive matching). -</tag-desc> - -</list> -Both <literal>send</literal> and <literal>expect</literal> parameters -can contain hexadecimal literals with the prefix “<literal>\x</literal>” -followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12). -</para> - -<para> -Health check is passed if: -<list type="bullet"> -<listitem> -the TCP connection was successfully established; -</listitem> - -<listitem> -the <value>string</value> from the <literal>send</literal> parameter, -if specified, was sent; -</listitem> - -<listitem> -the data obtained from the server matched the string or regular expression -from the <literal>expect</literal> parameter, if specified; -</listitem> - -<listitem> -the time elapsed does not exceed the value specified -in the <link id="health_check_timeout"/> directive. -</listitem> - -</list> -</para> - -<para> -Example: -<example> -upstream backend { - zone upstream_backend 10m; - server 127.0.0.1:12345; -} - -match http { - send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; - expect ~ "200 OK"; -} - -server { - listen 12346; - proxy_pass backend; - health_check match=http; -} -</example> -</para> - -<para> -<note> -Only the first -<link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/> -bytes of data obtained from the server are examined. -</note> -</para> - -</directive> - -</section> - -</module>
--- 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="39"> + rev="40"> <section id="summary"> @@ -45,35 +45,6 @@ server { </example> </para> -<para> -Dynamically configurable group with -periodic <link doc="ngx_stream_upstream_hc_module.xml">health checks</link> is -available as part of our -<commercial_version>commercial subscription</commercial_version>: -<example> -resolver 10.0.0.1; - -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345 fail_timeout=5s slow_start=30s; - server 192.0.2.1:12345 max_fails=3; - server backend3.example.com:12345 resolve; - server backend4.example.com service=http resolve; - - server backup1.example.com:12345 backup; - server backup2.example.com:12345 backup; -} - -server { - listen 12346; - proxy_pass <emphasis>dynamic</emphasis>; - health_check; -} -</example> -</para> - </section> @@ -155,10 +126,6 @@ connections to the proxied server (1.11. Default value is zero, meaning there is no limit. If the server group does not reside in the <link id="zone">shared memory</link>, the limitation works per each worker process. -<note> -Prior to version 1.11.5, this parameter was available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> </tag-desc> <tag-name id="max_fails"> @@ -219,95 +186,9 @@ marks the server as permanently unavaila </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -<list type="tag"> - -<tag-name id="resolve"> -<literal>resolve</literal> -</tag-name> -<tag-desc> -monitors changes of the IP addresses -that correspond to a domain name of the server, -and automatically modifies the upstream configuration -without the need of restarting nginx. -The server group must reside in the <link id="zone">shared memory</link>. -<para> -In order for this parameter to work, -the <literal>resolver</literal> directive -must be specified in the -<link doc="ngx_stream_core_module.xml" id="resolver">stream</link> block -or in the corresponding <link id="resolver">upstream</link> block. -</para> -</tag-desc> - -<tag-name id="service"> -<literal>service</literal>=<value>name</value> -</tag-name> -<tag-desc> -enables resolving of DNS -<link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link> -records and sets the service <value>name</value> (1.9.13). -In order for this parameter to work, it is necessary to specify -the <link id="resolve"/> parameter for the server -and specify a hostname without a port number. -<para> -If the service name does not contain a dot (“<literal>.</literal>”), then -the <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>-compliant name -is constructed -and the TCP protocol is added to the service prefix. -For example, to look up the -<literal>_http._tcp.backend.example.com</literal> SRV record, -it is necessary to specify the directive: -<example> -server backend.example.com service=http resolve; -</example> -If the service name contains one or more dots, then the name is constructed -by joining the service prefix and the server name. -For example, to look up the <literal>_http._tcp.backend.example.com</literal> -and <literal>server1.backend.example.com</literal> SRV records, -it is necessary to specify the directives: -<example> -server backend.example.com service=_http._tcp resolve; -server example.com service=server1.backend resolve; -</example> -</para> - -<para> -Highest-priority SRV records -(records with the same lowest-number priority value) -are resolved as primary servers, -the rest of SRV records are resolved as backup servers. -If the <link id="backup"/> parameter is specified for the server, -high-priority SRV records are resolved as backup servers, -the rest of SRV records are ignored. -</para> -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the <value>time</value> during which the server will recover its weight -from zero to a nominal value, when unhealthy server becomes -<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">healthy</link>, -or when the server becomes available after a period of time -it was considered <link id="fail_timeout">unavailable</link>. -Default value is zero, i.e. slow start is disabled. <note> -The parameter cannot be used along with the -<link id="hash"/> and <link id="random"/> load balancing methods. -</note> -</tag-desc> - -</list> -</para> - -<para> -<note> -If there is only a single server in a group, <literal>max_fails</literal>, -<literal>fail_timeout</literal> and <literal>slow_start</literal> parameters +If there is only a single server in a group, +<literal>max_fails</literal> and <literal>fail_timeout</literal> parameters are ignored, and such a server will never be considered unavailable. </note> </para> @@ -328,70 +209,6 @@ Several groups may share the same zone. In this case, it is enough to specify the <value>size</value> only once. </para> -<para> -Additionally, -as part of our <commercial_version>commercial subscription</commercial_version>, -such groups allow changing the group membership -or modifying the settings of a particular server -without the need of restarting nginx. -The configuration is accessible via the -<link doc="../http/ngx_http_api_module.xml">API</link> module (1.13.3). -<note> -Prior to version 1.13.3, -the configuration was accessible only via a special location -handled by -<link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. -</note> -</para> - -</directive> - - -<directive name="state"> -<syntax><value>file</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.9.7</appeared-in> - -<para> -Specifies a <value>file</value> that keeps the state -of the dynamically configurable group. -</para> - -<para> -Examples: -<example> -state /var/lib/nginx/state/servers.conf; # path for Linux -state /var/db/nginx/state/servers.conf; # path for FreeBSD -</example> -</para> - -<para> -The state is currently limited to the list of servers with their parameters. -The file is read when parsing the configuration and is updated each time -the upstream configuration is -<link doc="../http/ngx_http_api_module.xml" id="stream_upstreams_stream_upstream_name_servers_">changed</link>. -Changing the file content directly should be avoided. -The directive cannot be used -along with the <link id="server"/> directive. -</para> - -<para> -<note> -Changes made during -<link doc="../control.xml" id="reconfiguration">configuration reload</link> -or <link doc="../control.xml" id="upgrade">binary upgrade</link> -can be lost. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> @@ -448,52 +265,6 @@ weighted round-robin balancing method. </directive> -<directive name="least_time"> -<syntax> - <literal>connect</literal> | - <literal>first_byte</literal> | - <literal>last_byte</literal> - [<literal>inflight</literal>]</syntax> -<default/> -<context>upstream</context> - -<para> -Specifies that a group should use a load balancing method where a connection -is passed to the server with the least average time and -least number of active connections, taking into account weights of servers. -If there are several such servers, they are tried in turn using a -weighted round-robin balancing method. -</para> - -<para> -If the <literal>connect</literal> parameter is specified, -time to -<link id="var_upstream_connect_time">connect</link> -to the upstream server is used. -If the <literal>first_byte</literal> parameter is specified, -time to receive the -<link id="var_upstream_first_byte_time">first byte</link> of data is used. -If the <literal>last_byte</literal> is specified, -time to receive the -<link id="var_upstream_session_time">last byte</link> of data is used. -If the <literal>inflight</literal> parameter is specified (1.11.6), -incomplete connections are also taken into account. -<note> -Prior to version 1.11.6, -incomplete connections were taken into account by default. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="random"> <syntax>[<literal>two</literal> [<value>method</value>]]</syntax> <default/> @@ -517,108 +288,6 @@ which passes a connection to a server with the least number of active connections. </para> -<para id="random_least_time"> -The <literal>least_time</literal> method passes a connection to a server -with the least average time and least number of active connections. -If <literal>least_time=connect</literal> parameter is specified, -time to -<link id="var_upstream_connect_time">connect</link> -to the upstream server is used. -If <literal>least_time=first_byte</literal> parameter is specified, -time to receive the -<link id="var_upstream_first_byte_time">first byte</link> of data is used. -If <literal>least_time=last_byte</literal> is specified, -time to receive the -<link id="var_upstream_session_time">last byte</link> of data is used. -<note> -The <literal>least_time</literal> method is available as a part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="resolver"> -<syntax> - <value>address</value> ... - [<literal>valid</literal>=<value>time</value>] - [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<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 IPv4 or IPv6 addresses is not desired, -the <literal>ipv4=off</literal> (1.23.1) or -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>
deleted file mode 100644 --- a/xml/en/docs/stream/ngx_stream_zone_sync_module.xml +++ /dev/null @@ -1,548 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_stream_zone_sync_module" - link="/en/docs/stream/ngx_stream_zone_sync_module.html" - lang="en" - rev="7"> - -<section id="summary"> - -<para> -The <literal>ngx_stream_zone_sync_module</literal> module (1.13.8) -provides the necessary support for synchronizing contents of -<link doc="ngx_stream_upstream_module.xml" id="zone">shared memory zones</link> -between nodes of a cluster. -To enable synchronization for a particular zone, a corresponding module -must support this feature. -Currently, it is possible to synchronize HTTP -<link doc="../http/ngx_http_upstream_module.xml" id="sticky">sticky</link> -sessions, information about -<link doc="../http/ngx_http_limit_req_module.xml">excessive HTTP requests</link>, -and key-value pairs both in -<link doc="../http/ngx_http_keyval_module.xml">http</link> -and <link doc="../stream/ngx_stream_keyval_module.xml">stream</link>. -</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> -Minimal configuration: -<example> -http { - ... - - upstream backend { - server backend1.example.com:8080; - server backend2.example.com:8081; - - sticky learn - create=$upstream_cookie_examplecookie - lookup=$cookie_examplecookie - zone=client_sessions:1m <emphasis>sync</emphasis>; - } - - ... -} - -stream { - ... - - - server { - zone_sync; - - listen 127.0.0.1:12345; - - # cluster of 2 nodes - zone_sync_server a.example.com:12345; - zone_sync_server b.example.com:12345; - - } -</example> -A more complex configuration with SSL enabled -and with cluster members defined by DNS: -<example> -... - -stream { - ... - - resolver 127.0.0.1 valid=10s; - - server { - zone_sync; - - # the name resolves to multiple addresses that correspond to cluster nodes - zone_sync_server cluster.example.com:12345 resolve; - - listen 127.0.0.1:4433 ssl; - - ssl_certificate localhost.crt; - ssl_certificate_key localhost.key; - - zone_sync_ssl on; - - zone_sync_ssl_certificate localhost.crt; - zone_sync_ssl_certificate_key localhost.key; - } -} -</example> -</para> - -</section> - - -<section id="directives" name="Directives"> - -<directive name="zone_sync"> -<syntax></syntax> -<default></default> -<context>server</context> - -<para> -Enables the synchronization of shared memory zones between cluster nodes. -Cluster nodes are defined using <link id="zone_sync_server"/> directives. -</para> - -</directive> - - -<directive name="zone_sync_buffers"> -<syntax><value>number</value> <value>size</value></syntax> -<default>8 4k|8k</default> -<context>stream</context> -<context>server</context> - -<para> -Sets the <value>number</value> and <value>size</value> of the -per-zone buffers used for pushing zone contents. -By default, the buffer size is equal to one memory page. -This is either 4K or 8K, depending on a platform. -</para> - -<para> -<note> -A single buffer must be large enough to hold any entry of each zone being -synchronized. -</note> -</para> - -</directive> - - -<directive name="zone_sync_connect_retry_interval"> -<syntax><value>time</value></syntax> -<default>1s</default> -<context>stream</context> -<context>server</context> - -<para> -Defines an interval between connection attempts to another cluster node. -</para> - -</directive> - - -<directive name="zone_sync_connect_timeout"> -<syntax><value>time</value></syntax> -<default>5s</default> -<context>stream</context> -<context>server</context> - -<para> -Defines a timeout for establishing a connection with another cluster node. -</para> - -</directive> - - -<directive name="zone_sync_interval"> -<syntax><value>time</value></syntax> -<default>1s</default> -<context>stream</context> -<context>server</context> - -<para> -Defines an interval for polling updates in a shared memory zone. -</para> - -</directive> - - -<directive name="zone_sync_recv_buffer_size"> -<syntax><value>size</value></syntax> -<default>4k|8k</default> -<context>stream</context> -<context>server</context> - -<para> -Sets <value>size</value> of a per-connection receive buffer used to parse -incoming stream of synchronization messages. -The buffer size must be equal or greater than one of the -<link id="zone_sync_buffers"/>. -By default, the buffer size is equal to -<link id="zone_sync_buffers">zone_sync_buffers</link> <value>size</value> -multiplied by <value>number</value>. -</para> - -</directive> - - -<directive name="zone_sync_server"> -<syntax><value>address</value> [<literal>resolve</literal>]</syntax> -<default></default> -<context>server</context> - -<para> -Defines the <value>address</value> of a cluster node. -The address can be specified as a domain name or IP address -with a mandatory port, or as a UNIX-domain socket path -specified after the “<literal>unix:</literal>” prefix. -A domain name that resolves to several IP addresses defines -multiple nodes at once. -</para> - -<para id="resolve"> -The <literal>resolve</literal> parameter instructs nginx to monitor -changes of the IP addresses that correspond to a domain name of the node -and automatically modify the configuration -without the need of restarting nginx. -</para> - -<para> -Cluster nodes are specified either dynamically as a single -<literal>zone_sync_server</literal> directive with -the <literal>resolve</literal> parameter, or statically as a series of several -directives without the parameter. -<note> -Each cluster node should be specified only once. -</note> -<note> -All cluster nodes should use the same configuration. -</note> -</para> - -<para> -In order for the <literal>resolve</literal> parameter to work, -the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive -must be specified in the -<link doc="ngx_stream_core_module.xml" id="stream"/> block. -Example: -<example> -stream { - resolver 10.0.0.1; - - server { - zone_sync; - zone_sync_server cluster.example.com:12345 resolve; - ... - } -} -</example> -</para> - -</directive> - - -<directive name="zone_sync_ssl"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> - -<para> -Enables the SSL/TLS protocol for connections to another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_certificate"> -<syntax><value>file</value></syntax> -<default/> -<context>stream</context> -<context>server</context> - -<para> -Specifies a <value>file</value> with the certificate in the PEM format -used for authentication to another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_certificate_key"> -<syntax><value>file</value></syntax> -<default/> -<context>stream</context> -<context>server</context> - -<para> -Specifies a <value>file</value> with the secret key in the PEM format -used for authentication to another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_ciphers"> -<syntax><value>ciphers</value></syntax> -<default>DEFAULT</default> -<context>stream</context> -<context>server</context> - -<para> -Specifies the enabled ciphers for connections to another cluster server. -The ciphers are specified in the format understood by the OpenSSL library. -</para> - -<para> -The full list can be viewed using the -“<command>openssl ciphers</command>” command. -</para> - -</directive> - - -<directive name="zone_sync_ssl_conf_command"> -<syntax><value>name</value> <value>value</value></syntax> -<default/> -<context>stream</context> -<context>server</context> -<appeared-in>1.19.4</appeared-in> - -<para> -Sets arbitrary OpenSSL configuration -<link url="https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html">commands</link> -when establishing a connection with another cluster server. -<note> -The directive is supported when using OpenSSL 1.0.2 or higher. -</note> -</para> - -<para> -Several <literal>zone_sync_ssl_conf_command</literal> directives -can be specified on the same level. -These directives are inherited from the previous configuration level -if and only if there are -no <literal>zone_sync_ssl_conf_command</literal> directives -defined on the current level. -</para> - -<para> -<note> -Note that configuring OpenSSL directly -might result in unexpected behavior. -</note> -</para> - -</directive> - - -<directive name="zone_sync_ssl_crl"> -<syntax><value>file</value></syntax> -<default/> -<context>stream</context> -<context>server</context> - -<para> -Specifies a <value>file</value> with revoked certificates (CRL) -in the PEM format used to <link id="zone_sync_ssl_verify">verify</link> -the certificate of another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_name"> -<syntax><value>name</value></syntax> -<default>host from zone_sync_server</default> -<context>stream</context> -<context>server</context> -<appeared-in>1.15.7</appeared-in> - -<para> -Allows overriding the server name used to -<link id="zone_sync_ssl_verify">verify</link> -the certificate of a cluster server and to be -<link id="zone_sync_ssl_server_name">passed through SNI</link> -when establishing a connection with the cluster server. -</para> - -<para> -By default, the host part of the <link id="zone_sync_server"/> address is used, -or resolved IP address if the <link id="resolve"/> parameter is specified. -</para> - -</directive> - - -<directive name="zone_sync_ssl_password_file"> -<syntax><value>file</value></syntax> -<default/> -<context>stream</context> -<context>server</context> - -<para> -Specifies a <value>file</value> with passphrases for -<link id="zone_sync_ssl_certificate_key">secret keys</link> -where each passphrase is specified on a separate line. -Passphrases are tried in turn when loading the key. -</para> - -</directive> - - -<directive name="zone_sync_ssl_protocols"> -<syntax> - [<literal>SSLv2</literal>] - [<literal>SSLv3</literal>] - [<literal>TLSv1</literal>] - [<literal>TLSv1.1</literal>] - [<literal>TLSv1.2</literal>] - [<literal>TLSv1.3</literal>]</syntax> -<default>TLSv1 TLSv1.1 TLSv1.2</default> -<context>stream</context> -<context>server</context> - -<para> -Enables the specified protocols for connections to another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_server_name"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> -<appeared-in>1.15.7</appeared-in> - -<para> -Enables or disables passing of the server name through -<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS -Server Name Indication extension</link> (SNI, RFC 6066) -when establishing a connection with another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_trusted_certificate"> -<syntax><value>file</value></syntax> -<default/> -<context>stream</context> -<context>server</context> - -<para> -Specifies a <value>file</value> with trusted CA certificates in the PEM format -used to <link id="zone_sync_ssl_verify">verify</link> -the certificate of another cluster server. -</para> - -</directive> - - -<directive name="zone_sync_ssl_verify"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> - -<para> -Enables or disables verification of another cluster server certificate. -</para> - -</directive> - - -<directive name="zone_sync_ssl_verify_depth"> -<syntax><value>number</value></syntax> -<default>1</default> -<context>stream</context> -<context>server</context> - -<para> -Sets the verification depth in another cluster server certificates chain. -</para> - -</directive> - - -<directive name="zone_sync_timeout"> -<syntax><value>timeout</value></syntax> -<default>5s</default> -<context>stream</context> -<context>server</context> - -<para> -Sets the <value>timeout</value> between two successive -read or write operations on connection to another cluster node. -If no data is transmitted within this time, the connection is closed. -</para> - -</directive> - -</section> - - -<section id="stream_zone_sync_status" name="API endpoints"> -<para> -The synchronization status of a node is available via the -<link doc= "../http/ngx_http_api_module.xml" id="stream_zone_sync_">/stream/zone_sync/</link> -endpoint of the API which returns the -<link doc= "../http/ngx_http_api_module.xml" id="def_nginx_stream_zone_sync">following</link> -metrics. -</para> - -</section> - - -<section id="controlling_cluster_node" name="Starting, stopping, removing a cluster node"> -<para> -To start a new node, update a DNS record of a cluster hostname -with the IP address of the new node and start an instance. -The new node will discover other nodes from DNS or static configuration -and will start sending updates to them. -Other nodes will eventually discover the new node using DNS and -start pushing updates to it. -In case of static configuration, -other nodes need to be reloaded in order to send updates to the new node. -</para> - -<para> -To stop a node, send the <literal>QUIT</literal> signal to the instance. -The node will finish zone synchronization -and gracefully close open connections. -</para> - -<para> -To remove a node, update a DNS record of a cluster hostname -and remove the IP address of the node. -All other nodes will eventually discover that the node is removed, -close connections to the node, and will no longer try to connect to it. -After the node is removed, it can be stopped as described above. -In case of static configuration, other nodes need to be reloaded -in order to stop sending updates to the removed node. -</para> - -</section> - -</module>
--- a/xml/en/docs/syslog.xml +++ b/xml/en/docs/syslog.xml @@ -96,9 +96,6 @@ access_log syslog:server=[2001:db8::1]:1 <para> <note> Logging to syslog is available since version 1.7.1. -As part of our -<commercial_version>commercial subscription</commercial_version> -logging to syslog is available since version 1.5.3. </note> </para>
--- a/xml/en/donation.xml +++ b/xml/en/donation.xml @@ -8,22 +8,12 @@ <article name="nginx: donation" link="/en/donation.html" lang="en" - rev="1"> + rev="2"> <section> <para> Thank you very much for all your support of the nginx project. -We as a company have created a commercial model to help support -the ongoing development of the software, so we no longer need to -ask for charitable donations to support our work. -If you use and enjoy nginx, and want to support the project please -consider purchasing one of our paid products and services. -You can learn more at <link url="https://nginx.com">nginx.com</link>. -</para> - -<para> -Thank you! </para> </section>
--- a/xml/en/support.xml +++ b/xml/en/support.xml @@ -8,18 +8,7 @@ <article name="nginx: support" link="/en/support.html" lang="en" - rev="10"> - - -<section name="Commercial Support"> - -<para> -We offer -<link url="https://www.nginx.com/support/">commercial support</link> -for nginx and our commercial products. -</para> - -</section> + rev="11"> <section name="Mailing Lists">
--- a/xml/it/docs/index.xml +++ b/xml/it/docs/index.xml @@ -198,11 +198,6 @@ ngx_http_empty_gif_module</link> </listitem> <listitem> -<link doc="http/ngx_http_f4f_module.xml"> -ngx_http_f4f_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_fastcgi_module.xml"> ngx_http_fastcgi_module</link> </listitem> @@ -243,11 +238,6 @@ ngx_http_headers_module</link> </listitem> <listitem> -<link doc="http/ngx_http_hls_module.xml"> -ngx_http_hls_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_image_filter_module.xml"> ngx_http_image_filter_module</link> </listitem> @@ -323,11 +313,6 @@ ngx_http_secure_link_module</link> </listitem> <listitem> -<link doc="http/ngx_http_session_log_module.xml"> -ngx_http_session_log_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_spdy_module.xml"> ngx_http_spdy_module</link> </listitem> @@ -348,11 +333,6 @@ ngx_http_ssl_module</link> </listitem> <listitem> -<link doc="http/ngx_http_status_module.xml"> -ngx_http_status_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_sub_module.xml"> ngx_http_sub_module</link> </listitem>
--- a/xml/it/support.xml +++ b/xml/it/support.xml @@ -9,33 +9,7 @@ link="/it/support.html" lang="it" translator="Angelo Papadia" - rev="4"> - - -<section name="Supporto commerciale"> - -<para> -E' possibile ottenere supporto commerciale per nginx; -per maggiori informazioni consultare la pagina relativa a -<link url="http://nginx.com/products.html">nginx.com</link>. -</para> - -</section> - - -<section name="Wiki"> - -<para> -<list type="bullet"> - -<listitem> -<link url="http://wiki.nginx.org">wiki.nginx.org</link> -</listitem> - -</list> -</para> - -</section> + rev="11"> <section name="Mailing List"> @@ -78,30 +52,6 @@ archivio Gmane</link> </section> -<section name="Forum"> - -<para> -<list type="bullet"> - -<listitem> -<link url="http://forum.nginx.org">forum.nginx.org</link> -(integrato da mailing list) -</listitem> - -<listitem> -<link url="http://www.ruby-forum.com/forum/nginx"> -Forum Ruby</link> -(integrato da mailing list -<link url="http://nginx.org/mailman/listinfo/nginx">nginx@nginx.org</link> -) -</listitem> - -</list> -</para> - -</section> - - <section name="Sviluppo"> <para>
--- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -29,7 +29,6 @@ REFS = \ http/ngx_http_access_module \ http/ngx_http_addition_module \ http/ngx_http_auth_basic_module \ - http/ngx_http_auth_jwt_module \ http/ngx_http_auth_request_module \ http/ngx_http_autoindex_module \ http/ngx_http_browser_module \ @@ -38,7 +37,6 @@ REFS = \ http/ngx_http_dav_module \ http/ngx_http_empty_gif_module \ http/ngx_http_fastcgi_module \ - http/ngx_http_f4f_module \ http/ngx_http_flv_module \ http/ngx_http_geo_module \ http/ngx_http_geoip_module \ @@ -47,10 +45,8 @@ REFS = \ http/ngx_http_gzip_module \ http/ngx_http_gzip_static_module \ http/ngx_http_headers_module \ - http/ngx_http_hls_module \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \ - http/ngx_http_internal_redirect_module \ http/ngx_http_js_module \ http/ngx_http_limit_conn_module \ http/ngx_http_limit_req_module \ @@ -62,7 +58,6 @@ REFS = \ http/ngx_http_mp4_module \ http/ngx_http_perl_module \ http/ngx_http_proxy_module \ - http/ngx_http_proxy_protocol_vendor_module \ http/ngx_http_random_index_module \ http/ngx_http_realip_module \ http/ngx_http_referer_module \ @@ -74,12 +69,9 @@ REFS = \ http/ngx_http_split_clients_module \ http/ngx_http_ssi_module \ http/ngx_http_ssl_module \ - http/ngx_http_status_module \ http/ngx_http_stub_status_module \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ - http/ngx_http_upstream_conf_module \ - http/ngx_http_upstream_hc_module \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_v2_module \ @@ -101,10 +93,7 @@ REFS = \ stream/ngx_stream_limit_conn_module \ stream/ngx_stream_log_module \ stream/ngx_stream_map_module \ - stream/ngx_stream_mqtt_filter_module \ - stream/ngx_stream_mqtt_preread_module \ stream/ngx_stream_proxy_module \ - stream/ngx_stream_proxy_protocol_vendor_module \ stream/ngx_stream_realip_module \ stream/ngx_stream_return_module \ stream/ngx_stream_set_module \ @@ -112,7 +101,6 @@ REFS = \ stream/ngx_stream_ssl_module \ stream/ngx_stream_ssl_preread_module \ stream/ngx_stream_upstream_module \ - stream/ngx_stream_upstream_hc_module \ stream/stream_processing \ ngx_google_perftools_module \ njs/index \
--- a/xml/ru/docs/http/ngx_http_access_module.xml +++ b/xml/ru/docs/http/ngx_http_access_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_access_module" link="/ru/docs/http/ngx_http_access_module.html" lang="ru" - rev="4"> + rev="5"> <section id="summary"> @@ -21,9 +21,8 @@ <para> Ограничить доступ можно также по -<link doc="ngx_http_auth_basic_module.xml">паролю</link>, по -<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link> -или по <link doc="ngx_http_auth_jwt_module.xml">JWT</link>. +<link doc="ngx_http_auth_basic_module.xml">паролю</link> или по +<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link>. Одновременное ограничение доступа по адресу и паролю управляется директивой <link doc="ngx_http_core_module.xml" id="satisfy"/>. </para>
--- a/xml/ru/docs/http/ngx_http_auth_basic_module.xml +++ b/xml/ru/docs/http/ngx_http_auth_basic_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_auth_basic_module" link="/ru/docs/http/ngx_http_auth_basic_module.html" lang="ru" - rev="10"> + rev="11"> <section id="summary"> @@ -22,9 +22,8 @@ <para> Ограничить доступ можно также по -<link doc="ngx_http_access_module.xml">адресу</link>, по -<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link> -или по <link doc="ngx_http_auth_jwt_module.xml">JWT</link>. +<link doc="ngx_http_access_module.xml">адресу</link> или по +<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link>. Одновременное ограничение доступа по адресу и паролю управляется директивой <link doc="ngx_http_core_module.xml" id="satisfy"/>. </para>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_auth_jwt_module.xml +++ /dev/null @@ -1,459 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_auth_jwt_module" - link="/ru/docs/http/ngx_http_auth_jwt_module.html" - lang="ru" - rev="12"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_auth_jwt_module</literal> (1.11.3) -предоставляет возможность авторизации клиента с проверкой предоставляемого -<link url="https://datatracker.ietf.org/doc/html/rfc7519">JSON Web Token</link> (JWT) -при помощи указанных ключей. -Модуль поддерживает -<link url="https://datatracker.ietf.org/doc/html/rfc7515">JSON Web Signature</link> (JWS), -<link url="https://datatracker.ietf.org/doc/html/rfc7516">JSON Web Encryption</link> (JWE) -(1.19.7) и Nested JWT (1.21.0). -Модуль может использоваться для настройки аутентификации -<link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link>. -</para> - -<para> -Модуль может быть скомбинирован с -другими модулями доступа, такими как -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> -и -<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link> -с помощью директивы <link doc="ngx_http_core_module.xml" id="satisfy"/>. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="algorithms" name="Поддерживаемые алгоритмы"> - -<para> -Модуль поддерживает следующие криптографические -<link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">алгоритмы</link>. -</para> - -<para> -Алгоритмы JWS: -<list type="bullet"> - -<listitem> -HS256, HS384, HS512 -</listitem> - -<listitem> -RS256, RS384, RS512 -</listitem> - -<listitem> -ES256, ES384, ES512 -</listitem> - -<listitem> -EdDSA (подписи Ed25519 и Ed448) (1.15.7) -</listitem> - -</list> - -<note> -До версии 1.13.7 -поддерживались только алгоритмы HS256, RS256 и ES256. -</note> -</para> - -<para> -Алгоритмы JWE для шифрования содержимого (1.19.7): -<list type="bullet"> - -<listitem> -A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 -</listitem> - -<listitem> -A128GCM, A192GCM, A256GCM -</listitem> - -</list> -</para> - -<para> -Алгоритмы JWE для управления ключом (1.19.9): -<list type="bullet"> - -<listitem> -A128KW, A192KW, A256KW -</listitem> - -<listitem> -A128GCMKW, A192GCMKW, A256GCMKW -</listitem> - -<listitem> -dir—прямое использование симметричного ключа -в качестве ключа шифрования содержимого -</listitem> - -<listitem> -RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0) -</listitem> - -</list> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -location / { - auth_jwt "closed site"; - auth_jwt_key_file conf/keys.json; -} -</example> -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="auth_jwt"> -<syntax> - <value>строка</value> - [<literal>token=</literal><value>$переменная</value>] | - <literal>off</literal></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> - -<para> -Включает проверку JSON Web Token. -Заданная <value>строка</value> используется в качестве <literal>realm</literal>. -В значении параметра допустимо использование переменных. -</para> - -<para> -Необязательный параметр <literal>token</literal> задаёт переменную, -содержащую JSON Web Token. -По умолчанию JWT передаётся в заголовке <header>Authorization</header> -в качестве -<link url="https://datatracker.ietf.org/doc/html/rfc6750">Bearer Token</link>. -JWT может также передаваться как кука или часть строки запроса: -<example> -auth_jwt "closed site" token=$cookie_auth_token; -</example> -</para> - -<para> -Специальное значение <literal>off</literal> отменяет действие -унаследованной с предыдущего уровня конфигурации -директивы <literal>auth_jwt</literal>. -</para> - -</directive> - - -<directive name="auth_jwt_claim_set"> -<syntax><value>$переменная</value> <value>имя</value> ...</syntax> -<default/> -<context>http</context> -<appeared-in>1.11.10</appeared-in> - -<para> -Устанавливает <value>переменную</value> в параметр JWT claim, -определяемый именами ключей. -Сопоставление имён начинается с верхнего уровня дерева JSON. -Для массива переменная хранит список его элементов, разделяемых запятыми. -<example> -auth_jwt_claim_set $email info e-mail; -auth_jwt_claim_set $job info "job title"; -</example> -<note> -До версии 1.13.7 можно было указать лишь одно имя, -результат для массивов был не определён. -</note> -</para> - -<para> -<note> -Значения переменных для tokens, зашифрованных при помощи JWE, -доступны только после дешифрования, которое происходит в -<link doc="../dev/development_guide.xml" id="http_phases">Access</link>-фазе. -</note> -</para> - -</directive> - - -<directive name="auth_jwt_header_set"> -<syntax><value>$переменная</value> <value>имя</value> ...</syntax> -<default/> -<context>http</context> -<appeared-in>1.11.10</appeared-in> - -<para> -Устанавливает <value>переменную</value> в параметр заголовка JOSE, -определяемый именами ключей. -Сопоставление имён начинается с верхнего уровня дерева JSON. -Для массива переменная хранит список его элементов, разделяемых запятыми. -<note> -До версии 1.13.7 можно было указать лишь одно имя, -результат для массивов был не определён. -</note> -</para> - -</directive> - -<directive name="auth_jwt_key_cache"> -<syntax><value> время</value></syntax> -<default>0</default> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.21.4</appeared-in> - -<para> -Разрешает или запрещает кэширование ключей, -полученных из <link id="auth_jwt_key_file">файла</link> или из -<link id="auth_jwt_key_request">подзапроса</link>, -и задаёт время их кэширования. -Кэширование ключей, полученных из переменных, не поддерживается. -По умолчанию кэширование ключей выключено. -</para> - -</directive> - - -<directive name="auth_jwt_key_file"> -<syntax><value>файл</value></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> - -<para> -Задаёт <value>файл</value> в формате -<link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> -для проверки подписи JWT. -В значении параметра допустимо использование переменных. -</para> - -<para> -На одном уровне может быть указано -несколько директив <literal>auth_jwt_key_file</literal> (1.21.1): -<example> -auth_jwt_key_file conf/keys.json; -auth_jwt_key_file conf/key.jwk; -</example> -Если хотя бы один из указанных ключей не может быть загружен или обработан, -nginx вернёт ошибку -<http-status code="500" text="Internal Server Error"/>. -</para> - -</directive> - - -<directive name="auth_jwt_key_request"> -<syntax><value>uri</value></syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> -<appeared-in>1.15.6</appeared-in> - -<para> -Позволяет получать файл в формате -<link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> -из подзапроса для проверки подписи JWT и -задаёт URI, на который будет отправлен подзапрос. -В значении параметра допустимо использование переменных. -Для предотвращения дополнительных затрат на проверку -файл рекомендутеся кэшировать. -<example> -proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m; - -server { - ... - - location / { - auth_jwt "closed site"; - auth_jwt_key_request /jwks_uri; - } - - location = /jwks_uri { - internal; - proxy_cache foo; - proxy_pass http://idp.example.com/keys; - } -} -</example> -На одном уровне может быть указано -несколько директив <literal>auth_jwt_key_request</literal> (1.21.1): -<example> -auth_jwt_key_request /jwks_uri; -auth_jwt_key_request /jwks2_uri; -</example> -Если хотя бы один из указанных ключей не может быть загружен или обработан, -nginx вернёт ошибку -<http-status code="500" text="Internal Server Error"/>. -</para> - -</directive> - - -<directive name="auth_jwt_leeway"> -<syntax><value>время</value></syntax> -<default>0s</default> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.13.10</appeared-in> - -<para> -Задаёт максимально допустимое отклонение времени для компенсации -расхождения часов при проверке JWT claims -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4">exp</link> -и -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5">nbf</link>. -</para> - -</directive> - - -<directive name="auth_jwt_type"> -<syntax><value>signed</value> | - <value>encrypted</value> | - <value>nested</value></syntax> -<default>signed</default> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> -<appeared-in>1.19.7</appeared-in> - -<para> -Задаёт ожидаемый тип JSON Web Token: -JWS (<literal>signed</literal>), -JWE (<literal>encrypted</literal>) -или подписанный и затем зашифрованный -Nested JWT (<literal>nested</literal>) (1.21.0). -</para> - -</directive> - - -<directive name="auth_jwt_require"> -<syntax> - <value>$значение</value> ... - [<literal>error</literal>=<literal>401</literal> | - <literal>403</literal>] -</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<context>limit_except</context> -<appeared-in>1.21.2</appeared-in> - -<para> -Задаёт дополнительные условия для проверки JWT. -В качестве значения можно использовать текст, переменные и их комбинации, -значение должно начинаться c переменной (1.21.7). -Для успешной аутентификации необходимо, чтобы -значение всех строковых параметров было непустое или не равно “0”. -<example> -map $jwt_claim_iss $valid_jwt_iss { - "good" 1; -} -... - -auth_jwt_require $valid_jwt_iss; -</example> -</para> - -<para> -При невыполнении любого из условий -возвращается код ответа <literal>401</literal>. -Необязательный параметр <literal>error</literal> (1.21.7) -позволяет переопределить код ответа на <literal>403</literal>. -</para> - -</directive> - -</section> - - -<section id="variables" name="Встроенные переменные"> - -<para> -Модуль <literal>ngx_http_auth_jwt_module</literal> -поддерживает встроенные переменные: -</para> - -<para> -<list type="tag" compact="yes"> -<tag-name id="var_jwt_header_"><var>$jwt_header_</var><value>имя</value></tag-name> -<tag-desc> -возвращает значение указанного -<link url="https://datatracker.ietf.org/doc/html/rfc7515#section-4">заголовка JOSE</link> -</tag-desc> - -<tag-name id="var_jwt_claim_"><var>$jwt_claim_</var><value>имя</value></tag-name> -<tag-desc> -возвращает значение указанной -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4">JWT claim</link> - -<para> -Для вложенных claim, а также claim, содержащих точку (“.”), -значение переменной вычислить невозможно, -следует использовать директиву <link id="auth_jwt_claim_set"/>. -</para> - -<para> -Значения переменных для tokens, зашифрованных при помощи JWE, -доступны только после дешифрования, которое происходит в -<link doc="../dev/development_guide.xml" id="http_phases">Access</link>-фазе. -</para> -</tag-desc> - -<tag-name id="var_jwt_payload"><var>$jwt_payload</var></tag-name> -<tag-desc> -возвращает расшифрованную полезную нагрузку (payload) верхнего уровня -для <literal>вложенных</literal> -или <literal>зашифрованных</literal> токенов (1.21.2). -Для вложенных токенов возвращает внутренний JWS токен. -Для зашифрованных токенов возвращает JSON с claims. -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/ru/docs/http/ngx_http_auth_request_module.xml +++ b/xml/ru/docs/http/ngx_http_auth_request_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_auth_request_module" link="/ru/docs/http/ngx_http_auth_request_module.html" lang="ru" - rev="5"> + rev="6"> <section id="summary"> @@ -36,10 +36,8 @@ <para> Модуль может быть скомбинирован с другими модулями доступа, такими как -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> -и -<link doc="ngx_http_auth_jwt_module.xml">ngx_http_auth_jwt_module</link>, +<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> и +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, с помощью директивы <link doc="ngx_http_core_module.xml" id="satisfy"/>. <note> До версии 1.7.3 ответы на авторизационные подзапросы не могли быть закэшированы
--- a/xml/ru/docs/http/ngx_http_core_module.xml +++ b/xml/ru/docs/http/ngx_http_core_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_core_module" link="/ru/docs/http/ngx_http_core_module.html" lang="ru" - rev="106"> + rev="107"> <section id="directives" name="Директивы"> @@ -259,9 +259,8 @@ location /images/ { <para> Задерживает обработку неавторизованных запросов с кодом ответа 401 для предотвращения атак по времени в случае ограничения доступа по -<link doc="ngx_http_auth_basic_module.xml">паролю</link>, по -<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link> -или по <link doc="ngx_http_auth_jwt_module.xml">JWT</link>. +<link doc="ngx_http_auth_basic_module.xml">паролю</link> или по +<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link>. </para> </directive> @@ -848,7 +847,6 @@ error_page 404 =301 http://example.com/n запросы, перенаправленные директивами <link id="error_page"/>, <link doc="ngx_http_index_module.xml" id="index"/>, -<link doc="ngx_http_internal_redirect_module.xml" id="internal_redirect"/>, <link doc="ngx_http_random_index_module.xml" id="random_index"/> и <link id="try_files"/>; </listitem> @@ -1065,11 +1063,8 @@ keep-alive, эти буферы освобождаются. Если разрешён метод <literal>GET</literal>, то метод <literal>HEAD</literal> также будет разрешён. Доступ к остальным методам может быть ограничен при помощи директив модулей -<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> -и -<link doc="ngx_http_auth_jwt_module.xml">ngx_http_auth_jwt_module</link> -(1.13.10): +<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> и +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: <example> limit_except GET { allow 192.168.1.0/32; @@ -2182,8 +2177,7 @@ open_file_cache_events on; <value>адрес</value> ... [<literal>valid</literal>=<value>время</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>зона</value>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <default/> <context>http</context> <context>server</context> @@ -2235,16 +2229,6 @@ resolver 127.0.0.1 [::1]:5353 valid=30s; </note> </para> -<para id="resolver_status_zone"> -Необязательный параметр <literal>status_zone</literal> (1.17.1) -включает -<link doc="ngx_http_api_module.xml" id="resolvers_">сбор информации</link> -о запросах и ответах сервера DNS -в указанной <value>зоне</value>. -Параметр доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</para> - </directive> @@ -2311,10 +2295,9 @@ location /i/ { Разрешает доступ, если все (<literal>all</literal>) или хотя бы один (<literal>any</literal>) из модулей <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, -<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> +или <link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link> -или -<link doc="ngx_http_auth_jwt_module.xml">ngx_http_auth_jwt_module</link> разрешают доступ. </para> @@ -2666,8 +2649,7 @@ server { <syntax> <literal>on</literal> | <literal>off</literal> | - <literal>build</literal> | - <value>строка</value></syntax> + <literal>build</literal></syntax> <default>on</default> <context>http</context> <context>server</context> @@ -2684,16 +2666,6 @@ server { <link doc="../configure.xml" id="build">имя сборки</link>. </para> -<para> -Дополнительно, как часть -<commercial_version>коммерческой подписки</commercial_version>, -начиная с версии 1.9.13 -подписи на страницах ошибок и -значение поля <header>Server</header> заголовка ответа -можно задать явно с помощью строки с переменными. -Пустая строка запрещает выдачу поля <header>Server</header>. -</para> - </directive>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_f4f_module.xml +++ /dev/null @@ -1,89 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_f4f_module" - link="/ru/docs/http/ngx_http_f4f_module.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_f4f_module</literal> обеспечивает -серверную поддержку протокола Adobe HTTP Dynamic Streaming (HDS). -</para> - -<para> -Модуль предоставляет возможность обработки запросов HTTP Dynamic Streaming в -виде “<literal>/videoSeg1-Frag1</literal>”, т.е. извлечения необходимого фрагмента -из <path>videoSeg1.f4f</path> при помощи -индексного файла <path>videoSeg1.f4x</path>. -Модуль является альтернативой модулю Adobe f4f (HTTP Origin Module) -для Apache. -</para> - -<para> -Необходима предварительная обработка данных при помощи Adobe f4fpackager, -дополнительную информацию см. в соответствующей документации. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -location /video/ { - f4f; - ... -} -</example> -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="f4f"> -<syntax/> -<default/> -<context>location</context> - -<para> -Включает обработку данным модулем во вложенном location. -</para> - -</directive> - - -<directive name="f4f_buffer_size"> -<syntax><value>размер</value></syntax> -<default>512k</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Задаёт <value>размер</value> буфера, в который будет -читаться индексный файл <path>.f4x</path>. -</para> - -</directive> - -</section> - -</module>
--- a/xml/ru/docs/http/ngx_http_fastcgi_module.xml +++ b/xml/ru/docs/http/ngx_http_fastcgi_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_fastcgi_module" link="/ru/docs/http/ngx_http_fastcgi_module.html" lang="ru" - rev="53"> + rev="54"> <section id="summary"> @@ -393,11 +393,7 @@ range-запрос будет передан на FastCGI-сервер [<literal>manager_threshold</literal>=<value>время</value>] [<literal>loader_files</literal>=<value>число</value>] [<literal>loader_sleep</literal>=<value>время</value>] - [<literal>loader_threshold</literal>=<value>время</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>число</value>] - [<literal>purger_sleep</literal>=<value>время</value>] - [<literal>purger_threshold</literal>=<value>время</value>]</syntax> + [<literal>loader_threshold</literal>=<value>время</value>]</syntax> <default/> <context>http</context> @@ -442,16 +438,6 @@ fastcgi_cache_path /data/nginx/cache lev разделяемой памяти, <value>имя</value> и <value>размер</value> которой задаются параметром <literal>keys_zone</literal>. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. -<note> -Как часть -<commercial_version>коммерческой подписки</commercial_version> -в зоне разделяемой памяти также хранится расширенная -<link doc="ngx_http_api_module.xml" id="http_caches_">информация</link> о кэше, -поэтому для хранения аналогичного количества ключей необходимо указывать -больший размер зоны. -Например -зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч ключей. -</note> </para> <para> @@ -494,56 +480,6 @@ fastcgi_cache_path /data/nginx/cache lev </para> <para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Указывает, будут ли записи в кэше, соответствующие -<link id="fastcgi_cache_purge">маске</link>, -удалены с диска при помощи процесса “cache purger” (1.7.12). -Установка параметра в значение <literal>on</literal> -(по умолчанию <literal>off</literal>) -активирует процесс “cache purger”, который -проходит по всем записям в кэше -и удаляет записи, соответствующие этой маске. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>число</value> -</tag-name> -<tag-desc> -Задаёт число элементов, которые будут сканироваться за одну итерацию (1.7.12). -По умолчанию <literal>purger_files</literal> равен 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт продолжительность одной итерации (1.7.12). -По умолчанию <literal>purger_threshold</literal> равен 50 миллисекундам. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт паузу между итерациями (1.7.12). -По умолчанию <literal>purger_sleep</literal> равен 50 миллисекундам. -</tag-desc> - -</list> -</para> - -<para> <note> В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён. При обновлении на более новую версию nginx @@ -554,64 +490,6 @@ fastcgi_cache_path /data/nginx/cache lev </directive> -<directive name="fastcgi_cache_purge"> -<syntax>строка ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Задаёт условия, при которых запрос будет считаться запросом -на очистку кэша. -Если значение хотя бы одного из строковых параметров непустое и не равно “0”, -то запись в кэше с соответствующим -<link id="fastcgi_cache_key">ключом кэширования</link> удаляется. -В результате успешной операции возвращается ответ с кодом -<http-status code="204" text="No Content"/>. -</para> - -<para> -Если <link id="fastcgi_cache_key">ключ кэширования</link> -запроса на очистку заканчивается -звёздочкой (“<literal>*</literal>”), то все записи в кэше, соответствующие -этой маске, будут удалены из кэша. -Тем не менее, эти записи будут оставаться на диске или до момента удаления -из-за <link id="fastcgi_cache_path">отсутствия обращения к данным</link>, -или до обработки их процессом “<link id="purger">cache purger</link>” (1.7.12), -или до попытки клиента получить к ним доступ. -</para> - -<para> -Пример конфигурации: -<example> -fastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - fastcgi_pass http://backend; - fastcgi_cache cache_zone; - fastcgi_cache_key $uri; - fastcgi_cache_purge $purge_method; - } -} -</example> -<note> -Функциональность доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="fastcgi_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_hls_module.xml +++ /dev/null @@ -1,278 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Module ngx_http_hls_module" - link="/ru/docs/http/ngx_http_hls_module.html" - lang="ru" - rev="7"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_hls_module</literal> обеспечивает серверную поддержку -протокола HTTP Live Streaming (HLS) для медиафайлов в формате MP4 и MOV. -Такие файлы обычно имеют расширения <path>.mp4</path>, <path>.m4v</path>, -<path>.m4a</path>, <path>.mov</path> или <path>.qt</path>. -Модуль поддерживает видеокодек H.264, а также аудиокодеки AAC и MP3. -</para> - -<para> -Для каждого медиафайла поддерживается два URI: -<list type="bullet"> - -<listitem> -URI плейлиста, имеющий расширение “<literal>.m3u8</literal>”. -URI может принимать необязательные аргументы: -<list type="bullet"> - -<listitem> -“<literal>start</literal>” и “<literal>end</literal>” -задают границы плейлиста в секундах (1.9.0). -</listitem> - -<listitem> -“<literal>offset</literal>” сдвигает первоначальную позицию воспроизведения -на указанное время в секундах (1.9.0). -Положительное значение задаёт временной сдвиг с начала плейлиста. -Отрицательное значение задаёт временной сдвиг с конца последнего фрагмента -в плейлисте. -</listitem> - -<listitem> -“<literal>len</literal>” задаёт длину фрагмента в секундах. -</listitem> -</list> - -</listitem> - -<listitem> -URI фрагмента, имеющий расширение “<literal>.ts</literal>”. -URI может принимать необязательные аргументы: -<list type="bullet"> - -<listitem> -“<literal>start</literal>” и “<literal>end</literal>” -задают границы фрагмента в секундах. -</listitem> - -</list> -</listitem> - -</list> -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -location / { - hls; - hls_fragment 5s; - hls_buffers 10 10m; - hls_mp4_buffer_size 1m; - hls_mp4_max_buffer_size 5m; - root /var/video/; -} -</example> -В такой конфигурации для файла “<path>/var/video/test.mp4</path>” -будут поддерживаться следующие URI: -<example> -http://hls.example.com/test.mp4.m3u8?offset=1.000&start=1.000&end=2.200 -http://hls.example.com/test.mp4.m3u8?len=8.000 -http://hls.example.com/test.mp4.ts?start=1.000&end=2.200 -</example> -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="hls"> -<syntax/> -<default/> -<context>location</context> - -<para> -Включает HLS-поток во вложенном location. -</para> - -</directive> - - -<directive name="hls_buffers"> -<syntax><value>число</value> <value>размер</value></syntax> -<default>8 2m</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Задаёт максимальное <value>число</value> и <value>размер</value> буферов, -которые используются для чтения и записи блоков данных. -</para> - -</directive> - - -<directive name="hls_forward_args"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.12</appeared-in> - -<para> -Добавляет аргументы из запроса плейлиста в URI фрагментов. -Это может быть необходимо для авторизации клиента -во время запроса фрагментов, а также для защиты HLS-потока с помощью -модуля -<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>. -</para> - -<para> -Например, если клиент запрашивает плейлист -<literal>http://example.com/hls/test.mp4.m3u8?a=1&b=2</literal>, -то аргументы <literal>a=1</literal> и <literal>b=2</literal> -будут добавлены в URI фрагментов после аргументов -<literal>start</literal> и <literal>end</literal>: -<example> -#EXTM3U -#EXT-X-VERSION:3 -#EXT-X-TARGETDURATION:15 -#EXT-X-PLAYLIST-TYPE:VOD - -#EXTINF:9.333, -test.mp4.ts?start=0.000&end=9.333&a=1&b=2 -#EXTINF:7.167, -test.mp4.ts?start=9.333&end=16.500&a=1&b=2 -#EXTINF:5.416, -test.mp4.ts?start=16.500&end=21.916&a=1&b=2 -#EXTINF:5.500, -test.mp4.ts?start=21.916&end=27.416&a=1&b=2 -#EXTINF:15.167, -test.mp4.ts?start=27.416&end=42.583&a=1&b=2 -#EXTINF:9.626, -test.mp4.ts?start=42.583&end=52.209&a=1&b=2 - -#EXT-X-ENDLIST -</example> -</para> - -<para> -Если HLS-поток защищён с помощью модуля -<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>, -переменную <var>$uri</var> не следует использовать в выражении -<link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/>, -так как это приведёт к ошибкам при запросах к фрагментам. -Вместо <var>$uri</var> следует использовать -<link doc="ngx_http_map_module.xml" id="map">базовую часть URI</link> -(<var>$hls_uri</var> в примере): -<example> -http { - ... - - map $uri $hls_uri { - ~^(?<base_uri>.*).m3u8$ $base_uri; - ~^(?<base_uri>.*).ts$ $base_uri; - default $uri; - } - - server { - ... - - location /hls/ { - hls; - hls_forward_args on; - - alias /var/videos/; - - secure_link $arg_md5,$arg_expires; - secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret"; - - if ($secure_link = "") { - return 403; - } - - if ($secure_link = "0") { - return 410; - } - } - } -} -</example> -</para> - -</directive> - - -<directive name="hls_fragment"> -<syntax><value>время</value></syntax> -<default>5s</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Задаёт длину фрагмента по умолчанию для всех URI в плейлисте, -запрошенных без аргумента “<literal>len</literal>”. -</para> - -</directive> - - -<directive name="hls_mp4_buffer_size"> -<syntax><value>размер</value></syntax> -<default>512k</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Задаёт начальный <value>размер</value> буфера, используемого для -обработки MP4- и MOV-файлов. -</para> - -</directive> - - -<directive name="hls_mp4_max_buffer_size"> -<syntax><value>размер</value></syntax> -<default>10m</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -В ходе обработки метаданных может понадобиться буфер большего размера. -Его <value>размер</value> не может превышать указанного, -иначе nginx вернёт серверную ошибку -<http-status code="500" text="Internal Server Error"/> -и запишет в лог следующее сообщение: -<example> -"/some/movie/file.mp4" mp4 moov atom is too large: -12583268, you may want to increase hls_mp4_max_buffer_size -</example> -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_internal_redirect_module.xml +++ /dev/null @@ -1,99 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_internal_redirect_module" - link="/ru/docs/http/ngx_http_internal_redirect_module.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_internal_redirect_module</literal> (1.23.4) позволяет -осуществлять внутреннее перенаправление. -В отличие от -<link doc="ngx_http_rewrite_module.xml">изменения URI</link>, -перенаправление происходит после проверок ограничений -<link doc="ngx_http_limit_req_module.xml">скорости обработки запросов</link>, -<link doc="ngx_http_limit_conn_module.xml">числа соединений</link> -и <link doc="ngx_http_access_module.xml">доступа</link>. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version> -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -limit_req_zone $jwt_claim_sub zone=jwt_sub:10m rate=1r/s; - -server { - location / { - auth_jwt "realm"; - auth_jwt_key_file key.jwk; - - internal_redirect @rate_limited; - } - - location @rate_limited { - internal; - - limit_req zone=jwt_sub burst=10; - proxy_pass http://backend; - } -} -</example> -В примере -<link doc="ngx_http_limit_req_module.xml">скорость обработки запросов</link> -ограничивается по -<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2">идентификатору -клиента</link>. -Конфигурация без <link id="internal_redirect">internal_redirect</link> -может быть подвержена DoS-атакам при помощи неподписанных JWT, так как проверка -<link doc="ngx_http_limit_req_module.xml" id="limit_req">limit_req</link> -выполняется -<link doc="../dev/development_guide.xml" id="http_phases">перед</link> -проверкой -<link doc="ngx_http_auth_jwt_module.xml" id="auth_jwt">auth_jwt</link>. -Использование <link id="internal_redirect">internal_redirect</link> -позволяет изменить порядок этих проверок. -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="internal_redirect"> -<syntax><value>uri</value></syntax> -<default/> -<context>server</context> -<context>location</context> - -<para> -Задаёт URI для внутреннего перенаправления запроса. -Вместо URI также можно использовать -<link doc="ngx_http_core_module.xml" id="location_named">именованный location</link>. -В значении <value>uri</value> можно использовать переменные. -Если значение <value>uri</value> пустое, -то перенаправление не осуществляется. -</para> - -</directive> - -</section> - -</module>
--- a/xml/ru/docs/http/ngx_http_limit_conn_module.xml +++ b/xml/ru/docs/http/ngx_http_limit_conn_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_limit_conn_module" link="/ru/docs/http/ngx_http_limit_conn_module.html" lang="ru" - rev="14"> + rev="15"> <section id="summary"> @@ -198,19 +198,6 @@ limit_conn_zone $binary_remote_addr zone <link id="limit_conn_status">ошибку</link>. </para> -<para> -<note> -Дополнительно, как часть -<commercial_version>коммерческой подписки</commercial_version>, -<link doc="ngx_http_api_module.xml" id="http_limit_conns_">информацию о состоянии</link> -каждой такой зоны разделяемой памяти можно -<link doc="ngx_http_api_module.xml" id="getHttpLimitConnZone">получить</link> или -<link doc="ngx_http_api_module.xml" id="deleteHttpLimitConnZoneStat">сбросить</link> -при помощи <link doc="ngx_http_api_module.xml">API</link> -начиная с версии 1.17.7. -</note> -</para> - </directive>
--- a/xml/ru/docs/http/ngx_http_limit_req_module.xml +++ b/xml/ru/docs/http/ngx_http_limit_req_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_limit_req_module" link="/ru/docs/http/ngx_http_limit_req_module.html" lang="ru" - rev="16"> + rev="17"> <section id="summary"> @@ -186,8 +186,7 @@ server { <syntax> <value>ключ</value> <literal>zone</literal>=<value>название</value>:<value>размер</value> - <literal>rate</literal>=<value>скорость</value> - [<literal>sync</literal>]</syntax> + <literal>rate</literal>=<value>скорость</value></syntax> <default/> <context>http</context> @@ -237,29 +236,6 @@ 64 байтам на 32-битных платформах и 128 байтам на 64-битных платформах. ползапроса в секунду — это 30r/m. </para> -<para id="limit_req_zone_sync"> -Параметр <literal>sync</literal> (1.15.3) разрешает -<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">синхронизацию</link> -данной зоны разделяемой памяти. -<note> -Параметр <literal>sync</literal> доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -<para> -<note> -Дополнительно, как часть -<commercial_version>коммерческой подписки</commercial_version>, -<link doc="ngx_http_api_module.xml" id="http_limit_reqs_">информацию о состоянии</link> -каждой такой зоны разделяемой памяти можно -<link doc="ngx_http_api_module.xml" id="getHttpLimitReqZone">получить</link> или -<link doc="ngx_http_api_module.xml" id="deleteHttpLimitReqZoneStat">сбросить</link> -при помощи <link doc="ngx_http_api_module.xml">API</link> -начиная с версии 1.17.7. -</note> -</para> - </directive> </section>
--- a/xml/ru/docs/http/ngx_http_mp4_module.xml +++ b/xml/ru/docs/http/ngx_http_mp4_module.xml @@ -185,62 +185,6 @@ 12583268, you may want to increase mp4_m </directive> -<directive name="mp4_limit_rate"> -<syntax> - <literal>on</literal> | - <literal>off</literal> | - <value>множитель</value></syntax> -<default>off</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Ограничивает скорость передачи ответа клиенту. -Ограничение основывается на значении усреднённого битрейта запрашиваемого -MP4-файла. -Скорость вычисляется умножением битрейта на задаваемый -<value>множитель</value>. -Специальное значение “<literal>on</literal>” соответствует множителю 1.1. -Специальное значение “<literal>off</literal>” отключает ограничение скорости. -Ограничение устанавливается на запрос, поэтому, если клиент одновременно -откроет два соединения, суммарная скорость будет вдвое выше -заданного ограничения. -</para> - -<para> -<note> -Директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="mp4_limit_rate_after"> -<syntax><value>время</value></syntax> -<default>60s</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -Задаёт начальный объём медиаданных (измеряется как время воспроизведения), -после отправки которого начинает ограничиваться -скорость передачи ответа клиенту. -</para> - -<para> -<note> -Директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="mp4_start_key_frame"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
--- a/xml/ru/docs/http/ngx_http_proxy_module.xml +++ b/xml/ru/docs/http/ngx_http_proxy_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_proxy_module" link="/ru/docs/http/ngx_http_proxy_module.html" lang="ru" - rev="76"> + rev="77"> <section id="summary"> @@ -410,11 +410,7 @@ range-запрос будет передан на проксируемый сервер [<literal>manager_threshold</literal>=<value>время</value>] [<literal>loader_files</literal>=<value>число</value>] [<literal>loader_sleep</literal>=<value>время</value>] - [<literal>loader_threshold</literal>=<value>время</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>число</value>] - [<literal>purger_sleep</literal>=<value>время</value>] - [<literal>purger_threshold</literal>=<value>время</value>]</syntax> + [<literal>loader_threshold</literal>=<value>время</value>]</syntax> <default/> <context>http</context> @@ -459,16 +455,6 @@ proxy_cache_path /data/nginx/cache level разделяемой памяти, <value>имя</value> и <value>размер</value> которой задаются параметром <literal>keys_zone</literal>. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. -<note> -Как часть -<commercial_version>коммерческой подписки</commercial_version> -в зоне разделяемой памяти также хранится расширенная -<link doc="ngx_http_api_module.xml" id="http_caches_">информация</link> о кэше, -поэтому для хранения аналогичного количества ключей необходимо указывать -больший размер зоны. -Например -зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч ключей. -</note> </para> <para> @@ -511,56 +497,6 @@ proxy_cache_path /data/nginx/cache level </para> <para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Указывает, будут ли записи в кэше, соответствующие -<link id="proxy_cache_purge">маске</link>, -удалены с диска при помощи процесса “cache purger” (1.7.12). -Установка параметра в значение <literal>on</literal> -(по умолчанию <literal>off</literal>) -активирует процесс “cache purger”, который -проходит по всем записям в кэше -и удаляет записи, соответствующие этой маске. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>число</value> -</tag-name> -<tag-desc> -Задаёт число элементов, которые будут сканироваться за одну итерацию (1.7.12). -По умолчанию <literal>purger_files</literal> равен 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт продолжительность одной итерации (1.7.12). -По умолчанию <literal>purger_threshold</literal> равен 50 миллисекундам. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт паузу между итерациями (1.7.12). -По умолчанию <literal>purger_sleep</literal> равен 50 миллисекундам. -</tag-desc> - -</list> -</para> - -<para> <note> В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён. При обновлении на более новую версию nginx @@ -571,64 +507,6 @@ proxy_cache_path /data/nginx/cache level </directive> -<directive name="proxy_cache_purge"> -<syntax>строка ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Задаёт условия, при которых запрос будет считаться запросом -на очистку кэша. -Если значение хотя бы одного из строковых параметров непустое и не равно “0”, -то запись в кэше с соответствующим -<link id="proxy_cache_key">ключом кэширования</link> удаляется. -В результате успешной операции возвращается ответ с кодом -<http-status code="204" text="No Content"/>. -</para> - -<para> -Если <link id="proxy_cache_key">ключ кэширования</link> -запроса на очистку заканчивается -звёздочкой (“<literal>*</literal>”), то все записи в кэше, соответствующие -этой маске, будут удалены из кэша. -Тем не менее, эти записи будут оставаться на диске или до момента удаления -из-за <link id="proxy_cache_path">отсутствия обращения к данным</link>, -или до обработки их процессом “<link id="purger">cache purger</link>” (1.7.12), -или до попытки клиента получить к ним доступ. -</para> - -<para> -Пример конфигурации: -<example> -proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - proxy_pass http://backend; - proxy_cache cache_zone; - proxy_cache_key $uri; - proxy_cache_purge $purge_method; - } -} -</example> -<note> -Функциональность доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="proxy_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_proxy_protocol_vendor_module.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_proxy_protocol_vendor_module" - link="/ru/docs/http/ngx_http_proxy_protocol_vendor_module.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_proxy_protocol_vendor_module</literal> (1.23.3) -позволяет получать дополнительную информацию о соединении из -облачных платформ при помощи TLV, полученных из -заголовка -<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">протокола -PROXY</link>. -</para> - -<para> -Поддерживаемые облачные платформы: -<list type="bullet"> - -<listitem> -Amazon Web Services -</listitem> - -<listitem> -Google Cloud Platform -</listitem> - -<listitem> -Microsoft Azure -</listitem> - -</list> -</para> - -<para> -Протокол PROXY должен быть предварительно включён при помощи установки -параметра <literal>proxy_protocol</literal> в директиве -<link doc="ngx_http_core_module.xml" id="listen"/>. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version> -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -proxy_set_header X-Conn-ID $proxy_protocol_tlv_gcp_conn_id; - -server { - listen 80 proxy_protocol; - listen 443 ssl proxy_protocol; - ... -} -</example> -</para> - -</section> - - -<section id="variables" name="Встроенные переменные"> - -<para> -<list type="tag"> - -<tag-name id="var_proxy_protocol_tlv_aws_vpce_id"><var>$proxy_protocol_tlv_aws_vpce_id</var></tag-name> -<tag-desc> -значение TLV, полученное из заголовка протокола PROXY, содержащее -<link url="https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol">ID -конечной точки VPC AWS</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_azure_pel_id"><var>$proxy_protocol_tlv_azure_pel_id</var></tag-name> -<tag-desc> -значение TLV, полученное из заголовка протокола PROXY, содержащее -<link url="https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview#getting-connection-information-using-tcp-proxy-v2">LinkID -частной конечной точки Azure</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_gcp_conn_id"><var>$proxy_protocol_tlv_gcp_conn_id</var></tag-name> -<tag-desc> -значение TLV, полученное из заголовка протокола PROXY, содержащее -<link url="https://cloud.google.com/vpc/docs/configure-private-service-connect-producer#proxy-protocol">ID соединения -Google Cloud PSC</link> -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/ru/docs/http/ngx_http_scgi_module.xml +++ b/xml/ru/docs/http/ngx_http_scgi_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_scgi_module" link="/ru/docs/http/ngx_http_scgi_module.html" lang="ru" - rev="41"> + rev="42"> <section id="summary"> @@ -384,11 +384,7 @@ range-запрос будет передан на SCGI-сервер [<literal>manager_threshold</literal>=<value>время</value>] [<literal>loader_files</literal>=<value>число</value>] [<literal>loader_sleep</literal>=<value>время</value>] - [<literal>loader_threshold</literal>=<value>время</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>число</value>] - [<literal>purger_sleep</literal>=<value>время</value>] - [<literal>purger_threshold</literal>=<value>время</value>]</syntax> + [<literal>loader_threshold</literal>=<value>время</value>]</syntax> <default/> <context>http</context> @@ -433,16 +429,6 @@ scgi_cache_path /data/nginx/cache levels разделяемой памяти, <value>имя</value> и <value>размер</value> которой задаются параметром <literal>keys_zone</literal>. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. -<note> -Как часть -<commercial_version>коммерческой подписки</commercial_version> -в зоне разделяемой памяти также хранится расширенная -<link doc="ngx_http_api_module.xml" id="http_caches_">информация</link> о кэше, -поэтому для хранения аналогичного количества ключей необходимо указывать -больший размер зоны. -Например -зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч ключей. -</note> </para> <para> @@ -485,56 +471,6 @@ scgi_cache_path /data/nginx/cache levels </para> <para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Указывает, будут ли записи в кэше, соответствующие -<link id="scgi_cache_purge">маске</link>, -удалены с диска при помощи процесса “cache purger” (1.7.12). -Установка параметра в значение <literal>on</literal> -(по умолчанию <literal>off</literal>) -активирует процесс “cache purger”, который -проходит по всем записям в кэше -и удаляет записи, соответствующие этой маске. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>число</value> -</tag-name> -<tag-desc> -Задаёт число элементов, которые будут сканироваться за одну итерацию (1.7.12). -По умолчанию <literal>purger_files</literal> равен 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт продолжительность одной итерации (1.7.12). -По умолчанию <literal>purger_threshold</literal> равен 50 миллисекундам. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт паузу между итерациями (1.7.12). -По умолчанию <literal>purger_sleep</literal> равен 50 миллисекундам. -</tag-desc> - -</list> -</para> - -<para> <note> В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён. При обновлении на более новую версию nginx @@ -545,64 +481,6 @@ scgi_cache_path /data/nginx/cache levels </directive> -<directive name="scgi_cache_purge"> -<syntax>строка ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Задаёт условия, при которых запрос будет считаться запросом -на очистку кэша. -Если значение хотя бы одного из строковых параметров непустое и не равно “0”, -то запись в кэше с соответствующим -<link id="scgi_cache_key">ключом кэширования</link> удаляется. -В результате успешной операции возвращается ответ с кодом -<http-status code="204" text="No Content"/>. -</para> - -<para> -Если <link id="scgi_cache_key">ключ кэширования</link> -запроса на очистку заканчивается -звёздочкой (“<literal>*</literal>”), то все записи в кэше, соответствующие -этой маске, будут удалены из кэша. -Тем не менее, эти записи будут оставаться на диске или до момента удаления -из-за <link id="scgi_cache_path">отсутствия обращения к данным</link>, -или до обработки их процессом “<link id="purger">cache purger</link>” (1.7.12), -или до попытки клиента получить к ним доступ. -</para> - -<para> -Пример конфигурации: -<example> -scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - scgi_pass http://backend; - scgi_cache cache_zone; - scgi_cache_key $uri; - scgi_cache_purge $purge_method; - } -} -</example> -<note> -Функциональность доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="scgi_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_status_module.xml +++ /dev/null @@ -1,1170 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_status_module" - link="/ru/docs/http/ngx_http_status_module.html" - lang="ru" - rev="19"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_status_module</literal> предоставляет -доступ к информации о состоянии сервера. -<note> -Этот модуль был доступен как часть -<commercial_version>коммерческой подписки</commercial_version> -до версии 1.13.10. -Модуль был заменён модулем -<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> -в версии 1.13.3. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -http { - upstream <emphasis>backend</emphasis> { - <emphasis>zone</emphasis> http_backend 64k; - - server backend1.example.com weight=5; - server backend2.example.com; - } - - proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m; - - server { - server_name backend.example.com; - - location / { - proxy_pass http://backend; - proxy_cache cache_backend; - - health_check; - } - - <emphasis>status_zone server_backend;</emphasis> - } - - server { - listen 127.0.0.1; - - location /upstream_conf { - upstream_conf; - } - - location /status { - status; - } - - location = /status.html { - } - } -} - -stream { - upstream <emphasis>backend</emphasis> { - <emphasis>zone</emphasis> 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; - <emphasis>status_zone server_backend;</emphasis> - health_check; - } -} -</example> -</para> - -<para> -Примеры запросов информации о состоянии, -возможные с данной конфигурацией: -<example> -http://127.0.0.1/status -http://127.0.0.1/status/nginx_version -http://127.0.0.1/status/caches/cache_backend -http://127.0.0.1/status/upstreams -http://127.0.0.1/status/upstreams/backend -http://127.0.0.1/status/upstreams/backend/peers/1 -http://127.0.0.1/status/upstreams/backend/peers/1/weight -http://127.0.0.1/status/stream -http://127.0.0.1/status/stream/upstreams -http://127.0.0.1/status/stream/upstreams/backend -http://127.0.0.1/status/stream/upstreams/backend/peers/1 -http://127.0.0.1/status/stream/upstreams/backend/peers/1/weight -</example> -</para> - -<para> -В составе дистрибутива nginx имеется простая страница мониторинга, доступная -по запросу “<literal>/status.html</literal>” в стандартной конфигурации. -Для работы этой страницы требуется настроить location -“<literal>/status</literal>” и location “<literal>/status.html</literal>” -как показано выше. -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="status"> -<syntax/> -<default/> -<context>location</context> - -<para> -Информация о состоянии будет доступна из содержащего location. -Доступ в location следует -<link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>. -</para> - -</directive> - - -<directive name="status_format"> -<syntax><literal>json</literal></syntax> -<syntax><literal>jsonp</literal> [<value>callback</value>]</syntax> -<default>json</default> -<context>http</context> -<context>server</context> -<context>location</context> - -<para> -По умолчанию информация выводится в формате JSON. -</para> - -<para> -Также данные могут выводиться в формате JSONP. -Параметр <value>callback</value> задаёт имя callback-функции. -В значении параметра можно использовать переменные. -Если параметр не задан или вычисленное значение является пустой строкой, -используется имя “<literal>ngx_status_jsonp_callback</literal>”. -</para> - -</directive> - - -<directive name="status_zone"> -<syntax><value>зона</value></syntax> -<default/> -<context>server</context> - -<para> -Включает сбор информации о состоянии виртуального сервера группы -<link doc="ngx_http_core_module.xml" id="server">http</link> -или -<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> -(1.7.11) в указанной <value>зоне</value>. -В одной и той же зоне может одновременно собираться информация -сразу по нескольким серверам. -</para> - -</directive> - -</section> - - -<section id="data" name="Данные"> - -<para> -Доступна следующая информация: -<list type="tag"> - -<tag-name id="version"><literal>version</literal></tag-name> -<tag-desc> -Версия предоставляемого набора данных. -Текущей является версия 8. -</tag-desc> - -<tag-name><literal>nginx_version</literal></tag-name> -<tag-desc> -Версия nginx. -</tag-desc> - -<tag-name id="nginx_build"><literal>nginx_build</literal></tag-name> -<tag-desc> -Название сборки nginx. -</tag-desc> - -<tag-name><literal>address</literal></tag-name> -<tag-desc> -Адрес сервера, принявшего запрос на получение информации о состоянии. -</tag-desc> - -<tag-name id="generation"><literal>generation</literal></tag-name> -<tag-desc> -Суммарное число -<link doc="../control.xml" id="reconfiguration">перезагрузок</link> -конфигурации. -</tag-desc> - -<tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name> -<tag-desc> -Время последней перезагрузки конфигурации, в миллисекундах с начала эпохи. -</tag-desc> - -<tag-name><literal>timestamp</literal></tag-name> -<tag-desc> -Текущее время в миллисекундах с начала эпохи. -</tag-desc> - -<tag-name id="pid"><literal>pid</literal></tag-name> -<tag-desc> -Идентификатор рабочего процесса, -обработавшего запрос на получение информации о состоянии. -</tag-desc> - -<tag-name id="ppid"><literal>ppid</literal></tag-name> -<tag-desc> -Идентификатор главного процесса, -запустившего <link id="pid">рабочий процесс</link>. -</tag-desc> - -<tag-name id="processes"><literal>processes</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name id="respawned"><literal>respawned</literal></tag-name> -<tag-desc> -Суммарное число перезапусков аварийно завершённых -дочерних процессов. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>connections</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>accepted</literal></tag-name> -<tag-desc> -Суммарное число принятых клиентских соединений. -</tag-desc> - -<tag-name><literal>dropped</literal></tag-name> -<tag-desc> -Суммарное число отвергнутых клиентских соединений. -</tag-desc> - -<tag-name><literal>active</literal></tag-name> -<tag-desc> -Текущее число активных клиентских соединений. -</tag-desc> - -<tag-name><literal>idle</literal></tag-name> -<tag-desc> -Текущее число бездействующих клиентских соединений. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="ssl"><literal>ssl</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>handshakes</literal></tag-name> -<tag-desc> -Суммарное число успешных операций SSL handshake. -</tag-desc> - -<tag-name><literal>handshakes_failed</literal></tag-name> -<tag-desc> -Суммарное число неуспешных операций SSL handshake. -</tag-desc> - -<tag-name><literal>session_reuses</literal></tag-name> -<tag-desc> -Суммарное число повторных использований SSL-сессий -во время операций SSL handshake. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>requests</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -Суммарное число клиентских запросов. -</tag-desc> - -<tag-name><literal>current</literal></tag-name> -<tag-desc> -Текущее число клиентских запросов. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="server_zones"><literal>server_zones</literal></tag-name> -<tag-desc> -Для каждой <link id="status_zone"/>: -<list type="tag"> - -<tag-name><literal>processing</literal></tag-name> -<tag-desc> -Число обрабатываемых в настоящий момент -клиентских запросов. -</tag-desc> - -<tag-name><literal>requests</literal></tag-name> -<tag-desc> -Суммарное число -запросов, полученных от клиентов. -</tag-desc> - -<tag-name><literal>responses</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -Суммарное число -ответов, отправленных клиентам. -</tag-desc> - -<tag-name> -<literal>1xx</literal>, -<literal>2xx</literal>, -<literal>3xx</literal>, -<literal>4xx</literal>, -<literal>5xx</literal> -</tag-name> -<tag-desc> -Число ответов со статусами 1xx, 2xx, 3xx, 4xx и 5xx. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="discarded"><literal>discarded</literal></tag-name> -<tag-desc> -Суммарное число запросов, завершившихся без отправки ответа. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -Суммарное число байт, полученных от клиентов. -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -Суммарное число байт, отправленных клиентам. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="slabs"><literal>slabs</literal></tag-name> -<tag-desc> -Для каждой зоны разделяемой памяти, в которой используется распределение slab: -<list type="tag"> - -<tag-name><literal>pages</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>used</literal></tag-name> -<tag-desc> -Текущее число занятых страниц памяти. -</tag-desc> - -<tag-name><literal>free</literal></tag-name> -<tag-desc> -Текущее число свободных страниц памяти. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>slots</literal></tag-name> -<tag-desc> -Для каждого размера слота памяти (8, 16, 32, 64, 128 и т.д.) -доступны следующие данные: -<list type="tag"> - -<tag-name><literal>used</literal></tag-name> -<tag-desc> -Текущее число занятых слотов памяти. -</tag-desc> - -<tag-name><literal>free</literal></tag-name> -<tag-desc> -Текущее число свободных слотов памяти. -</tag-desc> - -<tag-name><literal>reqs</literal></tag-name> -<tag-desc> -Суммарное число попыток выделения памяти указанного размера. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -Число неудачных попыток выделения памяти указанного размера. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="upstreams"><literal>upstreams</literal></tag-name> -<tag-desc> -Для каждой -<link doc="ngx_http_upstream_module.xml" id="zone">динамически -настраиваемой</link> -<link doc="ngx_http_upstream_module.xml" id="upstream">группы</link> -доступны следующие данные: -<list type="tag"> - -<tag-name id="peers"><literal>peers</literal></tag-name> -<tag-desc> -Для каждого -<link doc="ngx_http_upstream_module.xml" id="server">сервера</link> -доступны следующие данные: -<list type="tag"> - -<tag-name id="id"><literal>id</literal></tag-name> -<tag-desc> -Идентификатор сервера. -</tag-desc> - -<tag-name><literal>server</literal></tag-name> -<tag-desc> -<link doc="ngx_http_upstream_module.xml" id="server">Адрес</link> -сервера. -</tag-desc> - -<tag-name id="name"><literal>name</literal></tag-name> -<tag-desc> -Имя сервера, указанное в директиве -<link doc="ngx_http_upstream_module.xml" id="server"/>. -</tag-desc> - -<tag-name id="service"><literal>service</literal></tag-name> -<tag-desc> -Значение параметра -<link doc="ngx_http_upstream_module.xml" id="service"/> -директивы <link doc="ngx_http_upstream_module.xml" id="server"/>. -</tag-desc> - -<tag-name><literal>backup</literal></tag-name> -<tag-desc> -Логическое значение, означающее, является ли сервер -<link doc="ngx_http_upstream_module.xml" id="backup">запасным</link>. -</tag-desc> - -<tag-name><literal>weight</literal></tag-name> -<tag-desc> -<link doc="ngx_http_upstream_module.xml" id="weight">Вес</link> -сервера. -</tag-desc> - -<tag-name id="state"><literal>state</literal></tag-name> -<tag-desc> -Текущее состояние, которое может быть одним из -“<literal>up</literal>”, -“<literal>draining</literal>”, -“<literal>down</literal>”, -“<literal>unavail</literal>”, -“<literal>checking</literal>” -или -“<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name><literal>active</literal></tag-name> -<tag-desc> -Текущее число активных соединений. -</tag-desc> - -<tag-name id="max_conns"><literal>max_conns</literal></tag-name> -<tag-desc> -Ограничение <link doc="ngx_http_upstream_module.xml" id="max_conns"/> -для сервера. -</tag-desc> - -<tag-name><literal>requests</literal></tag-name> -<tag-desc> -Суммарное число -клиентских запросов, перенаправленных на этот сервер. -</tag-desc> - -<tag-name><literal>responses</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -Суммарное число -ответов, полученных от этого сервера. -</tag-desc> - -<tag-name> -<literal>1xx</literal>, -<literal>2xx</literal>, -<literal>3xx</literal>, -<literal>4xx</literal>, -<literal>5xx</literal> -</tag-name> -<tag-desc> -Число ответов со статусами 1xx, 2xx, 3xx, 4xx и 5xx. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -Суммарное число байт, отправленных на этот сервер. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -Суммарное число байт, полученных с этого сервера. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -Суммарное число -неудачных попыток работы с этим сервером. -</tag-desc> - -<tag-name><literal>unavail</literal></tag-name> -<tag-desc> -Количество раз, когда -сервер становился недоступным для клиентских запросов -(состояние “<literal>unavail</literal>”) -из-за достижения порогового числа неудачных попыток -<link doc="ngx_http_upstream_module.xml" id="max_fails"/>. -</tag-desc> - -<tag-name><literal>health_checks</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>checks</literal></tag-name> -<tag-desc> -Суммарное число запросов -<link doc="ngx_http_upstream_hc_module.xml" id="health_check">проверки -работоспособности</link>. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -Число неудачных проверок работоспособности. -</tag-desc> - -<tag-name><literal>unhealthy</literal></tag-name> -<tag-desc> -Количество раз, когда -сервер становился неработоспособным (состояние “<literal>unhealthy</literal>”). -</tag-desc> - -<tag-name><literal>last_passed</literal></tag-name> -<tag-desc> -Логическое значение, означающее, была ли последняя проверка -работоспособности удачной и удовлетворял ли ответ заданным -<link doc="ngx_http_upstream_hc_module.xml" id="match">тестам</link>. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>downtime</literal></tag-name> -<tag-desc> -Суммарное время, -когда сервер находился в состояниях “<literal>unavail</literal>”, -“<literal>checking</literal>” и “<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name><literal>downstart</literal></tag-name> -<tag-desc> -Время (в миллисекундах с начала эпохи), -когда сервер стал -“<literal>unavail</literal>”, -“<literal>checking</literal>” или “<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name id="selected"><literal>selected</literal></tag-name> -<tag-desc> -Время (в миллисекундах с начала эпохи), -когда сервер в последний раз был выбран для обработки запроса (1.7.5). -</tag-desc> - -<tag-name id="header_time"><literal>header_time</literal></tag-name> -<tag-desc> -Среднее время получения -<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">заголовка -ответа</link> от сервера (1.7.10). -До версии 1.11.6 -поле было доступно только при использовании метода балансировки -<link doc="ngx_http_upstream_module.xml" id="least_time"/>. -</tag-desc> - -<tag-name id="response_time"><literal>response_time</literal></tag-name> -<tag-desc> -Среднее время получения -<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">всего -ответа</link> от сервера (1.7.10). -До версии 1.11.6 -поле было доступно только при использовании метода балансировки -<link doc="ngx_http_upstream_module.xml" id="least_time"/>. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>keepalive</literal></tag-name> -<tag-desc> -Текущее число бездействующих -<link doc="ngx_http_upstream_module.xml" id="keepalive"/>-соединений. -</tag-desc> - -<tag-name id="zombies"><literal>zombies</literal></tag-name> -<tag-desc> -Текущее число серверов, удалённых -из группы, но всё ещё обрабатывающих активные клиентские запросы. -</tag-desc> - -<tag-name id="zone"><literal>zone</literal></tag-name> -<tag-desc> -Имя <link doc="ngx_http_upstream_module.xml" id="zone">зоны</link> -разделяемой памяти, -в которой хранятся конфигурация группы и её рабочее состояние. -</tag-desc> - -<tag-name id="queue"><literal>queue</literal></tag-name> -<tag-desc> -Для <link doc="ngx_http_upstream_module.xml" id="queue">очереди</link> запросов -доступны следующие данные: -<list type="tag"> - -<tag-name><literal>size</literal></tag-name> -<tag-desc> -Текущее число запросов в очереди. -</tag-desc> - -<tag-name><literal>max_size</literal></tag-name> -<tag-desc> -Максимальное число запросов, которые могут одновременно находиться в очереди. -</tag-desc> - -<tag-name><literal>overflows</literal></tag-name> -<tag-desc> -Суммарное число запросов, отклонённых из-за переполнения очереди. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="caches"><literal>caches</literal></tag-name> -<tag-desc> -Для каждого кэша, сконфигурированного при помощи -<link doc="ngx_http_proxy_module.xml" id="proxy_cache_path"/> -и аналогичных директив: -<list type="tag"> - -<tag-name><literal>size</literal></tag-name> -<tag-desc> -Текущий размер кэша. -</tag-desc> - -<tag-name><literal>max_size</literal></tag-name> -<tag-desc> -Ограничение на максимальный размер кэша, заданное в конфигурации. -</tag-desc> - -<tag-name><literal>cold</literal></tag-name> -<tag-desc> -Логическое значение, указывающее, продолжается ли загрузка -данных процессом “cache loader” с диска в кэш. -</tag-desc> - -<tag-name> - <literal>hit</literal>, - <literal>stale</literal>, - <literal>updating</literal>, - <literal>revalidated</literal> -</tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>responses</literal></tag-name> -<tag-desc> -Суммарное число ответов, прочитанных из кэша (попадания в кэш -или просроченные ответы вследствие -<link doc="ngx_http_proxy_module.xml" id="proxy_cache_use_stale"/> -и аналогичных директив). -</tag-desc> - -<tag-name><literal>bytes</literal></tag-name> -<tag-desc> -Суммарное число байт, прочитанных из кэша. -</tag-desc> - -</list> -</tag-desc> - -<tag-name> - <literal>miss</literal>, - <literal>expired</literal>, - <literal>bypass</literal> -</tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>responses</literal></tag-name> -<tag-desc> -Суммарное число ответов, взятых не из кэша (<literal>miss</literal> — -отсутствие данных в кэше, <literal>expired</literal> — просроченные ответы, -<literal>bypass</literal> — ответ не был взят из кэша -вследствие <link doc="ngx_http_proxy_module.xml" id="proxy_cache_bypass"/> -и аналогичных директив). -</tag-desc> - -<tag-name><literal>bytes</literal></tag-name> -<tag-desc> -Суммарное число байт, прочитанных с проксируемого сервера. -</tag-desc> - -<tag-name><literal>responses_written</literal></tag-name> -<tag-desc> -Суммарное число ответов, записанных в кэш. -</tag-desc> - -<tag-name><literal>bytes_written</literal></tag-name> -<tag-desc> -Суммарное число байт, записанных в кэш. -</tag-desc> - -</list> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="stream"><literal>stream</literal></tag-name> -<tag-desc> - -<list type="tag"> -<tag-name id="stream_server_zones"><literal>server_zones</literal></tag-name> -<tag-desc> -Для каждой <link id="status_zone"/>: -<list type="tag"> - -<tag-name><literal>processing</literal></tag-name> -<tag-desc> -Число обрабатываемых в настоящий момент -клиентских соединений. -</tag-desc> - -<tag-name><literal>connections</literal></tag-name> -<tag-desc> -Суммарное число -соединений, полученных от клиентов. -</tag-desc> - -<tag-name id="sessions"><literal>sessions</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>total</literal></tag-name> -<tag-desc> -Суммарное число завершённых клиентских сессий. -</tag-desc> - -<tag-name> -<literal>2xx</literal>, -<literal>4xx</literal>, -<literal>5xx</literal> -</tag-name> -<tag-desc> -Число завершённых сессий со -<link doc="../stream/ngx_stream_core_module.xml" id="var_status">статусами</link> -2xx, 4xx или 5xx. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="stream_discarded"><literal>discarded</literal></tag-name> -<tag-desc> -Суммарное число соединений, завершённых без создания сессии. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -Суммарное число байт, полученных от клиентов. -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -Суммарное число байт, отправленных клиентам. -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="stream_upstreams"><literal>upstreams</literal></tag-name> -<tag-desc> -Для каждого -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">сервера</link> -в -<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">динамически -настраиваемой</link> -<link doc="../stream/ngx_stream_upstream_module.xml" id="upstream">группе</link> -доступны следующие данные: -<list type="tag"> - -<tag-name><literal>id</literal></tag-name> -<tag-desc> -Идентификатор сервера. -</tag-desc> - -<tag-name><literal>server</literal></tag-name> -<tag-desc> -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">Адрес</link> -сервера. -</tag-desc> - -<tag-name id="stream_name"><literal>name</literal></tag-name> -<tag-desc> -Имя сервера, указанное в директиве -<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/>. -</tag-desc> - -<tag-name id="stream_service"><literal>service</literal></tag-name> -<tag-desc> -Значение параметра -<link doc="ngx_http_upstream_module.xml" id="service"/> -директивы <link doc="ngx_http_upstream_module.xml" id="server"/>. -</tag-desc> - -<tag-name><literal>backup</literal></tag-name> -<tag-desc> -Логическое значение, означающее, является ли сервер -<link doc="../stream/ngx_stream_upstream_module.xml" id="backup">запасным</link>. -</tag-desc> - -<tag-name><literal>weight</literal></tag-name> -<tag-desc> -<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">Вес</link> -сервера. -</tag-desc> - -<tag-name><literal>state</literal></tag-name> -<tag-desc> -Текущее состояние, которое может быть одним из -“<literal>up</literal>”, -“<literal>down</literal>”, -“<literal>unavail</literal>”, -“<literal>checking</literal>” -или -“<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name><literal>active</literal></tag-name> -<tag-desc> -Текущее число соединений. -</tag-desc> - -<tag-name><literal>max_conns</literal></tag-name> -<tag-desc> -Ограничение -<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns"/> -для сервера. -</tag-desc> - -<tag-name><literal>connections</literal></tag-name> -<tag-desc> -Суммарное число -клиентских соединений, перенаправленных на этот сервер. -</tag-desc> - -<tag-name><literal>connect_time</literal></tag-name> -<tag-desc> -Среднее время установки соединения с сервером группы. -До версии 1.11.6 -поле было доступно только при использовании метода балансировки -<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/>. -</tag-desc> - -<tag-name><literal>first_byte_time</literal></tag-name> -<tag-desc> -Среднее время получения первого байта данных. -До версии 1.11.6 -поле было доступно только при использовании метода балансировки -<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/>. -</tag-desc> - -<tag-name><literal>response_time</literal></tag-name> -<tag-desc> -Среднее время получения последнего байта данных. -До версии 1.11.6 -поле было доступно только при использовании метода балансировки -<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/>. -</tag-desc> - -<tag-name><literal>sent</literal></tag-name> -<tag-desc> -Суммарное число байт, отправленных на этот сервер. -</tag-desc> - -<tag-name><literal>received</literal></tag-name> -<tag-desc> -Суммарное число байт, полученных с этого сервера. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -Суммарное число -неудачных попыток работы с этим сервером. -</tag-desc> - -<tag-name><literal>unavail</literal></tag-name> -<tag-desc> -Количество раз, когда -сервер становился недоступным для клиентских соединений -(состояние “<literal>unavail</literal>”) -из-за достижения порогового числа неудачных попыток -<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails"/>. -</tag-desc> - -<tag-name><literal>health_checks</literal></tag-name> -<tag-desc> -<list type="tag"> - -<tag-name><literal>checks</literal></tag-name> -<tag-desc> -Суммарное число запросов -<link doc="../stream/ngx_stream_upstream_hc_module.xml" id="health_check">проверки -работоспособности</link>. -</tag-desc> - -<tag-name><literal>fails</literal></tag-name> -<tag-desc> -Число неудачных проверок работоспособности. -</tag-desc> - -<tag-name><literal>unhealthy</literal></tag-name> -<tag-desc> -Количество раз, когда -сервер становился неработоспособным (состояние “<literal>unhealthy</literal>”). -</tag-desc> - -<tag-name><literal>last_passed</literal></tag-name> -<tag-desc> -Логическое значение, означающее, была ли последняя проверка -работоспособности удачной и удовлетворял ли ответ заданным -<link doc="../stream/ngx_stream_upstream_hc_module.xml" id="match">тестам</link>. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>downtime</literal></tag-name> -<tag-desc> -Суммарное время, -когда сервер находился в состояниях “<literal>unavail</literal>”, -“<literal>checking</literal>” и “<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name><literal>downstart</literal></tag-name> -<tag-desc> -Время (в миллисекундах с начала эпохи), -когда сервер стал -“<literal>unavail</literal>”, -“<literal>checking</literal>” или “<literal>unhealthy</literal>”. -</tag-desc> - -<tag-name><literal>selected</literal></tag-name> -<tag-desc> -Время (в миллисекундах с начала эпохи), -когда сервер в последний раз был выбран для обработки соединения. -</tag-desc> - -</list> -</tag-desc> - -<tag-name><literal>zombies</literal></tag-name> -<tag-desc> -Текущее число серверов, удалённых -из группы, но всё ещё обрабатывающих активные клиентские соединения. -</tag-desc> - -<tag-name><literal>zone</literal></tag-name> -<tag-desc> -Имя <link doc="../stream/ngx_stream_upstream_module.xml" id="zone">зоны</link> -разделяемой памяти, -в которой хранятся конфигурация группы и её рабочее состояние. -</tag-desc> - -</list> -</tag-desc> - -</list> -</para> - -</section> - -<section id="compatibility" name="Совместимость"> - -<para> -<list type="bullet"> - -<listitem> -Поле <link id="zone"/> в -<link id="upstreams">http</link> и <link id="stream_upstreams">stream</link> -upstreams -было добавлено в <link id="version">версии</link> 8. -</listitem> - -<listitem> -Поля <link id="slabs"/> -были добавлены в <link id="version">версии</link> 8. -</listitem> - -<listitem> -Состояние -<link id="state">checking</link> -было добавлено в <link id="version">версии</link> 8. -</listitem> - -<listitem> -Поля -<link id="name"/> и <link id="service"/> в -<link id="upstreams">http</link> и <link id="stream_upstreams">stream</link> -upstreams -были добавлены в <link id="version">версии</link> 8. -</listitem> - -<listitem> -Поля <link id="nginx_build"/> и <link id="ppid"/> -были добавлены в <link id="version">версии</link> 8. -</listitem> - -<listitem> -Поля <link id="sessions"/> -и поле <link id="stream_discarded">discarded</link> в -stream <link id="stream_server_zones">server_zones</link> -были добавлены в <link id="version">версии</link> 7. -</listitem> - -<listitem> -Поле <link id="zombies"/> -было перемещено из <link doc="../debugging_log.xml">debug</link>-версии nginx -в <link id="version">версии</link> 6. -</listitem> - -<listitem> -Поля <link id="ssl"/> -были добавлены в <link id="version">версии</link> 6. -</listitem> - -<listitem> -Поле <link id="discarded"/> в -<link id="server_zones"/> -было добавлено в <link id="version">версии</link> 6. -</listitem> - -<listitem> -Поля <link id="queue"/> -были добавлены в <link id="version">версии</link> 6. -</listitem> - -<listitem> -Поле <link id="pid"/> -было добавлено в <link id="version">версии</link> 6. -</listitem> - -<listitem> -Список серверов в <link id="upstreams"/> был -перемещён в <link id="peers"/> в -<link id="version">версии</link> 6. -</listitem> - -<listitem> -Поле <literal>keepalive</literal> сервера группы -было удалено в <link id="version">версии</link> 5. -</listitem> - -<listitem> -<link id="stream">stream</link> -был добавлен в <link id="version">версии</link> 5. -</listitem> - -<listitem> -Поле <link id="generation"/> -было добавлено в <link id="version">версии</link> 5. -</listitem> - -<listitem> -Поле <link id="respawned"/> в -<link id="processes"/> -было добавлено в <link id="version">версии</link> 5. -</listitem> - -<listitem> -Поля <link id="header_time"/> и <link id="response_time"/> в -<link id="upstreams"/> -были добавлены в <link id="version">версии</link> 5. -</listitem> - -<listitem> -Поле <link id="selected"/> в -<link id="upstreams"/> -было добавлено в <link id="version">версии</link> 4. -</listitem> - -<listitem> -Состояние <link id="state">draining</link> в -<link id="upstreams"/> -было добавлено в <link id="version">версии</link> 4. -</listitem> - -<listitem> -Поля <link id="id"/> и <link id="max_conns"/> в -<link id="upstreams"/> -были добавлены в <link id="version">версии</link> 3. -</listitem> - -<listitem> -Поле <literal>revalidated</literal> в <link id="caches"/> -было добавлено в <link id="version">версии</link> 3. -</listitem> - -<listitem> -<link id="server_zones"/>, <link id="caches"/> -и <link id="load_timestamp"/> -были добавлены в <link id="version">версии</link> 2. -</listitem> - -</list> -</para> - -</section> - -</module>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_upstream_conf_module.xml +++ /dev/null @@ -1,351 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_upstream_conf_module" - link="/ru/docs/http/ngx_http_upstream_conf_module.html" - lang="ru" - rev="6"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_upstream_conf_module</literal> -позволяет оперативно настраивать группы серверов -при помощи простого HTTP-интерфейса без необходимости перезапуска nginx. -Группа серверов -<link doc="ngx_http_upstream_module.xml" id="zone">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> -должна находиться в разделяемой памяти. -<note> -Этот модуль был доступен как часть -<commercial_version>коммерческой подписки</commercial_version> -до версии 1.13.10. -Модуль был заменён модулем -<link doc="ngx_http_api_module.xml">ngx_http_api_module</link> -в версии 1.13.3. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -upstream backend { - zone upstream_backend 64k; - - ... -} - -server { - location /upstream_conf { - <emphasis>upstream_conf</emphasis>; - allow 127.0.0.1; - deny all; - } -} -</example> -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="upstream_conf"> -<syntax/> -<default/> -<context>location</context> - -<para> -Активирует HTTP-интерфейс для настройки групп серверов в содержащем location. -Доступ в location следует -<link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>. -</para> - -<para> -С помощью команд настройки можно: -<list type="bullet"> - -<listitem>просматривать конфигурацию группы;</listitem> - -<listitem> -просматривать или изменять конфигурацию, а также -удалять серверы; -</listitem> - -<listitem>добавлять новые серверы.</listitem> - -</list> -<note> -Поскольку адреса в группе не обязаны быть уникальными, -обращение к отдельным серверам в группе осуществляется по их идентификаторам. -Идентификаторы назначаются автоматически и показываются при добавлении сервера -или просмотре конфигурации группы. -</note> -</para> - -<para> -Команда настройки состоит из параметров, передаваемых в аргументах запроса, -например: -<example> -http://127.0.0.1/upstream_conf?upstream=backend -</example> -</para> - -<para> -Поддерживаются следующие параметры: - -<list type="tag" compact="no"> - -<tag-name> -<literal>stream=</literal></tag-name> -<tag-desc> -Выбирает группу серверов -<link doc="../stream/ngx_stream_upstream_module.xml">stream</link>. -Если параметр не задан, будет выбрана группа серверов -<link doc="ngx_http_upstream_module.xml">http</link>. -</tag-desc> - -<tag-name> -<literal>upstream=</literal><value>имя</value></tag-name> -<tag-desc> -Выбирает группу серверов для работы. -Параметр является обязательным. -</tag-desc> - -<tag-name> -<literal>id=</literal><value>число</value></tag-name> -<tag-desc> -Выбирает сервер для просмотра, изменения или удаления. -</tag-desc> - -<tag-name> -<literal>remove=</literal></tag-name> -<tag-desc> -Удаляет сервер из группы. -</tag-desc> - -<tag-name> -<literal>add=</literal></tag-name> -<tag-desc> -Добавляет новый сервер в группу. -</tag-desc> - -<tag-name> -<literal>backup=</literal></tag-name> -<tag-desc> -Необходим для добавления запасного сервера. -<note> -До версии 1.7.2 параметр <literal>backup=</literal> требовался -также для просмотра, изменения или удаления существующих запасных серверов. -</note> -</tag-desc> - -<tag-name> -<literal>server=</literal><value>адрес</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>адрес</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="server">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link>. -<para> -При добавлении сервер можно задать в виде доменного имени. -В этом случае любые изменения IP-адресов, соответствующих доменному имени -сервера, отслеживаются и автоматически применяются к конфигурации группы -без необходимости перезапуска nginx (1.7.2). -Для этого в блоке -<link doc="ngx_http_core_module.xml" id="resolver">http</link> -или -<link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> -должна быть задана директива “<literal>resolver</literal>”. -См. также параметр “<literal>resolve</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="resolve">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link>. -</para> -</tag-desc> - -<tag-name> -<literal>service=</literal><value>имя</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>service</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="service">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="service">stream</link> -(1.9.13). -</tag-desc> - -<tag-name> -<literal>weight=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>weight</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="weight">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link>. -</tag-desc> - -<tag-name> -<literal>max_conns=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>max_conns</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link>. -</tag-desc> - -<tag-name> -<literal>max_fails=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>max_fails</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link>. -</tag-desc> - -<tag-name> -<literal>fail_timeout=</literal><value>время</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>fail_timeout</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link>. -</tag-desc> - -<tag-name> -<literal>slow_start=</literal><value>время</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>slow_start</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link>. -</tag-desc> - -<tag-name> -<literal>down=</literal></tag-name> -<tag-desc> -То же, что и параметр “<literal>down</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="down">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link>. -</tag-desc> - -<tag-name id="drain"><literal>drain=</literal></tag-name> -<tag-desc> -Переводит сервер группы серверов -<link doc="ngx_http_upstream_module.xml">http</link> -в режим “draining” (1.7.5). -В этом режиме на сервер будут проксироваться только -<link doc="ngx_http_upstream_module.xml" id="sticky">привязанные</link> -к нему запросы. -</tag-desc> - -<tag-name> -<literal>up=</literal></tag-name> -<tag-desc> -Параметр, обратный по значению параметру “<literal>down</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="down">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link>. -</tag-desc> - -<tag-name> -<literal>route=</literal><value>строка</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>route</literal>” сервера группы -<link doc="ngx_http_upstream_module.xml" id="route">http</link>. -</tag-desc> - -</list> - -Первые три параметра выбирают объект. -Объектом может быть либо группа серверов http или stream, -либо отдельный сервер. -Если остальные параметры не указаны, то показывается конфигурация выбранной -группы или сервера. -</para> - -<para> -Например, команда для просмотра конфигурации всей группы -выглядит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=backend -</example> - -Для просмотра конфигурации отдельного сервера следует указать его идентификатор: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42 -</example> -</para> - -<para> -Для добавления нового сервера в группу -следует указать его адрес в параметре “<literal>server=</literal>”. -Если остальные параметры не указаны, то при добавлении сервера -их значения будут установлены по умолчанию (см. директиву -“<literal>server</literal>” для -<link doc="ngx_http_upstream_module.xml" id="server">http</link> -или -<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link>). -</para> - -<para> -Например, команда для добавления нового основного сервера в группу -выглядит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 -</example> - -Добавление нового запасного сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 -</example> - -Добавление нового основного сервера с нестандартными -значениями параметров и с пометкой его как постоянно недоступного -(“<literal>down</literal>”) происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= -</example> - -Для удаления сервера следует указать его идентификатор: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 -</example> - -Пометка существующего сервера как постоянно недоступного -(“<literal>down</literal>”) происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= -</example> - -Изменение адреса существующего сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 -</example> - -Изменение других параметров существующего сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 -</example> - -Вышеприведённые примеры актуальны для группы серверов -<link doc="ngx_http_upstream_module.xml">http</link>. -Аналогичные примеры для группы серверов -<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> -требуют указания параметра “<literal>stream=</literal>”. -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/ru/docs/http/ngx_http_upstream_hc_module.xml +++ /dev/null @@ -1,411 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_http_upstream_hc_module" - link="/ru/docs/http/ngx_http_upstream_hc_module.html" - lang="ru" - rev="5"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_http_upstream_hc_module</literal> -позволяет активировать периодические проверки работоспособности серверов в -<link doc="ngx_http_upstream_module.xml" id="upstream">группе</link>, -указанной в содержащем location. -Группа должна находиться в -<link doc="ngx_http_upstream_module.xml" id="zone">зоне разделяемой памяти</link>. -</para> - -<para> -Если проверка работоспособности была неуспешной, -то сервер признаётся неработоспособным. -Если для группы задано несколько проверок, -то при любой неуспешной проверке соответствующий сервер будет -считаться неработоспособным. -На неработоспособные серверы и серверы в состоянии “checking” -клиентские запросы передаваться не будут. -</para> - -<para> -<note> -Обратите внимание, что при использовании проверок -большинство переменных имеют пустые значения. -</note> -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -upstream dynamic { - zone upstream_dynamic 64k; - - server backend1.example.com weight=5; - server backend2.example.com:8080 fail_timeout=5s slow_start=30s; - server 192.0.2.1 max_fails=3; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://dynamic; - health_check; - } -} -</example> -Каждому серверу группы <literal>backend</literal> -с интервалом в 5 секунд посылаются запросы “<literal>/</literal>”. -Если происходит ошибка или таймаут при работе с сервером, или -код ответа проксируемого сервера не равен -2xx или 3xx, проверка считается неуспешной и сервер -признаётся неработоспособным. -</para> - -<para> -Проверки работоспособности могут тестировать код ответа, -наличие или отсутствие определённых полей заголовка и их значений, -а также содержимое тела ответа. -Тесты настраиваются отдельно при помощи директивы <link id="match"/> -и указываются в параметре <literal>match</literal>. -Например: -<example> -http { - server { - ... - location / { - proxy_pass http://backend; - health_check match=welcome; - } - } - - match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; - } -} -</example> -В такой конфигурации успешный ответ на проверочный запрос -должен иметь код 200, тип содержимого “<literal>text/html</literal>” -и “<literal>Welcome to nginx!</literal>” в теле ответа. -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="health_check"> -<syntax>[<value>параметры</value>]</syntax> -<default/> -<context>location</context> - -<para> -Активирует периодические проверки работоспособности серверов в -<link doc="ngx_http_upstream_module.xml" id="upstream">группе</link>, -указанной в содержащем location. -</para> - -<para> -Могут быть заданы следующие необязательные параметры: -<list type="tag"> - -<tag-name id="health_check_interval"> -<literal>interval</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт интервал между двумя последовательными проверками, -по умолчанию 5 секунд. -</tag-desc> - -<tag-name id="health_check_jitter"> -<literal>jitter</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт время, в пределах которого -случайным образом задерживается каждая проверка, -по умолчанию задержки нет. -</tag-desc> - -<tag-name id="health_check_fails"> -<literal>fails</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число последовательных неуспешных проверок для определённого сервера, -после которых сервер будет считаться неработоспособным, -по умолчанию 1. -</tag-desc> - -<tag-name id="health_check_passes"> -<literal>passes</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число последовательных успешных проверок для определённого сервера, -после которых сервер будет считаться работоспособным, -по умолчанию 1. -</tag-desc> - -<tag-name id="health_check_uri"> -<literal>uri</literal>=<value>uri</value> -</tag-name> -<tag-desc> -задаёт URI, используемый в запросах, проверяющих работоспособность, -по умолчанию “<literal>/</literal>”. -</tag-desc> - -<tag-name id="health_check_mandatory"> -<literal>mandatory</literal> [<literal>persistent</literal>] -</tag-name> -<tag-desc> -<para> -устанавливает исходное состояние “checking” для сервера -до завершения первой проверки работоспособности (1.11.7). -На серверы в состоянии “checking” клиентские запросы передаваться не будут. -Если параметр не указан, -то исходно сервер будет считаться работоспособным. -</para> - -<para id="health_check_persistent"> -Параметр <literal>persistent</literal> (1.19.7) -устанавливает исходное состояние “up” для сервера после перезагрузки nginx -в случае, если до перезагрузки сервер считался работоспособным. -</para> -</tag-desc> - -<tag-name id="health_check_match"> -<literal>match</literal>=<value>имя</value> -</tag-name> -<tag-desc> -указывает на блок <literal>match</literal> с условиями, которым должен -удовлетворять ответ, чтобы результат проверки считался успешным. -По умолчанию код ответа должен быть 2xx или 3xx. -</tag-desc> - -<tag-name id="health_check_port"> -<literal>port</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт порт, используемый при подключении к серверу -для проверки его работоспособности (1.9.7). -По умолчанию совпадает с портом -<link doc="ngx_http_upstream_module.xml" id="server">сервера</link>. -</tag-desc> - -<tag-name id="health_check_grpc"> -<literal>type</literal>=<literal>grpc</literal> -[<literal>grpc_service</literal>=<value>имя</value>] -[<literal>grpc_status</literal>=<value>код</value>] -</tag-name> -<tag-desc> -активирует периодические -<link url="https://github.com/grpc/grpc/blob/master/doc/health-checking.md#grpc-health-checking-protocol">проверки -работоспособности</link> gRPC-сервера -или службы gRPC, указанной при помощи необязательного -параметра <literal>grpc_service</literal> (1.19.5). -Если сервер не поддерживает протокол проверки работоспособности gRPC, -то можно использовать необязательный параметр <literal>grpc_status</literal> -для указания -<link url="https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc">статуса</link> -(например -статус “<literal>12</literal>” / “<literal>UNIMPLEMENTED</literal>”) -при получении которого сервер признаётся работоспособным: -<example> -health_check mandatory type=grpc grpc_status=12; -</example> -Параметр <literal>type</literal>=<literal>grpc</literal> -должен быть указан после остальных параметров директивы, -<literal>grpc_service</literal> и <literal>grpc_status</literal> -должны быть указаны после <literal>type</literal>=<literal>grpc</literal>. -Параметр несовместим с параметрами -<link id="health_check_uri"><literal>uri</literal></link> и -<link id="health_check_match"><literal>match</literal></link>. -</tag-desc> - -<tag-name id="health_check_keepalive_time"> -<literal>keepalive_time</literal>=<value>время</value> -</tag-name> -<tag-desc> -включает <link doc="ngx_http_upstream_module.xml" id="keepalive">keepalive</link> -соединения в проверках работоспособности и задаёт время, в течение которого -могут обрабатываться запросы в рамках keepalive соединения (1.21.7). -По умолчанию keepalive соединения выключены. -</tag-desc> - -</list> -</para> - -</directive> - - -<directive name="match"> -<syntax block="yes"><value>имя</value></syntax> -<default/> -<context>http</context> - -<para> -Задаёт именованный набор тестов для анализа ответов -на запросы проверки работоспособности. -</para> - -<para> -В ответе могут быть протестированы следующие объекты: -<list type="tag"> - -<tag-name><literal>status 200;</literal></tag-name> -<tag-desc>код ответа равен 200</tag-desc> - -<tag-name><literal>status ! 500;</literal></tag-name> -<tag-desc>код ответа не равен 500</tag-desc> - -<tag-name><literal>status 200 204;</literal></tag-name> -<tag-desc>код ответа равен 200 или 204</tag-desc> - -<tag-name><literal>status ! 301 302;</literal></tag-name> -<tag-desc>код ответа не равен ни 301, ни 302</tag-desc> - -<tag-name><literal>status 200-399;</literal></tag-name> -<tag-desc>код ответа находится в диапазоне от 200 до 399</tag-desc> - -<tag-name><literal>status ! 400-599;</literal></tag-name> -<tag-desc>код ответа находится вне диапазона от 400 до 599</tag-desc> - -<tag-name><literal>status 301-303 307;</literal></tag-name> -<tag-desc>код ответа равен 301, 302, 303 или 307</tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>header Content-Type = text/html;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Content-Type</header> -со значением <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Content-Type != text/html;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Content-Type</header> -со значением, отличным от <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Connection ~ close;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Connection</header> -со значением, совпадающим с регулярным выражением <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Connection !~ close;</literal></tag-name> -<tag-desc> -заголовок содержит <header>Connection</header> -со значением, не совпадающим с регулярным выражением <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Host;</literal></tag-name> -<tag-desc>заголовок содержит <header>Host</header></tag-desc> - -<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name> -<tag-desc>заголовок не содержит <header>X-Accel-Redirect</header></tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -тело ответа совпадает с регулярным выражением -“<literal>Welcome to nginx!</literal>” -</tag-desc> - -<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -тело ответа не совпадает с регулярным выражением -“<literal>Welcome to nginx!</literal>” -</tag-desc> - -</list> - -<list type="tag"> - -<tag-name id="match_require"><literal>require</literal> - <value>$переменная</value> - <literal>...;</literal></tag-name> -<tag-desc> -все указанные переменные непустые и не равны “0” (1.15.9). -</tag-desc> - -</list> -</para> - -<para> -Если задано несколько тестов, -то ответ должен удовлетворять всем тестам. -<note> -Проверяются только первые 256 Кбайт тела ответа. -</note> -</para> - -<para> -Примеры: -<example> -# код ответа 200, тип содержимого "text/html" -# и тело ответа содержит "Welcome to nginx!" -match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; -} -</example> - -<example> -# код ответа не равен 301, 302, 303 и 307 и заголовок не содержит "Refresh:" -match not_redirect { - status ! 301-303 307; - header ! Refresh; -} -</example> - -<example> -# код ответа успешный и сервер не в сервисном режиме -match server_ok { - status 200-399; - body !~ "maintenance mode"; -} -</example> - -<example> -# код ответа равен 200 или 204 -map $upstream_status $good_status { - 200 1; - 204 1; -} - -match server_ok { - require $good_status; -} -</example> - -</para> - -</directive> - -</section> - -</module>
--- 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="88"> + rev="89"> <section id="summary"> @@ -50,37 +50,6 @@ server { </example> </para> -<para> -Динамически настраиваемая группа -с периодическими -<link doc="ngx_http_upstream_hc_module.xml">проверками работоспособности</link> -доступна как часть -<commercial_version>коммерческой подписки</commercial_version>: -<example> -resolver 10.0.0.1; - -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; - - server backend1.example.com weight=5; - server backend2.example.com:8080 fail_timeout=5s slow_start=30s; - server 192.0.2.1 max_fails=3; - server backend3.example.com resolve; - server backend4.example.com service=http resolve; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://<emphasis>dynamic</emphasis>; - health_check; - } -} -</example> -</para> - </section> @@ -172,11 +141,6 @@ 5 запросов на <literal>backend1.example.com</literal> суммарное число активных и неактивных соединений с проксируемым сервером может превышать значение <literal>max_conns</literal>. </note> -<note> -Начиная с версии 1.5.9 и до версии 1.11.5 -этот параметр был доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> </tag-desc> <tag-name id="max_fails"> @@ -242,118 +206,9 @@ 5 запросов на <literal>backend1.example.com</literal> </para> <para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -<list type="tag"> - -<tag-name id="resolve"> -<literal>resolve</literal> -</tag-name> -<tag-desc> -отслеживает изменения IP-адресов, соответствующих доменному имени сервера, -и автоматически изменяет конфигурацию группы -без необходимости перезапуска nginx (1.5.12). -Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>. -<para> -Для работы этого параметра -директива <literal>resolver</literal> -должна быть задана в блоке -<link doc="ngx_http_core_module.xml" id="resolver">http</link> -или в соответствующем блоке <link id="resolver">upstream</link>. -</para> -</tag-desc> - -<tag-name id="route"> -<literal>route</literal>=<value>строка</value> -</tag-name> -<tag-desc> -задаёт имя маршрута к серверу. -</tag-desc> - -<tag-name id="service"> -<literal>service</literal>=<value>имя</value> -</tag-name> -<tag-desc> -включает преобразование -<link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>-записей -DNS и задаёт <value>имя</value> сервиса (1.9.13). -Для работы параметра необходимо указать -параметр <link id="resolve"/> для сервера -и не указывать порт сервера. -<para> -Если имя сервиса не содержит точку (“<literal>.</literal>”), то -имя составляется в соответствии с -<link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link> -и в префикс службы добавляется протокол TCP. -Например, для получения -SRV-записи <literal>_http._tcp.backend.example.com</literal> -необходимо указать директиву: -<example> -server backend.example.com service=http resolve; -</example> -Если имя сервиса содержит одну и более точек, то имя составляется -при помощи соединения префикса службы и имени сервера. -Например, для получения SRV-записей -<literal>_http._tcp.backend.example.com</literal> -и <literal>server1.backend.example.com</literal> -необходимо указать директивы: -<example> -server backend.example.com service=_http._tcp resolve; -server example.com service=server1.backend resolve; -</example> -</para> - -<para> -SRV-записи с наивысшим приоритетом -(записи с одинаковым наименьшим значением приоритета) -преобразуются в основные серверы, -остальные SRV-записи преобразуются в запасные серверы. -Если в конфигурации сервера указан параметр <link id="backup"/>, -высокоприоритетные SRV-записи преобразуются в запасные серверы, -остальные SRV-записи игнорируются. -</para> -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт <value>время</value>, в течение которого вес сервера -восстановится от нуля до своего номинального значения в ситуации, когда -неработоспособный (unhealthy) сервер вновь становится работоспособным -(<link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>) -или когда сервер становится доступным по прошествии времени, -в течение которого он считался <link id="fail_timeout">недоступным</link>. -Значение по умолчанию равно нулю и означает, что медленный старт выключен. <note> -Параметр нельзя использовать совместно с -методами балансировки нагрузки -<link id="hash"/>, <link id="ip_hash"/> и <link id="random"/>. -</note> -</tag-desc> - -<tag-name id="drain"> -<literal>drain</literal> -</tag-name> -<tag-desc> -переводит сервер в режим “draining” (1.13.6). -В этом режиме на сервер будут проксироваться только -<link id="sticky">привязанные</link> к нему запросы. -<note> -До версии 1.13.6 -параметр мог быть изменён только при помощи -модуля <link doc="ngx_http_api_module.xml">API</link>. -</note> -</tag-desc> - -</list> -</para> - -<para> -<note> -Если в группе только один сервер, параметры <literal>max_fails</literal>, -<literal>fail_timeout</literal> и <literal>slow_start</literal> +Если в группе только один сервер, +параметры <literal>max_fails</literal> и <literal>fail_timeout</literal> игнорируются и такой сервер никогда не будет считаться недоступным. </note> </para> @@ -375,70 +230,6 @@ SRV-записи с наивысшим приоритетом В этом случае достаточно указать <value>размер</value> только один раз. </para> -<para> -Дополнительно, как часть -<commercial_version>коммерческой подписки</commercial_version>, -в таких группах для изменения состава группы -или настроек отдельных серверов -нет необходимости перезапускать nginx. -Конфигурация доступна через -модуль <link doc="ngx_http_api_module.xml">API</link> (1.13.3). -<note> -До версии 1.13.3 -конфигурация была доступна только через специальный location, -в котором указана директива -<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. -</note> -</para> - -</directive> - - -<directive name="state"> -<syntax><value>файл</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.9.7</appeared-in> - -<para> -Задаёт <value>файл</value>, в котором хранится состояние -динамически настраиваемой группы. -</para> - -<para> -Примеры: -<example> -state /var/lib/nginx/state/servers.conf; # путь для Linux -state /var/db/nginx/state/servers.conf; # путь для FreeBSD -</example> -</para> - -<para> -В данный момент состояние ограничено списком серверов с их параметрами. -Файл читается при парсинге конфигурации и обновляется каждый раз при -<link doc="ngx_http_api_module.xml" id="http_upstreams_http_upstream_name_servers_">изменении</link> -конфигурации группы. -Изменение содержимого файла напрямую не рекомендуется. -Директиву нельзя использовать -совместно с директивой <link id="server"/>. -</para> - -<para> -<note> -Изменения, совершённые в момент -<link doc="../control.xml" id="reconfiguration">перезагрузки конфигурации</link> -или <link doc="../control.xml" id="upgrade">обновления бинарного файла</link>, -могут быть потеряны. -</note> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - </directive> @@ -704,69 +495,6 @@ server { </directive> -<directive name="ntlm"> -<syntax/> -<default/> -<context>upstream</context> -<appeared-in>1.9.2</appeared-in> - -<para> -Позволяет проксировать запросы с -<link url="https://en.wikipedia.org/wiki/Integrated_Windows_Authentication">проверкой -подлинности NTLM</link>. -Соединение с сервером группы привязывается к клиентскому соединению -как только клиент отправляет запрос, в заголовке которого есть поле -<header>Authorization</header> со значением, -начинающимся с “<literal>Negotiate</literal>” или “<literal>NTLM</literal>”. -Последующие запросы клиента будут проксироваться через это же соединение -с сервером группы, -сохраняя контекст аутентификации. -</para> - -<para> -Для работы проверки подлинности NTLM -необходимо разрешить постоянные соединения с серверами группы. -Директиву <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/> -следует установить в “<literal>1.1</literal>”, -а поле заголовка <header>Connection</header> — очистить: -<example> -upstream http_backend { - server 127.0.0.1:8080; - - ntlm; -} - -server { - ... - - location /http/ { - proxy_pass http://http_backend; - proxy_http_version 1.1; - proxy_set_header Connection ""; - ... - } -} -</example> -</para> - -<para> -<note> -При использовании методов балансировки нагрузки, отличных -от стандартного round-robin, следует активировать их до -директивы <literal>ntlm</literal>. -</note> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="least_conn"> <syntax/> <default/> @@ -785,86 +513,6 @@ server { </directive> -<directive name="least_time"> -<syntax> - <literal>header</literal> | - <literal>last_byte</literal> - [<literal>inflight</literal>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.7.10</appeared-in> - -<para> -Задаёт для группы метод балансировки нагрузки, при котором запрос -передаётся серверу с наименьшими средним временем ответа и -числом активных соединений с учётом весов серверов. -Если подходит сразу несколько серверов, то они выбираются циклически -(в режиме round-robin) с учётом их весов. -</para> - -<para> -Если указан параметр <literal>header</literal>, -то учитывается время получения -<link id="var_upstream_header_time">заголовка ответа</link>. -Если указан параметр <literal>last_byte</literal>, то учитывается -время получения <link id="var_upstream_response_time">всего ответа</link>. -Если указан параметр <literal>inflight</literal> (1.11.6), -то также учитываются незавершённые запросы. -<note> -До версии 1.11.6 незавершённые запросы учитывались по умолчанию. -</note> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="queue"> -<syntax> -<value>число</value> -[<literal>timeout</literal>=<value>время</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.12</appeared-in> - -<para> -Если при обработке запроса невозможно сразу выбрать сервер группы, то -запрос будет помещён в очередь. -Директива задаёт максимальное <value>число</value> запросов, -которые могут одновременно находиться в очереди. -Если очередь переполнена -или за время, задаваемое параметром <literal>timeout</literal>, -так и не удастся выбрать сервер для передачи ему запроса, -клиенту будет возвращена ошибка -<http-status code="502" text="Bad Gateway"/>. -</para> - -<para> -По умолчанию параметр <literal>timeout</literal> равен 60 секундам. -</para> - -<para> -<note> -При использовании методов балансировки нагрузки, отличных -от стандартного round-robin, следует активировать их до -директивы <literal>queue</literal>. -</note> - -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="random"> <syntax>[<literal>two</literal> [<value>метод</value>]]</syntax> <default/> @@ -888,380 +536,6 @@ server { с наименьшим количеством активных соединений. </para> -<para id="random_least_time"> -Если указан метод <literal>least_time</literal>, то запрос передаётся серверу -с наименьшими средним временем ответа и числом активных соединений. -Если указан <literal>least_time=header</literal>, то учитывается -время получения <link id="var_upstream_header_time">заголовка ответа</link>. -Если указан <literal>least_time=last_byte</literal>, то учитывается -время получения <link id="var_upstream_response_time">всего ответа</link>. -<note> -Метод <literal>least_time</literal> доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="resolver"> -<syntax> - <value>адрес</value> ... - [<literal>valid</literal>=<value>время</value>] - [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<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-адреса -при преобразовании имён в адреса. -Если поиск IPv4- или IPv6-адресов нежелателен, -можно указать параметр <literal>ipv4=off</literal> (1.23.1) или -<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> - [<literal>expires=</literal><value>время</value>] - [<literal>domain=</literal><value>домен</value>] - [<literal>httponly</literal>] - [<literal>samesite=</literal><literal>strict</literal>|<literal>lax</literal>|<literal>none</literal>|<value>$переменная</value>] - [<literal>secure</literal>] - [<literal>path=</literal><value>путь</value>]</syntax> -<syntax> - <literal>route</literal> <value>$переменная</value> ...</syntax> -<syntax> - <literal>learn</literal> - <literal>create=</literal><value>$переменная</value> - <literal>lookup=</literal><value>$переменная</value> - <literal>zone=</literal><value>имя</value>:<value>размер</value> - [<literal>timeout=</literal><value>время</value>] - [<literal>header</literal>] - [<literal>sync</literal>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Включает режим привязки сеансов, в котором запросы клиента -будут передаваться на один и тот же сервер группы. -Доступны три метода: -<list type="tag"> -<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name> -<tag-desc> - -<para> -При использовании метода <literal>cookie</literal> информация о -назначенном сервере передаётся в HTTP-куке: -<example> -upstream backend { - server backend1.example.com; - server backend2.example.com; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -</para> - -<para> -Запрос от клиента, ещё не привязанного к определённому серверу, -передаётся на сервер, выбранный согласно настроенному методу балансировки. -Дальнейшие запросы от этого клиента передаются на тот же сервер. -Если назначенный сервер не может обработать запрос, выбирается новый -сервер как если бы клиент не имел привязки к серверу. - -<note> -Так как любой метод балансировки пытается равномерно распределить нагрузку, -учитывая уже привязанные запросы, -сервер с наибольшим количеством привязанных запросов -имеет меньшую вероятность получить новые, не привязанные запросы. -</note> -</para> - -<para> -Первый параметр задаёт имя куки, которую необходимо установить или проверить. -Значением куки является MD5-хэш IP-адреса и порта -(или пути UNIX-сокета) в шестнадцатеричном виде. -Однако если указан параметр “<literal>route</literal>” -директивы <link id="server"/>, то значением куки будет -значение параметра “<literal>route</literal>”: -<example> -upstream backend { - server backend1.example.com route=<emphasis>a</emphasis>; - server backend2.example.com route=<emphasis>b</emphasis>; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -В этом случае значение куки “<literal>srv_id</literal>” будет -или <value>a</value>, или <value>b</value>. -</para> - -<para> -Дополнительные параметры могут быть следующими: -<list type="tag"> - -<tag-name><literal>expires=</literal><value>время</value></tag-name> -<tag-desc> -Задаёт <value>время</value>, в течение которого браузеру необходимо хранить куку. -Специальное значение <literal>max</literal> устанавливает срок хранения куки до -31 декабря 2037 года 23:55:55 GMT. -Если параметр не указан, то время действия куки ограничивается сессией браузера. -</tag-desc> - -<tag-name><literal>domain=</literal><value>домен</value></tag-name> -<tag-desc> -Задаёт <value>домен</value>, для которого устанавливается кука. -В значении параметра можно использовать переменные (1.11.5). -</tag-desc> - -<tag-name><literal>httponly</literal></tag-name> -<tag-desc> -Добавляет атрибут <literal>HttpOnly</literal> к куке (1.7.11). -</tag-desc> - -<tag-name id="sticky_samesite"><literal>samesite=</literal><literal>strict</literal> | -<literal>lax</literal> | <literal>none</literal> | <literal>$переменная</literal></tag-name> -<tag-desc> -Добавляет атрибут <literal>SameSite</literal> (1.19.4) к куке -с одним из следующих значений: -<literal>Strict</literal>, -<literal>Lax</literal>, -<literal>None</literal> или -при помощи переменных (1.23.3). -В последнем случае если переменная имеет пустое значение, -то атрибут <literal>SameSite</literal> не будет добавлен к куке, -если значение переменной равно -<literal>Strict</literal>, -<literal>Lax</literal> или -<literal>None</literal>, -то атрибуту будет назначено соответствующее значение, -иначе атрибуту будет назначено значение <literal>Strict</literal>. -</tag-desc> - -<tag-name><literal>secure</literal></tag-name> -<tag-desc> -Добавляет атрибут <literal>Secure</literal> к куке (1.7.11). -</tag-desc> - -<tag-name><literal>path=</literal><value>путь</value></tag-name> -<tag-desc> -Задаёт <value>путь</value>, для которого устанавливается кука. -</tag-desc> - -</list> -Если пропущен тот или иной параметр, то соответствующего поля в куке не будет. -</para> -</tag-desc> - -<tag-name id="sticky_route"><literal>route</literal></tag-name> -<tag-desc> - -<para> -При использовании метода <literal>route</literal> проксируемый сервер назначает -клиенту маршрут по получении первого запроса. -Все последующие запросы от этого клиента будут содержать информацию о -маршруте в куке или URI. -Эта информация сравнивается с параметром “<literal>route</literal>” директивы -<link id="server"/> для идентификации сервера, на который -следует проксировать запрос. -Если параметр “<literal>route</literal>” не задан, то именем маршрута -будет являться MD5-хэш IP-адреса и порта -(или пути UNIX-сокета) в шестнадцатеричном виде. -Если назначенный сервер не может обработать запрос, выбирается новый сервер -согласно настроенному методу балансировки как если бы в запросе не было -информации о маршруте. -</para> - -<para> -Параметры метода <literal>route</literal> задают переменные, которые -могут содержать информацию о маршруте. -Первая непустая переменная используется для поиска соответствующего сервера. -</para> - -<para> -Пример: -<example> -map $cookie_jsessionid $route_cookie { - ~.+\.(?P<route>\w+)$ $route; -} - -map $request_uri $route_uri { - ~jsessionid=.+\.(?P<route>\w+)$ $route; -} - -upstream backend { - server backend1.example.com route=a; - server backend2.example.com route=b; - - sticky route $route_cookie $route_uri; -} -</example> -В этом примере маршрут берётся из куки “<literal>JSESSIONID</literal>”, -если она присутствует в запросе. -В противном случае используется маршрут из URI. -</para> - -</tag-desc> - -<tag-name id="sticky_learn"><literal>learn</literal></tag-name> -<tag-desc> -<para> -При использовании метода <literal>learn</literal> (1.7.1) nginx -анализирует ответы от вышестоящего сервера и запоминает -начатые им сессии, которые обычно передаются в HTTP-куке. -<example> -upstream backend { - server backend1.example.com:8080; - server backend2.example.com:8081; - - sticky learn - create=$upstream_cookie_examplecookie - lookup=$cookie_examplecookie - zone=client_sessions:1m; -} -</example> - -В примере выше сервер группы создаёт сессию путём установки -куки “<literal>EXAMPLECOOKIE</literal>” в своём ответе. -Последующие запросы с этой кукой будут передаваться на этот же сервер. -Если сервер не может обработать запрос, выбирается новый -сервер как если бы клиент не имел привязки к серверу. -</para> - -<para> -Параметры <literal>create</literal> и <literal>lookup</literal> -задают переменные, в которых соответственно указывается способ -создания новых и поиска существующих сессий. -Оба параметра могут быть указаны больше одного раза -(в этом случае используется первая непустая переменная). -</para> - -<para> -Сессии хранятся в зоне разделяемой памяти, <value>имя</value> и -<value>размер</value> которой задаются параметром <literal>zone</literal>. -Зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч сессий -на 64-битной платформе. -Сессии, к которым не было обращений в течение времени, заданного параметром -<literal>timeout</literal>, удаляются из зоны. -По умолчанию <literal>timeout</literal> равен 10 минутам. -</para> - -<para id="sticky_learn_header"> -Параметр <literal>header</literal> (1.13.1) позволяет создавать сессию -сразу после получения заголовков ответа от сервера группы. -</para> - -<para id="sticky_learn_sync"> -Параметр <literal>sync</literal> (1.13.8) разрешает -<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">синхронизацию</link> -данной зоны разделяемой памяти. -</para> - -</tag-desc> -</list> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky_cookie_insert"> -<syntax><value>имя</value> -[<literal>expires=</literal><value>время</value>] -[<literal>domain=</literal><value>домен</value>] -[<literal>path=</literal><value>путь</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -Эта директива устарела начиная с версии 1.5.7. -Вместо неё следует использовать аналогичную директиву -<link id="sticky"/> с изменённым синтаксисом: -<note> -<literal>sticky cookie</literal> <value>имя</value> -[<literal>expires=</literal><value>время</value>] -[<literal>domain=</literal><value>домен</value>] -[<literal>path=</literal><value>путь</value>]; -</note> -</para> - </directive> </section> @@ -1360,25 +634,6 @@ upstream backend { последнего сервера. </tag-desc> -<tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name> -<tag-desc> -хранит имя последнего выбранного сервера группы (1.25.3); -позволяет передать его -<link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">через SNI</link>: -<example> -proxy_ssl_server_name on; -proxy_ssl_name $upstream_last_server_name; -</example> - -<para> -<note> -Эта переменная доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</tag-desc> - <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> <tag-desc> хранит время, проведённое запросом в <link id="queue">очереди</link>
--- a/xml/ru/docs/http/ngx_http_uwsgi_module.xml +++ b/xml/ru/docs/http/ngx_http_uwsgi_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_uwsgi_module" link="/ru/docs/http/ngx_http_uwsgi_module.html" lang="ru" - rev="50"> + rev="51"> <section id="summary"> @@ -383,11 +383,7 @@ range-запрос будет передан на uwsgi-сервер [<literal>manager_threshold</literal>=<value>время</value>] [<literal>loader_files</literal>=<value>число</value>] [<literal>loader_sleep</literal>=<value>время</value>] - [<literal>loader_threshold</literal>=<value>время</value>] - [<literal>purger</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>purger_files</literal>=<value>число</value>] - [<literal>purger_sleep</literal>=<value>время</value>] - [<literal>purger_threshold</literal>=<value>время</value>]</syntax> + [<literal>loader_threshold</literal>=<value>время</value>]</syntax> <default/> <context>http</context> @@ -432,16 +428,6 @@ uwsgi_cache_path /data/nginx/cache level разделяемой памяти, <value>имя</value> и <value>размер</value> которой задаются параметром <literal>keys_zone</literal>. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. -<note> -Как часть -<commercial_version>коммерческой подписки</commercial_version> -в зоне разделяемой памяти также хранится расширенная -<link doc="ngx_http_api_module.xml" id="http_caches_">информация</link> о кэше, -поэтому для хранения аналогичного количества ключей необходимо указывать -больший размер зоны. -Например -зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч ключей. -</note> </para> <para> @@ -484,56 +470,6 @@ uwsgi_cache_path /data/nginx/cache level </para> <para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -</para> - -<para> -<list type="tag"> - -<tag-name id="purger"> -<literal>purger</literal>=<literal>on</literal>|<literal>off</literal> -</tag-name> -<tag-desc> -Указывает, будут ли записи в кэше, соответствующие -<link id="uwsgi_cache_purge">маске</link>, -удалены с диска при помощи процесса “cache purger” (1.7.12). -Установка параметра в значение <literal>on</literal> -(по умолчанию <literal>off</literal>) -активирует процесс “cache purger”, который -проходит по всем записям в кэше -и удаляет записи, соответствующие этой маске. -</tag-desc> - -<tag-name id="purger_files"> -<literal>purger_files</literal>=<value>число</value> -</tag-name> -<tag-desc> -Задаёт число элементов, которые будут сканироваться за одну итерацию (1.7.12). -По умолчанию <literal>purger_files</literal> равен 10. -</tag-desc> - -<tag-name id="purger_threshold"> -<literal>purger_threshold</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт продолжительность одной итерации (1.7.12). -По умолчанию <literal>purger_threshold</literal> равен 50 миллисекундам. -</tag-desc> - -<tag-name id="purger_sleep"> -<literal>purger_sleep</literal>=<value>время</value> -</tag-name> -<tag-desc> -Задаёт паузу между итерациями (1.7.12). -По умолчанию <literal>purger_sleep</literal> равен 50 миллисекундам. -</tag-desc> - -</list> -</para> - -<para> <note> В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён. При обновлении на более новую версию nginx @@ -544,64 +480,6 @@ uwsgi_cache_path /data/nginx/cache level </directive> -<directive name="uwsgi_cache_purge"> -<syntax>строка ...</syntax> -<default/> -<context>http</context> -<context>server</context> -<context>location</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Задаёт условия, при которых запрос будет считаться запросом -на очистку кэша. -Если значение хотя бы одного из строковых параметров непустое и не равно “0”, -то запись в кэше с соответствующим -<link id="uwsgi_cache_key">ключом кэширования</link> удаляется. -В результате успешной операции возвращается ответ с кодом -<http-status code="204" text="No Content"/>. -</para> - -<para> -Если <link id="uwsgi_cache_key">ключ кэширования</link> -запроса на очистку заканчивается -звёздочкой (“<literal>*</literal>”), то все записи в кэше, соответствующие -этой маске, будут удалены из кэша. -Тем не менее, эти записи будут оставаться на диске или до момента удаления -из-за <link id="uwsgi_cache_path">отсутствия обращения к данным</link>, -или до обработки их процессом “<link id="purger">cache purger</link>” (1.7.12), -или до попытки клиента получить к ним доступ. -</para> - -<para> -Пример конфигурации: -<example> -uwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; - -map $request_method $purge_method { - PURGE 1; - default 0; -} - -server { - ... - location / { - uwsgi_pass http://backend; - uwsgi_cache cache_zone; - uwsgi_cache_key $uri; - uwsgi_cache_purge $purge_method; - } -} -</example> -<note> -Функциональность доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="uwsgi_cache_revalidate"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
--- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="49" + rev="50" toc="no"> @@ -224,21 +224,11 @@ ngx_http_addition_module</link> </listitem> <listitem> -<link doc="http/ngx_http_api_module.xml"> -ngx_http_api_module</link> [en] -</listitem> - -<listitem> <link doc="http/ngx_http_auth_basic_module.xml"> ngx_http_auth_basic_module</link> </listitem> <listitem> -<link doc="http/ngx_http_auth_jwt_module.xml"> -ngx_http_auth_jwt_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_auth_request_module.xml"> ngx_http_auth_request_module</link> </listitem> @@ -269,11 +259,6 @@ ngx_http_empty_gif_module</link> </listitem> <listitem> -<link doc="http/ngx_http_f4f_module.xml"> -ngx_http_f4f_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_fastcgi_module.xml"> ngx_http_fastcgi_module</link> </listitem> @@ -319,11 +304,6 @@ ngx_http_headers_module</link> </listitem> <listitem> -<link doc="http/ngx_http_hls_module.xml"> -ngx_http_hls_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_image_filter_module.xml"> ngx_http_image_filter_module</link> </listitem> @@ -334,21 +314,11 @@ ngx_http_index_module</link> </listitem> <listitem> -<link doc="http/ngx_http_internal_redirect_module.xml"> -ngx_http_internal_redirect_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_js_module.xml"> ngx_http_js_module</link> </listitem> <listitem> -<link doc="http/ngx_http_keyval_module.xml"> -ngx_http_keyval_module</link> [en] -</listitem> - -<listitem> <link doc="http/ngx_http_limit_conn_module.xml"> ngx_http_limit_conn_module</link> </listitem> @@ -394,11 +364,6 @@ ngx_http_proxy_module</link> </listitem> <listitem> -<link doc="http/ngx_http_proxy_protocol_vendor_module.xml"> -ngx_http_proxy_protocol_vendor_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_random_index_module.xml"> ngx_http_random_index_module</link> </listitem> @@ -429,11 +394,6 @@ ngx_http_secure_link_module</link> </listitem> <listitem> -<link doc="http/ngx_http_session_log_module.xml"> -ngx_http_session_log_module</link> [en] -</listitem> - -<listitem> <link doc="http/ngx_http_slice_module.xml"> ngx_http_slice_module</link> </listitem> @@ -454,11 +414,6 @@ ngx_http_ssl_module</link> </listitem> <listitem> -<link doc="http/ngx_http_status_module.xml"> -ngx_http_status_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_stub_status_module.xml"> ngx_http_stub_status_module</link> </listitem> @@ -474,16 +429,6 @@ ngx_http_upstream_module</link> </listitem> <listitem> -<link doc="http/ngx_http_upstream_conf_module.xml"> -ngx_http_upstream_conf_module</link> -</listitem> - -<listitem> -<link doc="http/ngx_http_upstream_hc_module.xml"> -ngx_http_upstream_hc_module</link> -</listitem> - -<listitem> <link doc="http/ngx_http_userid_module.xml"> ngx_http_userid_module</link> </listitem> @@ -587,11 +532,6 @@ ngx_stream_js_module</link> </listitem> <listitem> -<link doc="stream/ngx_stream_keyval_module.xml"> -ngx_stream_keyval_module</link> [en] -</listitem> - -<listitem> <link doc="stream/ngx_stream_limit_conn_module.xml"> ngx_stream_limit_conn_module</link> </listitem> @@ -607,26 +547,11 @@ ngx_stream_map_module</link> </listitem> <listitem> -<link doc="stream/ngx_stream_mqtt_preread_module.xml"> -ngx_stream_mqtt_preread_module</link> -</listitem> - -<listitem> -<link doc="stream/ngx_stream_mqtt_filter_module.xml"> -ngx_stream_mqtt_filter_module</link> -</listitem> - -<listitem> <link doc="stream/ngx_stream_proxy_module.xml"> ngx_stream_proxy_module</link> </listitem> <listitem> -<link doc="stream/ngx_stream_proxy_protocol_vendor_module.xml"> -ngx_stream_proxy_protocol_vendor_module</link> -</listitem> - -<listitem> <link doc="stream/ngx_stream_realip_module.xml"> ngx_stream_realip_module</link> </listitem> @@ -661,16 +586,6 @@ ngx_stream_ssl_preread_module</link> ngx_stream_upstream_module</link> </listitem> -<listitem> -<link doc="stream/ngx_stream_upstream_hc_module.xml"> -ngx_stream_upstream_hc_module</link> -</listitem> - -<listitem> -<link doc="stream/ngx_stream_zone_sync_module.xml"> -ngx_stream_zone_sync_module</link> [en] -</listitem> - </list> </para> @@ -682,16 +597,6 @@ ngx_stream_zone_sync_module</link> [en] ngx_google_perftools_module</link> </listitem> -<listitem> -<link doc="ngx_mgmt_module.xml"> -ngx_mgmt_module</link> [en] -</listitem> - -<listitem> -<link doc="ngx_otel_module.xml"> -ngx_otel_module [en]</link> -</listitem> - </list> </para>
--- a/xml/ru/docs/mail/ngx_mail_core_module.xml +++ b/xml/ru/docs/mail/ngx_mail_core_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_mail_core_module" link="/ru/docs/mail/ngx_mail_core_module.html" lang="ru" - rev="21"> + rev="22"> <section id="summary"> @@ -317,8 +317,7 @@ FreeBSD 9.0-STABLE) <value>адрес</value> ... [<literal>valid</literal>=<value>time</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>зона</value>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <syntax><literal>off</literal></syntax> <default>off</default> <context>mail</context> @@ -375,16 +374,6 @@ resolver 127.0.0.1 [::1]:5353 valid=30s; </note> </para> -<para id="resolver_status_zone"> -Необязательный параметр <literal>status_zone</literal> (1.17.1) -включает -<link doc="../http/ngx_http_api_module.xml" id="resolvers_">сбор информации</link> -о запросах и ответах сервера DNS -в указанной <value>зоне</value>. -Параметр доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</para> - <para id="resolver_off"> Специальное значение <literal>off</literal> запрещает использование DNS. </para>
--- a/xml/ru/docs/njs/examples.xml +++ b/xml/ru/docs/njs/examples.xml @@ -9,7 +9,7 @@ <article name="Примеры использования" link="/ru/docs/njs/examples.html" lang="ru" - rev="21"> + rev="22"> <section id="summary"> @@ -197,72 +197,6 @@ export default {jwt_payload_sub}; <section id="http_proxying" name="HTTP-проксирование"> -<section id="subrequest" name="Доступ к API из подзапроса"> - -<para> -<path>nginx.conf</path>: -<example> -js_import http.js; - -keyval_zone zone=foo:10m; -#... - -location /keyval { - js_content http.set_keyval; -} - -location /version { - js_content http.version; -} - -location /api { - api write=on; -} -</example> -</para> - -<para> -<path>http.js</path>: -<example> -async function set_keyval(r) { - let res = await r.subrequest('/api/7/http/keyvals/foo', - { method: 'POST', - body: JSON.stringify({ foo: 789, bar: "ss dd 00" })}); - - if (res.status >= 300) { - r.return(res.status, res.responseBody); - return; - } - - r.return(200); -} - -async function version(r) { - let res = await r.subrequest('/api/7/nginx', { method: 'GET' }); - - if (res.status != 200) { - r.return(res.status); - return; - } - - var json = JSON.parse(res.responseBody); - r.return(200, json.version); -} - -export default {set_keyval, version}; -</example> -<note> -Директивы <link doc="../http/ngx_http_keyval_module.xml" id="keyval"/>, -<link doc="../http/ngx_http_keyval_module.xml" id="keyval_zone"/> -и <link doc="../http/ngx_http_api_module.xml" id="api"/> -доступны как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - <section id="fast_response" name="Возвращение самого быстрого ответа от прокси"> <para> @@ -392,56 +326,6 @@ export default {redirect}; </section> - -<section id="requests" name="Запись в лог количества запросов от клиента"> - -<para> -<path>nginx.conf</path>: -<example> -js_import http.js; - -js_set $num_requests http.num_requests; - -keyval_zone zone=foo:10m; - -keyval $remote_addr $foo zone=foo; - -log_format bar '$remote_addr [$time_local] $num_requests'; -access_log logs/access.log bar; - -server { - listen 8000; - - location / { - root html; - } -} -</example> -</para> - -<para> -<path>http.js</path>: -<example> -function num_requests(r) -{ - var n = r.variables.foo; - n = n ? Number(n) + 1 : 1; - r.variables.foo = n; - return n; -} - -export default {num_requests}; -</example> -<note> -Директивы <link doc="../http/ngx_http_keyval_module.xml" id="keyval"/> и -<link doc="../http/ngx_http_keyval_module.xml" id="keyval_zone"/> -доступны как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - </section> </article>
--- a/xml/ru/docs/stream/ngx_stream_core_module.xml +++ b/xml/ru/docs/stream/ngx_stream_core_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_stream_core_module" link="/ru/docs/stream/ngx_stream_core_module.html" lang="ru" - rev="37"> + rev="38"> <section id="summary"> @@ -347,8 +347,7 @@ FreeBSD 9.0-STABLE) <value>адрес</value> ... [<literal>valid</literal>=<value>время</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>зона</value>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <default/> <context>stream</context> <context>server</context> @@ -387,23 +386,6 @@ resolver 127.0.0.1 [::1]:5353 valid=30s; </note> </para> -<para id="resolver_status_zone"> -Необязательный параметр <literal>status_zone</literal> (1.17.1) -включает -<link doc="../http/ngx_http_api_module.xml" id="resolvers_">сбор информации</link> -о запросах и ответах сервера DNS -в указанной <value>зоне</value>. -Параметр доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</para> - -<para> -<note> -До версии 1.11.3 эта директива была доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - </directive> @@ -419,10 +401,6 @@ resolver 127.0.0.1 [::1]:5353 valid=30s; <example> resolver_timeout 5s; </example> -<note> -До версии 1.11.3 эта директива была доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> </para> </directive>
--- a/xml/ru/docs/stream/ngx_stream_limit_conn_module.xml +++ b/xml/ru/docs/stream/ngx_stream_limit_conn_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_stream_limit_conn_module" link="/ru/docs/stream/ngx_stream_limit_conn_module.html" lang="ru" - rev="7"> + rev="8"> <section id="summary"> @@ -152,19 +152,6 @@ limit_conn_zone $binary_remote_addr zone </directive> -<para> -<note> -Дополнительно, как часть -<commercial_version>коммерческой подписки</commercial_version>, -<link doc="../http/ngx_http_api_module.xml" id="stream_limit_conns_">информацию о состоянии</link> -каждой такой зоны разделяемой памяти можно -<link doc="../http/ngx_http_api_module.xml" id="getStreamLimitConnZone">получить</link> или -<link doc="../http/ngx_http_api_module.xml" id="deleteStreamLimitConnZoneStat">сбросить</link> -при помощи <link doc="../http/ngx_http_api_module.xml">API</link> -начиная с версии 1.17.7. -</note> -</para> - </section>
deleted file mode 100644 --- a/xml/ru/docs/stream/ngx_stream_mqtt_filter_module.xml +++ /dev/null @@ -1,135 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_stream_mqtt_filter_module" - link="/ru/docs/http/ngx_stream_mqtt_filter_module.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_stream_mqtt_filter_module</literal> (1.23.4) обеспечивает -поддержку протокола Message Queuing Telemetry Transport (MQTT) -версий -<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> -и -<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -listen 127.0.0.1:18883; -proxy_pass backend; -proxy_buffer_size 16k; - -mqtt on; -mqtt_set_connect clientid "$client"; -mqtt_set_connect username "$name"; -</example> -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="mqtt"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> - -<para> -Включает протокол MQTT для данного виртуального сервера. -</para> - -</directive> - - -<directive name="mqtt_buffers"> -<syntax><value>число</value> <value>размер</value></syntax> -<default>100 1k</default> -<context>stream</context> -<context>server</context> -<appeared-in>1.25.1</appeared-in> - -<para> -Задаёт <value>число</value> и <value>размер</value> буферов, -необходимых для обработки MQTT-сообщений, -для одного соединения. -</para> - -</directive> - - -<directive name="mqtt_rewrite_buffer_size"> -<syntax><value>размер</value></syntax> -<default>4k|8k</default> -<context>server</context> - -<para> -<note> -Эта директива устарела начиная с версии 1.25.1. -Вместо неё следует использовать директиву -<link id="mqtt_buffers"/>. -</note> -</para> - -<para> -Задаёт <value>размер</value> буфера, -в который будет записываться модифицированное сообщение. -По умолчанию размер одного буфера равен размеру страницы памяти. -В зависимости от платформы это или 4K, или 8K, -однако его можно сделать меньше. -</para> - -</directive> - - -<directive name="mqtt_set_connect"> -<syntax><literal>поле</literal> <value>значение</value></syntax> -<default/> -<context>server</context> - -<para> -Устанавливает <literal>поле</literal> -в заданное <literal>значение</literal> для сообщения CONNECT. -Поддерживаются следующие поля: -<literal>clientid</literal>, -<literal>username</literal> и -<literal>password</literal>. -В качестве значения можно использовать текст, переменные и их комбинации. -</para> - -<para> -На одном уровне может быть указано -несколько директив <literal>mqtt_set_connect</literal>: -<example> -mqtt_set_connect clientid "$client"; -mqtt_set_connect username "$name"; -</example> -</para> - -</directive> - -</section> - -</module>
deleted file mode 100644 --- a/xml/ru/docs/stream/ngx_stream_mqtt_preread_module.xml +++ /dev/null @@ -1,87 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_stream_mqtt_preread_module" - link="/ru/docs/http/ngx_stream_mqtt_preread_module.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_stream_mqtt_preread_module</literal> (1.23.4) позволяет -извлекать информацию из сообщения CONNECT -протокола Message Queuing Telemetry Transport (MQTT) -версий -<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> -и -<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>, -например имя пользователя или ID клиента. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -mqtt_preread on; -return $mqtt_preread_clientid; -</example> -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="mqtt_preread"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> - -<para> -Разрешает извлечение информации из сообщения СONNECT во время фазы -<link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>. -</para> - -</directive> - -</section> - - -<section id="variables" name="Встроенные переменные"> - -<para> -<list type="tag"> - -<tag-name id="var_mqtt_preread_clientid"><var>$mqtt_preread_clientid</var></tag-name> -<tag-desc> -значение <literal>clientid</literal> из СONNECT-сообщения -</tag-desc> - -<tag-name id="var_mqtt_preread_username"><var>$mqtt_preread_username</var></tag-name> -<tag-desc> -значение <literal>username</literal> из СONNECT-сообщения -</tag-desc> - -</list> -</para> - -</section> - -</module>
--- a/xml/ru/docs/stream/ngx_stream_proxy_module.xml +++ b/xml/ru/docs/stream/ngx_stream_proxy_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_stream_proxy_module" link="/ru/docs/stream/ngx_stream_proxy_module.html" lang="ru" - rev="32"> + rev="33"> <section id="summary"> @@ -328,38 +328,6 @@ Cессия завершится после отправки всех принятых датаграмм </directive> -<directive name="proxy_session_drop"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> -<context>stream</context> -<context>server</context> -<appeared-in>1.15.8</appeared-in> - -<para> -Позволяет завершить все сессии к проксируемому серверу, -если он был удалён из группы или помечен как постоянно недоступный. -Это может произойти вследствие повторного -<link doc="ngx_stream_core_module.xml" id="resolver">преобразования имён</link> -в адреса, а также при помощи команды API -<link doc="../http/ngx_http_api_module.xml" id="deleteStreamUpstreamServer"><literal>DELETE</literal></link>. -Сервер может быть помечен как постоянно недоступный в случае неуспешной -<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">проверки работоспособности</link>, -а также при помощи команды API -<link doc="../http/ngx_http_api_module.xml" id="patchStreamUpstreamServer"><literal>PATCH</literal></link>. -Сессия завершается при обработке очередного -события чтения или записи на стороне клиента или проксируемого сервера. -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="proxy_socket_keepalive"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default>
deleted file mode 100644 --- a/xml/ru/docs/stream/ngx_stream_proxy_protocol_vendor_module.xml +++ /dev/null @@ -1,105 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_stream_proxy_protocol_vendor_module" - link="/ru/docs/stream/ngx_stream_proxy_protocol_vendor_module.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_stream_proxy_protocol_vendor_module</literal> (1.23.3) -позволяет получать дополнительную информацию о соединении из -облачных платформ при помощи TLV, полученных из -заголовка -<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">протокола -PROXY</link>. -</para> - -<para> -Поддерживаемые облачные платформы: -<list type="bullet"> - -<listitem> -Amazon Web Services -</listitem> - -<listitem> -Google Cloud Platform -</listitem> - -<listitem> -Microsoft Azure -</listitem> - -</list> -</para> - -<para> -Протокол PROXY должен быть предварительно включён при помощи установки -параметра <literal>proxy_protocol</literal> в директиве -<link doc="ngx_stream_core_module.xml" id="listen"/>. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version> -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -server { - listen 12345 proxy_protocol; - return $proxy_protocol_tlv_gcp_conn_id; -} -</example> -</para> - -</section> - - -<section id="variables" name="Встроенные переменные"> - -<para> -<list type="tag"> - -<tag-name id="var_proxy_protocol_tlv_aws_vpce_id"><var>$proxy_protocol_tlv_aws_vpce_id</var></tag-name> -<tag-desc> -значение TLV, полученное из заголовка протокола PROXY, содержащее -<link url="https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol">ID -конечной точки VPC AWS</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_azure_pel_id"><var>$proxy_protocol_tlv_azure_pel_id</var></tag-name> -<tag-desc> -значение TLV, полученное из заголовка протокола PROXY, содержащее -<link url="https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview#getting-connection-information-using-tcp-proxy-v2">LinkID -частной конечной точки Azure</link> -</tag-desc> - -<tag-name id="var_proxy_protocol_tlv_gcp_conn_id"><var>$proxy_protocol_tlv_gcp_conn_id</var></tag-name> -<tag-desc> -значение TLV, полученное из заголовка протокола PROXY, содержащее -<link url="https://cloud.google.com/vpc/docs/configure-private-service-connect-producer#proxy-protocol">ID соединения -Google Cloud PSC</link> -</tag-desc> - -</list> -</para> - -</section> - -</module>
deleted file mode 100644 --- a/xml/ru/docs/stream/ngx_stream_upstream_hc_module.xml +++ /dev/null @@ -1,332 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> - -<module name="Модуль ngx_stream_upstream_hc_module" - link="/ru/docs/stream/ngx_stream_upstream_hc_module.html" - lang="ru" - rev="6"> - -<section id="summary"> - -<para> -Модуль <literal>ngx_stream_upstream_hc_module</literal> (1.9.0) -позволяет активировать периодические проверки работоспособности серверов в -<link doc="ngx_stream_upstream_module.xml" id="upstream">группе</link>. -Группа должна находиться в -<link doc="ngx_stream_upstream_module.xml" id="zone">зоне разделяемой памяти</link>. -</para> - -<para> -Если проверка работоспособности была неуспешной, -то сервер признаётся неработоспособным. -Если для группы задано несколько проверок, -то при любой неуспешной проверке соответствующий сервер будет -считаться неработоспособным. -На неработоспособные серверы и серверы в состоянии “checking” -клиентские соединения передаваться не будут. -</para> - -<para> -<note> -Модуль доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</section> - - -<section id="example" name="Пример конфигурации"> - -<para> -<example> -upstream tcp { - zone upstream_tcp 64k; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345 fail_timeout=5s slow_start=30s; - server 192.0.2.1:12345 max_fails=3; - - server backup1.example.com:12345 backup; - server backup2.example.com:12345 backup; -} - -server { - listen 12346; - proxy_pass tcp; - health_check; -} -</example> -Для каждого сервера группы <literal>tcp</literal> -с интервалом в 5 секунд проверяется возможность установки TCP-соединения. -Если соединение с сервером не может быть установлено, -проверка считается неуспешной и сервер -признаётся неработоспособным. -</para> - -<para> -Проверки работоспособности можно настроить для протокола UDP: -<example> -upstream dns_upstream { - - zone dns_zone 64k; - - server dns1.example.com:53; - server dns2.example.com:53; - server dns3.example.com:53; -} - -server { - listen 53 udp; - proxy_pass dns_upstream; - health_check udp; -} -</example> -В этом случае проверяется отсутствие -сообщения ICMP “<literal>Destination Unreachable</literal>” -в ответ на отправленную строку “<literal>nginx health check</literal>”. -</para> - -<para> -Проверки работоспособности могут тестировать данные, полученные от сервера. -Тесты настраиваются отдельно при помощи директивы <link id="match"/> -и указываются в параметре <literal>match</literal> директивы -<link id="health_check"/>. -</para> - -</section> - - -<section id="directives" name="Директивы"> - -<directive name="health_check"> -<syntax>[<value>параметры</value>]</syntax> -<default/> -<context>server</context> - -<para> -Активирует периодические проверки работоспособности серверов в -<link doc="ngx_stream_upstream_hc_module.xml" id="upstream">группе</link>. -</para> - -<para> -Могут быть заданы следующие необязательные параметры: -<list type="tag"> - -<tag-name id="health_check_interval"> -<literal>interval</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт интервал между двумя последовательными проверками, -по умолчанию 5 секунд. -</tag-desc> - -<tag-name id="health_check_jitter"> -<literal>jitter</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт время, в пределах которого -случайным образом задерживается каждая проверка, -по умолчанию задержки нет. -</tag-desc> - -<tag-name id="health_check_fails"> -<literal>fails</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число последовательных неуспешных проверок для определённого сервера, -после которых сервер будет считаться неработоспособным, -по умолчанию 1. -</tag-desc> - -<tag-name id="health_check_passes"> -<literal>passes</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт число последовательных успешных проверок для определённого сервера, -после которых сервер будет считаться работоспособным, -по умолчанию 1. -</tag-desc> - -<tag-name id="health_check_mandatory"> -<literal>mandatory</literal> [<literal>persistent</literal>] -</tag-name> -<tag-desc> -<para> -устанавливает исходное состояние “checking” для сервера -до завершения первой проверки работоспособности (1.11.7). -На серверы в состоянии “checking” клиентские соединения передаваться не будут. -Если параметр не указан, -то исходно сервер будет считаться работоспособным. -</para> - -<para id="health_check_persistent"> -Параметр <literal>persistent</literal> (1.21.1) -устанавливает исходное состояние “up” для сервера после перезагрузки nginx -в случае, если до перезагрузки сервер считался работоспособным. -</para> -</tag-desc> - -<tag-name id="health_check_match"> -<literal>match</literal>=<value>имя</value> -</tag-name> -<tag-desc> -указывает на блок <literal>match</literal> с условиями, которым должно -удовлетворять соединение, чтобы результат проверки считался успешным. -По умолчанию для TCP проверяется -лишь возможность установки TCP-соединения с сервером, -для <link id="health_check_udp">UDP</link> проверяется отсутствие -сообщения ICMP “<literal>Destination Unreachable</literal>” -в ответ на отправленную строку “<literal>nginx health check</literal>”. -<note> -До версии 1.11.7 по умолчанию для UDP -требовалось наличие блока <link id="hc_match">match</link> с параметрами -<link id="match_send">send</link> и <link id="match_expect">expect</link>. -</note> -</tag-desc> - -<tag-name id="health_check_port"> -<literal>port</literal>=<value>число</value> -</tag-name> -<tag-desc> -задаёт порт, используемый при подключении к серверу -для проверки его работоспособности (1.9.7). -По умолчанию совпадает с портом -<link doc="ngx_stream_upstream_module.xml" id="server">сервера</link>. -</tag-desc> - -<tag-name id="health_check_udp"> -<literal>udp</literal> -</tag-name> -<tag-desc> -указывает, что для проверки работоспособности будет использоваться протокол -<literal>UDP</literal> -вместо протокола <literal>TCP</literal>, используемого по умолчанию (1.9.13). -</tag-desc> - -</list> -</para> - -</directive> - - -<directive name="health_check_timeout"> -<syntax><value>время</value></syntax> -<default>5s</default> -<context>stream</context> -<context>server</context> - -<para> -Переопределяет значение -<link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> -для проверок работоспособности. -</para> - -</directive> - - -<directive name="match"> -<syntax block="yes"><value>имя</value> </syntax> -<default/> -<context>stream</context> - -<para> -Задаёт именованный набор тестов для для анализа ответов сервера -на запросы проверки работоспособности. -</para> - -<para> -Могут быть заданы следующие параметры: -<list type="tag"> - -<tag-name id="match_send"> -<literal>send</literal> <value>строка</value>; -</tag-name> -<tag-desc> -отправляет <value>строку</value> на сервер; -</tag-desc> - -<tag-name id="match_expect"> -<literal>expect</literal> <value>стока</value> | -<literal>~</literal> <value>regex</value>; -</tag-name> -<tag-desc> -текстовая строка (1.9.12) или регулярное выражение, -которым должны соответствовать данные, полученные с сервера. -Регулярное выражение задаётся либо с модификатором -“<literal>~*</literal>” (для поиска совпадения без учёта регистра символов), -либо с модификатором “<literal>~</literal>” (с учётом регистра). -</tag-desc> - -</list> -Параметры <literal>send</literal> и <literal>expect</literal> -могут содержать строки в шестнадцатеричном виде -с префиксом “<literal>\x</literal>” -и последующими двумя шестнадцатеричными цифрами, -например “<literal>\x80</literal>” (1.9.12). -</para> - -<para> -Проверка работоспособности считается успешной, если -<list type="bullet"> -<listitem> -TCP-соединение успешно установлено; -</listitem> - -<listitem> -<value>строка</value> из параметра <literal>send</literal> -была отправлена (если была задана); -</listitem> - -<listitem> -данные, полученные от сервера, совпали со строкой или регулярным выражением -из параметра <literal>expect</literal> (если был задан); -</listitem> - -<listitem> -истёкшее время не превышает значение, указанное -в директиве <link id="health_check_timeout"/>. -</listitem> - -</list> -</para> - -<para> -Пример: -<example> -upstream backend { - zone upstream_backend 10m; - server 127.0.0.1:12345; -} - -match http { - send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; - expect ~ "200 OK"; -} - -server { - listen 12346; - proxy_pass backend; - health_check match=http; -} -</example> -</para> - -<para> -<note> -Проверяются лишь первые байты данных -<link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>, -полученные от сервера. -</note> -</para> - -</directive> - -</section> - -</module>
--- 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="39"> + rev="40"> <section id="summary"> @@ -45,36 +45,6 @@ server { </example> </para> -<para> -Динамически настраиваемая группа -с периодическими -<link doc="ngx_stream_upstream_hc_module.xml">проверками работоспособности</link> -доступна как часть -<commercial_version>коммерческой подписки</commercial_version>: -<example> -resolver 10.0.0.1; - -upstream <emphasis>dynamic</emphasis> { - zone upstream_dynamic 64k; - - server backend1.example.com:12345 weight=5; - server backend2.example.com:12345 fail_timeout=5s slow_start=30s; - server 192.0.2.1:12345 max_fails=3; - server backend3.example.com:12345 resolve; - server backend4.example.com service=http resolve; - - server backup1.example.com:12345 backup; - server backup2.example.com:12345 backup; -} - -server { - listen 12346; - proxy_pass <emphasis>dynamic</emphasis>; - health_check; -} -</example> -</para> - </section> @@ -156,10 +126,6 @@ 5 соединений на <literal>backend1.example.com:12345</literal> Значение по умолчанию равно 0 и означает, что ограничения нет. Если группа не находится в <link id="zone">зоне разделяемой памяти</link>, то ограничение работает отдельно для каждого рабочего процесса. -<note> -До версии 1.11.5 этот параметр был доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> </tag-desc> <tag-name id="max_fails"> @@ -220,96 +186,9 @@ 5 соединений на <literal>backend1.example.com:12345</literal> </para> <para> -Кроме того, -следующие параметры доступны как часть -<commercial_version>коммерческой подписки</commercial_version>: -<list type="tag"> - -<tag-name id="resolve"> -<literal>resolve</literal> -</tag-name> -<tag-desc> -отслеживает изменения IP-адресов, соответствующих доменному имени сервера, -и автоматически изменяет конфигурацию группы -без необходимости перезапуска nginx. -Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>. -<para> -Для работы этого параметра -директива <literal>resolver</literal> -должна быть задана в блоке -<link doc="ngx_stream_core_module.xml" id="resolver">stream</link> -или в соответствующем блоке <link id="resolver">upstream</link>. -</para> -</tag-desc> - -<tag-name id="service"> -<literal>service</literal>=<value>имя</value> -</tag-name> -<tag-desc> -включает преобразование -<link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>-записей -DNS и задаёт <value>имя</value> сервиса (1.9.13). -Для работы параметра необходимо указать -параметр <link id="resolve"/> для сервера -и не указывать порт сервера. -<para> -Если имя сервиса не содержит точку (“<literal>.</literal>”), то -имя составляется в соответствии с -<link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link> -и в префикс службы добавляется протокол TCP. -Например, для получения -SRV-записи <literal>_http._tcp.backend.example.com</literal> -необходимо указать директиву: -<example> -server backend.example.com service=http resolve; -</example> -Если имя сервиса содержит одну и более точек, то имя составляется -при помощи соединения префикса службы и имени сервера. -Например, для получения SRV-записей -<literal>_http._tcp.backend.example.com</literal> -и <literal>server1.backend.example.com</literal> -необходимо указать директивы: -<example> -server backend.example.com service=_http._tcp resolve; -server example.com service=server1.backend resolve; -</example> -</para> - -<para> -SRV-записи с наивысшим приоритетом -(записи с одинаковым наименьшим значением приоритета) -преобразуются в основные серверы, -остальные SRV-записи преобразуются в запасные серверы. -Если в конфигурации сервера указан параметр <link id="backup"/>, -высокоприоритетные SRV-записи преобразуются в запасные серверы, -остальные SRV-записи игнорируются. -</para> -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>время</value> -</tag-name> -<tag-desc> -задаёт <value>время</value>, в течение которого вес сервера -восстановится от нуля до своего номинального значения в ситуации, когда -неработоспособный (unhealthy) сервер вновь становится работоспособным -(<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">healthy</link>) -или когда сервер становится доступным по прошествии времени, -в течение которого он считался <link id="fail_timeout">недоступным</link>. -Значение по умолчанию равно нулю и означает, что медленный старт выключен. <note> -Параметр нельзя использовать совместно с -методами балансировки нагрузки <link id="hash"/> и <link id="random"/>. -</note> -</tag-desc> - -</list> -</para> - -<para> -<note> -Если в группе только один сервер, параметры <literal>max_fails</literal>, -<literal>fail_timeout</literal> и <literal>slow_start</literal> +Если в группе только один сервер, +параметры <literal>max_fails</literal> и <literal>fail_timeout</literal> игнорируются и такой сервер никогда не будет считаться недоступным. </note> </para> @@ -330,70 +209,6 @@ SRV-записи с наивысшим приоритетом В этом случае достаточно указать <value>размер</value> только один раз. </para> -<para> -Дополнительно, как часть -<commercial_version>коммерческой подписки</commercial_version>, -в таких группах для изменения состава группы -или настроек отдельных серверов -нет необходимости перезапускать nginx. -Конфигурация доступна через -модуль <link doc="../http/ngx_http_api_module.xml">API</link> (1.13.3). -<note> -До версии 1.13.3 -конфигурация была доступна только через специальный location, -в котором указана директива -<link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. -</note> -</para> - -</directive> - - -<directive name="state"> -<syntax><value>файл</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.9.7</appeared-in> - -<para> -Задаёт <value>файл</value>, в котором хранится состояние -динамически настраиваемой группы. -</para> - -<para> -Примеры: -<example> -state /var/lib/nginx/state/servers.conf; # путь для Linux -state /var/db/nginx/state/servers.conf; # путь для FreeBSD -</example> -</para> - -<para> -В данный момент состояние ограничено списком серверов с их параметрами. -Файл читается при парсинге конфигурации и обновляется каждый раз при -<link doc="../http/ngx_http_api_module.xml" id="stream_upstreams_stream_upstream_name_servers_">изменении</link> -конфигурации группы. -Изменение содержимого файла напрямую не рекомендуется. -Директиву нельзя использовать -совместно с директивой <link id="server"/>. -</para> - -<para> -<note> -Изменения, совершённые в момент -<link doc="../control.xml" id="reconfiguration">перезагрузки конфигурации</link> -или <link doc="../control.xml" id="upgrade">обновления бинарного файла</link>, -могут быть потеряны. -</note> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - </directive> @@ -450,51 +265,6 @@ hash $remote_addr; </directive> -<directive name="least_time"> -<syntax> - <literal>connect</literal> | - <literal>first_byte</literal> | - <literal>last_byte</literal> - [<literal>inflight</literal>]</syntax> -<default/> -<context>upstream</context> - -<para> -Задаёт для группы метод балансировки нагрузки, при котором соединение -передаётся серверу с наименьшими средним временем ответа и -числом активных соединений с учётом весов серверов. -Если подходит сразу несколько серверов, то они выбираются циклически -(в режиме round-robin) с учётом их весов. -</para> - -<para> -Если указан параметр <literal>connect</literal>, -то учитывается время -<link id="var_upstream_connect_time">соединения</link> с сервером группы. -Если указан параметр <literal>first_byte</literal>, -то учитывается время получения -<link id="var_upstream_first_byte_time">первого байта</link> данных. -Если указан параметр <literal>last_byte</literal>, -то учитывается время получения -<link id="var_upstream_session_time">последнего байта</link> данных. -Если указан параметр <literal>inflight</literal> (1.11.6), -то также учитываются незавершённые соединения. -<note> -До версии 1.11.6 -незавершённые соединения учитывались по умолчанию. -</note> -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - <directive name="random"> <syntax>[<literal>two</literal> [<value>метод</value>]]</syntax> <default/> @@ -518,110 +288,6 @@ hash $remote_addr; с наименьшим количеством активных соединений. </para> -<para id="random_least_time"> -Если указан метод <literal>least_time</literal>, то соединение передаётся -серверу -с наименьшими средним временем ответа и числом активных соединений. -Если указан <literal>least_time=connect</literal>, -то учитывается время -<link id="var_upstream_connect_time">соединения</link> с сервером группы. -Если указан <literal>least_time=first_byte</literal>, -то учитывается время получения -<link id="var_upstream_first_byte_time">первого байта</link> данных. -Если указан <literal>least_time=last_byte</literal>, -то учитывается время получения -<link id="var_upstream_session_time">последнего байта</link> данных. -<note> -Метод <literal>least_time</literal> доступен как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="resolver"> -<syntax> - <value>адрес</value> ... - [<literal>valid</literal>=<value>время</value>] - [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<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-адреса -при преобразовании имён в адреса. -Если поиск IPv4- или IPv6-адресов нежелателен, -можно указать параметр <literal>ipv4=off</literal> (1.23.1) или -<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/xml/ru/docs/syslog.xml +++ b/xml/ru/docs/syslog.xml @@ -97,9 +97,6 @@ access_log syslog:server=[2001:db8::1]:1 <para> <note> Запись в syslog доступна начиная с версии 1.7.1. -Как часть -<commercial_version>коммерческой подписки</commercial_version> -запись в syslog доступна начиная с версии 1.5.3. </note> </para>
--- a/xml/ru/support.xml +++ b/xml/ru/support.xml @@ -8,18 +8,7 @@ <article name="nginx: поддержка" link="/ru/support.html" lang="ru" - rev="10"> - - -<section name="Коммерческая поддержка"> - -<para> -Мы предлагаем -<link url="https://www.nginx.com/support/">платную техническую поддержку</link> -для nginx и наших коммерческих продуктов. -</para> - -</section> + rev="11"> <section name="Списки рассылок">
--- a/xsls/versions.xsls +++ b/xsls/versions.xsls @@ -15,10 +15,4 @@ X:template = "stable_version" { /versions/download[@tag='stable'][1]/item[1]/@ver"; } -X:template = "commercial_version" { - <a href="http://nginx.com/products/"> - !!; - </a> } - -}
deleted file mode 100644 --- a/yaml/GNUmakefile +++ /dev/null @@ -1,11 +0,0 @@ -API_HEAD=../xml/en/docs/http/ngx_http_api_module_head.xml - -../xml/en/docs/http/ngx_http_api_module.xml: \ - nginx_api.yaml \ - yaml2xml.py \ - $(API_HEAD) - cat $(API_HEAD) > $@ - ./yaml2xml.py nginx_api.yaml >> $@ - echo "</module>" >> $@ - -.DELETE_ON_ERROR:
deleted file mode 100644 --- a/yaml/nginx_api.yaml +++ /dev/null @@ -1,4848 +0,0 @@ -swagger: '2.0' -info: - version: '9.0' - title: NGINX Plus REST API - description: NGINX Plus REST - [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) - provides access to NGINX Plus status information, - on-the-fly configuration of upstream servers and - 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/9 -tags: - - name: General Info - - name: Processes - - name: Connections - - name: Workers - - name: Slabs - - name: Resolvers - - name: SSL - - name: HTTP - - name: HTTP Requests - - 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 - - name: Method GET - - name: Method POST - - name: Method PATCH - - name: Method DELETE -schemes: - - http - - https -paths: - /: - get: - tags: - - General Info - - Method GET - summary: Return list of root endpoints - description: Returns a list of root endpoints. - operationId: getAPIEndpoints - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/ArrayOfStrings' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - /nginx: - get: - tags: - - General Info - - Method GET - summary: Return status of nginx running instance - description: Returns nginx version, build name, address, - number of configuration reloads, IDs of master and worker processes. - operationId: getNginx - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of nginx running instance will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxObject' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - /processes: - get: - tags: - - Processes - - Method GET - summary: Return nginx processes status - description: Returns the number of abnormally terminated - and respawned child processes. - operationId: getProcesses - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxProcesses' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Processes - - Method DELETE - summary: Reset nginx processes statistics - description: Resets counters of abnormally terminated and respawned - child processes. - operationId: deleteProcesses - responses: - '204': - description: Success - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /connections: - get: - tags: - - Connections - - Method GET - summary: Return client connections statistics - description: Returns statistics of client connections. - operationId: getConnections - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxConnections' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - parameters: - - in: query - name: fields - type: string - description: Limits which fields of the connections statistics will be output. - delete: - tags: - - Connections - - Method DELETE - summary: Reset client connections statistics - description: Resets statistics of accepted and dropped - client connections. - operationId: deleteConnections - responses: - '204': - description: Success - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /slabs/: - get: - tags: - - Slabs - - Method GET - summary: Return status of all slabs - description: Returns status of slabs - for each shared memory zone with slab allocator. - operationId: getSlabs - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of slab 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/NginxSlabZoneMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/slabs/{slabZoneName}': - parameters: - - name: slabZoneName - in: path - description: The name of the shared memory zone with slab allocator. - required: true - type: string - get: - tags: - - Slabs - - Method GET - summary: Return status of a slab - description: Returns status of slabs for a particular shared memory zone - with slab allocator. - operationId: getSlabZone - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of the slab zone will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxSlabZone' - '404': - description: | - Slab not found (*SlabNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Slabs - - Method DELETE - summary: Reset slab statistics - description: Resets the “<literal>reqs</literal>” and “<literal>fails</literal>” - metrics for each memory slot. - operationId: deleteSlabZoneStats - responses: - '204': - description: Success - '404': - description: | - Slab not found (*SlabNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /http/: - get: - tags: - - HTTP - - Method GET - summary: Return list of HTTP-related endpoints - description: Returns a list of first level HTTP endpoints. - operationId: getHttp - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/ArrayOfStrings' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - /http/requests: - get: - tags: - - HTTP Requests - - Method GET - summary: Return HTTP requests statistics - description: Returns status of client HTTP requests. - operationId: getHttpRequests - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of client HTTP requests statistics - will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPRequests' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Requests - - Method DELETE - summary: Reset HTTP requests statistics - description: Resets the number of total client HTTP requests. - operationId: deleteHttpRequests - responses: - '204': - description: Success - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /http/server_zones/: - get: - tags: - - HTTP Server Zones - - Method GET - summary: Return status of all HTTP server zones - description: Returns status information for each HTTP - [server zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone). - operationId: getHttpServerZones - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of server zones will be output. - If the “<literal>fields</literal>” value is empty, - then only server zone names will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPServerZonesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/http/server_zones/{httpServerZoneName}': - parameters: - - name: httpServerZoneName - in: path - description: The name of an HTTP server zone. - type: string - required: true - get: - tags: - - HTTP Server Zones - - Method GET - summary: Return status of an HTTP server zone - description: Returns status of a particular HTTP server zone. - operationId: getHttpServerZone - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the server zone will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPServerZone' - '404': - description: | - Server zone not found (*ServerZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Server Zones - - Method DELETE - summary: Reset statistics for an HTTP server zone - description: Resets statistics of accepted and discarded requests, responses, - received and sent bytes, counters of SSL handshakes and session reuses - in a particular HTTP server zone. - operationId: deleteHttpServerZoneStat - responses: - '204': - description: Success - '404': - description: | - Server zone not found (*ServerZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /http/location_zones/: - get: - tags: - - HTTP Location Zones - - Method GET - summary: Return status of all HTTP location zones - description: Returns status information for each HTTP - [location zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location). - operationId: getHttpLocationZones - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of location 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/NginxHTTPLocationZonesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/http/location_zones/{httpLocationZoneName}': - parameters: - - name: httpLocationZoneName - in: path - description: The name of an HTTP [location zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location). - type: string - required: true - get: - tags: - - HTTP Location Zones - - Method GET - summary: Return status of an HTTP location zone - description: Returns status of a particular - HTTP [location zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location). - operationId: getHttpLocationZone - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the location zone will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPLocationZone' - '404': - description: | - Location zone not found (*LocationZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Location Zones - - Method DELETE - summary: Reset statistics for a location zone. - description: Resets statistics of accepted and discarded requests, responses, - received and sent bytes in a particular location zone. - operationId: deleteHttpLocationZoneStat - responses: - '204': - description: Success - '404': - description: | - Location zone not found (*LocationZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /http/caches/: - get: - tags: - - HTTP Caches - - Method GET - summary: Return status of all caches - description: Returns status of each cache configured by - [proxy_cache_path](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path) - and other “<literal>*_cache_path</literal>” directives. - operationId: getHttpCaches - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of cache zones will be output. - If the “<literal>fields</literal>” value is empty, - then only names of cache zones will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPCachesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/http/caches/{httpCacheZoneName}': - parameters: - - name: httpCacheZoneName - in: path - description: The name of the cache zone. - type: string - required: true - get: - tags: - - HTTP Caches - - Method GET - summary: Return status of a cache - description: Returns status of a particular cache. - operationId: getHttpCacheZone - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the cache zone will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPCache' - '404': - description: | - Cache not found (*CacheNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Caches - - Method DELETE - summary: Reset cache statistics - description: Resets statistics of cache hits/misses in a particular cache zone. - operationId: deleteHttpCacheZoneStat - responses: - '204': - description: Success - '404': - description: | - Cache not found (*CacheNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - 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' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/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*), - unknown version (*UnknownVersion*) - 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*), - unknown version (*UnknownVersion*) - 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' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/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*), - unknown version (*UnknownVersion*) - 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*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /http/upstreams/: - get: - tags: - - HTTP Upstreams - - Method GET - summary: Return status of all HTTP upstream server groups - description: Returns status of each HTTP upstream server group - and its servers. - operationId: getHttpUpstreams - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of upstream server groups will be output. - If the “<literal>fields</literal>” value is empty, - only names of upstreams will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPUpstreamMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/http/upstreams/{httpUpstreamName}/': - parameters: - - name: httpUpstreamName - in: path - description: The name of an HTTP upstream server group. - required: true - type: string - get: - tags: - - HTTP Upstreams - - Method GET - summary: Return status of an HTTP upstream server group - description: Returns status of a particular HTTP upstream server group - and its servers. - operationId: getHttpUpstreamName - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the upstream server group will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPUpstream' - '400': - description: Upstream is static (*UpstreamStatic*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Upstreams - - Method DELETE - summary: Reset statistics of an HTTP upstream server group - description: Resets the statistics for each upstream server - in an upstream server group and queue statistics. - operationId: deleteHttpUpstreamStat - produces: - - application/json - responses: - '204': - description: Success - '400': - description: Upstream is static (*UpstreamStatic*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '/http/upstreams/{httpUpstreamName}/servers/': - parameters: - - name: httpUpstreamName - in: path - description: The name of an upstream server group. - required: true - type: string - get: - tags: - - HTTP Upstreams - - Method GET - summary: Return configuration of all servers in an HTTP upstream server group - description: Returns configuration of each server - in a particular HTTP upstream server group. - operationId: getHttpUpstreamServers - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServerMap' - '400': - description: Upstream is static (*UpstreamStatic*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - post: - tags: - - HTTP Upstreams - - Method POST - summary: Add a server to an HTTP upstream server group - description: Adds a new server to an HTTP upstream server group. - Server parameters are specified in the JSON format. - operationId: postHttpUpstreamServer - produces: - - application/json - parameters: - - in: body - name: postHttpUpstreamServer - description: Address of a new server and other optional parameters - in the JSON format. - The “*ID*”, “*backup*”, and “*service*” parameters - cannot be changed. - required: true - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServer' - responses: - '201': - description: Created - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServer' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid “**parameter**” value (*UpstreamConfFormatError*), - missing “*server*” argument (*UpstreamConfFormatError*), - unknown parameter “**name**” (*UpstreamConfFormatError*), - nested object or list (*UpstreamConfFormatError*), - “*error*” while parsing (*UpstreamBadAddress*), - service upstream “*host*” may not have port (*UpstreamBadAddress*), - service upstream “*host*” requires domain name (*UpstreamBadAddress*), - invalid “*weight*” (*UpstreamBadWeight*), - invalid “*max_conns*” (*UpstreamBadMaxConns*), - invalid “*max_fails*” (*UpstreamBadMaxFails*), - invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), - invalid “*slow_start*” (*UpstreamBadSlowStart*), - reading request body failed *BodyReadError*), - route is too long (*UpstreamBadRoute*), - “*service*” is empty (*UpstreamBadService*), - no resolver defined to resolve (*UpstreamConfNoResolver*), - upstream “**name**” has no backup (*UpstreamNoBackup*), - upstream “**name**” memory exhausted (*UpstreamOutOfMemory*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '409': - description: Entry exists (*EntryExists*) - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - '/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}': - parameters: - - name: httpUpstreamName - in: path - description: The name of the upstream server group. - required: true - type: string - - name: httpUpstreamServerId - in: path - description: The ID of the server. - required: true - type: string - get: - tags: - - HTTP Upstreams - - Method GET - summary: Return configuration of a server in an HTTP upstream server group - description: Returns configuration of a particular server - in the HTTP upstream server group. - operationId: getHttpUpstreamPeer - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServer' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid server ID (*UpstreamBadServerId*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Server with ID “**id**” does not exist (*UpstreamServerNotFound*), - unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - patch: - tags: - - HTTP Upstreams - - Method PATCH - summary: Modify a server in an HTTP upstream server group - description: Modifies settings of a particular server - in an HTTP upstream server group. - Server parameters are specified in the JSON format. - operationId: patchHttpUpstreamPeer - produces: - - application/json - parameters: - - in: body - name: patchHttpUpstreamServer - description: Server parameters, specified in the JSON format. - The “*ID*”, “*backup*”, and “*service*” parameters - cannot be changed. - required: true - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServer' - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServer' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid “**parameter**” value (*UpstreamConfFormatError*), - unknown parameter “**name**” (*UpstreamConfFormatError*), - nested object or list (*UpstreamConfFormatError*), - “*error*” while parsing (*UpstreamBadAddress*), - invalid “*server*” argument (*UpstreamBadAddress*), - invalid server ID (*UpstreamBadServerId*), - invalid “*weight*” (*UpstreamBadWeight*), - invalid “*max_conns*” (*UpstreamBadMaxConns*), - invalid “*max_fails*” (*UpstreamBadMaxFails*), - invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), - invalid “*slow_start*” (*UpstreamBadSlowStart*), - reading request body failed *BodyReadError*), - route is too long (*UpstreamBadRoute*), - “*service*” is empty (*UpstreamBadService*), - server “**ID**” address is immutable (*UpstreamServerImmutable*), - server “*ID*” weight is immutable (*UpstreamServerWeightImmutable*), - upstream “*name*” memory exhausted (*UpstreamOutOfMemory*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Server with ID “**id**” does not exist (*UpstreamServerNotFound*), - unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Upstreams - - Method DELETE - summary: Remove a server from an HTTP upstream server group - description: Removes a server from an HTTP upstream server group. - operationId: deleteHttpUpstreamServer - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPUpstreamConfServerMap' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid server ID (*UpstreamBadServerId*), - server “**id**” not removable (*UpstreamServerImmutable*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Server with ID “**id**” does not exist (*UpstreamServerNotFound*), - unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /http/keyvals/: - get: - tags: - - HTTP Keyvals - - Method GET - summary: Return key-value pairs from all HTTP keyval zones - description: Returns key-value pairs for each HTTP keyval shared memory - [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). - operationId: getHttpKeyvalZones - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: If the “<literal>fields</literal>” value is empty, - then only HTTP keyval zone names will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPKeyvalZonesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/http/keyvals/{httpKeyvalZoneName}': - parameters: - - name: httpKeyvalZoneName - in: path - description: The name of an HTTP keyval shared memory zone. - required: true - type: string - get: - tags: - - HTTP Keyvals - - Method GET - summary: Return key-value pairs from an HTTP keyval zone - description: Returns key-value pairs stored in a particular HTTP keyval shared memory - [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). - operationId: getHttpKeyvalZoneKeysValues - produces: - - application/json - parameters: - - name: key - in: query - type: string - description: Get a particular key-value pair from the HTTP keyval zone. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxHTTPKeyvalZone' - '404': - description: | - Keyval not found (*KeyvalNotFound*), - keyval key not found (*KeyvalKeyNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - post: - tags: - - HTTP Keyvals - - Method POST - summary: Add a key-value pair to the HTTP keyval zone - description: Adds a new key-value pair to the HTTP keyval shared memory - [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). - Several key-value pairs can be entered - if the HTTP keyval shared memory zone is empty. - operationId: postHttpKeyvalZoneData - produces: - - application/json - parameters: - - in: body - name: Key-value - description: A key-value pair is specified in the JSON format. - Several key-value pairs can be entered - if the HTTP keyval shared memory zone is empty. - Expiration time in milliseconds can be specified for a key-value pair - with the *expire* parameter - which overrides the [*timeout*](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout) - parameter of the - <a href="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</a> - directive. - required: true - schema: - $ref: '#/definitions/NginxHTTPKeyvalZonePostPatch' - responses: - '201': - description: Created - '400': - description: | - Invalid JSON (*KeyvalFormatError*), - invalid key format (*KeyvalFormatError*), - key required (*KeyvalFormatError*), - keyval timeout is not enabled (*KeyvalFormatError*), - only one key can be added (*KeyvalFormatError*), - reading request body failed *BodyReadError*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Keyval not found (*KeyvalNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '409': - description: | - Entry exists (*EntryExists*), - key already exists (*KeyvalKeyExists*) - schema: - $ref: '#/definitions/NginxError' - '413': - description: Request Entity Too Large - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - patch: - tags: - - HTTP Keyvals - - Method PATCH - summary: Modify a key-value or delete a key - description: Changes the value of the selected key in the key-value pair, - deletes a key by setting the key value to <literal>null</literal>, - changes expiration time of a key-value pair. - If - <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> - of keyval zones in a cluster is enabled, - deletes a key only on a target cluster node. - Expiration time in milliseconds can be specified for a key-value pair - with the *expire* parameter - which overrides the [*timeout*](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout) - parameter of the - <a href="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</a> - directive. - operationId: patchHttpKeyvalZoneKeyValue - produces: - - application/json - parameters: - - in: body - name: httpKeyvalZoneKeyValue - description: A new value for the key is specified in the JSON format. - required: true - schema: - $ref: '#/definitions/NginxHTTPKeyvalZonePostPatch' - responses: - '204': - description: Success - '400': - description: | - Invalid JSON (*KeyvalFormatError*), - key required (*KeyvalFormatError*), - keyval timeout is not enabled (*KeyvalFormatError*), - only one key can be updated (*KeyvalFormatError*), - reading request body failed *BodyReadError*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Keyval not found (*KeyvalNotFound*), - keyval key not found (*KeyvalKeyNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '413': - description: Request Entity Too Large - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - HTTP Keyvals - - Method DELETE - summary: Empty the HTTP keyval zone - description: Deletes all key-value pairs from the HTTP keyval shared memory - [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). - If - <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> - of keyval zones in a cluster is enabled, - empties the keyval zone only on a target cluster node. - operationId: deleteHttpKeyvalZoneData - responses: - '204': - description: Success - '404': - description: | - Keyval not found (*KeyvalNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /stream/: - get: - tags: - - Stream - summary: Return list of stream-related endpoints - description: Returns a list of first level stream endpoints. - operationId: getStream - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/ArrayOfStrings' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - /stream/server_zones/: - get: - tags: - - Stream Server Zones - - Method GET - summary: Return status of all stream server zones - description: Returns status information for each stream - [server zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone). - operationId: getStreamServerZones - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of server zones will be output. - If the “<literal>fields</literal>” value is empty, - then only server zone names will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamServerZonesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/stream/server_zones/{streamServerZoneName}': - parameters: - - name: streamServerZoneName - in: path - description: The name of a stream server zone. - type: string - required: true - get: - tags: - - Stream Server Zones - - Method GET - summary: Return status of a stream server zone - description: Returns status of a particular stream server zone. - operationId: getStreamServerZone - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the server zone will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamServerZone' - '404': - description: | - Server zone not found (*ServerZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Stream Server Zones - - Method DELETE - summary: Reset statistics for a stream server zone - description: Resets statistics of accepted and discarded connections, sessions, - received and sent bytes, counters of SSL handshakes and session reuses - in a particular stream server zone. - operationId: deleteStreamServerZoneStat - responses: - '204': - description: Success - '404': - description: | - Server zone not found (*ServerZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - 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' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/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*), - unknown version (*UnknownVersion*) - 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*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /stream/upstreams/: - get: - tags: - - Stream Upstreams - - Method GET - summary: Return status of all stream upstream server groups - description: Returns status of each stream upstream server group - and its servers. - operationId: getStreamUpstreams - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of upstream server groups will be output. - If the “<literal>fields</literal>” value is empty, - only names of upstreams will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamUpstreamMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/stream/upstreams/{streamUpstreamName}/': - parameters: - - name: streamUpstreamName - in: path - description: The name of a stream upstream server group. - required: true - type: string - get: - tags: - - Stream Upstreams - - Method GET - summary: Return status of a stream upstream server group - description: Returns status of a particular stream upstream server group - and its servers. - operationId: getStreamUpstream - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the upstream server group will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamUpstream' - '400': - description: Upstream is static (*UpstreamStatic*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Stream Upstreams - - Method DELETE - summary: Reset statistics of a stream upstream server group - description: Resets the statistics for each upstream server - in an upstream server group. - operationId: deleteStreamUpstreamStat - produces: - - application/json - responses: - '204': - description: Success - '400': - description: Upstream is static (*UpstreamStatic*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '/stream/upstreams/{streamUpstreamName}/servers/': - parameters: - - name: streamUpstreamName - in: path - description: The name of an upstream server group. - required: true - type: string - get: - tags: - - Stream Upstreams - - Method GET - summary: Return configuration of all servers in a stream upstream server group - description: Returns configuration of each server - in a particular stream upstream server group. - operationId: getStreamUpstreamServers - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServerMap' - '400': - description: Upstream is static (*UpstreamStatic*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - post: - tags: - - Stream Upstreams - - Method POST - summary: Add a server to a stream upstream server group - description: Adds a new server to a stream upstream server group. - Server parameters are specified in the JSON format. - operationId: postStreamUpstreamServer - produces: - - application/json - parameters: - - in: body - name: postStreamUpstreamServer - description: Address of a new server and other optional parameters - in the JSON format. - The “*ID*”, “*backup*”, and “*service*” parameters - cannot be changed. - required: true - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServer' - responses: - '201': - description: Created - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServer' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid “**parameter**” value (*UpstreamConfFormatError*), - missing “*server*” argument (*UpstreamConfFormatError*), - unknown parameter “**name**” (*UpstreamConfFormatError*), - nested object or list (*UpstreamConfFormatError*), - “*error*” while parsing (*UpstreamBadAddress*), - no port in server “*host*” (*UpstreamBadAddress*), - service upstream “*host*” may not have port (*UpstreamBadAddress*), - service upstream “*host*” requires domain name (*UpstreamBadAddress*), - invalid “*weight*” (*UpstreamBadWeight*), - invalid “*max_conns*” (*UpstreamBadMaxConns*), - invalid “*max_fails*” (*UpstreamBadMaxFails*), - invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), - invalid “*slow_start*” (*UpstreamBadSlowStart*), - “*service*” is empty (*UpstreamBadService*), - no resolver defined to resolve (*UpstreamConfNoResolver*), - upstream “**name**” has no backup (*UpstreamNoBackup*), - upstream “**name**” memory exhausted (*UpstreamOutOfMemory*), - reading request body failed *BodyReadError*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '409': - description: Entry exists (*EntryExists*) - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - '/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}': - parameters: - - name: streamUpstreamName - in: path - description: The name of the upstream server group. - required: true - type: string - - name: streamUpstreamServerId - in: path - description: The ID of the server. - required: true - type: string - get: - tags: - - Stream Upstreams - - Method GET - summary: Return configuration of a server in a stream upstream server group - description: Returns configuration of a particular server - in the stream upstream server group. - operationId: getStreamUpstreamServer - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServer' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid server ID (*UpstreamBadServerId*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*), - server with ID “**id**” does not exist (*UpstreamServerNotFound*) - schema: - $ref: '#/definitions/NginxError' - patch: - tags: - - Stream Upstreams - - Method PATCH - summary: Modify a server in a stream upstream server group - description: Modifies settings of a particular server - in a stream upstream server group. - Server parameters are specified in the JSON format. - operationId: patchStreamUpstreamServer - produces: - - application/json - parameters: - - in: body - name: patchStreamUpstreamServer - description: Server parameters, specified in the JSON format. - The “*ID*”, “*backup*”, and “*service*” parameters - cannot be changed. - required: true - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServer' - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServer' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid “**parameter**” value (*UpstreamConfFormatError*), - unknown parameter “**name**” (*UpstreamConfFormatError*), - nested object or list (*UpstreamConfFormatError*), - “*error*” while parsing (*UpstreamBadAddress*), - invalid “*server*” argument (*UpstreamBadAddress*), - no port in server “*host*” (*UpstreamBadAddress*), - invalid server ID (*UpstreamBadServerId*), - invalid “*weight*” (*UpstreamBadWeight*), - invalid “*max_conns*” (*UpstreamBadMaxConns*), - invalid “*max_fails*” (*UpstreamBadMaxFails*), - invalid “*fail_timeout*” (*UpstreamBadFailTimeout*), - invalid “*slow_start*” (*UpstreamBadSlowStart*), - reading request body failed *BodyReadError*), - “*service*” is empty (*UpstreamBadService*), - server “**ID**” address is immutable (*UpstreamServerImmutable*), - server “**ID**” weight is immutable (*UpstreamServerWeightImmutable*), - upstream “*name*” memory exhausted (*UpstreamOutOfMemory*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Server with ID “**id**” does not exist (*UpstreamServerNotFound*), - unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Stream Upstreams - - Method DELETE - summary: Remove a server from a stream upstream server group - description: Removes a server from a stream server group. - operationId: deleteStreamUpstreamServer - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamUpstreamConfServerMap' - '400': - description: | - Upstream is static (*UpstreamStatic*), - invalid server ID (*UpstreamBadServerId*), - server “**id**” not removable (*UpstreamServerImmutable*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Server with ID “**id**” does not exist (*UpstreamServerNotFound*), - unknown version (*UnknownVersion*), - upstream not found (*UpstreamNotFound*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /stream/keyvals/: - get: - tags: - - Stream Keyvals - - Method GET - summary: Return key-value pairs from all stream keyval zones - description: Returns key-value pairs for each stream keyval shared memory - [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). - operationId: getStreamKeyvalZones - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: If the “<literal>fields</literal>” value is empty, - then only stream keyval zone names will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamKeyvalZonesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '/stream/keyvals/{streamKeyvalZoneName}': - parameters: - - name: streamKeyvalZoneName - in: path - description: The name of a stream keyval shared memory zone. - required: true - type: string - get: - tags: - - Stream Keyvals - - Method GET - summary: Return key-value pairs from a stream keyval zone - description: Returns key-value pairs stored in a particular stream keyval shared memory - [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). - operationId: getStreamKeyvalZoneKeysValues - produces: - - application/json - parameters: - - name: key - in: query - type: string - description: Get a particular key-value pair from the stream keyval zone. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamKeyvalZone' - '404': - description: | - Keyval not found (*KeyvalNotFound*), - keyval key not found (*KeyvalKeyNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - post: - tags: - - Stream Keyvals - - Method POST - summary: Add a key-value pair to the stream keyval zone - description: Adds a new key-value pair to the stream keyval shared memory - [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). - Several key-value pairs can be entered - if the stream keyval shared memory zone is empty. - operationId: postStreamKeyvalZoneData - produces: - - application/json - parameters: - - in: body - name: Key-value - description: A key-value pair is specified in the JSON format. - Several key-value pairs can be entered - if the stream keyval shared memory zone is empty. - Expiration time in milliseconds can be specified for a key-value pair - with the *expire* parameter - which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) - parameter of the - <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> - directive. - required: true - schema: - $ref: '#/definitions/NginxStreamKeyvalZonePostPatch' - responses: - '201': - description: Created - '400': - description: | - Invalid JSON (*KeyvalFormatError*), - invalid key format (*KeyvalFormatError*), - key required (*KeyvalFormatError*), - keyval timeout is not enabled (*KeyvalFormatError*), - only one key can be added (*KeyvalFormatError*), - reading request body failed *BodyReadError*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Keyval not found (*KeyvalNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '409': - description: | - Entry exists (*EntryExists*), - key already exists (*KeyvalKeyExists*) - schema: - $ref: '#/definitions/NginxError' - '413': - description: Request Entity Too Large - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - patch: - tags: - - Stream Keyvals - - Method PATCH - summary: Modify a key-value or delete a key - description: Changes the value of the selected key in the key-value pair, - deletes a key by setting the key value to <literal>null</literal>, - changes expiration time of a key-value pair. - If - <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> - of keyval zones in a cluster is enabled, - deletes a key only on a target cluster node. - Expiration time is specified in milliseconds - with the *expire* parameter - which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) - parameter of the - <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> - directive. - operationId: patchStreamKeyvalZoneKeyValue - produces: - - application/json - parameters: - - in: body - name: streamKeyvalZoneKeyValue - description: A new value for the key is specified in the JSON format. - required: true - schema: - $ref: '#/definitions/NginxStreamKeyvalZonePostPatch' - responses: - '204': - description: Success - '400': - description: | - Invalid JSON (*KeyvalFormatError*), - key required (*KeyvalFormatError*), - keyval timeout is not enabled (*KeyvalFormatError*), - only one key can be updated (*KeyvalFormatError*), - reading request body failed *BodyReadError*) - schema: - $ref: '#/definitions/NginxError' - '404': - description: | - Keyval not found (*KeyvalNotFound*), - keyval key not found (*KeyvalKeyNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '413': - description: Request Entity Too Large - schema: - $ref: '#/definitions/NginxError' - '415': - description: JSON error (*JsonError*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Stream Keyvals - - Method DELETE - summary: Empty the stream keyval zone - description: Deletes all key-value pairs from the stream keyval shared memory - [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). - If - <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> - of keyval zones in a cluster is enabled, - empties the keyval zone only on a target cluster node. - operationId: deleteStreamKeyvalZoneData - responses: - '204': - description: Success - '404': - description: | - Keyval not found (*KeyvalNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /stream/zone_sync/: - get: - tags: - - Stream Zone Sync - - Method GET - summary: Return sync status of a node - description: Returns synchronization status of a cluster node. - operationId: getStreamZoneSync - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxStreamZoneSync' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - /resolvers/: - get: - tags: - - Resolvers - - Method GET - summary: Return status for all resolver zones - description: Returns status information for each - [resolver zone](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone). - operationId: getResolverZones - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxResolverZonesMap' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - parameters: - - in: query - name: fields - type: string - description: Limits which fields of resolvers statistics will be output. - '/resolvers/{resolverZoneName}': - parameters: - - name: resolverZoneName - in: path - description: The name of a resolver zone. - required: true - type: string - get: - tags: - - Resolvers - - Method GET - summary: Return statistics of a resolver zone - description: Returns statistics stored in a particular resolver - [zone](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone). - operationId: getResolverZone - produces: - - application/json - parameters: - - name: fields - in: query - type: string - description: Limits which fields of the resolver zone will be output - (requests, responses, or both). - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxResolverZone' - '404': - description: | - Resolver zone not found (*ResolverZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Resolvers - - Method DELETE - summary: Reset statistics for a resolver zone. - description: Resets statistics in a particular resolver zone. - operationId: deleteResolverZoneStat - responses: - '204': - description: Success - '404': - description: | - Resolver zone not found (*ResolverZoneNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /ssl: - get: - tags: - - SSL - - Method GET - summary: Return SSL statistics - description: Returns SSL statistics. - operationId: getSsl - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxSSLObject' - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - parameters: - - in: query - name: fields - type: string - description: Limits which fields of SSL statistics will be output. - delete: - tags: - - SSL - - Method DELETE - summary: Reset SSL statistics - description: Resets counters of SSL handshakes and session reuses. - operationId: deleteSslStat - responses: - '204': - description: Success - '404': - description: Unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - /workers/: - get: - tags: - - Workers - - Method GET - summary: Return statistics for all worker processes - description: Returns statistics for all worker processes such as accepted, dropped, active, idle connections, total and current requests. - operationId: getWorkers - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of worker process statistics will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxWorkersMap' - '404': - description: | - Worker not found (*WorkerNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Workers - - Method DELETE - summary: Reset statistics for all worker processes. - description: | - Resets statistics for all worker processes such as - accepted, dropped, active, idle connections, total and current requests. - operationId: deleteWorkersStat - produces: - - application/json - responses: - '204': - description: Success - '404': - description: | - Worker not found (*WorkerNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' - '/workers/{workerId}': - parameters: - - name: workerId - in: path - description: The ID of the worker process. - required: true - type: string - get: - tags: - - Workers - - Method GET - summary: Return status of a worker process - description: Returns status of a particular worker process. - operationId: getWorker - produces: - - application/json - parameters: - - in: query - name: fields - type: string - description: Limits which fields of worker process statistics will be output. - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxWorker' - '404': - description: | - Worker not found (*WorkerNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - delete: - tags: - - Workers - - Method DELETE - summary: Reset statistics for a worker process. - description: | - Resets statistics of accepted, dropped, active, idle connections, - as well as total and current requests. - operationId: deleteWorkerStat - produces: - - application/json - responses: - '204': - description: Success - '404': - description: | - Worker not found (*WorkerNotFound*), - unknown version (*UnknownVersion*) - schema: - $ref: '#/definitions/NginxError' - '405': - description: Method disabled (*MethodDisabled*) - schema: - $ref: '#/definitions/NginxError' -### -###DEFINITIONS -### -definitions: - ArrayOfStrings: - title: Array - description: | - An array of strings. - type: array - items: - type: string - NginxObject: - title: nginx - description: | - General information about nginx: - type: object - properties: - version: - type: string - description: Version of nginx. - build: - type: string - description: Name of nginx build. - address: - type: string - description: The address of the server that accepted status request. - generation: - type: integer - description: The total number of configuration - <a href="https://nginx.org/en/docs/control.html#reconfiguration">reloads</a>. - load_timestamp: - type: string - format: date-time - description: Time of the last reload of configuration, - in the ISO 8601 format with millisecond resolution. - timestamp: - type: string - format: date-time - description: Current time - in the ISO 8601 format with millisecond resolution. - pid: - type: integer - description: The ID of the worker process that handled status request. - ppid: - type: integer - description: The ID of the master process that started the - <a href="https://nginx.org/en/docs/http/ngx_http_status_module.html#pid">worker process</a>. - example: - nginx: - version: 1.21.6 - build: nginx-plus-r27 - address: 206.251.255.64 - generation: 6 - load_timestamp: 2022-06-28T11:15:44.467Z - timestamp: 2022-06-28T09:26:07.305Z - pid: 32212 - ppid: 32210 - NginxProcesses: - title: Processes - type: object - properties: - respawned: - type: integer - description: The total number of abnormally terminated - and respawned child processes. - example: - respawned: 0 - NginxConnections: - title: Connections - description: | - The number of accepted, dropped, active, and idle connections. - type: object - properties: - accepted: - type: integer - description: The total number of accepted client connections. - dropped: - type: integer - description: The total number of dropped client connections. - active: - type: integer - description: The current number of active client connections. - idle: - type: integer - description: The current number of idle client connections. - example: - accepted: 4968119 - dropped: 0 - active: 5 - idle: 117 - NginxSSLObject: - title: SSL - type: object - properties: - handshakes: - type: integer - description: The total number of successful SSL handshakes. - handshakes_failed: - type: integer - description: The total number of failed SSL handshakes. - session_reuses: - type: integer - description: The total number of session reuses during SSL handshake. - no_common_protocol: - type: integer - description: The number of SSL handshakes failed - because of no common protocol. - no_common_cipher: - type: integer - description: The number of SSL handshakes failed - because of no shared cipher. - handshake_timeout: - type: integer - description: The number of SSL handshakes failed - because of a timeout. - peer_rejected_cert: - type: integer - description: The number of failed SSL handshakes - when nginx presented the certificate to the client - but it was rejected with a corresponding alert message. - verify_failures: - type: object - description: SSL certificate verification errors - properties: - no_cert: - type: integer - description: A client did not provide the required certificate. - expired_cert: - type: integer - description: An expired or not yet valid certificate - was presented by a client. - revoked_cert: - type: integer - description: A revoked certificate was presented by a client. - hostname_mismatch: - type: integer - description: Server's certificate doesn't match the hostname. - other: - type: integer - description: Other SSL certificate verification errors. - example: - handshakes: 79572 - handshakes_failed: 21025 - session_reuses: 15762 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - NginxSlabZoneMap: - title: Slab Zones - description: | - Status zones that use slab allocator. - type: object - additionalProperties: - $ref: '#/definitions/NginxSlabZone' - example: - http_cache: - pages: - used: 2 - free: 2452 - slots: - 8: - used: 0 - free: 0 - reqs: 0 - fails: 0 - 16: - used: 0 - free: 0 - reqs: 0 - fails: 0 - 32: - used: 1 - free: 126 - reqs: 1 - fails: 0 - 64: - used: 2 - free: 62 - reqs: 2 - fails: 0 - 128: - used: 0 - free: 0 - reqs: 0 - fails: 0 - dns-backends: - 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 - NginxSlabZone: - title: Shared memory zone with slab allocator - description: | - Shared memory zone with slab allocator - type: object - properties: - pages: - type: object - description: The number of free and used memory pages. - properties: - used: - type: integer - description: The current number of used memory pages. - free: - type: integer - description: The current number of free memory pages. - slots: - type: object - title: Memory Slots - description: Status data for memory slots (8, 16, 32, 64, 128, etc.) - additionalProperties: - $ref: '#/definitions/NginxSlabZoneSlot' - 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 - NginxSlabZoneSlot: - title: Memory Slot - type: object - properties: - used: - type: integer - description: The current number of used memory slots. - free: - type: integer - description: The current number of free memory slots. - reqs: - type: integer - description: The total number of attempts - to allocate memory of specified size. - fails: - type: integer - description: The number of unsuccessful attempts - to allocate memory of specified size. - NginxHTTPRequests: - title: HTTP Requests - type: object - properties: - total: - type: integer - description: The total number of client requests. - current: - type: integer - description: The current number of client requests. - example: - total: 10624511 - current: 4 - NginxHTTPServerZonesMap: - title: HTTP Server Zones - description: | - Status data for all HTTP - <a href="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">status zones</a>. - type: object - additionalProperties: - $ref: '#/definitions/NginxHTTPServerZone' - example: - site1: - processing: 2 - requests: 736395 - responses: - 1xx: 0 - 2xx: 727290 - 3xx: 4614 - 4xx: 934 - 5xx: 1535 - codes: - 200: 727270 - 301: 4614 - 404: 930 - 503: 1535 - total: 734373 - discarded: 2020 - received: 180157219 - sent: 20183175459 - ssl: - handshakes: 65432 - handshakes_failed: 421 - session_reuses: 4645 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - site2: - processing: 1 - requests: 185307 - responses: - 1xx: 0 - 2xx: 112674 - 3xx: 45383 - 4xx: 2504 - 5xx: 4419 - codes: - 200: 112674 - 301: 45383 - 404: 2504 - 503: 4419 - total: 164980 - discarded: 20326 - received: 51575327 - sent: 2983241510 - ssl: - handshakes: 104303 - handshakes_failed: 1421 - session_reuses: 54645 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - NginxHTTPServerZone: - title: HTTP Server Zone - type: object - properties: - processing: - type: integer - description: The number of client requests - that are currently being processed. - requests: - type: integer - description: The total number of client requests received from clients. - responses: - description: The total number of responses sent to clients, the - number of responses with status codes - “<code>1xx</code>”, “<code>2xx</code>”, “<code>3xx</code>”, - “<code>4xx</code>”, and “<code>5xx</code>”, and - the number of responses per each status code. - type: object - readOnly: true - properties: - 1xx: - type: integer - description: The number of responses with “<code>1xx</code>” status codes. - readOnly: true - 2xx: - type: integer - description: The number of responses with “<code>2xx</code>” status codes. - readOnly: true - 3xx: - type: integer - description: The number of responses with “<code>3xx</code>” status codes. - readOnly: true - 4xx: - type: integer - description: The number of responses with “<code>4xx</code>” status codes. - readOnly: true - 5xx: - type: integer - description: The number of responses with “<code>5xx</code>” status codes. - readOnly: true - codes: - type: object - description: The number of responses per each status code. - readOnly: true - properties: - codeNumber: - type: integer - description: The number of responses with this particular status code. - readOnly: true - total: - type: integer - description: The total number of responses sent to clients. - readOnly: true - discarded: - type: integer - description: The total number of - requests completed without sending a response. - received: - type: integer - description: The total number of bytes received from clients. - sent: - type: integer - description: The total number of bytes sent to clients. - ssl: - type: object - readOnly: true - properties: - handshakes: - type: integer - description: The total number of successful SSL handshakes. - readOnly: true - handshakes_failed: - type: integer - description: The total number of failed SSL handshakes. - readOnly: true - session_reuses: - type: integer - description: The total number of session reuses during SSL handshake. - readOnly: true - no_common_protocol: - type: integer - description: The number of SSL handshakes failed - because of no common protocol. - no_common_cipher: - type: integer - description: The number of SSL handshakes failed - because of no shared cipher. - handshake_timeout: - type: integer - description: The number of SSL handshakes failed - because of a timeout. - peer_rejected_cert: - type: integer - description: The number of failed SSL handshakes - when nginx presented the certificate to the client - but it was rejected with a corresponding alert message. - verify_failures: - type: object - description: SSL certificate verification errors - properties: - no_cert: - type: integer - description: A client did not provide the required certificate. - expired_cert: - type: integer - description: An expired or not yet valid certificate - was presented by a client. - revoked_cert: - type: integer - description: A revoked certificate was presented by a client. - other: - type: integer - description: Other SSL certificate verification errors. - example: - processing: 1 - requests: 706690 - responses: - 1xx: 0 - 2xx: 699482 - 3xx: 4522 - 4xx: 907 - 5xx: 266 - codes: - 200: 699482 - 301: 4522 - 404: 907 - 503: 266 - total: 705177 - discarded: 1513 - received: 172711587 - sent: 19415530115 - ssl: - handshakes: 104303 - handshakes_failed: 1421 - session_reuses: 54645 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - other: 1 - NginxHTTPLocationZonesMap: - title: HTTP Location Zones - description: | - Status data for all HTTP - <a href="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">location zones</a>. - type: object - additionalProperties: - $ref: '#/definitions/NginxHTTPLocationZone' - example: - site1: - requests: 736395 - responses: - 1xx: 0 - 2xx: 727290 - 3xx: 4614 - 4xx: 934 - 5xx: 1535 - codes: - 200: 727290 - 301: 4614 - 404: 934 - 503: 1535 - total: 734373 - discarded: 2020 - received: 180157219 - sent: 20183175459 - site2: - requests: 185307 - responses: - 1xx: 0 - 2xx: 112674 - 3xx: 45383 - 4xx: 2504 - 5xx: 4419 - codes: - 200: 112674 - 301: 45383 - 404: 2504 - 503: 4419 - total: 164980 - discarded: 20326 - received: 51575327 - sent: 2983241510 - NginxHTTPLocationZone: - title: HTTP Location Zone - type: object - properties: - requests: - type: integer - description: The total number of client requests received from clients. - responses: - description: The total number of responses sent to clients, the - number of responses with status codes - “<code>1xx</code>”, “<code>2xx</code>”, “<code>3xx</code>”, - “<code>4xx</code>”, and “<code>5xx</code>”, and - the number of responses per each status code. - type: object - readOnly: true - properties: - 1xx: - type: integer - description: The number of responses with “<code>1xx</code>” status codes. - readOnly: true - 2xx: - type: integer - description: The number of responses with “<code>2xx</code>” status codes. - readOnly: true - 3xx: - type: integer - description: The number of responses with “<code>3xx</code>” status codes. - readOnly: true - 4xx: - type: integer - description: The number of responses with “<code>4xx</code>” status codes. - readOnly: true - 5xx: - type: integer - description: The number of responses with “<code>5xx</code>” status codes. - readOnly: true - codes: - type: object - description: The number of responses per each status code. - readOnly: true - properties: - codeNumber: - type: integer - description: The number of responses with this particular status code. - readOnly: true - total: - type: integer - description: The total number of responses sent to clients. - readOnly: true - discarded: - type: integer - description: The total number of - requests completed without sending a response. - received: - type: integer - description: The total number of bytes received from clients. - sent: - type: integer - description: The total number of bytes sent to clients. - example: - requests: 706690 - responses: - 1xx: 0 - 2xx: 699482 - 3xx: 4522 - 4xx: 907 - 5xx: 266 - codes: - 200: 112674 - 301: 4522 - 404: 2504 - 503: 266 - total: 705177 - discarded: 1513 - received: 172711587 - sent: 19415530115 - NginxHTTPCachesMap: - title: HTTP Caches - description: | - Status information of all HTTP caches configured by - <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path">proxy_cache_path</a> - and other “<code>*_cache_path</code>” directives. - type: object - additionalProperties: - $ref: '#/definitions/NginxHTTPCache' - example: - http-cache: - 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 - frontend-cache: - 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 - NginxHTTPCache: - title: HTTP Cache - type: object - properties: - size: - type: integer - description: The current size of the cache. - max_size: - type: integer - description: The limit on the maximum size of the cache - specified in the configuration. - cold: - type: boolean - description: A boolean value indicating whether the “cache loader” process - is still loading data from disk into the cache. - hit: - type: object - properties: - responses: - type: integer - description: The total number of - <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid">valid</a> - responses read from the cache. - bytes: - type: integer - description: The total number of bytes read from the cache. - stale: - type: object - properties: - responses: - type: integer - description: The total number of expired responses read from the cache (see - <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale">proxy_cache_use_stale</a> - and other “<code>*_cache_use_stale</code>” directives). - bytes: - type: integer - description: The total number of bytes read from the cache. - updating: - type: object - properties: - responses: - type: integer - description: The total number of expired responses read from the cache - while responses were being updated (see - <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale_updating">proxy_cache_use_stale</a> - and other “<code>*_cache_use_stale</code>” directives). - bytes: - type: integer - description: The total number of bytes read from the cache. - revalidated: - type: object - properties: - responses: - type: integer - description: The total number of expired and revalidated responses - read from the cache (see - <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_revalidate">proxy_cache_revalidate</a> - and other “<code>*_cache_revalidate</code>” directives. - bytes: - type: integer - description: The total number of bytes read from the cache. - miss: - type: object - properties: - responses: - type: integer - description: The total number of responses not found in the cache. - bytes: - type: integer - description: The total number of bytes read from the proxied server. - responses_written: - type: integer - description: The total number of responses written to the cache. - bytes_written: - type: integer - description: The total number of bytes written to the cache. - expired: - type: object - properties: - responses: - type: integer - description: The total number of expired responses not taken from the cache. - bytes: - type: integer - description: The total number of bytes read from the proxied server. - responses_written: - type: integer - description: The total number of responses written to the cache. - bytes_written: - type: integer - description: The total number of bytes written to the cache. - bypass: - type: object - properties: - responses: - type: integer - description: The total number of responses not looked up in the cache due to the - <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_bypass">proxy_cache_bypass</a> - and other “<code>*_cache_bypass</code>” directives. - bytes: - type: integer - description: The total number of bytes read from the proxied server. - responses_written: - type: integer - description: The total number of responses written to the cache. - bytes_written: - type: integer - description: The total number of bytes written to the cache. - 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 - 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: | - Status information of all HTTP - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">dynamically configurable</a> - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">groups</a>. - type: object - additionalProperties: - $ref: '#/definitions/NginxHTTPUpstream' - example: - trac-backend: - peers: - - id: 0 - server: 10.0.0.1:8088 - name: 10.0.0.1:8088 - backup: false - weight: 5 - state: up - active: 0 - ssl: - handshakes: 620311 - handshakes_failed: 3432 - session_reuses: 36442 - no_common_protocol: 4 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - requests: 667231 - header_time: 20 - response_time: 36 - responses: - 1xx: 0 - 2xx: 666310 - 3xx: 0 - 4xx: 915 - 5xx: 6 - codes: - 200: 666310 - 404: 915 - 503: 6 - total: 667231 - sent: 251946292 - received: 19222475454 - fails: 0 - unavail: 0 - health_checks: - checks: 26214 - fails: 0 - unhealthy: 0 - last_passed: true - downtime: 0 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - - id: 1 - server: 10.0.0.1:8089 - name: 10.0.0.1:8089 - backup: true - weight: 1 - state: unhealthy - active: 0 - requests: 0 - responses: - 1xx: 0 - 2xx: 0 - 3xx: 0 - 4xx: 0 - 5xx: 0 - codes: {} - total: 0 - sent: 0 - received: 0 - fails: 0 - unavail: 0 - health_checks: - checks: 26284 - fails: 26284 - unhealthy: 1 - last_passed: false - downtime: 262925617 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - keepalive: 0 - zombies: 0 - zone: trac-backend - hg-backend: - peers: - - id: 0 - server: 10.0.0.1:8088 - name: 10.0.0.1:8088 - backup: false - weight: 5 - state: up - active: 0 - ssl: - handshakes: 620311 - handshakes_failed: 3432 - session_reuses: 36442 - no_common_protocol: 4 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - requests: 667231 - header_time: 20 - response_time: 36 - responses: - 1xx: 0 - 2xx: 666310 - 3xx: 0 - 4xx: 915 - 5xx: 6 - codes: - 200: 666310 - 404: 915 - 503: 6 - total: 667231 - sent: 251946292 - received: 19222475454 - fails: 0 - unavail: 0 - health_checks: - checks: 26214 - fails: 0 - unhealthy: 0 - last_passed: true - downtime: 0 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - - id: 1 - server: 10.0.0.1:8089 - name: 10.0.0.1:8089 - backup: true - weight: 1 - state: unhealthy - active: 0 - requests: 0 - responses: - 1xx: 0 - 2xx: 0 - 3xx: 0 - 4xx: 0 - 5xx: 0 - codes: {} - total: 0 - sent: 0 - received: 0 - fails: 0 - unavail: 0 - health_checks: - checks: 26284 - fails: 26284 - unhealthy: 1 - last_passed: false - downtime: 262925617 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - keepalive: 0 - zombies: 0 - zone: hg-backend - NginxHTTPUpstream: - title: HTTP Upstream - type: object - properties: - peers: - $ref: '#/definitions/NginxHTTPUpstreamPeerMap' - keepalive: - type: integer - description: The current number of idle - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</a> - connections. - zombies: - type: integer - description: The current number of servers removed - from the group but still processing active client requests. - zone: - type: string - description: The name of the shared memory - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</a> - that keeps the group’s configuration and run-time state. - queue: - type: object - description: > - For the requests - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</a>, - the following data are provided: - properties: - size: - type: integer - description: The current number of requests in the queue. - max_size: - type: integer - description: The maximum number of requests that can be in the queue - at the same time. - overflows: - type: integer - description: The total number of requests rejected due to the queue overflow. - example: - upstream_backend: - peers: - - id: 0 - server: 10.0.0.1:8088 - name: 10.0.0.1:8088 - backup: false - weight: 5 - state: up - active: 0 - ssl: - handshakes: 620311 - handshakes_failed: 3432 - session_reuses: 36442 - no_common_protocol: 4 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - max_conns: 20 - requests: 667231 - header_time: 20 - response_time: 36 - responses: - 1xx: 0 - 2xx: 666310 - 3xx: 0 - 4xx: 915 - 5xx: 6 - codes: - 200: 666310 - 404: 915 - 503: 6 - total: 667231 - sent: 251946292 - received: 19222475454 - fails: 0 - unavail: 0 - health_checks: - checks: 26214 - fails: 0 - unhealthy: 0 - last_passed: true - downtime: 0 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - - id: 1 - server: 10.0.0.1:8089 - name: 10.0.0.1:8089 - backup: true - weight: 1 - state: unhealthy - active: 0 - max_conns: 20 - requests: 0 - responses: - 1xx: 0 - 2xx: 0 - 3xx: 0 - 4xx: 0 - 5xx: 0 - codes: {} - total: 0 - sent: 0 - received: 0 - fails: 0 - unavail: 0 - health_checks: - checks: 26284 - fails: 26284 - unhealthy: 1 - last_passed: false - downtime: 262925617 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - keepalive: 0 - zombies: 0 - zone: upstream_backend - NginxHTTPUpstreamPeerMap: - title: HTTP Upstream Servers - description: | - An array of HTTP - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">upstream servers</a>. - type: array - items: - $ref: '#/definitions/NginxHTTPUpstreamPeer' - NginxHTTPUpstreamPeer: - title: HTTP Upstream Server - type: object - properties: - id: - type: integer - description: The ID of the server. - readOnly: true - server: - type: string - description: An <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> - of the server. - service: - type: string - description: The - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> - parameter value of the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> - directive. - name: - type: string - description: The name of the server specified in the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> - directive. - readOnly: true - backup: - type: boolean - description: A boolean value indicating whether the server is a - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> - server. - weight: - type: integer - description: <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</a> - of the server. - state: - type: string - enum: - - up - - draining - - down - - unavail - - checking - - unhealthy - description: Current state, which may be one of - “<code>up</code>”, “<code>draining</code>”, “<code>down</code>”, - “<code>unavail</code>”, “<code>checking</code>”, - and “<code>unhealthy</code>”. - active: - type: integer - description: The current number of active connections. - readOnly: true - ssl: - type: object - readOnly: true - properties: - handshakes: - type: integer - description: The total number of successful SSL handshakes. - readOnly: true - handshakes_failed: - type: integer - description: The total number of failed SSL handshakes. - readOnly: true - session_reuses: - type: integer - description: The total number of session reuses during SSL handshake. - readOnly: true - no_common_protocol: - type: integer - description: The number of SSL handshakes failed - because of no common protocol. - handshake_timeout: - type: integer - description: The number of SSL handshakes failed - because of a timeout. - peer_rejected_cert: - type: integer - description: The number of failed SSL handshakes - when nginx presented the certificate to the upstream server - but it was rejected with a corresponding alert message. - verify_failures: - type: object - description: SSL certificate verification errors - properties: - expired_cert: - type: integer - description: An expired or not yet valid certificate - was presented by an upstream server. - revoked_cert: - type: integer - description: A revoked certificate was presented by an upstream server. - hostname_mismatch: - type: integer - description: Server's certificate doesn't match the hostname. - other: - type: integer - description: Other SSL certificate verification errors. - max_conns: - type: integer - description: The - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> - limit for the server. - requests: - type: integer - description: The total number of client requests forwarded to this server. - readOnly: true - responses: - type: object - readOnly: true - properties: - 1xx: - type: integer - description: The number of responses with “<code>1xx</code>” status codes. - readOnly: true - 2xx: - type: integer - description: The number of responses with “<code>2xx</code>” status codes. - readOnly: true - 3xx: - type: integer - description: The number of responses with “<code>3xx</code>” status codes. - readOnly: true - 4xx: - type: integer - description: The number of responses with “<code>4xx</code>” status codes. - readOnly: true - 5xx: - type: integer - description: The number of responses with “<code>5xx</code>” status codes. - readOnly: true - codes: - type: object - description: The number of responses per each status code. - readOnly: true - properties: - codeNumber: - type: integer - description: The number of responses with this particular status code. - readOnly: true - total: - type: integer - description: The total number of responses obtained from this server. - readOnly: true - sent: - type: integer - description: The total number of bytes sent to this server. - readOnly: true - received: - type: integer - description: The total number of bytes received from this server. - readOnly: true - fails: - type: integer - description: The total number of unsuccessful attempts - to communicate with the server. - readOnly: true - unavail: - type: integer - description: How many times the server became unavailable for client requests - (state “<code>unavail</code>”) due to the number of unsuccessful - attempts reaching the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> - threshold. - readOnly: true - health_checks: - type: object - readOnly: true - properties: - checks: - type: integer - description: The total number of - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</a> - requests made. - fails: - type: integer - description: The number of failed health checks. - unhealthy: - type: integer - description: How many times the server became unhealthy - (state “<code>unhealthy</code>”). - last_passed: - type: boolean - description: Boolean indicating if the last health check request was successful - and passed - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</a>. - downtime: - type: integer - readOnly: true - description: Total time the server was in the “<code>unavail</code>”, - “<code>checking</code>”, and “<code>unhealthy</code>” states. - downstart: - type: string - format: date-time - readOnly: true - description: The time when the server became - “<code>unavail</code>”, “<code>checking</code>”, - or “<code>unhealthy</code>”, - in the ISO 8601 format with millisecond resolution. - selected: - type: string - format: date-time - readOnly: true - description: The time when the server was last selected to process a request, - in the ISO 8601 format with millisecond resolution. - header_time: - type: integer - readOnly: true - description: The average time to get the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</a> - from the server. - response_time: - type: integer - readOnly: true - description: The average time to get the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</a> - from the server. - NginxHTTPUpstreamConfServerMap: - title: HTTP Upstream Servers - description: An array of HTTP upstream servers for dynamic configuration. - type: array - items: - $ref: '#/definitions/NginxHTTPUpstreamConfServer' - example: - - id: 0 - server: 10.0.0.1:8088 - weight: 1 - max_conns: 0 - max_fails: 0 - fail_timeout: 10s - slow_start: 10s - route: '' - backup: false - down: false - - 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 - NginxHTTPUpstreamConfServer: - title: HTTP Upstream Server - description: | - Dynamically configurable parameters of an HTTP upstream - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a>: - type: object - properties: - id: - type: integer - description: The ID of the HTTP upstream server. - The ID is assigned automatically and cannot be changed. - readOnly: true - server: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> - 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 - <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</a> - directive in the “<code>http</code>” block. - See also the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</a> - parameter of the HTTP upstream server. - service: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> - parameter of the HTTP upstream server. - This parameter cannot be changed. - readOnly: true - weight: - type: integer - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">weight</a> - parameter of the HTTP upstream server. - max_conns: - type: integer - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> - parameter of the HTTP upstream server. - max_fails: - type: integer - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> - parameter of the HTTP upstream server. - fail_timeout: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout">fail_timeout</a> - parameter of the HTTP upstream server. - slow_start: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start">slow_start</a> - parameter of the HTTP upstream server. - route: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#route">route</a> - parameter of the HTTP upstream server. - backup: - type: boolean - description: When <code>true</code>, adds a - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> - server. - This parameter cannot be changed. - readOnly: true - down: - type: boolean - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</a> - parameter of the HTTP upstream server. - drain: - type: boolean - description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#drain">drain</a> - parameter of the HTTP upstream server. - parent: - type: string - description: Parent server ID of the resolved server. - The ID is assigned automatically and cannot be changed. - readOnly: true - host: - type: string - description: Hostname of the resolved server. - The hostname is assigned automatically and cannot be changed. - readOnly: true - 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 - NginxHTTPKeyvalZonesMap: - title: HTTP Keyval Shared Memory Zones - description: | - Contents of all HTTP keyval shared memory zones. - type: object - additionalProperties: - $ref: '#/definitions/NginxHTTPKeyvalZone' - example: - keyval_zone: - key1: value1 - key2: value2 - key3: value3 - one: - arg1: value1 - arg2: value2 - arg3: value3 - NginxHTTPKeyvalZone: - title: HTTP Keyval Shared Memory Zone - description: | - Contents of an HTTP keyval shared memory zone - when using the GET method. - type: object - example: - key1: value1 - key2: value2 - key3: value3 - NginxHTTPKeyvalZonePostPatch: - title: HTTP Keyval Shared Memory Zone - description: | - Contents of an HTTP keyval shared memory zone - when using the POST or PATCH methods. - type: object - example: - key1: value1 - key2: value2 - key3: - value: value3 - expire: 30000 - NginxStreamServerZonesMap: - title: Stream Server Zones - description: | - Status information for all stream - <a href="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">status zones</a>. - type: object - additionalProperties: - $ref: '#/definitions/NginxStreamServerZone' - example: - mysql-frontend: - processing: 2 - connections: 270925 - sessions: - 2xx: 155564 - 4xx: 0 - 5xx: 0 - total: 270925 - discarded: 0 - received: 28988975 - sent: 3879346317 - ssl: - handshakes: 76455 - handshakes_failed: 432 - session_reuses: 28770 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - other: 1 - dns: - processing: 1 - connections: 155569 - sessions: - 2xx: 155564 - 4xx: 0 - 5xx: 0 - total: 155569 - discarded: 0 - received: 4200363 - sent: 20489184 - ssl: - handshakes: 2040 - handshakes_failed: 23 - session_reuses: 65 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - other: 1 - NginxStreamServerZone: - title: Stream Server Zone - type: object - properties: - processing: - type: integer - description: The number of client connections - that are currently being processed. - connections: - type: integer - description: The total number of connections accepted from clients. - sessions: - type: object - description: The total number of completed sessions, - and the number of sessions completed with status codes - “<code>2xx</code>”, “<code>4xx</code>”, or “<code>5xx</code>”. - properties: - 2xx: - type: integer - description: The total number of sessions completed with - <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</a> - “<code>2xx</code>”. - 4xx: - type: integer - description: The total number of sessions completed with - <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</a> - “<code>4xx</code>”. - 5xx: - type: integer - description: The total number of sessions completed with - <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status">status codes</a> - “<code>5xx</code>”. - total: - type: integer - description: The total number of completed client sessions. - discarded: - type: integer - description: The total number of - connections completed without creating a session. - received: - type: integer - description: The total number of bytes received from clients. - sent: - type: integer - description: The total number of bytes sent to clients. - ssl: - type: object - readOnly: true - properties: - handshakes: - type: integer - description: The total number of successful SSL handshakes. - readOnly: true - handshakes_failed: - type: integer - description: The total number of failed SSL handshakes. - readOnly: true - session_reuses: - type: integer - description: The total number of session reuses during SSL handshake. - readOnly: true - no_common_protocol: - type: integer - description: The number of SSL handshakes failed - because of no common protocol. - no_common_cipher: - type: integer - description: The number of SSL handshakes failed - because of no shared cipher. - handshake_timeout: - type: integer - description: The number of SSL handshakes failed - because of a timeout. - peer_rejected_cert: - type: integer - description: The number of failed SSL handshakes - when nginx presented the certificate to the client - but it was rejected with a corresponding alert message. - verify_failures: - type: object - description: SSL certificate verification errors - properties: - no_cert: - type: integer - description: A client did not provide the required certificate. - expired_cert: - type: integer - description: An expired or not yet valid certificate - was presented by a client. - revoked_cert: - type: integer - description: A revoked certificate was presented by a client. - other: - type: integer - description: Other SSL certificate verification errors. - example: - dns: - processing: 1 - connections: 155569 - sessions: - 2xx: 155564 - 4xx: 0 - 5xx: 0 - total: 155569 - discarded: 0 - received: 4200363 - sent: 20489184 - ssl: - handshakes: 76455 - handshakes_failed: 432 - session_reuses: 28770 - no_common_protocol: 4 - no_common_cipher: 2 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - no_cert: 0 - expired_cert: 2 - revoked_cert: 1 - other: 1 - 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. - type: object - additionalProperties: - $ref: '#/definitions/NginxStreamUpstream' - example: - mysql_backends: - peers: - - id: 0 - server: 10.0.0.1:12345 - name: 10.0.0.1:12345 - backup: false - weight: 5 - state: up - active: 0 - ssl: - handshakes: 1045 - handshakes_failed: 89 - session_reuses: 321 - no_common_protocol: 4 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - max_conns: 30 - connecions: 1231 - sent: 251946292 - received: 19222475454 - fails: 0 - unavail: 0 - health_checks: - checks: 26214 - fails: 0 - unhealthy: 0 - last_passed: true - downtime: 0 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - - id: 1 - server: 10.0.0.1:12346 - name: 10.0.0.1:12346 - backup: true - weight: 1 - state: unhealthy - active: 0 - max_conns: 30 - connections: 0 - sent: 0 - received: 0 - fails: 0 - unavail: 0 - health_checks: - checks: 26284 - fails: 26284 - unhealthy: 1 - last_passed: false - downtime: 262925617 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - zombies: 0 - zone: mysql_backends - dns: - peers: - - id: 0 - server: 10.0.0.1:12347 - name: 10.0.0.1:12347 - backup: false - weight: 5 - state: up - active: 0 - ssl: - handshakes: 5268 - handshakes_failed: 121 - session_reuses: 854 - no_common_protocol: 4 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - max_conns: 30 - connections: 667231 - sent: 251946292 - received: 19222475454 - fails: 0 - unavail: 0 - health_checks: - checks: 26214 - fails: 0 - unhealthy: 0 - last_passed: true - downtime: 0 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - - id: 1 - server: 10.0.0.1:12348 - name: 10.0.0.1:12348 - backup: true - weight: 1 - state: unhealthy - active: 0 - connections: 0 - max_conns: 30 - sent: 0 - received: 0 - fails: 0 - unavail: 0 - health_checks: - checks: 26284 - fails: 26284 - unhealthy: 1 - last_passed: false - downtime: 262925617 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - zombies: 0 - zone: dns - NginxStreamUpstream: - title: Stream Upstream - type: object - properties: - peers: - $ref: '#/definitions/NginxStreamUpstreamPeerMap' - zombies: - type: integer - description: The current number of servers removed from the group - but still processing active client connections. - zone: - type: string - description: The name of the shared memory - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone">zone</a> - that keeps the group’s configuration and run-time state. - example: - dns: - peers: - - id: 0 - server: 10.0.0.1:12347 - name: 10.0.0.1:12347 - backup: false - weight: 5 - state: up - active: 0 - ssl: - handshakes: 200 - handshakes_failed: 4 - session_reuses: 189 - no_common_protocol: 4 - handshake_timeout: 0 - peer_rejected_cert: 0 - verify_failures: - expired_cert: 2 - revoked_cert: 1 - hostname_mismatch: 2 - other: 1 - max_conns: 50 - connections: 667231 - sent: 251946292 - received: 19222475454 - fails: 0 - unavail: 0 - health_checks: - checks: 26214 - fails: 0 - unhealthy: 0 - last_passed: true - downtime: 0 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - - id: 1 - server: 10.0.0.1:12348 - name: 10.0.0.1:12348 - backup: true - weight: 1 - state: unhealthy - active: 0 - max_conns: 50 - connections: 0 - sent: 0 - received: 0 - fails: 0 - unavail: 0 - health_checks: - checks: 26284 - fails: 26284 - unhealthy: 1 - last_passed: false - downtime: 262925617 - downstart: 2022-06-28T11:09:21.602Z - selected: 2022-06-28T15:01:25Z - zombies: 0 - zone: dns - NginxStreamUpstreamPeerMap: - title: Stream Upstream Servers - description: Array of stream upstream servers. - type: array - items: - $ref: '#/definitions/NginxStreamUpstreamPeer' - NginxStreamUpstreamPeer: - title: Stream Upstream Server - type: object - properties: - id: - type: integer - description: The ID of the server. - readOnly: true - server: - type: string - description: An - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> - of the server. - service: - type: string - description: The - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> - parameter value of the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> - directive. - name: - type: string - format: hostname - description: The name of the server specified in the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> - directive. - readOnly: true - backup: - type: boolean - description: A boolean value indicating whether the server is a - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> - server. - weight: - type: integer - description: <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</a> - of the server. - state: - type: string - readOnly: true - enum: - - up - - down - - unavail - - checking - - unhealthy - description: Current state, which may be one of - “<code>up</code>”, “<code>down</code>”, “<code>unavail</code>”, - “<code>checking</code>”, or “<code>unhealthy</code>”. - active: - type: integer - description: The current number of connections. - readOnly: true - ssl: - type: object - readOnly: true - properties: - handshakes: - type: integer - description: The total number of successful SSL handshakes. - readOnly: true - handshakes_failed: - type: integer - description: The total number of failed SSL handshakes. - readOnly: true - session_reuses: - type: integer - description: The total number of session reuses during SSL handshake. - readOnly: true - no_common_protocol: - type: integer - description: The number of SSL handshakes failed - because of no common protocol. - handshake_timeout: - type: integer - description: The number of SSL handshakes failed - because of a timeout. - peer_rejected_cert: - type: integer - description: The number of failed SSL handshakes - when nginx presented the certificate to the upstream server - but it was rejected with a corresponding alert message. - verify_failures: - type: object - description: SSL certificate verification errors - properties: - expired_cert: - type: integer - description: An expired or not yet valid certificate - was presented by an upstream server. - revoked_cert: - type: integer - description: A revoked certificate was presented by an upstream server. - hostname_mismatch: - type: integer - description: Server's certificate doesn't match the hostname. - other: - type: integer - description: Other SSL certificate verification errors. - max_conns: - type: integer - description: The - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> - limit for the server. - connections: - type: integer - description: The total number of client connections forwarded to this server. - readOnly: true - connect_time: - type: integer - description: The average time to connect to the upstream server. - readOnly: true - first_byte_time: - type: integer - description: The average time to receive the first byte of data. - readOnly: true - response_time: - type: integer - description: The average time to receive the last byte of data. - readOnly: true - sent: - type: integer - description: The total number of bytes sent to this server. - readOnly: true - received: - type: integer - description: The total number of bytes received from this server. - readOnly: true - fails: - type: integer - description: The total number of unsuccessful attempts - to communicate with the server. - readOnly: true - unavail: - type: integer - description: How many times the server became unavailable for client connections - (state “<code>unavail</code>”) due to the number of unsuccessful - attempts reaching the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> - threshold. - readOnly: true - health_checks: - type: object - readOnly: true - properties: - checks: - type: integer - description: The total number of - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check">health check</a> - requests made. - readOnly: true - fails: - type: integer - description: The number of failed health checks. - readOnly: true - unhealthy: - type: integer - description: How many times the server became unhealthy - (state “<code>unhealthy</code>”). - readOnly: true - last_passed: - type: boolean - description: Boolean indicating whether the last health check request - was successful and passed - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match">tests</a>. - readOnly: true - downtime: - type: integer - description: Total time the server was in the - “<code>unavail</code>”, “<code>checking</code>”, - and “<code>unhealthy</code>” states. - readOnly: true - downstart: - type: string - format: date-time - description: The time when the server became - “<code>unavail</code>”, “<code>checking</code>”, - or “<code>unhealthy</code>”, - in the ISO 8601 format with millisecond resolution. - readOnly: true - selected: - type: string - format: date-time - description: The time when the server was last selected - to process a connection, - in the ISO 8601 format with millisecond resolution. - readOnly: true - NginxStreamUpstreamConfServerMap: - title: Stream Upstream Servers - description: | - An array of stream upstream servers for dynamic configuration. - type: array - items: - $ref: '#/definitions/NginxStreamUpstreamConfServer' - 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 - - id: 1 - server: 10.0.0.1:12349 - weight: 1 - max_conns: 0 - max_fails: 1 - fail_timeout: 10s - slow_start: 0 - backup: false - down: false - NginxStreamUpstreamConfServer: - title: Stream Upstream Server - description: | - Dynamically configurable parameters of a stream upstream - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a>: - type: object - properties: - id: - type: integer - description: The ID of the stream upstream server. - The ID is assigned automatically and cannot be changed. - readOnly: true - server: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> - 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 - <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</a> - directive in the “<code>stream</code>” block. - See also the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</a> - parameter of the stream upstream server. - service: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> - parameter of the stream upstream server. - This parameter cannot be changed. - readOnly: true - weight: - type: integer - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</a> - parameter of the stream upstream server. - max_conns: - type: integer - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> - parameter of the stream upstream server. - max_fails: - type: integer - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> - parameter of the stream upstream server. - fail_timeout: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</a> - parameter of the stream upstream server. - slow_start: - type: string - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</a> - parameter of the stream upstream server. - backup: - type: boolean - description: When <code>true</code>, adds a - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> - server. - This parameter cannot be changed. - readOnly: true - down: - type: boolean - description: Same as the - <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</a> - parameter of the stream upstream server. - parent: - type: string - description: Parent server ID of the resolved server. - The ID is assigned automatically and cannot be changed. - readOnly: true - host: - type: string - description: Hostname of the resolved server. - The hostname is assigned automatically and cannot be changed. - readOnly: true - 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 - NginxStreamKeyvalZonesMap: - title: Stream Keyval Shared Memory Zones - description: | - Contents of all stream keyval shared memory zones. - type: object - additionalProperties: - $ref: '#/definitions/NginxStreamKeyvalZone' - example: - keyval_zone: - key1: value1 - key2: value2 - key3: value3 - one: - arg1: value1 - arg2: value2 - arg3: value3 - NginxStreamKeyvalZone: - title: Stream Keyval Shared Memory Zone - description: | - Contents of a stream keyval shared memory zone when using the GET method. - type: object - example: - key1: value1 - key2: value2 - key3: value3 - NginxStreamKeyvalZonePostPatch: - title: Stream Keyval Shared Memory Zone - description: | - Contents of a stream keyval shared memory zone - when using the POST or PATCH methods. - type: object - example: - key1: value1 - key2: value2 - key3: - value: value3 - expire: 30000 - NginxStreamZoneSync: - title: Stream Zone Sync Node - type: object - properties: - zones: - type: object - title: Zone Sync Zones - description: Synchronization information per each shared memory zone. - additionalProperties: - $ref: '#/definitions/NginxStreamZoneSyncZone' - status: - type: object - description: Synchronization information per node in a cluster. - properties: - bytes_in: - type: integer - description: The number of bytes received by this node. - msgs_in: - type: integer - description: The number of messages received by this node. - msgs_out: - type: integer - description: The number of messages sent by this node. - bytes_out: - type: integer - description: The number of bytes sent by this node. - nodes_online: - type: integer - description: The number of peers this node is connected to. - example: - zones: - zone1: - records_pending: 2061 - records_total: 260575 - zone2: - records_pending: 0 - records_total: 14749 - status: - bytes_in: 1364923761 - msgs_in: 337236 - msgs_out: 346717 - bytes_out: 1402765472 - nodes_online: 15 - NginxStreamZoneSyncZone: - title: Sync Zone - description: Synchronization status of a shared memory zone. - type: object - properties: - records_pending: - type: integer - description: The number of records that need to be sent to the cluster. - records_total: - type: integer - description: The total number of records stored in the shared memory zone. - NginxResolverZonesMap: - title: Resolver Zones - description: | - Status data for all - <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zones</a>. - type: object - additionalProperties: - $ref: '#/definitions/NginxResolverZone' - example: - resolver_zone1: - requests: - name: 25460 - srv: 130 - addr: 2580 - responses: - noerror: 26499 - formerr: 0 - servfail: 3 - nxdomain: 0 - notimp: 0 - refused: 0 - timedout: 243 - unknown: 478 - resolver_zone2: - requests: - name: 325460 - srv: 1130 - addr: 12580 - responses: - noerror: 226499 - formerr: 0 - servfail: 283 - nxdomain: 0 - notimp: 0 - refused: 0 - timedout: 743 - unknown: 1478 - NginxResolverZone: - title: Resolver Zone - description: | - Statistics of DNS requests and responses per particular - <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</a>. - type: object - properties: - requests: - type: object - readOnly: true - properties: - name: - type: integer - description: The total number of requests - to resolve names to addresses. - readOnly: true - srv: - type: integer - description: The total number of requests - to resolve SRV records. - readOnly: true - addr: - type: integer - description: The total number of requests - to resolve addresses to names. - readOnly: true - responses: - type: object - readOnly: true - properties: - noerror: - type: integer - description: The total number of successful responses. - readOnly: true - formerr: - type: integer - description: The total number of - FORMERR (<literal>Format error</literal>) responses. - readOnly: true - servfail: - type: integer - description: The total number of - SERVFAIL (<literal>Server failure</literal>) responses. - readOnly: true - nxdomain: - type: integer - description: The total number of - NXDOMAIN (<literal>Host not found</literal>) responses. - readOnly: true - notimp: - type: integer - description: The total number of - NOTIMP (<literal>Unimplemented</literal>) responses. - readOnly: true - refused: - type: integer - description: The total number of - REFUSED (<literal>Operation refused</literal>) responses. - readOnly: true - timedout: - type: integer - description: The total number of timed out requests. - readOnly: true - unknown: - type: integer - description: The total number of requests - completed with an unknown error. - readOnly: true - example: - resolver_zone1: - requests: - name: 25460 - srv: 130 - addr: 2580 - responses: - noerror: 26499 - formerr: 0 - servfail: 3 - nxdomain: 0 - notimp: 0 - refused: 0 - timedout: 243 - unknown: 478 - NginxWorker: - title: Worker process - description: | - Statistics per each worker process. - properties: - id: - type: integer - description: The ID of the worker process. - pid: - type: integer - description: The PID identifier of the worker process used by the operating system. - connections: - type: object - description: | - The number of accepted, dropped, active, and idle connections - per worker process. - properties: - accepted: - type: integer - description: | - The total number of client connections - accepted by the worker process. - dropped: - type: integer - description: | - The total number of client connections - dropped by the worker process. - active: - type: integer - description: | - The current number of active client connections - that are currently being handled by the worker process. - idle: - type: integer - description: | - The number of idle client connections - that are currently being handled by the worker process. - http: - type: object - properties: - requests: - type: object - description: The total number of client requests handled by the worker process. - properties: - total: - type: integer - description: The total number of client requests received by the worker process. - current: - type: integer - description: The current number of client requests that are currently being processed by the worker process. - example: - id: 0 - pid: 32212 - connections: - accepted: 1 - dropped: 0 - active: 1 - idle: 0 - http: - requests: - total: 15 - current: 1 - NginxWorkersMap: - title: Worker processes - description: nginx worker processes object. - type: object - additionalProperties: - $ref: '#/definitions/NginxWorker' - example: - - id: 0 - pid: 32212 - connections: - accepted: 1 - dropped: 0 - active: 1 - idle: 0 - http: - requests: - total: 19 - current: 1 - - id: 1 - pid: 32214 - connections: - accepted: 1 - dropped: 0 - active: 1 - idle: 0 - http: - requests: - total: 15 - current: 0 - NginxError: - title: Error - description: | - nginx error object. - type: object - properties: - error: - type: object - properties: - status: - type: integer - description: HTTP error code. - text: - type: string - description: Error description. - code: - type: string - description: Internal nginx error code. - request_id: - type: string - description: The ID of the request, equals the value of the - <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</a> - variable. - href: - type: string - description: Link to reference documentation.
deleted file mode 100755 --- a/yaml/yaml2xml.py +++ /dev/null @@ -1,523 +0,0 @@ -#!/usr/bin/env python - -# Copyright (C) Nginx, Inc. - -import sys, re, datetime - -from yaml import load, dump -from collections import OrderedDict - -try: - from yaml import CLoader as Loader, CDumper as Dumper, resolver as resolver - -except ImportError: - from yaml import Loader, Dumper, resolver - - -# primitive markdown parser and utf encoding for output -def node_description(node): - - text = node.get('description') - if text == None: - return "" - - # - t = re.sub('\<code\>', r'<literal>', text) - t = re.sub('\</code\>', r'</literal>', t) - - t = re.sub('\<i\>', r'<value>', t) - t = re.sub('\</i\>', r'</value>', t) - - t = re.sub('\<a href=\"(.*?)\"\>(.*?)\</a\>', r'<link url="\1">\2</link>', t) - - # [desc](url) - t = re.sub('\[(.*)\]\((.*?)\)', r'<link url="\2">\1</link>', t) - - # ** foo ** is value - t = re.sub('[*?][*?](\w+)[*?][*?]', r'<value>\1</value>', t) - - # * foo * is literal - t = re.sub('[*?](\w+)[*?]', r'<literal>\1</literal>', t) - - - return t.encode('utf-8').rstrip() - - -def pretty_endpoint(ep): - return ep.replace('/slabs/','slabs').replace('/resolvers/','resolvers').replace('/http/','HTTP ').replace('/stream/','stream ').replace('s/','s').replace('_',' ') - - -# human-readable html element id based on path -def path_to_id(path): - if path == '/': - return 'root' - - str = path.replace('/', '_') - str = str.replace('{', '') - str = str.replace('}','') - - return uncamelcase(str[1:]) - - -def multiple(str): - fin2 = str[-2:] - fin = str[-1:] - - if fin2 == 's' or fin2 == 'sh' or fin2 == 'ch': - last = 'es' - elif fin == 'x' or fin == 'z': - last = 'es' - else: - last = 's' - - return str + last - -def uncamelcase(name): - s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name) - return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower() - -def make_defid(str): - return 'def_' + uncamelcase(str) - -# returns name of a referenced object -def get_refname(obj): - return obj['$ref'][14:] # remove '#/definitions/' - - -# returns referenced object itself from global definitions table -def node_from_ref(doc, obj): - return doc['definitions'][get_refname(obj)] - - -def render_doc(doc): - - out = "<section id=\"endpoints\" name=\"Endpoints\">\n" - out += render_paths(doc) - out += "</section>\n" - - # dry run, perform refcount - render_defs(doc) - - out += "<section id=\"definitions\" name=\"Response Objects\">\n" - out += render_defs(doc) - out += "</section>\n" - - return out - - -def render_paths(doc): - - global curr_endpoint - - paths = doc['paths'] - - out = "<para>\n" - out += "<list type=\"tag\">\n" - - for path_key in paths: - path_id = path_to_id(path_key) - curr_endpoint = path_key - out += render_path(doc, path_key, paths[path_key], path_id) - - curr_endpoint = None - - out += "</list>\n" - out += "</para>\n" - - return out - - -def render_defs(doc): - - out = "<para>\n" - out += "<list type=\"bullet\">\n" - - for d in doc['definitions']: - - if refs.get(d) == None: - continue - - node = doc['definitions'][d] - - out += "<listitem id=\"%s\">\n" % make_defid(d) - title = node.get('title', '') - - out += "<para>%s:</para>\n" % title - - out += render_node(doc, d, node, True) - - out += "</listitem>\n" - - out += "</list>\n" - out += "</para>\n" - - return out - - -def render_path(doc, path_key, path, path_id): - - out = "<tag-name id=\"%s\" name=\"%s\">\n" % (path_id, path_key) - out += "<literal>%s</literal>\n" % path_key - out += "</tag-name>\n" - - out += "<tag-desc>\n" - - # List of common method parameters - for method_key in path: - if method_key != 'parameters': - continue - - out += "Parameters common for all methods:\n" - out += render_parameters(doc, path[method_key]) - - - # List of methods for this path - out += '<para>Supported methods:</para>\n' - out += '<list type="bullet" compact="yes">\n' - - - for method_key in ['get', 'post', 'patch', 'delete']: - - if path.get(method_key) == None: - continue - - method = path[method_key] - - id = method['operationId'] - summ = method['summary'] - desc = node_description(method) - name = method_key.upper() - - out += "<listitem id=\"%s\">\n" % id - out += "<literal>%s</literal> - %s\n" % (name, summ) - out += "<para>%s</para>\n" % desc - - out += render_method(doc, name, method) - - out += "</listitem>\n" - - out += "</list>\n" - out += "</tag-desc>\n" - - return out - - -def render_method(doc, method_name, method): - - out = "" - - if method.get('parameters'): - out += "<para>\n" - out += "Request parameters:\n" - out += render_parameters(doc, method['parameters']) - out += "</para>\n" - - out += "<para>\n" - out += "Possible responses:\n" - out += "</para>\n" - - out += "<list type=\"bullet\">\n" - - for response_key in method['responses']: - out += "<listitem>" - out += render_response(doc, response_key, method['responses'][response_key]) - out += "</listitem>\n" - - out += "</list>\n" - - return out - - -def render_parameters(doc, params): - - out = '<list type="tag">\n' - - for p in params: - - out += "<tag-name><literal>%s</literal>\n" % p['name'] - out += "(" - - out += render_node(doc, None, p, True) - - if p.get("required"): - - if p["required"] == True: - out += ", required" - else: - out += ", optional" - else: - out += ", optional" - - out += ")" - - out += "</tag-name>\n" - out += "<tag-desc>\n" - - desc = node_description(p) - out += desc - - out += "</tag-desc>\n" - - out += "</list>\n" - - return out - - -def render_response(doc, response_key, response): - - out = "" - - desc = node_description(response) - - out += response_key + " - " + desc - - if response.get('schema'): - out += ", returns " - out += render_node(doc, None, response) - - return out - - - -def render_reference(doc, nodename, node): - - global in_array, refs - - out = "" - - ref = get_refname(node) - - refnode = node_from_ref(doc, node) - - if refnode.get('additionalProperties'): - # in entries - - out += "a collection of " - ref = get_refname(refnode['additionalProperties']) - target = node_from_ref(doc, refnode['additionalProperties']) - label = target.get('title', ref) - out += "\"<link id=\"%s\">%s</link>\"" % (make_defid(ref), label) - out += " objects" - refs[ref] = 1 - if curr_endpoint != None: - out += " for all %s" % pretty_endpoint(curr_endpoint) - - return out - - # arrays and primitive types are printed immediately - nt = refnode.get('type', 'object') - title = refnode.get('title', ref) - if nt == 'object': - if in_array == True: - title = multiple(title) - - out += "<link id=\"%s\">%s</link>" % (make_defid(ref), title) - refs[ref] = 1 - - elif nt == 'array': - - if nodename == 'peers': - ref = get_refname(refnode['items']) - out += "An array of:" - refnode = node_from_ref(doc, refnode['items']) - out += render_node(doc, ref, refnode, True) - return out - - out += "an array of " - - in_array = True - out += render_node(doc, nodename, refnode['items'], True) - in_array = False - else: - # dead code actually - out += "<literal>%s</literal>\n" % nt - - return out - - -# displays object recursively if described inline, or generates links -def render_node(doc, nodename, node, show_type=False): - - if node.get('$ref'): - return render_reference(doc, nodename, node) - - elif node.get('schema'): - return render_reference(doc, nodename, node['schema']) - - out = "" - - if node.get('additionalProperties'): - # in definitions - ref = get_refname(node['additionalProperties']) - target = node_from_ref(doc, node['additionalProperties']) - label = target.get('title', ref) - desc = node_description(node) - out += "<para>%s</para><para>A collection of " % desc - out += "\"<link id=\"%s\">%s</link>\"" % (make_defid(ref), label) - refs[ref] = 1 - out += " objects</para>\n" - - return out - - nt = node.get('type', 'object') - - if nt == 'object': - out += render_object(doc, node) - - elif nt == 'array': - desc = node_description(node) - out += "<para>%s</para>\n" % desc - out += "array element type:\n" - out += render_node(doc, nodename, node['items'], True) - - else: - if show_type: - if in_array == True: - out += "%s" % multiple(node['type']) - else: - out += "<literal>%s</literal>" % node['type'] - - if node.get('example'): - out += render_example(node['example']) - - return out - -def json_simple_type(obj): - - if isinstance(obj, bool): - if obj == True: - return 'true' - else: - return 'false' - - elif isinstance(obj, str): - return '"' + obj + '"' - - elif isinstance(obj,datetime.datetime): - t = obj.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] - z = obj.strftime("Z%Z") - return '"' + t + z + '"' - - else: - return str(obj) - -def render_example(obj, level = 0): - - out = "" - - if level == 0: - if isinstance(obj, dict) or isinstance(obj, list): - out += "<para>Example:</para>\n" - else: - out += "Example: <literal>%s</literal>\n" % json_simple_type(obj) - return out - - out += "<example>\n" - - indent = ' ' * level - next_indent = ' ' * (level + 1) - - if isinstance(obj, dict): - out += '{\n' - i = 0 - last = len(obj) - for key in obj: - out += next_indent + '"' + str(key) + '" : ' - out += render_example(obj[key], level + 1) - if i != last - 1: - out += ',' - out += '\n' - i = i + 1 - out += indent + "}" - - elif isinstance(obj, list): - out += '[\n' - i = 0 - last = len(obj) - for item in obj: - out += next_indent - out += render_example(item, level + 1) - if i != last - 1: - out += ',' - out += '\n' - i = i + 1 - out += indent + "]" - else: - out += json_simple_type(obj) - - if level == 0: - out += "</example>\n" - - - return out - - -def render_object(doc, obj): - - out = "" - - if obj.get('description'): - desc = node_description(obj) - out += desc - - if obj.get('properties') == None: - return out - - out += '<list type="tag">\n' - for p in obj['properties']: - - prop = obj['properties'][p] - - out += "<tag-name>\n" - out += "<literal>%s</literal>" % p - - if prop.get('properties') or prop.get('type') == 'object': - obj_type = None # there is nested object - else: - if prop.get('type'): - obj_type = prop['type'] # basic type - else: - obj_type = None # there is a reference - - if obj_type != None: - out += " (<literal>%s</literal>)\n" % obj_type - - out += "</tag-name>\n" - out += "<tag-desc>\n" - - if prop.get('description') and obj_type != None: - desc = node_description(prop) - out += desc + '\n' - - out += render_node(doc, p, prop) - - out += "</tag-desc>\n" - out += "</list>\n" - - return out - - -############################################################################### - -if len(sys.argv) < 2: - print("Usage: %s <nginx_api.yaml>" % sys.argv[0]) - sys.exit(1) - -refs = dict() -curr_endpoint = None -in_array = False - -def ordered_load(stream, Loader=Loader, object_pairs_hook=OrderedDict): - class OrderedLoader(Loader): - pass - def construct_mapping(loader, node): - loader.flatten_mapping(node) - return object_pairs_hook(loader.construct_pairs(node)) - OrderedLoader.add_constructor( - resolver.BaseResolver.DEFAULT_MAPPING_TAG,construct_mapping) - return load(stream, OrderedLoader) - -with open(sys.argv[1], 'r') as src: - content = src.read() - doc = ordered_load(content, Loader=Loader) - print(render_doc(doc))