# HG changeset patch # User Yaroslav Zhuravlev # Date 1632307643 -10800 # Node ID 9dd8c203a54a27a63703171838353d3eaf281c87 # Parent c56adb7148a47384919370c35f921934231052a3 Updated docs for the upcoming NGINX Plus release. diff -r c56adb7148a4 -r 9dd8c203a54a xml/en/docs/http/ngx_http_api_module.xml --- a/xml/en/docs/http/ngx_http_api_module.xml Tue Jul 13 13:44:05 2021 +0100 +++ b/xml/en/docs/http/ngx_http_api_module.xml Wed Sep 22 13:47:23 2021 +0300 @@ -110,21 +110,21 @@ a supported API version in the URI. Examples of API requests with this configuration: -http://127.0.0.1/api/6/ -http://127.0.0.1/api/6/nginx -http://127.0.0.1/api/6/connections -http://127.0.0.1/api/6/http/requests -http://127.0.0.1/api/6/http/server_zones/server_backend -http://127.0.0.1/api/6/http/caches/cache_backend -http://127.0.0.1/api/6/http/upstreams/backend -http://127.0.0.1/api/6/http/upstreams/backend/servers/ -http://127.0.0.1/api/6/http/upstreams/backend/servers/1 -http://127.0.0.1/api/6/http/keyvals/one?key=arg1 -http://127.0.0.1/api/6/stream/ -http://127.0.0.1/api/6/stream/server_zones/server_backend -http://127.0.0.1/api/6/stream/upstreams/ -http://127.0.0.1/api/6/stream/upstreams/backend -http://127.0.0.1/api/6/stream/upstreams/backend/servers/1 +http://127.0.0.1/api/7/ +http://127.0.0.1/api/7/nginx +http://127.0.0.1/api/7/connections +http://127.0.0.1/api/7/http/requests +http://127.0.0.1/api/7/http/server_zones/server_backend +http://127.0.0.1/api/7/http/caches/cache_backend +http://127.0.0.1/api/7/http/upstreams/backend +http://127.0.0.1/api/7/http/upstreams/backend/servers/ +http://127.0.0.1/api/7/http/upstreams/backend/servers/1 +http://127.0.0.1/api/7/http/keyvals/one?key=arg1 +http://127.0.0.1/api/7/stream/ +http://127.0.0.1/api/7/stream/server_zones/server_backend +http://127.0.0.1/api/7/stream/upstreams/ +http://127.0.0.1/api/7/stream/upstreams/backend +http://127.0.0.1/api/7/stream/upstreams/backend/servers/1 @@ -155,14 +155,14 @@ 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 “6”. +The current API version is “7”. The optional “fields” argument in the request line specifies which fields of the requested objects will be output: -http://127.0.0.1/api/6/nginx?fields=version,build +http://127.0.0.1/api/7/nginx?fields=version,build @@ -208,6 +208,15 @@ +The codes data +in responses for each HTTP +upstream, +server zone, and +location zone +were added in version 7. + + + The /stream/limit_conns/ data were added in version 6. @@ -2284,7 +2293,7 @@ responses -The total number of responses sent to clients and the number of responses with status codes “1xx”, “2xx”, “3xx”, “4xx”, and “5xx”. +The total number of responses sent to clients, the number of responses with status codes “1xx”, “2xx”, “3xx”, “4xx”, and “5xx”, and the number of responses per each status code. 1xx (integer) @@ -2316,6 +2325,18 @@ The number of responses with “5xx” status codes. +codes + +The number of responses per each status code. + +codeNumber (integer) + + +The number of responses with this particular status code. + + + + total (integer) @@ -2353,6 +2374,12 @@ "3xx" : 4522, "4xx" : 907, "5xx" : 266, + "codes" : { + "200" : 699482, + "301" : 4522, + "404" : 907, + "503" : 266 + }, "total" : 705177 }, "discarded" : 1513, @@ -2372,7 +2399,7 @@ responses -The total number of responses sent to clients and the number of responses with status codes “1xx”, “2xx”, “3xx”, “4xx”, and “5xx”. +The total number of responses sent to clients, the number of responses with status codes “1xx”, “2xx”, “3xx”, “4xx”, and “5xx”, and the number of responses per each status code. 1xx (integer) @@ -2404,6 +2431,18 @@ The number of responses with “5xx” status codes. +codes + +The number of responses per each status code. + +codeNumber (integer) + + +The number of responses with this particular status code. + + + + total (integer) @@ -2440,6 +2479,12 @@ "3xx" : 4522, "4xx" : 907, "5xx" : 266, + "codes" : { + "200" : 112674, + "301" : 4522, + "404" : 2504, + "503" : 266 + }, "total" : 705177 }, "discarded" : 1513, @@ -2847,6 +2892,18 @@ The number of responses with “5xx” status codes. +codes + +The number of responses per each status code. + +codeNumber (integer) + + +The number of responses with this particular status code. + + + + total (integer) @@ -3006,6 +3063,11 @@ "3xx" : 0, "4xx" : 915, "5xx" : 6, + "codes" : { + "200" : 666310, + "404" : 915, + "503" : 6 + }, "total" : 667231 }, "sent" : 251946292, @@ -3038,6 +3100,8 @@ "3xx" : 0, "4xx" : 0, "5xx" : 0, + "codes" : { + }, "total" : 0 }, "sent" : 0, diff -r c56adb7148a4 -r 9dd8c203a54a xml/en/docs/http/ngx_http_api_module_head.xml --- a/xml/en/docs/http/ngx_http_api_module_head.xml Tue Jul 13 13:44:05 2021 +0100 +++ b/xml/en/docs/http/ngx_http_api_module_head.xml Wed Sep 22 13:47:23 2021 +0300 @@ -110,21 +110,21 @@ a supported API version in the URI. Examples of API requests with this configuration: -http://127.0.0.1/api/6/ -http://127.0.0.1/api/6/nginx -http://127.0.0.1/api/6/connections -http://127.0.0.1/api/6/http/requests -http://127.0.0.1/api/6/http/server_zones/server_backend -http://127.0.0.1/api/6/http/caches/cache_backend -http://127.0.0.1/api/6/http/upstreams/backend -http://127.0.0.1/api/6/http/upstreams/backend/servers/ -http://127.0.0.1/api/6/http/upstreams/backend/servers/1 -http://127.0.0.1/api/6/http/keyvals/one?key=arg1 -http://127.0.0.1/api/6/stream/ -http://127.0.0.1/api/6/stream/server_zones/server_backend -http://127.0.0.1/api/6/stream/upstreams/ -http://127.0.0.1/api/6/stream/upstreams/backend -http://127.0.0.1/api/6/stream/upstreams/backend/servers/1 +http://127.0.0.1/api/7/ +http://127.0.0.1/api/7/nginx +http://127.0.0.1/api/7/connections +http://127.0.0.1/api/7/http/requests +http://127.0.0.1/api/7/http/server_zones/server_backend +http://127.0.0.1/api/7/http/caches/cache_backend +http://127.0.0.1/api/7/http/upstreams/backend +http://127.0.0.1/api/7/http/upstreams/backend/servers/ +http://127.0.0.1/api/7/http/upstreams/backend/servers/1 +http://127.0.0.1/api/7/http/keyvals/one?key=arg1 +http://127.0.0.1/api/7/stream/ +http://127.0.0.1/api/7/stream/server_zones/server_backend +http://127.0.0.1/api/7/stream/upstreams/ +http://127.0.0.1/api/7/stream/upstreams/backend +http://127.0.0.1/api/7/stream/upstreams/backend/servers/1 @@ -155,14 +155,14 @@ 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 “6”. +The current API version is “7”. The optional “fields” argument in the request line specifies which fields of the requested objects will be output: -http://127.0.0.1/api/6/nginx?fields=version,build +http://127.0.0.1/api/7/nginx?fields=version,build @@ -208,6 +208,15 @@ +The codes data +in responses for each HTTP +upstream, +server zone, and +location zone +were added in version 7. + + + The /stream/limit_conns/ data were added in version 6. diff -r c56adb7148a4 -r 9dd8c203a54a xml/en/docs/http/ngx_http_auth_jwt_module.xml --- a/xml/en/docs/http/ngx_http_auth_jwt_module.xml Tue Jul 13 13:44:05 2021 +0100 +++ b/xml/en/docs/http/ngx_http_auth_jwt_module.xml Wed Sep 22 13:47:23 2021 +0300 @@ -9,7 +9,7 @@ + rev="12">
@@ -18,11 +18,10 @@ implements client authorization by validating the provided JSON Web Token (JWT) using the specified keys. -JWT claims can be encoded in a -JSON Web Signature (JWS) -or +The module supports +JSON Web Signature (JWS), JSON Web Encryption (JWE) -(1.19.7) structure. +(1.19.7), and Nested JWT (1.21.0). The module can be used for OpenID Connect authentication. @@ -114,6 +113,10 @@ dir—direct use of a shared symmetric key as the content encryption key + +RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0) + + @@ -241,6 +244,18 @@ Parameter value can contain variables. + +Several auth_jwt_key_file directives +can be specified on the same level (1.21.1): + +auth_jwt_key_file conf/keys.json; +auth_jwt_key_file conf/key.jwk; + +If at least one of the specified keys cannot be loaded or processed, +nginx will return the + error. + + @@ -279,6 +294,15 @@ } } +Several auth_jwt_key_request directives +can be specified on the same level (1.21.1): + +auth_jwt_key_request /jwks_uri; +auth_jwt_key_request /jwks2_uri; + +If at least one of the specified keys cannot be loaded or processed, +nginx will return the + error. @@ -305,7 +329,9 @@ -signed | encrypted +signed | + encrypted | + nested signed http server @@ -315,8 +341,37 @@ Specifies which type of JSON Web Token to expect: -JWS (signed) or -JWE (encrypted). +JWS (signed), +JWE (encrypted), +or signed and then encrypted +Nested JWT (nested) (1.21.0). + + + + + + +value ... + +http +server +location +limit_except +1.21.2 + + +Defines additional conditions for JWT validation. +The value can contain text, variables, and their combination. +The authentication will succeed only +if all the values are not empty and are not equal to “0”. + +map $jwt_claim_iss $valid_jwt_iss { + "good" 1; +} +... + +auth_jwt_require $valid_jwt_iss; + @@ -357,6 +412,15 @@ +$jwt_payload + +returns the decrypted top-level payload +of nested +or encrypted tokens (1.21.2). +For nested tokens returns the enclosed JWS token. +For encrypted tokens returns JSON with claims. + + diff -r c56adb7148a4 -r 9dd8c203a54a xml/en/docs/stream/ngx_stream_upstream_hc_module.xml --- a/xml/en/docs/stream/ngx_stream_upstream_hc_module.xml Tue Jul 13 13:44:05 2021 +0100 +++ b/xml/en/docs/stream/ngx_stream_upstream_hc_module.xml Wed Sep 22 13:47:23 2021 +0300 @@ -9,7 +9,7 @@ + rev="6">
@@ -154,14 +154,23 @@ -mandatory +mandatory [persistent] + 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. + + + +The persistent parameter (1.21.1) +sets the initial “up” state for a server after reload +if the server was considered healthy before reload. + + diff -r c56adb7148a4 -r 9dd8c203a54a xml/ru/docs/http/ngx_http_auth_jwt_module.xml --- a/xml/ru/docs/http/ngx_http_auth_jwt_module.xml Tue Jul 13 13:44:05 2021 +0100 +++ b/xml/ru/docs/http/ngx_http_auth_jwt_module.xml Wed Sep 22 13:47:23 2021 +0300 @@ -9,7 +9,7 @@ + rev="12">
@@ -18,11 +18,10 @@ предоставляет возможность авторизации клиента с проверкой предоставляемого JSON Web Token (JWT) при помощи указанных ключей. -JWT claims могут быть зашифрованы в структуре -JSON Web Signature (JWS) -или +Модуль поддерживает +JSON Web Signature (JWS), JSON Web Encryption (JWE) -(1.19.7). +(1.19.7) и Nested JWT (1.21.0). Модуль может использоваться для настройки аутентификации OpenID Connect. @@ -98,7 +97,7 @@ -Алгоритмы JWE для управления ключом (1.19.7): +Алгоритмы JWE для управления ключом (1.19.9): @@ -114,6 +113,10 @@ в качестве ключа шифрования содержимого + +RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0) + + @@ -241,6 +244,18 @@ В значении параметра допустимо использование переменных. + +На одном уровне может быть указано +несколько директив auth_jwt_key_file (1.21.1): + +auth_jwt_key_file conf/keys.json; +auth_jwt_key_file conf/key.jwk; + +Если хотя бы один из указанных ключей не может быть загружен или обработан, +nginx вернёт ошибку +. + + @@ -279,6 +294,15 @@ } } +На одном уровне может быть указано +несколько директив auth_jwt_key_request (1.21.1): + +auth_jwt_key_request /jwks_uri; +auth_jwt_key_request /jwks2_uri; + +Если хотя бы один из указанных ключей не может быть загружен или обработан, +nginx вернёт ошибку +. @@ -302,8 +326,11 @@ + -signed | encrypted +signed | + encrypted | + nested signed http server @@ -313,8 +340,37 @@ Задаёт ожидаемый тип JSON Web Token: -JWS (signed) или -JWE (encrypted). +JWS (signed), +JWE (encrypted) +или подписанный и затем зашифрованный +Nested JWT (nested) (1.21.0). + + + + + + +значение ... + +http +server +location +limit_except +1.21.2 + + +Задаёт дополнительные условия для проверки JWT. +В качестве значения можно использовать текст, переменные и их комбинации. +Для успешной аутентификации необходимо, чтобы +значение всех строковых параметров было непустое или не равно “0”. + +map $jwt_claim_iss $valid_jwt_iss { + "good" 1; +} +... + +auth_jwt_require $valid_jwt_iss; + @@ -355,6 +411,15 @@ +$jwt_payload + +возвращает расшифрованную полезную нагрузку (payload) верхнего уровня +для вложенных +или зашифрованных токенов (1.21.2). +Для вложенных токенов возвращает внутренний JWS токен. +Для зашифрованных токенов возвращает JSON с claims. + + diff -r c56adb7148a4 -r 9dd8c203a54a xml/ru/docs/stream/ngx_stream_upstream_hc_module.xml --- a/xml/ru/docs/stream/ngx_stream_upstream_hc_module.xml Tue Jul 13 13:44:05 2021 +0100 +++ b/xml/ru/docs/stream/ngx_stream_upstream_hc_module.xml Wed Sep 22 13:47:23 2021 +0300 @@ -9,7 +9,7 @@ + rev="6">
@@ -154,14 +154,22 @@ -mandatory +mandatory [persistent] + устанавливает исходное состояние “checking” для сервера до завершения первой проверки работоспособности (1.11.7). На серверы в состоянии “checking” клиентские соединения передаваться не будут. Если параметр не указан, то исходно сервер будет считаться работоспособным. + + + +Параметр persistent (1.21.1) +устанавливает исходное состояние “up” для сервера после перезагрузки nginx +в случае, если до перезагрузки сервер считался работоспособным. + diff -r c56adb7148a4 -r 9dd8c203a54a yaml/nginx_api.yaml --- a/yaml/nginx_api.yaml Tue Jul 13 13:44:05 2021 +0100 +++ b/yaml/nginx_api.yaml Wed Sep 22 13:47:23 2021 +0300 @@ -1,6 +1,6 @@ swagger: '2.0' info: - version: '6.0' + version: '7.0' title: NGINX Plus REST API description: NGINX Plus REST [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) @@ -9,7 +9,7 @@ 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/6 +basePath: /api/7 tags: - name: General Info - name: Processes @@ -2384,6 +2384,11 @@ 3xx: 4614 4xx: 934 5xx: 1535 + codes: + 200: 727270 + 301: 4614 + 404: 930 + 503: 1535 total: 734373 discarded: 2020 received: 180157219 @@ -2397,6 +2402,11 @@ 3xx: 45383 4xx: 2504 5xx: 4419 + codes: + 200: 112674 + 301: 45383 + 404: 2504 + 503: 4419 total: 164980 discarded: 20326 received: 51575327 @@ -2413,10 +2423,11 @@ type: integer description: The total number of client requests received from clients. responses: - description: The total number of responses sent to clients and the + description: The total number of responses sent to clients, the number of responses with status codes “1xx”, “2xx”, “3xx”, - “4xx”, and “5xx”. + “4xx”, and “5xx”, and + the number of responses per each status code. type: object readOnly: true properties: @@ -2440,6 +2451,15 @@ type: integer description: The number of responses with “5xx” 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. @@ -2463,6 +2483,11 @@ 3xx: 4522 4xx: 907 5xx: 266 + codes: + 200: 699482 + 301: 4522 + 404: 907 + 503: 266 total: 705177 discarded: 1513 received: 172711587 @@ -2484,6 +2509,11 @@ 3xx: 4614 4xx: 934 5xx: 1535 + codes: + 200: 727290 + 301: 4614 + 404: 934 + 503: 1535 total: 734373 discarded: 2020 received: 180157219 @@ -2496,6 +2526,11 @@ 3xx: 45383 4xx: 2504 5xx: 4419 + codes: + 200: 112674 + 301: 45383 + 404: 2504 + 503: 4419 total: 164980 discarded: 20326 received: 51575327 @@ -2508,10 +2543,11 @@ type: integer description: The total number of client requests received from clients. responses: - description: The total number of responses sent to clients and the + description: The total number of responses sent to clients, the number of responses with status codes “1xx”, “2xx”, “3xx”, - “4xx”, and “5xx”. + “4xx”, and “5xx”, and + the number of responses per each status code. type: object readOnly: true properties: @@ -2535,6 +2571,15 @@ type: integer description: The number of responses with “5xx” 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. @@ -2557,6 +2602,11 @@ 3xx: 4522 4xx: 907 5xx: 266 + codes: + 200: 112674 + 301: 4522 + 404: 2504 + 503: 266 total: 705177 discarded: 1513 received: 172711587 @@ -2860,6 +2910,10 @@ 3xx: 0 4xx: 915 5xx: 6 + codes: + 200: 666310 + 404: 915 + 503: 6 total: 667231 sent: 251946292 received: 19222475454 @@ -2887,6 +2941,7 @@ 3xx: 0 4xx: 0 5xx: 0 + codes: {} total: 0 sent: 0 received: 0 @@ -2921,6 +2976,10 @@ 3xx: 0 4xx: 915 5xx: 6 + codes: + 200: 666310 + 404: 915 + 503: 6 total: 667231 sent: 251946292 received: 19222475454 @@ -2948,6 +3007,7 @@ 3xx: 0 4xx: 0 5xx: 0 + codes: {} total: 0 sent: 0 received: 0 @@ -3021,6 +3081,10 @@ 3xx: 0 4xx: 915 5xx: 6 + codes: + 200: 666310 + 404: 915 + 503: 6 total: 667231 sent: 251946292 received: 19222475454 @@ -3049,6 +3113,7 @@ 3xx: 0 4xx: 0 5xx: 0 + codes: {} total: 0 sent: 0 received: 0 @@ -3157,6 +3222,15 @@ type: integer description: The number of responses with “5xx” 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.