Mercurial > hg > nginx-site
changeset 2139:f6e578b1b02d
Updated docs for the upcoming NGINX Plus release.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Mon, 09 Apr 2018 11:52:48 +0300 |
| parents | cf86c259c9a0 |
| children | acef9537383c |
| files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_api_module.xml xml/en/docs/http/ngx_http_api_module_head.xml xml/en/docs/http/ngx_http_auth_jwt_module.xml xml/en/docs/http/ngx_http_core_module.xml xml/en/docs/http/ngx_http_upstream_module.xml xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_zone_sync_module.xml xml/ru/docs/http/ngx_http_auth_jwt_module.xml xml/ru/docs/http/ngx_http_core_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/index.xml yaml/nginx_api.yaml |
| diffstat | 13 files changed, 798 insertions(+), 55 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -119,6 +119,7 @@ REFS = \ 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 \ dev/development_guide \
--- a/xml/en/docs/http/ngx_http_api_module.xml +++ b/xml/en/docs/http/ngx_http_api_module.xml @@ -101,21 +101,21 @@ All API requests include a supported API <link id="api_version">version</link> in the URI. Examples of API requests with this configuration: <example> -http://127.0.0.1/api/2/ -http://127.0.0.1/api/2/nginx -http://127.0.0.1/api/2/connections -http://127.0.0.1/api/2/http/requests -http://127.0.0.1/api/2/http/server_zones/server_backend -http://127.0.0.1/api/2/http/caches/cache_backend -http://127.0.0.1/api/2/http/upstreams/backend -http://127.0.0.1/api/2/http/upstreams/backend/servers/ -http://127.0.0.1/api/2/http/upstreams/backend/servers/1 -http://127.0.0.1/api/2/http/keyvals/one?key=arg1 -http://127.0.0.1/api/2/stream/ -http://127.0.0.1/api/2/stream/server_zones/server_backend -http://127.0.0.1/api/2/stream/upstreams/ -http://127.0.0.1/api/2/stream/upstreams/backend -http://127.0.0.1/api/2/stream/upstreams/backend/servers/1 +http://127.0.0.1/api/3/ +http://127.0.0.1/api/3/nginx +http://127.0.0.1/api/3/connections +http://127.0.0.1/api/3/http/requests +http://127.0.0.1/api/3/http/server_zones/server_backend +http://127.0.0.1/api/3/http/caches/cache_backend +http://127.0.0.1/api/3/http/upstreams/backend +http://127.0.0.1/api/3/http/upstreams/backend/servers/ +http://127.0.0.1/api/3/http/upstreams/backend/servers/1 +http://127.0.0.1/api/3/http/keyvals/one?key=arg1 +http://127.0.0.1/api/3/stream/ +http://127.0.0.1/api/3/stream/server_zones/server_backend +http://127.0.0.1/api/3/stream/upstreams/ +http://127.0.0.1/api/3/stream/upstreams/backend +http://127.0.0.1/api/3/stream/upstreams/backend/servers/1 </example> </para> @@ -146,14 +146,14 @@ By default, the API is read-only. All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. -The current API version is “<literal>2</literal>”. +The current API version is “<literal>3</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/2/nginx?fields=version,build +http://127.0.0.1/api/3/nginx?fields=version,build </example> </para> @@ -167,6 +167,11 @@ http://127.0.0.1/api/2/nginx?fields=vers <list type="bullet"> <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> @@ -1434,6 +1439,26 @@ Possible responses: </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 - Zone sync not configured (<literal>ZoneSyncNotConfigured</literal>), +<link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +</list> +</tag-desc> </list> </para> </section> @@ -2878,6 +2903,90 @@ Contents of a stream keyval shared memor "key3" : "value3" }</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_error"> <para>Error:</para> nginx error object.<list type="tag">
--- a/xml/en/docs/http/ngx_http_api_module_head.xml +++ b/xml/en/docs/http/ngx_http_api_module_head.xml @@ -101,21 +101,21 @@ All API requests include a supported API <link id="api_version">version</link> in the URI. Examples of API requests with this configuration: <example> -http://127.0.0.1/api/2/ -http://127.0.0.1/api/2/nginx -http://127.0.0.1/api/2/connections -http://127.0.0.1/api/2/http/requests -http://127.0.0.1/api/2/http/server_zones/server_backend -http://127.0.0.1/api/2/http/caches/cache_backend -http://127.0.0.1/api/2/http/upstreams/backend -http://127.0.0.1/api/2/http/upstreams/backend/servers/ -http://127.0.0.1/api/2/http/upstreams/backend/servers/1 -http://127.0.0.1/api/2/http/keyvals/one?key=arg1 -http://127.0.0.1/api/2/stream/ -http://127.0.0.1/api/2/stream/server_zones/server_backend -http://127.0.0.1/api/2/stream/upstreams/ -http://127.0.0.1/api/2/stream/upstreams/backend -http://127.0.0.1/api/2/stream/upstreams/backend/servers/1 +http://127.0.0.1/api/3/ +http://127.0.0.1/api/3/nginx +http://127.0.0.1/api/3/connections +http://127.0.0.1/api/3/http/requests +http://127.0.0.1/api/3/http/server_zones/server_backend +http://127.0.0.1/api/3/http/caches/cache_backend +http://127.0.0.1/api/3/http/upstreams/backend +http://127.0.0.1/api/3/http/upstreams/backend/servers/ +http://127.0.0.1/api/3/http/upstreams/backend/servers/1 +http://127.0.0.1/api/3/http/keyvals/one?key=arg1 +http://127.0.0.1/api/3/stream/ +http://127.0.0.1/api/3/stream/server_zones/server_backend +http://127.0.0.1/api/3/stream/upstreams/ +http://127.0.0.1/api/3/stream/upstreams/backend +http://127.0.0.1/api/3/stream/upstreams/backend/servers/1 </example> </para> @@ -146,14 +146,14 @@ By default, the API is read-only. All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. -The current API version is “<literal>2</literal>”. +The current API version is “<literal>3</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/2/nginx?fields=version,build +http://127.0.0.1/api/3/nginx?fields=version,build </example> </para> @@ -167,6 +167,11 @@ http://127.0.0.1/api/2/nginx?fields=vers <list type="bullet"> <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>
--- a/xml/en/docs/http/ngx_http_auth_jwt_module.xml +++ b/xml/en/docs/http/ngx_http_auth_jwt_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_http_auth_jwt_module" link="/en/docs/http/ngx_http_auth_jwt_module.html" lang="en" - rev="5"> + rev="6"> <section id="summary"> @@ -95,6 +95,7 @@ location / { <context>http</context> <context>server</context> <context>location</context> +<context>limit_except</context> <para> Enables validation of JSON Web Token. @@ -155,8 +156,12 @@ 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"; +location / { + auth_jwt "closed site"; + auth_jwt_key_file conf/keys.json; + 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, @@ -167,12 +172,33 @@ and the result was undefined for arrays. </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.11</appeared-in> + +<para> +Sets the maximum allowable leeway to compensate +clock skew when verifying the +<link url="https://tools.ietf.org/html/rfc7519#section-4.1.4">exp</link> +and +<link url="https://tools.ietf.org/html/rfc7519#section-4.1.5">nbf</link> +JWT claims. +</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
--- 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="77"> + rev="78"> <section id="directives" name="Directives"> @@ -1005,9 +1005,11 @@ 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_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_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) modules directives: <example> limit_except GET {
--- 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="69"> + rev="70"> <section id="summary"> @@ -820,7 +820,8 @@ This directive is available as part of o <literal>lookup=</literal><value>$variable</value> <literal>zone=</literal><value>name</value>:<value>size</value> [<literal>timeout=</literal><value>time</value>] - [<literal>header</literal>]</syntax> + [<literal>header</literal>] + [<literal>sync</literal>]</syntax> <default/> <context>upstream</context> <appeared-in>1.5.7</appeared-in> @@ -1000,7 +1001,7 @@ non-empty variable is used. <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 8000 sessions on the 64-bit platform. +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. @@ -1011,6 +1012,12 @@ The <literal>header</literal> parameter 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> @@ -1133,6 +1140,16 @@ 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_queue_time"><var>$upstream_queue_time</var></tag-name> +<tag-desc> +keeps time the request spent in the upstream <link id="queue">queue</link> +(1.13.9); +the time is kept in seconds with millisecond resolution. +Times of several responses +are separated by commas and colons like addresses in the +<link id="var_upstream_addr">$upstream_addr</link> variable. +</tag-desc> + <tag-name id="var_upstream_response_length"><var>$upstream_response_length</var> </tag-name> <tag-desc>
--- 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="44" + rev="45" toc="no"> @@ -621,6 +621,11 @@ ngx_stream_upstream_module</link> 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>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/stream/ngx_stream_zone_sync_module.xml @@ -0,0 +1,453 @@ +<?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="1"> + +<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 +<link doc="../http/ngx_http_upstream_module.xml" id="sticky">sticky</link> +sessions. +</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:8090; + + # cluster of 2 nodes: each name resolves to a single IP address + zone_sync_server a.example.com; + zone_sync_server b.example.com; + + } +</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 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>stream</context> +<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_server"> +<syntax><value>address</value> [<literal>resolve</literal>]</syntax> +<default></default> +<context>stream</context> +<context>server</context> + +<para> +Defines the <value>address</value> of a cluster node +and an optional method of resolving it. +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 servers at once. +</para> + +<para> +The "<literal>resolve</literal>" parameter makes nginx to +monitor changes of the IP addresses +that correspond to a domain name of the server +and automatically modifies the configuration +without the need of restarting nginx. +</para> + +<para> +In order for this 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 example.com resolve; + } +} +</example> +</para> + +<para> +<note> +Each cluster node must be specified only once. +If using domain names, ensure they are resolvable to a single IP address. +</note> +<note> +The own address of a node is ignored, thus, there is no need to have different +configurations on different nodes. +</note> +</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_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_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_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> + + +<directive name="zone_sync_buffers"> +<syntax><value>number</value> <value>size</value></syntax> +<default>256 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> + +</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. +By default, the buffer size is equal to one memory page. +This is either 4K or 8K, depending on a platform. +</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_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_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_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> + +</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/ru/docs/http/ngx_http_auth_jwt_module.xml +++ b/xml/ru/docs/http/ngx_http_auth_jwt_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_auth_jwt_module" link="/ru/docs/http/ngx_http_auth_jwt_module.html" lang="ru" - rev="5"> + rev="6"> <section id="summary"> @@ -93,6 +93,7 @@ location / { <context>http</context> <context>server</context> <context>location</context> +<context>limit_except</context> <para> Включает проверку JSON Web Token. @@ -153,8 +154,12 @@ auth_jwt "closed site" token=$cookie_aut Сопоставление имён начинается с верхнего уровня дерева JSON. Для массива переменная хранит список его элементов, разделяемых запятыми. <example> -auth_jwt_claim_set $email info e-mail; -auth_jwt_claim_set $job info "job title"; +location / { + auth_jwt "closed site"; + auth_jwt_key_file conf/keys.json; + auth_jwt_claim_set $email info e-mail; + auth_jwt_claim_set $job info "job title"; +} </example> <note> До версии 1.13.7 можно было указать лишь одно имя, @@ -165,12 +170,32 @@ auth_jwt_claim_set $job info "job title" </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.11</appeared-in> + +<para> +Задаёт максимально допустимое отклонение времени для компенсации +расхождения часов при проверке JWT claims +<link url="https://tools.ietf.org/html/rfc7519#section-4.1.4">exp</link> +и +<link url="https://tools.ietf.org/html/rfc7519#section-4.1.5">nbf</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> в формате
--- 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="77"> + rev="78"> <section id="directives" name="Директивы"> @@ -1002,9 +1002,11 @@ keep-alive, эти буферы освобождаются. Если разрешён метод <literal>GET</literal>, то метод <literal>HEAD</literal> также будет разрешён. Доступ к остальным методам может быть ограничен при помощи директив модулей -<link doc="ngx_http_access_module.xml">ngx_http_access_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_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): <example> limit_except GET { allow 192.168.1.0/32;
--- 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="69"> + rev="70"> <section id="summary"> @@ -827,7 +827,8 @@ server { <literal>lookup=</literal><value>$переменная</value> <literal>zone=</literal><value>имя</value>:<value>размер</value> [<literal>timeout=</literal><value>время</value>] - [<literal>header</literal>]</syntax> + [<literal>header</literal>] + [<literal>sync</literal>]</syntax> <default/> <context>upstream</context> <appeared-in>1.5.7</appeared-in> @@ -1004,7 +1005,7 @@ upstream backend { <para> Сессии хранятся в зоне разделяемой памяти, <value>имя</value> и <value>размер</value> которой задаются параметром <literal>zone</literal>. -Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч сессий +Зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч сессий на 64-битной платформе. Сессии, к которым не было обращений в течение времени, заданного параметром <literal>timeout</literal>, удаляются из зоны. @@ -1016,6 +1017,12 @@ upstream backend { сразу после получения заголовков ответа от сервера группы. </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> @@ -1140,6 +1147,16 @@ upstream backend { последнего сервера. </tag-desc> +<tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> +<tag-desc> +хранит время, проведённое запросом в <link id="queue">очереди</link> +(1.13.9); +время хранится в секундах с точностью до миллисекунд. +Времена нескольких ответов +разделяются запятыми и двоеточиями подобно адресам в переменной +<link id="var_upstream_addr">$upstream_addr</link>. +</tag-desc> + <tag-name id="var_upstream_response_length"><var>$upstream_response_length</var> </tag-name> <tag-desc>
--- 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="44" + rev="45" toc="no"> @@ -626,6 +626,11 @@ ngx_stream_upstream_module</link> 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>
--- a/yaml/nginx_api.yaml +++ b/yaml/nginx_api.yaml @@ -9,7 +9,7 @@ info: key-value pairs management for [http](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) and [stream](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html). -basePath: /api/2 +basePath: /api/3 tags: - name: General Info - name: Processes @@ -26,6 +26,7 @@ tags: - name: Stream Server Zones - name: Stream Upstreams - name: Stream Keyvals + - name: Stream Zone Sync - name: Method GET - name: Method POST - name: Method PATCH @@ -1476,6 +1477,27 @@ paths: 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: | + Zone sync not configured (*ZoneSyncNotConfigured*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' ### ###DEFINITIONS ### @@ -3140,6 +3162,60 @@ definitions: key1: value1 key2: value2 key3: value3 + 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. NginxError: title: Error description: |