=encoding utf-8

=head1 NAME

ngx_mgmt_module - Module ngx_mgmt_module




=head1



The C<ngx_mgmt_module> module enables
NGINX Plus license verification and usage reporting.
This is mandatory for each NGINX Plus instance since 1.27.2 (
L<NGINX Plus R33|https://docs.nginx.com/nginx/releases/#r33>).





A JWT license file named C<license.jwt>
should be located at
C<E<sol>etcE<sol>nginxE<sol>> for Linux or
C<E<sol>usrE<sol>localE<sol>etcE<sol>nginxE<sol>> for FreeBSD
or at the path specified by the L</license_token> directive.
The license file is available from
L<MyF5|https://my.f5.com>.





Usage report is sent directly or via proxy
to F5 licensing endpoint
every hour using the
secure connection.
Optionally, in network-restricted environments
reporting can be configured to
L<F5 NGINX
Instance Manager|https://docs.nginx.com/nginx-management-suite/about/> from which the report can be sent
to F5 licensing endpoint.





By default, if the initial usage report
is not received by F5 licensing endpoint, nginx will stop processing traffic.





Automatic license renewal is supported since 1.29.0
(L<NGINX Plus R35|https://docs.nginx.com/nginx/releases/#r35>)
for instances that report directly to the F5 licensing endpoint.
On renewal, NGINX downloads the updated JWT from F5 licensing endpoint
and applies it without
configuration L<reload|switches>.
The updated license is stored
in the state_path directory.






B<NOTE>

This module is available as part of our
commercial subscription.





=head1 Example Configuration




    
    mgmt {
        # in case if custom path is required
        license_token custom/file/path/license.jwt;
    
        # in case of reporting to NGINX Instance Manager
        usage_report endpoint=NIM_FQDN;
    }






=head1 Directives

=head2 mgmt


mgmt { B<...> }



B<context:> I<main>





Provides the configuration file context in which
usage reporting and license management directives
are specified.







=head2 enforce_initial_report


B<syntax:> enforce_initial_report I<C<on> E<verbar> C<off>>


B<default:> I<on>


B<context:> I<mgmt>



This directive appeared in version 1.27.2.





Enables or disables the 180-day grace period
for sending the initial usage report.





The initial usage report is sent immediately
upon nginx first start after installation.
By default, if the initial report is not received by F5 licensing endpoint,
nginx stops processing traffic until the report is successfully delivered.
Setting the directive value to C<off> enables
the 180-day grace period during which
the initial usage report must be received by F5 licensing endpoint.







=head2 license_token


B<syntax:> license_token I<I<C<file>>>


B<default:> I<license.jwt>


B<context:> I<mgmt>



This directive appeared in version 1.27.2.





Specifies a JWT license I<C<file>>.
By default, the I<C<license.jwt>> file is expected to be at
C<E<sol>etcE<sol>nginxE<sol>> for Linux or at
C<E<sol>usrE<sol>localE<sol>etcE<sol>nginxE<sol>> for FreeBSD.







=head2 proxy


B<syntax:> proxy I<I<C<host>>:I<C<port>>>



B<context:> I<mgmt>



This directive appeared in version 1.27.4.





Sets the HTTP CONNECT proxy
used for sending the usage report.







=head2 proxy_username


B<syntax:> proxy_username I<I<C<string>>>



B<context:> I<mgmt>



This directive appeared in version 1.27.4.





Sets the user name used for authentication on
the proxy.







=head2 proxy_password


B<syntax:> proxy_password I<I<C<string>>>



B<context:> I<mgmt>



This directive appeared in version 1.27.4.





Sets the password used for authentication on
the proxy.





The password is sent unencrypted by default.
If the proxy supports TLS, the connection to the proxy can be
protected with the L<stream|ngx_stream_proxy_module>
module:

    
    mgmt {
        proxy          127.0.0.1:8080;
        proxy_username <name>;
        proxy_password <password>;
    }
    
    stream {
        server {
            listen 127.0.0.1:8080;
            
            proxy_ssl                     on;
            proxy_ssl_verify              on;
            proxy_ssl_trusted_certificate <proxy_ca_file>;
    
            proxy_pass <proxy_host>:<proxy_port>;
        }
    }









=head2 resolver


B<syntax:> resolver I<
    I<C<address>> ...
    [C<valid>=I<C<time>>]
    [C<ipv4>=C<on>E<verbar>C<off>]
    [C<ipv6>=C<on>E<verbar>C<off>]
    [C<status_zone>=I<C<zone>>]>



B<context:> I<mgmt>





Configures name servers used to resolve usage reporting endpoint name.
By default, the system resolver is used.





See L<ngx_http_core_module> for details.







=head2 ssl_crl


B<syntax:> ssl_crl I<I<C<file>>>



B<context:> I<mgmt>





Specifies a I<C<file>> with revoked certificates (CRL)
in the PEM format used to verify
the certificate of the usage reporting endpoint.
When using intermediate certificates, their CRLs should be
specified in the same file.







=head2 ssl_trusted_certificate


B<syntax:> ssl_trusted_certificate I<I<C<file>>>


B<default:> I<system CA bundle>


B<context:> I<mgmt>





Specifies a I<C<file>> with trusted CA certificates in the PEM format
used to verify
the certificate of the usage reporting endpoint.







=head2 ssl_verify


B<syntax:> ssl_verify I<C<on> E<verbar> C<off>>


B<default:> I<on>


B<context:> I<mgmt>





Enables or disables verification of the usage reporting endpoint certificate.






B<NOTE>

Before 1.27.2, the default value was C<off>.








=head2 state_path


B<syntax:> state_path I<I<C<path>>>



B<context:> I<mgmt>



This directive appeared in version 1.27.2.





Defines a directory for storing state files
(C<nginx-mgmt-*>)
created by the C<ngx_mgmt_module> module.
The default directory
for Linux is C<E<sol>varE<sol>libE<sol>nginxE<sol>state>,
for FreeBSD is C<E<sol>varE<sol>dbE<sol>nginxE<sol>state>.







=head2 usage_report


B<syntax:> usage_report I< [C<endpoint>=I<C<address>>]
         [C<interval>=I<C<time>>]>


B<default:> I<endpoint=product.connect.nginx.com interval=1h>


B<context:> I<mgmt>





Sets the I<C<address>> and I<C<port>>
of the usage reporting endpoint.
The C<interval> parameter sets an interval between
two consecutive reports.

B<NOTE>

Before 1.27.2, the default values were
C<nginx-mgmt.local> and
C<30m>.








