<?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>