Tutorial: Configure NGINX Usage Reporting

NGINX Plus R31 introduces a simpler and more efficient way to report NGINX Plus usage. Native integration of usage reporting eliminates the need for a separate NGINX Agent, making the reporting process seamless and hassle-free for customers in F5's Flex Consumption Program (FCP), and for non-FCP customers on a term subscription. With this functionality built directly into NGINX Plus, instances can communicate necessary usage information to the NGINX Instance Manager periodically, without any performance impact. This feature is available for virtual machines and NGINX Ingress Controllers, but this blog focuses on NGINX Plus instances — you can find a guide on reporting the NGINX Ingress Controller to the NGINX Instance Manager here.

By simplifying setup, offering customization options, and providing fallback methods, we aim to make the required usage reporting an efficient and adaptable process for customers to implement and maintain compliance with FCP. For customers not yet on R31 or not planning to upgrade, alternative methods to enable usage reporting are available, either by installing the NGINX Agent or configuring HTTP health checks.

Note: To report NGINX Plus usage, you must install NGINX Instance Manager on a dedicated host. Refer to the installation guide to learn about different methods of installation.

There are three possible ways you can choose from to report NGINX Plus instances to F5.

• NGINX Plus R31 users — Configuring native NGINX usage reporting
• R31 or pre-R31 users — Installing NGINX Agent
• Pre-R31 users — Configuring HTTP health check for NGINX Plus

Let's explore them one by one:

Configure Native NGINX Usage Reporting

Upon installation, NGINX Plus establishes an automated connection to the NGINX Instance Manager via the default DNS entry "nginx-mgmt.local". By default, every 30 minutes, NGINX Plus communicates with the Instance Manager and sends the usage information. If you need to change the Instance Manager DNS entry or alter the default connection interval to suit your needs better, add the mgmt{} block to your NGINX configuration. Additionally, it comes with other default directives, such as the UUID file, mTLS, DNS resolver, usage interval and usage_report endpoint. For a full list of customizable directives, refer to the comprehensive mgmtmodule documentation. With the ngx_mgmt_module, you can easily customize the directives, offering greater flexibility and convenience.

The following sections explain how to configure this feature for your environment.

Configure NGINX Plus

1. It is advisable to use mTLS to enhance the security of your system. You can achieve this by generating a certificate, key, and CA key certificate for both the NGINX Plus instance and NGINX Instance Manager. For more information on how to generate keys, click here.
2. Specify the path to the client certificate and private key file inside the management block of the configure file nginx.conf.

   		
      mgmt {
             ssl_protocols TLSv1.2 TLSv1.3;
             ssl_ciphers DEFAULT;
             ssl_certificate          /home/ubuntu/agent.crt;
             ssl_certificate_key      /home/ubuntu/agent.key
          }
   

3. For a secure and reliable authentication process, specify the path to the CA chain to validate the authenticity of the certificates.

   
      mgmt {
             ssl_trusted_certificate  /home/ubuntu/ca.pem;
             ssl_verify               on;
             ssl_verify_depth         2;
          }
   

4. For custom DNS resolvers, specify the resolver address in the mgmt{}block using the resolver directive.

   
      mgmt {
             resolver 3.X.X.X;
          }
   

5. To configure a custom FQDN for NGINX Instance Manager, specify the FQDN in the usage_report directive. Then, add an A record to your local DNS that associates the hostname with the NGINX Instance Manager IP address.

   
      mgmt {
             resolver 3.X.X.X;
             usage_report endpoint=nms.local interval=15m;
          }
   

Example NGINX Plus configuration:

  mgmt {
         usage_report endpoint=nms.local interval=30m;
         resolver 3.X.X.X;
         ssl_protocols TLSv1.2 TLSv1.3;
         ssl_ciphers DEFAULT;
         ssl_certificate          /home/ubuntu/agent.crt;
         ssl_certificate_key      /home/ubuntu/agent.key;

         ssl_trusted_certificate  /home/ubuntu/ca.pem;
         ssl_verify               on;
         ssl_verify_depth         2;
     }

Save the NGINX configuration and reload NGINX Plus.

sudo nginx -s reload

Configure NGINX Instance Manager

Add the SSL certificate in /etc/nginx/conf.d/nms-HTTP.conf inside the server block. Click here to learn how to configure an SSL certificate in the NGINX Management Suite server.

server {
    listen 443 ssl http2;
    root /var/www/nms;
    server_name _;
    ssl_protocols       TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_certificate         /etc/nms/certs/server.crt;
    ssl_certificate_key     /etc/nms/certs/server.key;
    ssl_client_certificate  /etc/nms/certs/ca.pem;
    ssl_verify_client on;
 }

To view NGINX Plus usage, log in to NGINX Management Suite on your browser and navigate to the NGINX Instance Manager module. Then, select the NGINX Plus tab located at the bottom left of the page.

Watch this video tutorial with step-by-step instructions:

Error Log Messages

Here is a list of error messages to troubleshoot in NGINX Plus instance when you are unable to see usage data in the NGINX Instance Manager: Here are some examples of the error messages:

