Report usage data to F5 (connected)

For disconnected environments, see Report usage data to F5 (disconnected).

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 will stop processing traffic. 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.

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

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 to NGINX Instance Manager

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

1. Allow NGINX Plus instances to connect to NGINX Instance Manager over HTTPS (TCP 443).

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

   nginx

   Copy

   mgmt {
    usage_report endpoint=<NGINX-INSTANCE-MANAGER-FQDN>;
   }

3. Reload NGINX:

   Copy

   systemctl reload nginx

If you’re using self-signed certificates with NGINX Instance Manager,
see Configure SSL verification for self-signed certificates for additional steps.

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 processing traffic. 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.

What’s reported

By default, NGINX Plus sends usage data to F5 every hour in a POST request. The report includes information such as traffic volume, runtime, and instance activity.

Here’s an example of a usage report:

{
    "version": "<nginx_version>",
    "uuid": "<nginx_uuid>",
    "nap": "<active/inactive>", // NGINX App Protect status
    "http": {
        "client": {
            "received": 0, // bytes received
            "sent": 0,     // bytes sent
            "requests": 0  // 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,        // seconds the instance has been running
    "reloads": 0,       // number of reloads
    "start_time": "epoch", // start of data collection
    "end_time": "epoch"    // end of data collection
}

Error log location and monitoring

Monitor the NGINX error log, usually at /var/log/nginx/error.log, to identify subscription issues early. The log records problems such as failed usage reports or licenses that are about to expire. Check it regularly to avoid downtime and stay compliant.

You can also use the license API endpoint to check license status programmatically. For details, see the ngx_http_api_module docs.

Examples of log entries:

• Failed usage reports:

  text

  Copy

  [error] 36387#36387: server returned 500 for <fqdn>:<port> during usage report
  [error] 36528#36528: <fqdn>:<port> could not be resolved (host not found) during usage report
  [error] 36619#36619: connect() failed (111: Connection refused) for <fqdn>:<port> during usage report
  [error] 38888#88: server returned 401 for <ip_address>:443 during usage report

• License nearing expiration:

  Copy

  [warn] license will expire in 14 days

• License expired:

  text

  Copy

  [alert] license expiry; grace period will end in 89 days
  [emerg] license expired

Important

NGINX Plus stops processing traffic if the license has been expired for more than 90 days.