Module ngx_mgmt_module

The ngx_mgmt_module module enables reporting of current nginx installation to NGINX Management Suite Instance Manager (1.25.3). By default, nginx sends usage info to the Instance Manager located at nginx-mgmt.local every 30 minutes using the SSL connection. The system resolver is used unless a custom resolver is configured and is invoked only once when the configuration is loaded.

This module is available as part of our commercial subscription.

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;
}

connect_timeout 15s;

Defines a timeout for establishing a connection with the Instance Manager.

Provides the configuration file context in which the management server directives are specified.

read_timeout 60s;

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.

Configures name servers used to resolve names of the Instance Manager into addresses, for example:

resolver 127.0.0.1 [::1]:5353;

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.

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 ipv4=off or the ipv6=off parameter can be specified.

By default, nginx caches answers using the TTL value of a response. An optional valid parameter allows overriding it:

resolver 127.0.0.1 [::1]:5353 valid=30s;

To prevent DNS spoofing, it is recommended configuring DNS servers in a properly secured trusted local network.

The optional status_zone parameter enables collection of DNS server statistics of requests and responses in the specified zone.

resolver_timeout 30s;

Sets a timeout for name resolution.

send_timeout 60s;

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.

ssl on;

Enables the HTTPS protocol for all connections to the Instance Manager.

Specifies a file with the certificate in the PEM format used for authentication to the Instance Manager.

Specifies a file with the secret key in the PEM format used for authentication to the Instance Manager.

ssl_ciphers DEFAULT;

Specifies the enabled ciphers for requests to the Instance Manager. The ciphers are specified in the format understood by the OpenSSL library.

The full list can be viewed using the “openssl ciphers” command.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificate of the Instance Manager.

ssl_name ssl_name host;

Allows overriding the server name used to verify the certificate of the Instance Manager and to be passed through SNI when establishing a connection with the Instance Manager.

Specifies a file with passphrases for secret keys where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

Enables the specified protocols for requests to the Instance Manager.

ssl_server_name off;

Enables or disables passing of the server name through TLS Server Name Indication extension (SNI, RFC 6066) when establishing a connection with the Instance Manager.

Specifies a file with trusted CA certificates in the PEM format used to verify the certificate of the Instance Manager.

ssl_verify off;

Enables or disables verification of the Instance Manager certificate.

ssl_verify_depth 1;

Sets the verification depth in the Instance Manager certificates chain.

Sets the address and port for IP, or the path for a UNIX-domain socket on which the Instance Manager is installed, by default nginx-mgmt.local. The interval sets an interval between reports to the Instance Manager, by default 30m.

uuid_file logs/uuid;

Specifies a file that keeps the ID of nginx instance.

Examples:

uuid_file /var/lib/nginx/nginx.id; # path for Linux
uuid_file /var/db/nginx/nginx.id;  # path for FreeBSD

Changing the file content directly should be avoided.