About subscription licenses

Overview

We’re updating NGINX Plus to align with F5’s entitlement and visibility policy, bringing benefits like fair and compliant usage, better visibility into license management, and improved customer support.

Starting with NGINX Plus R33, all NGINX Plus instances require a valid JSON Web Token (JWT) license. This license is tied to your subscription (not individual instances) and is used to validate your subscription and automatically send usage reports to F5’s licensing endpoint (product.connect.nginx.com), as required by your subscription agreement. In offline environments, usage reporting is routed through NGINX Instance Manager.

Important changes

NGINX Plus won’t start if:
  • The JWT license is missing or invalid.
  • The JWT license expired over 90 days ago.
NGINX Plus will stop processing traffic if:

  • It can’t submit an initial usage report to F5’s licensing endpoint or NGINX Instance Manager.

    If the first report fails, NGINX Plus immediately stops processing traffic and logs an EMERG message. NGINX Plus will attempt to report every minute, and traffic processing will resume once the initial report succeeds. If you need time to prepare for usage reporting, see Postpone reporting enforcement.

  • It hasn’t submitted a usage report in the last 180 days (for subsequent reports).

    Once the first successful report is made, NGINX Plus saves a record of the transaction. If subsequent reports fail, a 180-day reporting grace period starts, beginning from the last successful report. During this period, NGINX Plus will continue to operate normally, even during reloads, restarts, or reboots. However, if reporting isn’t restored by the end of the grace period, NGINX Plus will stop processing traffic.

What this means for you

When installing or upgrading to NGINX Plus R33 or later, take the following steps:

Add the JWT license

Before you install or upgrade to NGINX Plus R33 or later, make sure to:

Download the license from MyF5

  1. Log in to MyF5.
  2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
  3. Find your NGINX products or services subscription, and select the Subscription ID for details.
  4. Download the JSON Web Token from the subscription page.

Copy the license to each NGINX Plus instance

  1. Copy the license file to /etc/nginx/license.jwt on Linux or /usr/local/etc/nginx/license.jwt on FreeBSD for each NGINX Plus instance.

  2. SELinux: If you’re running a Linux distribution with SELinux enabled, set the file security context type with the following command:

    chcon -t httpd_config_t /etc/nginx/license.jwt

Custom paths:

If you plan to use a custom path for the license file, note that custom paths won’t work until after the R33 upgrade. You’ll need to create a placeholder file at /etc/nginx/license.jwt or /usr/local/etc/nginx/license.jwt on FreeBSD before upgrading.

  1. Before upgrading: Create the placeholder file by running:

    touch /etc/nginx/license.jwt

  2. After upgrading: Update the license_token directive in the NGINX configuration mgmt block to point to your custom path:

    mgmt {
  license_token <custom_path>;
}

Prepare your environment for reporting

To ensure NGINX Plus R33 or later can send usage reports, follow these steps based on your environment:

For internet-connected environments

Allow outbound HTTPS traffic on TCP port 443 to communicate with F5’s licensing endpoint (product.connect.nginx.com). Ensure that the following IP addresses are allowed:

  • 3.135.72.139
  • 3.133.232.50
  • 52.14.85.249

For network-restricted environments

In environments where NGINX Plus instances cannot access the internet, you’ll need NGINX Instance Manager to handle usage reporting.

Configure NGINX Plus to report usage to NGINX Instance Manager

Extra setup for self-signed certificates
If your NGINX Instance Manager environment uses self-signed certificates, see Configure SSL verification for usage reporting with self-signed certificates.

To configure NGINX Plus R33 or 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>;
}
Self-signed certificates
For details on using self-signed certificates, see [Configure SSL verification for usage reporting with self-signed certificates](/nginx-instance-manager/system-configuration/secure-traffic/#configure-ssl-verify).

  1. Reload NGINX:

    nginx -s reload

To send NGINX Plus usage reports to F5, follow the instructions in Submit usage reports to F5 from NGINX Instance Manager.

Postpone reporting enforcement

To give yourself more time to submit the initial usage report, you can postpone reporting by setting enforce_initial_report to off. This change enables a 180-day reporting grace period, during which NGINX Plus will operate normally while still attempting to report.

# Modify this directive to start the 180-day grace period for initial reporting.
mgmt {
  enforce_initial_report off;
}
Important:
After 180 days, if usage reporting still hasn’t been established, NGINX Plus will stop processing traffic.

Understand reported usage metrics

NGINX Plus automatically sends usage data to F5 every hour by default. This data is sent as a POST request and includes details like how much traffic is processed and how long the instance has been running. Here’s an example of the data that’s sent:

{
    "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
}

NGINX Plus

NGINX Plus installation guide

For detailed instructions on installing or upgrading NGINX Plus, visit the NGINX Plus installation guide.

mgmt module and directives

For full details about the mgmt module and its directives, visit the Module ngx_mgmt_module reference guide.

NGINX Instance Manager

The instructions below use the terms “internet-connected” and “network-restricted” to describe how NGINX Instance Manager accesses the internet.

License NGINX Instance Manager

Submit usage reports to F5 from NGINX Instance Manager

NGINX App Protect WAF

For details on installing or upgrading NGINX App Protect WAF, visit the guide for the respective version:

NGINX App Protect DoS

For detailed instructions on installing or upgrading NGINX App Protect DoS, visit the NGINX App Protect DoS installation guide.

Watch instructional videos

Submit usage reports in a connected environment

Submit usage reports in a disconnected environment

Install or upgrade to NGINX Plus R33

Last modified December 9, 2024