Report usage data to F5

Overview

In environments where NGINX Instance Manager has internet access but NGINX Plus doesn’t, NGINX Plus sends usage data to NGINX Instance Manager. NGINX Instance Manager will automatically send the usage reports to F5 for verification, or you can choose to send them manually.

If usage reporting fails, NGINX Plus stops accepting new connections. There’s an exception for previously reported instances — refer to handling outages for more details.

See the steps below to configure NGINX Plus to report usage data to NGINX Instance Manager and how to submit the report to F5 for verification.

For network-restricted environments:
If your deployment of NGINX Instance Manager doesn’t allow internet access, follow the steps in Report usage data in network-restricted environments to report usage data to F5.

Before you begin

Before submitting usage data to F5, first ensure that the appropriate network ports are open for NGINX Instance Manager to report to F5, and then configure NGINX Plus to report telemetry data to NGINX Instance Manager.

Configure network ports for reporting usage data

To allow NGINX Instance Manager to report usage data to F5, make sure port 443 is open for these URLs:

  • https://product.apis.f5.com/
  • https://product-s.apis.f5.com/ee

Configure NGINX Plus to report usage data to NGINX Instance Manager

To configure NGINX Plus (R33 and later) to report usage data to NGINX Instance Manger:

  1. Open port 443 for NGINX Instance Manager.

  2. On each NGINX Plus instance, update the usage_report directive in the mgmt block of the NGINX configuration (/etc/nginx/nginx.conf) to point to your NGINX Instance Manager host:

    mgmt {
      usage_report endpoint=<NGINX-INSTANCE-MANAGER-FQDN>;
    }
    
  3. Reload NGINX:

    nginx -s reload
    

Submit usage report to F5

Automatic reporting

When you add your JSON Web Token (JWT) to NGINX Instance Manager, usage reporting is enabled by default.

NGINX Instance Manager will automatically report subscription entitlement and usage data to F5 if internet access is available.

Manual reporting

Usage reporting requirement:
You need to report usage to F5 regularly. If usage isn’t reported for 180 days, NGINX Plus will stop accepting new connections. For more details about the usage reporting process, see About subscription licenses.

If you prefer submitting usage reports to F5 manually, follow these steps:

  1. Log in to the NGINX Instance Manager web interface (https://<NIM-FQDN>/ui/).
  2. Select the Settings (gear) icon.
  3. On the Licenses > Overview page, turn off Enable Continuous Connection.
  4. To manually submit a usage report, select Send Usage to F5.

Reported usage metrics

See also: ngx_mgmt_module reference guide
For complete details about the mgmt module and directives, visit the Module ngx_mgmt_module reference guide.

NGINX Plus reports the following usage metrics every hour by default.

Only operational metrics are reported — no personally identifiable information (PII) or sensitive customer data is transmitted.

The ssl_verify directive, which verifies the usage reporting endpoint’s certificate, is set to on by default. This ensures communication is secure and protects against untrusted endpoints.

We recommend keeping this setting enabled.

For detailed steps on configuring ssl_verify for NGINX Plus instances in network-restricted environments, see Configure SSL verification for usage reporting with self-signed certificates.

The following JSON example shows the NGINX Plus usage data sent to F5 in a POST request, every hour by default.

{
    "version": "<nginx_version>",
    "uuid": "<nginx_uuid>",
    "nap": "<active/inactive>", // status of NGINX App Protect
    "http": {
        "client": {
            "received": 0, // bytes received
            "sent": 0, // bytes sent
            "requests": 0 // number of HTTP requests processed
        },
        "upstream": {
            "received": 0, // bytes received
            "sent": 0 // bytes sent
        }
    },
    "stream": {
        "client": {
            "received": 0, // bytes received
            "sent": 0 // bytes sent
        },
        "upstream": {
            "received": 0, // bytes received
            "sent": 0 // bytes sent
        }
    },
    "workers": 0, // number of worker processes running
    "uptime": 0, // number of seconds the instance has been running
    "reloads": 0, // number of times the instance has been reloaded
    "start_time": "epoch", // start time of data collection for the report
    "end_time": "epoch" // end time of data collection for the report
}

Handling outages

If a temporary outage occurs, either on your side or F5’s:

  • As long as your instance has successfully reported at least once, you’ll have a 180-day grace period to resolve the issue.
    During this grace period, NGINX Plus will continue running without any restrictions.

    For more information about the reporting process, see About subscription licenses.


Last modified November 13, 2024