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:
- Download and add a valid JWT license to each NGINX Plus instance.
- Set up your environment to allow NGINX Plus to send usage reports.
Add the JWT license
Before you install or upgrade to NGINX Plus R33 or later, make sure to:
Download the license from MyF5
- Log in to MyF5.
- Go to My Products & Plans > Subscriptions to see your active subscriptions.
- Find your NGINX products or services subscription, and select the Subscription ID for details.
- Download the JSON Web Token from the subscription page.
Copy the license to each NGINX Plus instance
-
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. -
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.
-
Before upgrading: Create the placeholder file by running:
touch /etc/nginx/license.jwt
-
After upgrading: Update the
license_token
directive in the NGINX configurationmgmt
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:
-
Open port
443
for NGINX Instance Manager. -
On each NGINX Plus instance, update the
usage_report
directive in themgmt
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. -
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
}
Learn more about related topics
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
- Internet-connected: Follow the steps in Add license.
- Network-restricted: Follow the steps in Add a license in a disconnected environment.
Submit usage reports to F5 from NGINX Instance Manager
- Internet-connected: Follow the steps in Report usage to F5.
- Network-restricted: Follow the steps in Report usage to F5 in a network-restricted environment.