• Dynamic resolver failures: Failure to resolve DNS resolver.

  2024/04/02 04:02:10 [error] 574079#574079: recv() failed (111: Connection refused) while resolving, resolver: 3.17.128.165:53
  2024/04/02 04:02:35 [warn] 574079#574079: usage report: nginx-mgmt.locals could not be resolved (110: Operation timed out)
  

• System resolver failures: Failure to resolve the NGINX Instance Manager hostname

  2024/04/02 13:20:44 [info] 103888#0: usage report: host not found in resolver "nginx-mgmt.local"
  

• SSL connection failures: Not able to verify or expired SSL certificate.

  2024/04/02 13:13:50 [warn] 103877#0: usage report: peer SSL connection failed
  

• Peer communication failures: Failure to reach NGINX Instance Manager.

  2024/04/02 13:15:25 [warn] 103877#0: usage report: peer connection failed (-1: Unknown error)
  2024/04/02 13:23:32 [warn] 103877#0: usage report: failed (server returned: 404 Not Found)
  2024/04/02 19:53:45 [warn] 4648#4648: usage report: connection timed out
  

Install NGINX Agent

If you haven't moved to R31 yet or don't intend to do so soon, you can still report your NGINX Plus instances to the NGINX Instance Manager. You can achieve this by installing the NGINX Agent in your environment. Once the installation is complete, you can establish a connection with the Instance Manager and start transmitting usage data. To install the NGINX Agent, follow the instructions provided in this link.

To view NGINX Plus usage, log in to NGINX Management Suite on your browser and navigate to the NGINX Instance Manager module. Then, select the NGINX Plus tab located at the bottom left of the page.

Watch this video tutorial with step-by-step instructions:

Configure HTTP Health Check for NGINX Plus

If you are not planning to install the NGINX Agent or upgrade to R31, you can still report your NGINX Plus instances. This can be achieved by configuring an HTTP health check through the NGINX configuration file. However, you must manually update the NGINX Plus configuration file to utilize this option. This method can be time-consuming and cumbersome, particularly if your environment has multiple instances. Therefore, it is advisable to consider these factors before choosing this option.

Configure NGINX Plus

1. Open the NGINX Plus configuration and insert the code within the http {} block:

   
      keyval_zone zone=uuid:32K state=/var/lib/nginx/state/instance_uuid.json;
      keyval 1 $nginx_uuid zone=uuid;
      upstream receiver {
       zone receiver 64k;
   
       # REQUIRED: Update NMS_FQDN with NGINX Management Suite IP Address or hostname.
       # If configuring with hostname, please ensure to uncomment the resolver
       # directive below and define a DNS server that can resolve the hostname.
       server NMS_FQDN:443;
   
       # OPTIONAL: Update DNS_UP with DNS server IP address that can resolve
       # the hostname defined above.
       #resolver DNS_IP;
      }  
   
   map CERT $repo_crt {
       # OPTIONAL: Location of client certificate
         default /home/ubuntu/agent.crt;
      }  
   
   map KEY $repo_key {
       # OPTIONAL: Location of client certificate private key
         default /home/ubuntu/agent.key; 
      }
   
   
    server {
       location @ngx_usage_https {
           # OPTIONAL: Configure scheme (http|https) here
           proxy_pass https://receiver;
   
           # REQUIRED: If using NGINX APP PROTECT (NAP) on this instance, set nap=active on the following line:
   proxy_set_header Nginx-Usage "Version=$nginx_version;Hostname=$hostname;uuid=$nginx_uuid;nap=active";	 
   
           health_check uri=/api/nginx-usage interval=1800s;       # DO NOT MODIFY
           proxy_ssl_certificate     $repo_crt;                    # DO NOT MODIFY
           proxy_ssl_certificate_key $repo_key;                    # DO NOT MODIFY
       }
   
       location @self {
           health_check uri=/_uuid interval=1d;
           proxy_pass http://self;
       }
   
       location = /_uuid {
           if ($nginx_uuid !~ .) {
               set $nginx_uuid $request_id;
           }
           return 204;
       }
   
       listen unix:/tmp/ngx_usage.sock;
     }
   
    upstream self {
       zone self 64k;
       server unix:/tmp/ngx_usage.sock;
    }
   

2. Update the NMS FQDN with your Instance Manager hostname or IP address. If you are using private DNS, uncomment and update your DNS IP address.
3. To ensure the security of HTTP traffic to the NGINX Instance Manager, it's essential to specify the locations of the SSL certificate and key in the map CERT and map KEY blocks.

Save the changes and reload NGINX.

sudo nginx -s reload

To view NGINX Plus usage, log in to NGINX Management Suite on your browser and navigate to the NGINX Instance Manager module. Then, select the NGINX Plus tab at the bottom left of the page.

Watch this video tutorial with step-by-step instructions:

Conclusion

We are committed to meeting you where you are and helping you streamline and automate usage reporting with ease. That's why we're providing multiple options for reporting flexibility. The recently released NGINX Plus R31 update makes it even simpler and more efficient to report monthly usage data on NGINX Plus instances — without impacting performance, while ensuring compliance with F5's requirements.