Getting started

NGINX Plus R33 and later require a valid JSON Web Token (JWT) license.

The license:

• Is tied to your subscription (not to individual instances).
• Checks your subscription and reports usage either to F5’s licensing endpoint (product.connect.nginx.com) or, in disconnected environments, through NGINX Instance Manager.

If you have multiple subscriptions

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.

Combining licenses with NGINX Instance Manager requires version 2.20 or later. {{</ call-out >}}

Important changes

NGINX Plus requires a valid license and regular usage reporting to run. The sections below explain the requirements and what happens if they aren’t met.

{{< call-out class=“note” title=“Licensing workflows” >}} For flowcharts that show how these requirements work in practice, see NGINX Plus licensing workflows.

Starting NGINX Plus

Starting NGINX Plus requires a valid, unexpired license. If the license has expired, NGINX Plus can still start during the 90-day grace period.

Processing traffic

Processing traffic requires:

• A successful initial usage report. If the F5 licensing endpoint does not receive the initial report, NGINX Plus will not process traffic until the report is received. To add a grace period, see Postpone reporting enforcement.
• Ongoing usage reports, at least every 180 days. If reporting stops, NGINX Plus keeps running but stops processing traffic once 180 days have passed without a report. To avoid disruption, send usage reports regularly instead of waiting until the 180-day cutoff.

Download your license from MyF5

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

Deploy the license

After you download the JWT license, deploy it to your NGINX Plus instances in one of two ways:

• Use a group sync feature (recommended):
  • In the NGINX One Console, use a Config Sync Group to keep instances consistent, avoid manual copying, and apply license updates automatically.
  • In NGINX Instance Manager, use an instance group, which works the same way as a Config Sync Group.
• Copy the license manually: Place the license file on each NGINX Plus instance yourself.

Choose the option that fits your environment:

{{< details summary=“Deploy with a group sync feature (recommended)” >}}

Deploy with a group sync feature

Before you begin

Before you deploy with a Config Sync Group, you need to create one in the NGINX One Console.
If you haven’t created a group yet, see Manage Config Sync Groups for instructions.

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

2. Open the Configuration tab and select Edit Configuration.

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

4. In the File name field, enter the exact path:

   • On Linux: /etc/nginx/license.jwt
   • On FreeBSD: /usr/local/etc/nginx/license.jwt

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

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

Note

In NGINX Instance Manager, instance groups provide the same sync functionality as Config Sync Groups in the NGINX One Console.
See Manage instance groups for setup instructions.

{{< /details >}}

{{< details summary=“Deploy manually” >}}

Deploy manually

Copy the JWT license file to each NGINX Plus instance.

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

3. If SELinux is enabled, set the correct file context so NGINX can read the license:

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

{{< /details >}}

{{< details summary=“Use custom paths” >}}

Custom paths

If you’re upgrading from NGINX Plus R32 or earlier to R33 or later and plan to use a custom path for the license file, note that the custom path isn’t recognized until after the upgrade. You must first create a placeholder file at /etc/nginx/license.jwt (or /usr/local/etc/nginx/license.jwt on FreeBSD).

1. Before upgrading: Create the placeholder file:

   touch /etc/nginx/license.jwt

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

   mgmt {
     license_token <custom_path>;
   }

{{< /details >}}

Prepare your environment for reporting

NGINX Plus R33 and later must send usage reports.

Choose the setup steps that match your environment:

{{< details summary=“Configure reporting in internet-connected environments” >}}

Internet-connected environments

In connected environments, NGINX Plus sends usage reports directly to the F5 licensing endpoint.

Allow the necessary outbound traffic so reports can reach F5.

1. Allow NGINX Plus instances to connect to the F5 licensing endpoint (product.connect.nginx.com) over HTTPS (TCP 443). Allow the following IP addresses:

   • 3.135.72.139
   • 3.133.232.50
   • 52.14.85.249

2. (R34 and later) If your company restricts outbound traffic, configure NGINX Plus instances to connect through an outbound proxy. Update the proxy directive in the mgmt block of (/etc/nginx/nginx.conf) to point to your proxy server:

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

{{< /details >}}

{{< details summary=“Configure reporting in network-restricted environments” >}}

Network-restricted environments

In environments without internet access, NGINX Plus sends usage reports to NGINX Instance Manager. NGINX Instance Manager collects the reports and later forwards them to F5.

To configure NGINX Plus to send usage reports 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:

   mgmt {
    usage_report endpoint=;
   }

3. Reload NGINX:

   systemctl reload nginx

If you’re using self-signed certificates

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

Forwarding reports in network-restricted environments

For instructions on forwarding usage reports from NGINX Instance Manager to F5, see Report usage data to F5 (disconnected).

{{< /details >}}

Postpone reporting enforcement

By default, NGINX Plus requires a successful initial usage report before it continues processing traffic.

If you need to delay this requirement, you can set enforce_initial_report to off. This starts a 180-day grace period where NGINX Plus keeps running while it continues trying to report.

# Modify this directive to start the 180-day grace period for initial reporting.
mgmt {
  enforce_initial_report off;
}

[Important]

After 180 days without usage reporting, NGINX Plus stops processing traffic.

Update the license

How you update the JWT license depends on your NGINX Plus release and environment:

• In R35 and later, the license is updated automatically when the subscription renews (if reporting is configured).
• In earlier releases or disconnected environments, you need to update the license manually.

[FCP subscription renewals require manual JWT updates]

If your subscription was renewed under the Flexible Consumption Program (FCP), automatic JWT renewal isn’t supported. You must apply updated JWT licenses manually at each renewal to make sure NGINX Plus continues to work.

Check your subscription details, including subscription type, on MyF5.

For more information, see K000160880: JWT license auto-renewal may fail in NGINX Plus.

{{< details summary=“Update the license automatically (R35 and later)” >}}

Automatic update (R35 and later)

Starting in NGINX Plus R35, JWT licenses are updated automatically for instances that report directly to the F5 licensing endpoint. NGINX Plus downloads the new license and applies it without requiring a reload or restart.

Here’s how the automatic update works:

• Beginning 30 days before the current license expires, NGINX Plus notifies the licensing endpoint as part of usage reporting.
• The licensing endpoint checks for a renewed subscription with F5.
• After the subscription is renewed, the licensing endpoint sends the updated JWT license to the instance.
• NGINX Plus applies the updated license automatically and stores it as nginx-mgmt-license in the state_path directory.
• The original JWT license file at /etc/nginx/license.jwt (or a custom path set by license_token) is not modified. You can replace the original file manually if needed, but this does not affect NGINX Plus operation.
• This process also applies if the license has already expired but is still within the 90-day grace period.
• Traffic continues without interruption.

[Important]

Automatic updates only work if:

• License reporting is configured, and
• At least one usage report has already been sent successfully.

If these conditions aren’t met, you must update the JWT license manually.

{{< /details >}}

{{< details summary=“Update the license manually (all releases)” >}}

Manual update (all releases)

If automatic updates are not available (for example, in disconnected environments), update the license manually:

1. Download the new JWT license from MyF5.
2. Deploy the JWT license to your NGINX Plus instances.

Note for internet-connected environments

If you manually updated your JWT license after subscription renewal, you may see this error log message: [notice] renewed license does not match the original one; using original license. You don’t need to take action. You can safely ignore this message. For details, see K000159013.

{{< /details >}}

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:

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

  [warn] license will expire in 14 days

• License expired:

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

Reported usage metrics

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:

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

## What's Next

- [Watch instructional videos](/nginx/solutions/about-subscription-licenses/instructional-videos) on how to upgrade to R33 or later, and how to submit usage reports