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

If you have multiple subscriptions, you’ll also have multiple JWT licenses. You can assign each NGINX Plus instance to the license you prefer. NGINX combines usage reporting across all licensed instances.

This feature is available in NGINX Instance Manager 2.20 and later.

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:

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.

Deploy the JWT license

After you download the JWT license, you can deploy it to your NGINX Plus instances using either of the following methods:

  • Use a Config Sync Group if you’re managing instances with the NGINX One Console (recommended)
  • Copy the license manually to each instance

Each method ensures your NGINX Plus instances have access to the required license file.

If you’re using the NGINX One Console, the easiest way to manage your JWT license is with a Config Sync Group. This method lets you:

  • Avoid manual file copying
  • Keep your fleet consistent
  • Automatically apply updates to new NGINX Plus instances

To deploy the JWT license with a Config Sync Group:

  1. In the NGINX One Console, go to Manage > Config Sync Groups, then select your group.

    If you haven’t created a Config Sync Group yet, see Manage Config Sync Groups for setup instructions.

  2. Select the Configuration tab, then choose Edit Configuration.

  3. Select Add File, then choose New Configuration File.

  4. In the File name field, enter:

    • On Linux: /etc/nginx/license.jwt
    • On FreeBSD: /usr/local/etc/nginx/license.jwt
      The name must be exact.

  5. Paste the contents of your JWT license file into the editor.

  6. Select Next to preview the diff, then Save and Publish to apply the update.

Your JWT license now syncs to all NGINX Plus instances in the group.

When your subscription renews and a new JWT license is issued, update the file in the Config Sync Group to apply the change across your fleet.

New instances added to the group automatically inherit the license.

If you’re using NGINX Instance Manager If you’re using NGINX Instance Manager instead of the NGINX One Console, the equivalent feature is called an instance group. You can manage your JWT license in the same way by adding or updating the file in the instance group. For details, see Manage instance groups.

Copy the license manually

If you’re not using the NGINX One Console, copy the JWT license file to each NGINX Plus instance manually.

  1. Copy the license file to:

    • /etc/nginx/license.jwt on Linux
    • /usr/local/etc/nginx/license.jwt on FreeBSD

  2. Reload NGINX:

    systemctl reload nginx

If SELinux is enabled:

Set the correct file context so NGINX can read the license:

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

  1. 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

  2. (Optional, R34 and later) If your company enforces a strict outbound traffic policy, you can use an outbound proxy for establishing an end-to-end tunnel to the F5 licensing endpoint. On each NGINX Plus instance, update the proxy directive in the mgmt block of the NGINX configuration (/etc/nginx/nginx.conf) to point to the company’s outbound proxy server:

    mgmt {
    proxy          PROXY_ADDR:PORT; #can be http or https
    proxy_username USER;            #optional
    proxy_password PASS;            #optional
}

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

To configure NGINX Plus R33 or later to report usage data to NGINX Instance Manager:

  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>;
}
    Extra steps for self-signed certificates If you use self-signed certificates in your NGINX Instance Manager environment, follow the steps in Configure SSL verification for usage reporting with self-signed certificates.

  3. Reload NGINX:

    systemctl reload nginx

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.

Error log location and monitoring

Monitor the NGINX error log, typically located at /var/log/nginx/error.log, for subscription-related issues — such as failed usage reports or approaching license expirations — to catch problems early and keep your subscription compliant.


Examples of subscription-related log entries include:

  • Failure to upload usage reports:

    [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 approaching expiration:

    [warn] license will expire in 14 days

  • License expiration:

    [alert] license expiry; grace period will end in 89 days
[emerg] license expired
    Important When a license expires, NGINX Plus stops 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