Mercurial > hg > nginx-site
changeset 3029:27008cb3fb27
Updated docs for the upcoming NGINX Plus release.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 19 Dec 2023 12:58:01 +0000 |
parents | 55f8ce8a8cb0 |
children | cd1d5312e47c |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_upstream_module.xml xml/en/docs/index.xml xml/en/docs/ngx_mgmt_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/index.xml |
diffstat | 6 files changed, 456 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -130,6 +130,7 @@ REFS = \ stream/ngx_stream_zone_sync_module \ stream/stream_processing \ ngx_google_perftools_module \ + ngx_mgmt_module \ ngx_otel_module \ dev/development_guide \ njs/index \
--- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_module.xml @@ -1349,6 +1349,25 @@ as for the variables that start with the Only the header fields from the response of the last server are saved. </tag-desc> +<tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name> +<tag-desc> +keeps the name of last selected upstream server (1.25.3); +allows passing it +<link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">through SNI</link>: +<example> +proxy_ssl_server_name on; +proxy_ssl_name $upstream_last_server_name; +</example> + +<para> +<note> +This variable is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</tag-desc> + <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> <tag-desc> keeps time the request spent in the upstream <link id="queue">queue</link>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -677,6 +677,11 @@ ngx_google_perftools_module</link> </listitem> <listitem> +<link doc="ngx_mgmt_module.xml"> +ngx_mgmt_module</link> +</listitem> + +<listitem> <link doc="ngx_otel_module.xml"> ngx_otel_module</link> </listitem>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/ngx_mgmt_module.xml @@ -0,0 +1,407 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../dtd/module.dtd"> + +<module name="Module ngx_mgmt_module" + link="/en/docs/ngx_mgmt_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_mgmt_module</literal> module enables reporting of +current nginx installation to +<link url="https://docs.nginx.com/nginx-management-suite/about/">NGINX +Management Suite Instance Manager</link> (1.25.3). +By default, nginx sends usage info +to the Instance Manager located at <literal>nginx-mgmt.local</literal> +every 30 minutes using the SSL connection. +The system resolver is used unless +a <link id="resolver">custom resolver</link> is configured +and is invoked only once when the +configuration is <link doc="beginners_guide.xml" id="control">loaded</link>. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +mgmt { + usage_report endpoint=nginx-mgmt.local interval=30m; + resolver DNS_IP; + + uuid_file /var/lib/nginx/nginx.id; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers DEFAULT; + + ssl_certificate client_cert.pem; + ssl_certificate_key client_cert.key; + + # configure server certificate verification + # to validate the authenticity of NMS + ssl_trusted_certificate trusted_ca_cert.crt; + ssl_verify on; + ssl_verify_depth 2; +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="connect_timeout"> +<syntax><value>time</value></syntax> +<default>15s</default> +<context>mgmt</context> + +<para> +Defines a timeout for establishing a connection with the Instance Manager. +</para> + +</directive> + + +<directive name="mgmt"> +<syntax block="yes"/> +<default/> +<context>main</context> + +<para> +Provides the configuration file context +in which the management server directives are specified. +</para> + +</directive> + + +<directive name="read_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>mgmt</context> + +<para> +Defines a timeout for reading a response from the Instance Manager. +The timeout is set only between two successive read operations, +not for the transmission of the whole response. +If the Instance Manager does not transmit anything within this time, +the connection is closed. +</para> + +</directive> + + +<directive name="resolver"> +<syntax> + <value>address</value> ... + [<literal>valid</literal>=<value>time</value>] + [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>zone</value>]</syntax> +<default/> +<context>mgmt</context> + +<para> +Configures name servers used to resolve names of the Instance Manager +into addresses, for example: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +The address can be specified as a domain name or IP address, +with an optional port. +If port is not specified, the port 53 is used. +Name servers are queried in a round-robin fashion. +</para> + +<para id="resolver_ipv6"> +By default, nginx will look up both IPv4 and IPv6 addresses while resolving. +If looking up of IPv4 or IPv6 addresses is not desired, +the <literal>ipv4=off</literal> or +the <literal>ipv6=off</literal> parameter can be specified. +</para> + +<para id="resolver_valid"> +By default, nginx caches answers using the TTL value of a response. +An optional <literal>valid</literal> parameter allows overriding it: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +<note> +To prevent DNS spoofing, it is recommended +configuring DNS servers in a properly secured trusted local network. +</note> +</para> + +<para id="resolver_status_zone"> +The optional <literal>status_zone</literal> parameter +enables +<link doc="ngx_http_api_module.xml" id="resolvers_">collection</link> +of DNS server statistics of requests and responses +in the specified <value>zone</value>. +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>mgmt</context> + +<para> +Sets a timeout for name resolution. +</para> + +</directive> + + +<directive name="send_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>mgmt</context> + +<para> +Sets a timeout for transmitting a request to the Instance Manager. +The timeout is set only between two successive write operations, +not for the transmission of the whole request. +If the Instance Manager does not receive anything within this time, +the connection is closed. +</para> + +</directive> + + +<directive name="ssl"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>mgmt</context> + +<para> +Enables the HTTPS protocol for all +connections to the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>mgmt</context> + +<para> +Specifies a <value>file</value> with the certificate in the PEM format +used for authentication to the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_certificate_key"> +<syntax><value>file</value></syntax> +<default/> +<context>mgmt</context> + +<para> +Specifies a <value>file</value> with the secret key in the PEM format +used for authentication to the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_ciphers"> +<syntax><value>ciphers</value></syntax> +<default>DEFAULT</default> +<context>mgmt</context> + +<para> +Specifies the enabled ciphers for requests to the Instance Manager. +The ciphers are specified in the format understood by the OpenSSL library. +</para> + +<para> +The full list can be viewed using the +“<command>openssl ciphers</command>” command. +</para> + +</directive> + + +<directive name="ssl_crl"> +<syntax><value>file</value></syntax> +<default/> +<context>mgmt</context> + +<para> +Specifies a <value>file</value> with revoked certificates (CRL) +in the PEM format used to <link id="ssl_verify">verify</link> +the certificate of the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_name"> +<syntax><value>name</value></syntax> +<default>ssl_name host</default> +<context>mgmt</context> + +<para> +Allows overriding the server name used to +<link id="ssl_verify">verify</link> +the certificate of the Instance Manager and to be +<link id="ssl_server_name">passed through SNI</link> +when establishing a connection with the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_password_file"> +<syntax><value>file</value></syntax> +<default/> +<context>mgmt</context> + +<para> +Specifies a <value>file</value> with passphrases for +<link id="ssl_certificate_key">secret keys</link> +where each passphrase is specified on a separate line. +Passphrases are tried in turn when loading the key. +</para> + +</directive> + + +<directive name="ssl_protocols"> +<syntax> + [<literal>SSLv2</literal>] + [<literal>SSLv3</literal>] + [<literal>TLSv1</literal>] + [<literal>TLSv1.1</literal>] + [<literal>TLSv1.2</literal>] + [<literal>TLSv1.3</literal>]</syntax> +<default>TLSv1 TLSv1.1 TLSv1.2 TLSv1.3</default> +<context>mgmt</context> + +<para> +Enables the specified protocols for requests to the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_server_name"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>mgmt</context> + +<para> +Enables or disables passing of the server name through +<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS +Server Name Indication extension</link> (SNI, RFC 6066) +when establishing a connection with the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_trusted_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>mgmt</context> + +<para> +Specifies a <value>file</value> with trusted CA certificates in the PEM format +used to <link id="ssl_verify">verify</link> +the certificate of the Instance Manager. +</para> + +</directive> + + +<directive name="ssl_verify"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>mgmt</context> + +<para> +Enables or disables verification of the Instance Manager certificate. +</para> + +</directive> + + +<directive name="ssl_verify_depth"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>mgmt</context> + +<para> +Sets the verification depth in the Instance Manager certificates chain. +</para> + +</directive> + + +<directive name="usage_report"> +<syntax> [<literal>endpoint</literal>=<value>address</value>] + [<literal>interval</literal>=<value>time</value>]</syntax> +<default/> +<context>mgmt</context> + +<para> +Sets the <value>address</value> and <value>port</value> for IP, +or the <value>path</value> for a UNIX-domain socket on which +the Instance Manager is installed, +by default <literal>nginx-mgmt.local</literal>. +The <literal>interval</literal> sets an interval between reports +to the Instance Manager, by default 30m. +</para> + +</directive> + + +<directive name="uuid_file"> +<syntax><value>file</value></syntax> +<default>logs/uuid</default> +<context>mgmt</context> + +<para> +Specifies a <value>file</value> that keeps the ID of nginx instance. +</para> + +<para> +Examples: +<example> +state /var/lib/nginx/nginx.id; # path for Linux +state /var/db/nginx/nginx.id; # path for FreeBSD +</example> +</para> + +<para> +Changing the file content directly should be avoided. +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml @@ -1360,6 +1360,25 @@ upstream backend { последнего сервера. </tag-desc> +<tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name> +<tag-desc> +хранит имя последнего выбранного сервера группы (1.25.3); +позволяет передать его +<link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">через SNI</link>: +<example> +proxy_ssl_server_name on; +proxy_ssl_name $upstream_last_server_name; +</example> + +<para> +<note> +Эта переменная доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</tag-desc> + <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> <tag-desc> хранит время, проведённое запросом в <link id="queue">очереди</link>