# 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](nim/licensing-and-reporting/report-usage-disconnected-deployment.md). **Note:** 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**. ## 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. **Note:** For flowcharts that show how these requirements work in practice, see [NGINX Plus licensing workflows](/solutions/about-subscription-licenses/nginx-plus-licensing-workflows.md). ### 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](#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 {#download-jwt} 1. Log in to [MyF5](https://my.f5.com/manage/s/). 1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. 1. Find your NGINX subscription, and select the **Subscription ID** for details. 1. Download the **JSON Web Token** file from the subscription page. ## Deploy the license {#deploy-jwt} 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](/nginx-one-console/getting-started.md), use a **Config Sync Group** to keep instances consistent, avoid manual copying, and apply license updates automatically. - In [NGINX Instance Manager](/nim/nginx-instances/manage-instance-groups.md), 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: #### Deploy with a group sync feature (recommended) ### Deploy with a group sync feature **Note:** 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](/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md) 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](/nim/nginx-instances/manage-instance-groups.md) for setup instructions. #### 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 1. Reload NGINX: ```shell systemctl reload nginx ``` 1. If SELinux is enabled, set the correct file context so NGINX can read the license: ```shell chcon -t httpd_config_t /etc/nginx/license.jwt ``` #### Use custom paths ### 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: ```bash touch /etc/nginx/license.jwt ``` 1. **After upgrading**: Update the [`license_token`](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive in the [`mgmt`](https://nginx.org/en/docs/ngx_mgmt_module.html) block of the configuration to point to your custom path: ```nginx mgmt { license_token ; } ``` ## Prepare your environment for reporting {#set-up-environment} NGINX Plus R33 and later must send usage reports. Choose the setup steps that match your environment: #### Configure reporting in internet-connected environments ### Internet-connected environments {#internet-connected} 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` 1. *(R34 and later)* If your company restricts outbound traffic, configure NGINX Plus instances to connect through an outbound proxy. Update the [`proxy`](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) directive in the [`mgmt`](https://nginx.org/en/docs/ngx_mgmt_module.html) block of (`/etc/nginx/nginx.conf`) to point to your proxy server: ```nginx mgmt { proxy PROXY_ADDR:PORT; # can be http or https proxy_username USER; # optional proxy_password PASS; # optional } ``` #### Configure reporting in network-restricted environments ### Network-restricted environments {#network-restricted} 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`). 1. On each NGINX Plus instance, set the [`usage_report`](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive in the [`mgmt`](https://nginx.org/en/docs/ngx_mgmt_module.html) block of `/etc/nginx/nginx.conf` to point to your NGINX Instance Manager host: ```nginx mgmt { usage_report endpoint=; } ``` 1. Reload NGINX: ``` bash systemctl reload nginx ``` **Note:** If you’re using self-signed certificates with NGINX Instance Manager, see [Configure SSL verification for self-signed certificates](nim/system-configuration/secure-traffic.md#configure-ssl-verify) for additional steps. **Note:** For instructions on forwarding usage reports from NGINX Instance Manager to F5, see [Report usage data to F5 (disconnected)](/nim/licensing-and-reporting/report-usage-disconnected-deployment.md). ### Postpone reporting enforcement {#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`](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) to `off`. This starts a 180-day grace period where NGINX Plus keeps running while it continues trying to report. ```nginx # Modify this directive to start the 180-day grace period for initial reporting. mgmt { enforce_initial_report off; } ``` **Note:** After 180 days without usage reporting, NGINX Plus stops processing traffic. ## Update the license {#update-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. **Note:** If your subscription was renewed under the Flexible Consumption Program (FCP), automatic JWT renewal isn't supported. You must [apply updated JWT licenses manually](https://docs.nginx.com/solutions/about-subscription-licenses/getting-started/#manually-update-license) at each renewal to make sure NGINX Plus continues to work. Check your subscription details, including subscription type, on [MyF5](https://my.f5.com). For more information, see [K000160880: JWT license auto-renewal may fail in NGINX Plus](https://my.f5.com/manage/s/article/K000160880). #### Update the license automatically (R35 and later) ### Automatic update (R35 and later) {#automatic-renewal} Starting in NGINX Plus R35, [JWT licenses are updated automatically](#automatic-renewal) 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`](https://nginx.org/en/docs/ngx_mgmt_module.html#state_path) directory. - The original JWT license file at `/etc/nginx/license.jwt` (or a custom path set by [`license_token`](https://nginx.org/en/docs/ngx_mgmt_module.html#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. **Note:** 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](#manually-update-license). #### Update the license manually (all releases) ### Manual update (all releases) {#manually-update-license} If automatic updates are not available (for example, in disconnected environments), update the license manually: 1. [Download the new JWT license](#download-jwt) from MyF5. 1. [Deploy the JWT license](#deploy-jwt) to your NGINX Plus instances. **Note:** If you manually updated your JWT license after subscription renewal, you may see this [error log message](#log-monitoring): `[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](https://my.f5.com/manage/s/article/K000159013). ## Error log location and monitoring {#log-monitoring} Monitor the [NGINX error log](https://nginx.org/en/docs/ngx_core_module.html#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](https://demo.nginx.com/api/9/license) to check license status programmatically. For details, see the [ngx_http_api_module docs](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_license_object). Examples of log entries: - **Failed usage reports:** ``` text [error] 36387#36387: server returned 500 for : during usage report [error] 36528#36528: : could not be resolved (host not found) during usage report [error] 36619#36619: connect() failed (111: Connection refused) for : during usage report [error] 38888#88: server returned 401 for :443 during usage report ``` - **License nearing expiration:** ``` text [warn] license will expire in 14 days ``` - **License expired:** ``` text [alert] license expiry; grace period will end in 89 days [emerg] license expired ``` **Note:** NGINX Plus stops processing traffic if the license has been expired for more than 90 days. ## Reported usage metrics {#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: ```json { "version": "", "uuid": "", "nap": "", // F5 WAF for NGINX 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 } ## What's Next - [Watch instructional videos](/solutions/about-subscription-licenses/instructional-videos.md) on how to upgrade to R33 or later, and how to submit usage reports