Mercurial > hg > nginx-site
view xml/en/docs/ngx_mgmt_module.xml @ 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 | |
children | 6ffde2466d2d |
line wrap: on
line source
<?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>