Reporting NGINX Plus Installation Counts for Compliance

Tracking your NGINX Plus installations is straightforward with NGINX Management Suite Instance Manager. If you’re enrolled in a commercial program like the F5 Flex Consumption Program, you’ll need to regularly report this data to F5.

Overview

Start by installing NGINX Instance Manager on a dedicated host. Then, configure your NGINX Plus systems to report back to Instance Manager. Once connected, you can easily view and report on your NGINX Plus inventory using the NGINX Management Suite REST API or web interface. You can send these reports to your F5 contact as needed.

Tip for Automated Reporting
To set up automatic reporting, add your JWT-based license to NGINX Management Suite. This license can be downloaded from MyF5 if needed.

Prerequisites

Install NGINX Instance Manager on a dedicated host

Note:
A separate license for NGINX Management Suite is not required to track your NGINX product usage.

To start reporting on your NGINX Plus installations, you’ll first need to install NGINX Instance Manager on a dedicated host. You can choose between two installation options: either on a virtual machine or bare metal server, or by deploying on a Kubernetes cluster. Instructions for both methods are below:

Virtual Machine or Bare Metal

Kubernetes

View your NGINX Plus and NGINX App Protect Inventory

After you’ve installed NGINX Instance Manager, the next step involves configuring your NGINX Plus data plane to report back. This can be done in two ways. First, you can install NGINX Agent on each instance. Alternatively, for an agentless approach, you can set up HTTP Health Checks, which don’t require additional installations. Both methods enable your instances to communicate with Instance Manager.

Set up instance reporting for NGINX Plus

Select the tab that matches your preferred method for setting up reporting:

  • Install NGINX Agent
  • Configure HTTP Health Check for NGINX Plus without NGINX Agent

When you install NGINX Agent on an NGINX Plus instance, it will establish a connection with Instance Manager and begin transmitting usage data.

  1. To install NGINX Agent, follow these instructions.

  2. (Optional) If you’re using Instance Manager primarily for tracking NGINX Plus usage, you can optimize performance by modifying the NGINX Agent configuration. Add this line to /etc/nginx-agent/nginx-agent.conf:

    features: registration,dataplane-status
    
    Note:
    If you upgrade to the full version of Instance Manager later, remove the features: registration,dataplane-status line from the configuration. This change will enable NGINX Agent to collect a broader range of metrics and manage configurations remotely.

You can track NGINX Plus instances using an HTTP Health Check without installing NGINX Agent. This involves updating the NGINX Plus configuration file. Follow these steps:

  1. Open the NGINX Plus configuration file (/etc/nginx/conf.d) and insert the following code within the http {} block:

    ### F5 / NGINX Required Configuration Code ###
    ### Insert the following into the http {} block of your NGINX configuration file ###
    
    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 /etc/ssl/nginx/nginx-client.crt;
    }
    
    map KEY $repo_key {
        # OPTIONAL: Location of client certificate private key
        #default /etc/ssl/nginx/nginx-client.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=inactive"; 
    
            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;
    }
    
    ### End of F5 / NGINX Required Configuration Code ###
    
  2. Modify the configuration to suit your specific NGINX Instance Manager installation:

    • Update the NMS_FQDN variable in the upstream receiver block with your Instance Manager hostname or IP address. If using a private DNS, uncomment and update the resolver with your DNS IP Address.
    • If your Instance Manager server requires client SSL certification, specify the locations of the SSL certificate and key in the map CERT and map KEY blocks. For more details, see Securing HTTP Traffic to Upstream Servers.
    • If you’re using NGINX App Protect, change nap=inactive to nap=active in the location @ngx_usage_https block.
    • Optionally, you can limit access to the /api/nginx-usage location on your NGINX Instance Manager server based on client network address. For guidance on how to do this, refer to Module ngx_http_access_module.
  3. Save the changes.

Important:
If you install NGINX Agent later, remove this configuration to prevent double-counting instances.

Reporting your NGINX Plus inventory to F5

Follow these steps to view and export the list of NGINX Plus instances that have successfully registered with Instance Manager:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select NGINX Plus.
  3. To download a list of your NGINX Plus instances, select Export. Note that the export will include only the instances on the current page. You can then forward this list to your F5 representative.

View your NGINX Ingress Controller instances and nodes

You can set up your Kubernetes-based NGINX Plus products, including NGINX Ingress Controller and Connectivity Stack for Kubernetes, to report usage data to NGINX Instance Manager.

Set up usage reporting for NGINX Ingress Controller

Follow the instructions in the Enabling Usage Reporting guide to enable usage reporting for NGINX Ingress Controller.

Reporting your NGINX Ingress Controller clusters to F5

To report your NGINX Ingress Controller clusters to F5, follow these steps:

  1. Run the following command in your terminal to get a list of NGINX Ingress Controller instances and nodes in your cluster. Remember to replace <NMS_FQDN> with the fully-qualified domain name of your NGINX Management Suite host:

    curl -X GET --url "https://<NMS_FQDN>/api/platform/v1/k8s-usage"
    
  2. Once you have the list of instances and nodes, send it to your F5 representative.