Mercurial > hg > nginx-site

changeset 3029:27008cb3fb27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>
--- a/xml/ru/docs/index.xml
+++ b/xml/ru/docs/index.xml
@@ -683,6 +683,11 @@ ngx_google_perftools_module</link>
 </listitem>
 
 <listitem>
+<link doc="ngx_mgmt_module.xml">
+ngx_mgmt_module</link> [en]
+</listitem>
+
+<listitem>
 <link doc="ngx_otel_module.xml">
 ngx_otel_module [en]</link>
 </listitem>