Mercurial > hg > nginx-site
changeset 2082:fee7627f6a5a
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 11 Dec 2017 12:13:09 +0300 |
parents | f29bd40e9a62 |
children | fb5eef3637a4 |
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_upstream_module.xml xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_keyval_module.xml xml/ru/docs/http/ngx_http_auth_jwt_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/index.xml yaml/nginx_api.yaml |
diffstat | 11 files changed, 726 insertions(+), 109 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/en/GNUmakefile Mon Dec 11 12:13:09 2017 +0300 @@ -106,6 +106,7 @@ 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 \
--- a/xml/en/docs/http/ngx_http_api_module.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/en/docs/http/ngx_http_api_module.xml Mon Dec 11 12:13:09 2017 +0300 @@ -97,24 +97,25 @@ } } </example> -All API requests include a supported API version in the URI. +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/1/ -http://127.0.0.1/api/1/nginx -http://127.0.0.1/api/1/connections -http://127.0.0.1/api/1/http/requests -http://127.0.0.1/api/1/http/server_zones/server_backend -http://127.0.0.1/api/1/http/caches/cache_backend -http://127.0.0.1/api/1/http/upstreams/backend -http://127.0.0.1/api/1/http/upstreams/backend/servers/ -http://127.0.0.1/api/1/http/upstreams/backend/servers/1 -http://127.0.0.1/api/1/http/keyvals/one?key=arg1 -http://127.0.0.1/api/1/stream/ -http://127.0.0.1/api/1/stream/server_zones/server_backend -http://127.0.0.1/api/1/stream/upstreams/ -http://127.0.0.1/api/1/stream/upstreams/backend -http://127.0.0.1/api/1/stream/upstreams/backend/servers/1 +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 </example> </para> @@ -141,24 +142,44 @@ By default, the API is read-only. </para> -<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 and the only API version is “<literal>1</literal>”. +The current API version is “<literal>2</literal>”. </para> <para> The optional “<literal>fields</literal>” argument in the request line specifies which fields of the requested objects will be output: <example> -http://127.0.0.1/api/1/nginx?fields=version,build +http://127.0.0.1/api/2/nginx?fields=version,build </example> </para> </directive> </section> + +<section id="compatibility" name="Compatibility"> + +<para> +<list type="bullet"> + +<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"> @@ -826,22 +847,22 @@ <para>Supported methods:</para> <list type="bullet" compact="yes"> <listitem id="getHttpKeyvalZones"> -<literal>GET</literal> - Return key-value pairs from all keyval zones -<para>Returns key-value pairs for each keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> +<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 keyval zone names are output.</tag-desc> +If the “<literal>fields</literal>” value is empty, then only HTTP keyval zone names are output.</tag-desc> </list> </para> <para> Possible responses: </para> <list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>" objects for all http keyvals </listitem> +<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> </list> </listitem> </list> @@ -855,41 +876,41 @@ <tag-name><literal>httpKeyvalZoneName</literal> (<literal>string</literal>, required)</tag-name> <tag-desc> -The name of a keyval shared memory zone.</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 a keyval zone -<para>Returns key-value pairs stored in a particular keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> +<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 keyval zone.</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">Keyval Shared Memory Zone</link></listitem> +<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>), returns <link id="def_nginx_error">Error</link></listitem> </list> </listitem> <listitem id="postHttpKeyvalZoneData"> -<literal>POST</literal> - Add a key-value pair to the keyval zone -<para>Adds a new key-value pair to the keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the keyval shared memory zone is empty.</para> +<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">Keyval Shared Memory Zone</link>, required)</tag-name> +(<link id="def_nginx_http_keyval_zone">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 keyval shared memory zone is empty.</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.</tag-desc> </list> </para> <para> @@ -913,7 +934,7 @@ Request parameters: <list type="tag"> <tag-name><literal>httpKeyvalZoneKeyValue</literal> -(<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>, required)</tag-name> +(<link id="def_nginx_http_keyval_zone">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> @@ -933,8 +954,8 @@ </list> </listitem> <listitem id="deleteHttpKeyvalZoneData"> -<literal>DELETE</literal> - Empty the keyval zone -<para>Deletes all key-value pairs from the keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> +<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>.</para> <para> Possible responses: </para> @@ -1281,6 +1302,138 @@ </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 are output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>" objects for all stream keyvals </listitem> +<listitem>404 - <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="stream_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>), +<link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="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">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.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>201 - Created</listitem> +<listitem>400 - Key required (<literal>KeyvalFormatError</literal>), +only one key can be added (<literal>KeyvalFormatError</literal>), +nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), +<link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="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 or deletes a key by setting the key value to <literal>null</literal>.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>streamKeyvalZoneKeyValue</literal> +(<link id="def_nginx_stream_keyval_zone">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 - Key required (<literal>KeyvalFormatError</literal>), +only one key can be updated (<literal>KeyvalFormatError</literal>), +nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), +keyval key not found (<literal>KeyvalKeyNotFound</literal>), +<link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>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="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>.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +<listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), +<link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +</list> +</tag-desc> </list> </para> </section> @@ -2268,6 +2421,12 @@ 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> @@ -2279,12 +2438,6 @@ <tag-desc> Hostname of the resolved server. The hostname is assigned automatically and cannot be changed. </tag-desc> -<tag-name> -<literal>drain</literal> (<literal>boolean</literal>) -</tag-name> -<tag-desc> -Puts the HTTP upstream server into the “draining” mode. In this mode, only requests <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</link> to the server will be proxied to it. The parameter cannot be initially set, it can only be changed with the <literal>PATCH</literal> method. -</tag-desc> </list> <para>Example:</para> <example> @@ -2302,8 +2455,8 @@ }</example> </listitem> <listitem id="def_nginx_http_keyval_zone"> -<para>Keyval Shared Memory Zone:</para> -Contents of a keyval shared memory zone.<para>Example:</para> +<para>HTTP Keyval Shared Memory Zone:</para> +Contents of an HTTP keyval shared memory zone.<para>Example:</para> <example> { "key1" : "value1", @@ -2715,6 +2868,16 @@ "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.<para>Example:</para> +<example> +{ + "key1" : "value1", + "key2" : "value2", + "key3" : "value3" +}</example> +</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 Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/en/docs/http/ngx_http_api_module_head.xml Mon Dec 11 12:13:09 2017 +0300 @@ -97,24 +97,25 @@ } } </example> -All API requests include a supported API version in the URI. +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/1/ -http://127.0.0.1/api/1/nginx -http://127.0.0.1/api/1/connections -http://127.0.0.1/api/1/http/requests -http://127.0.0.1/api/1/http/server_zones/server_backend -http://127.0.0.1/api/1/http/caches/cache_backend -http://127.0.0.1/api/1/http/upstreams/backend -http://127.0.0.1/api/1/http/upstreams/backend/servers/ -http://127.0.0.1/api/1/http/upstreams/backend/servers/1 -http://127.0.0.1/api/1/http/keyvals/one?key=arg1 -http://127.0.0.1/api/1/stream/ -http://127.0.0.1/api/1/stream/server_zones/server_backend -http://127.0.0.1/api/1/stream/upstreams/ -http://127.0.0.1/api/1/stream/upstreams/backend -http://127.0.0.1/api/1/stream/upstreams/backend/servers/1 +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 </example> </para> @@ -141,21 +142,41 @@ By default, the API is read-only. </para> -<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 and the only API version is “<literal>1</literal>”. +The current API version is “<literal>2</literal>”. </para> <para> The optional “<literal>fields</literal>” argument in the request line specifies which fields of the requested objects will be output: <example> -http://127.0.0.1/api/1/nginx?fields=version,build +http://127.0.0.1/api/2/nginx?fields=version,build </example> </para> </directive> </section> + +<section id="compatibility" name="Compatibility"> + +<para> +<list type="bullet"> + +<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>
--- a/xml/en/docs/http/ngx_http_auth_jwt_module.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/en/docs/http/ngx_http_auth_jwt_module.xml Mon Dec 11 12:13:09 2017 +0300 @@ -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="3"> + rev="4"> <section id="summary"> @@ -37,6 +37,30 @@ </para> <para> +The module supports the following cryptographic +<link url="https://tools.ietf.org/html/rfc7518#section-3.1">algorithms</link>: + +<list type="bullet"> + +<listitem> +HS256, HS384, HS512 +</listitem> + +<listitem> +RS256, RS384, RS512 +</listitem> + +<listitem> +ES256, ES384, ES512 +</listitem> + +</list> + +Prior to version 1.13.7, +only HS256, RS256, ES256 algorithms were supported. +</para> + +<para> <note> This module is available as part of our <commercial_version>commercial subscription</commercial_version>. @@ -100,28 +124,48 @@ <directive name="auth_jwt_header_set"> -<syntax><value>$variable</value> <value>name</value></syntax> +<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 the given -JOSE header parameter <value>name</value>. +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_claim_set"> -<syntax><value>$variable</value> <value>name</value></syntax> +<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 the given -JWT claim parameter <value>name</value>. +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> +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, +and the result was undefined for arrays. +</note> </para> </directive>
--- a/xml/en/docs/http/ngx_http_upstream_module.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/en/docs/http/ngx_http_upstream_module.xml Mon Dec 11 12:13:09 2017 +0300 @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="65"> + rev="66"> <section id="summary"> @@ -332,6 +332,20 @@ </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>
--- a/xml/en/docs/index.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/en/docs/index.xml Mon Dec 11 12:13:09 2017 +0300 @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="41" + rev="42" toc="no"> @@ -557,6 +557,11 @@ </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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/stream/ngx_stream_keyval_module.xml Mon Dec 11 12:13:09 2017 +0300 @@ -0,0 +1,109 @@ +<?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="1"> + +<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>. +</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=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. +Strings are matched ignoring the case. +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>]</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="ngx_http_api_module.xml" id="stream_keyvals_">API</link>. +</para> + +<para> +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. +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/docs/http/ngx_http_auth_jwt_module.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/ru/docs/http/ngx_http_auth_jwt_module.xml Mon Dec 11 12:13:09 2017 +0300 @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_auth_jwt_module" link="/ru/docs/http/ngx_http_auth_jwt_module.html" lang="ru" - rev="3"> + rev="4"> <section id="summary"> @@ -35,6 +35,30 @@ </para> <para> +Модуль поддерживает следующие криптографические +<link url="https://tools.ietf.org/html/rfc7518#section-3.1">алгоритмы</link>: + +<list type="bullet"> + +<listitem> +HS256, HS384, HS512 +</listitem> + +<listitem> +RS256, RS384, RS512 +</listitem> + +<listitem> +ES256, ES384, ES512 +</listitem> + +</list> + +До версии 1.13.7 +поддерживались только алгоритмы HS256, RS256 и RS256. +</para> + +<para> <note> Модуль доступен как часть <commercial_version>коммерческой подписки</commercial_version>. @@ -98,28 +122,48 @@ <directive name="auth_jwt_header_set"> -<syntax><value>$переменная</value> <value>имя</value></syntax> +<syntax><value>$переменная</value> <value>имя</value> ...</syntax> <default/> <context>http</context> <appeared-in>1.11.10</appeared-in> <para> -Устанавливает <value>переменную</value> в заданное -<value>имя</value> параметра заголовка JOSE. +Устанавливает <value>переменную</value> в параметр заголовка JOSE, +определяемый именами ключей. +Сопоставление имён начинается с верхнего уровня дерева JSON. +Для массива переменная хранит список его элементов, разделяемых запятыми. +<note> +До версии 1.13.7 можно было указать лишь одно имя, +результат для массивов был не определён. +</note> </para> </directive> <directive name="auth_jwt_claim_set"> -<syntax><value>$переменная</value> <value>имя</value></syntax> +<syntax><value>$переменная</value> <value>имя</value> ...</syntax> <default/> <context>http</context> <appeared-in>1.11.10</appeared-in> <para> -Устанавливает <value>переменную</value> в заданное -<value>имя</value> параметра JWT claim. +Устанавливает <value>переменную</value> в параметр JWT claim, +определяемый именами ключей. +Сопоставление имён начинается с верхнего уровня дерева JSON. +Для массива переменная хранит список его элементов, разделяемых запятыми. +<example> +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 можно было указать лишь одно имя, +результат для массивов был не определён. +</note> </para> </directive>
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml Mon Dec 11 12:13:09 2017 +0300 @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_upstream_module" link="/ru/docs/http/ngx_http_upstream_module.html" lang="ru" - rev="65"> + rev="66"> <section id="summary"> @@ -336,6 +336,20 @@ </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>
--- a/xml/ru/docs/index.xml Tue Dec 05 16:54:22 2017 +0300 +++ b/xml/ru/docs/index.xml Mon Dec 11 12:13:09 2017 +0300 @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="41" + rev="42" toc="no"> @@ -562,6 +562,11 @@ </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>
--- a/yaml/nginx_api.yaml Tue Dec 05 16:54:22 2017 +0300 +++ b/yaml/nginx_api.yaml Mon Dec 11 12:13:09 2017 +0300 @@ -1,14 +1,15 @@ swagger: '2.0' info: - version: '1.0' + version: '2.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](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) - pairs management. -basePath: /api/1 + 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 tags: - name: General Info - name: Processes @@ -24,6 +25,7 @@ - name: Stream - name: Stream Server Zones - name: Stream Upstreams + - name: Stream Keyvals - name: Method GET - name: Method POST - name: Method PATCH @@ -729,8 +731,8 @@ tags: - HTTP Keyvals - Method GET - summary: Return key-value pairs from all keyval zones - description: Returns key-value pairs for each keyval shared memory + 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: @@ -740,7 +742,7 @@ in: query type: string description: If the “<literal>fields</literal>” value is empty, - then only keyval zone names are output. + then only HTTP keyval zone names are output. responses: '200': description: Success @@ -750,15 +752,15 @@ parameters: - name: httpKeyvalZoneName in: path - description: The name of a keyval shared memory zone. + 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 a keyval zone - description: Returns key-value pairs stored in a particular keyval shared memory + 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: @@ -767,7 +769,7 @@ - name: key in: query type: string - description: Get a particular key-value pair from the keyval zone. + description: Get a particular key-value pair from the HTTP keyval zone. responses: '200': description: Success @@ -783,11 +785,11 @@ tags: - HTTP Keyvals - Method POST - summary: Add a key-value pair to the keyval zone - description: Adds a new key-value pair to the keyval shared memory + 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 keyval shared memory zone is empty. + if the HTTP keyval shared memory zone is empty. operationId: postHttpKeyvalZoneData produces: - application/json @@ -796,7 +798,7 @@ name: Key-value description: A key-value pair is specified in the JSON format. Several key-value pairs can be entered - if the keyval shared memory zone is empty. + if the HTTP keyval shared memory zone is empty. required: true schema: $ref: '#/definitions/NginxHTTPKeyvalZone' @@ -871,8 +873,8 @@ tags: - HTTP Keyvals - Method DELETE - summary: Empty the keyval zone - description: Deletes all key-value pairs from the keyval shared memory + 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). operationId: deleteHttpKeyvalZoneData responses: @@ -1301,6 +1303,179 @@ 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 are output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxStreamKeyvalZonesMap' + '404': + description: | + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) + 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*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) + 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. + required: true + schema: + $ref: '#/definitions/NginxStreamKeyvalZone' + responses: + '201': + description: Created + '400': + description: | + Key required (*KeyvalFormatError*), + only one key can be added (*KeyvalFormatError*), + nested object or list (*KeyvalFormatError*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Keyval not found (*KeyvalNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' + '409': + description: Key already exists (*KeyvalKeyExists*) + 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 + or deletes a key by setting the key value to <literal>null</literal>. + 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/NginxStreamKeyvalZone' + responses: + '204': + description: Success + '400': + description: | + Key required (*KeyvalFormatError*), + only one key can be updated (*KeyvalFormatError*), + nested object or list (*KeyvalFormatError*) + schema: + $ref: '#/definitions/NginxError' + '404': + description: | + Keyval not found (*KeyvalNotFound*), + keyval key not found (*KeyvalKeyNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) + 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 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). + operationId: deleteStreamKeyvalZoneData + responses: + '204': + description: Success + '404': + description: | + Keyval not found (*KeyvalNotFound*), + [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' ### ###DEFINITIONS ### @@ -2378,6 +2553,11 @@ 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. @@ -2388,14 +2568,6 @@ description: Hostname of the resolved server. The hostname is assigned automatically and cannot be changed. readOnly: true - drain: - type: boolean - description: Puts the HTTP upstream server into the “draining” mode. - In this mode, only requests - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</a> - to the server will be proxied to it. - The parameter cannot be initially set, - it can only be changed with the <code>PATCH</code> method. example: id: 1 server: 10.0.0.1:8089 @@ -2408,9 +2580,9 @@ backup: true down: true NginxHTTPKeyvalZonesMap: - title: Keyval Shared Memory Zones + title: HTTP Keyval Shared Memory Zones description: | - Contents of all keyval shared memory zones. + Contents of all HTTP keyval shared memory zones. type: object additionalProperties: $ref: '#/definitions/NginxHTTPKeyvalZone' @@ -2424,9 +2596,9 @@ arg2: value2 arg3: value3 NginxHTTPKeyvalZone: - title: Keyval Shared Memory Zone + title: HTTP Keyval Shared Memory Zone description: | - Contents of a keyval shared memory zone. + Contents of an HTTP keyval shared memory zone. type: object example: key1: value1 @@ -2943,6 +3115,31 @@ 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. + type: object + example: + key1: value1 + key2: value2 + key3: value3 NginxError: title: Error description: |