diff --git a/content/includes/licensing-and-reporting/apply-jwt.md b/content/includes/licensing-and-reporting/apply-jwt.md index d04116675..943c69046 100644 --- a/content/includes/licensing-and-reporting/apply-jwt.md +++ b/content/includes/licensing-and-reporting/apply-jwt.md @@ -15,10 +15,8 @@ file: systemctl reload nginx ``` -**If SELinux is enabled**: +1. If SELinux is enabled, set the correct file context so NGINX can read the license: -Set the correct file context so NGINX can read the license: - -```shell -chcon -t httpd_config_t /etc/nginx/license.jwt -``` + ```shell + chcon -t httpd_config_t /etc/nginx/license.jwt + ``` diff --git a/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md b/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md index 68da7ec26..d5282b25d 100644 --- a/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md +++ b/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md @@ -2,20 +2,23 @@ docs: --- -1. Open port `443` for NGINX Instance Manager. +1. Allow NGINX Plus instances to connect to NGINX Instance Manager over HTTPS (TCP `443`). -2. On each NGINX Plus instance, update 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 the NGINX configuration (`/etc/nginx/nginx.conf`) to point to your NGINX Instance Manager host: +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=; + usage_report endpoint=; } ``` - {{}}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]({{< ref "nim/system-configuration/secure-traffic.md#configure-ssl-verify" >}}).{{}} - -3. Reload NGINX: +1. Reload NGINX: ``` bash systemctl reload nginx ``` + +{{}} +If you’re using self-signed certificates with NGINX Instance Manager, +see [Configure SSL verification for self-signed certificates]({{< ref "nim/system-configuration/secure-traffic.md#configure-ssl-verify" >}}) for additional steps. +{{}} diff --git a/content/includes/licensing-and-reporting/custom-paths-jwt.md b/content/includes/licensing-and-reporting/custom-paths-jwt.md index 2ac1fb9b3..1066c4258 100644 --- a/content/includes/licensing-and-reporting/custom-paths-jwt.md +++ b/content/includes/licensing-and-reporting/custom-paths-jwt.md @@ -2,15 +2,15 @@ docs: --- -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. +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 by running: +1. **Before upgrading**: Create the placeholder file: ```bash touch /etc/nginx/license.jwt ``` -2. **After upgrading**: Update the [`license_token`](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive in the NGINX configuration [`mgmt`](https://nginx.org/en/docs/ngx_mgmt_module.html) block to point to your custom path: +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 { diff --git a/content/includes/licensing-and-reporting/deploy-jwt-with-csgs.md b/content/includes/licensing-and-reporting/deploy-jwt-with-csgs.md index 913c1862d..0b279a83e 100644 --- a/content/includes/licensing-and-reporting/deploy-jwt-with-csgs.md +++ b/content/includes/licensing-and-reporting/deploy-jwt-with-csgs.md @@ -3,14 +3,22 @@ file: - content/solutions/about-subscription-licenses.md --- -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]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}) 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: + +{{}} +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]({{< ref "/nginx-one/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` - 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. \ No newline at end of file + +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. \ No newline at end of file diff --git a/content/includes/licensing-and-reporting/log-location-and-monitoring.md b/content/includes/licensing-and-reporting/log-location-and-monitoring.md index 673b74671..217f53461 100644 --- a/content/includes/licensing-and-reporting/log-location-and-monitoring.md +++ b/content/includes/licensing-and-reporting/log-location-and-monitoring.md @@ -2,13 +2,13 @@ docs: --- -Monitor the [NGINX error log](https://nginx.org/en/docs/ngx_core_module.html#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. +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 subscription-related log entries include: +Examples of log entries: -- **Failure to upload usage reports**: +- **Failed usage reports:** ``` text [error] 36387#36387: server returned 500 for : during usage report @@ -17,17 +17,19 @@ Examples of subscription-related log entries include: [error] 38888#88: server returned 401 for :443 during usage report ``` -- **License approaching expiration**: +- **License nearing expiration:** ``` text [warn] license will expire in 14 days ``` -- **License expiration**: +- **License expired:** ``` text [alert] license expiry; grace period will end in 89 days [emerg] license expired ``` - {{< call-out "important" >}}When a license expires, NGINX Plus stops processing traffic.{{< /call-out >}} \ No newline at end of file +{{< call-out "important" "Important" >}} +NGINX Plus stops processing traffic if the license has been expired for more than 90 days. +{{< /call-out >}} \ No newline at end of file diff --git a/content/includes/licensing-and-reporting/reported-usage-data.md b/content/includes/licensing-and-reporting/reported-usage-data.md index 5a2876091..2ca23644c 100644 --- a/content/includes/licensing-and-reporting/reported-usage-data.md +++ b/content/includes/licensing-and-reporting/reported-usage-data.md @@ -2,38 +2,39 @@ docs: --- -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: +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": "", // status of NGINX App Protect + "nap": "", // NGINX App Protect status "http": { "client": { "received": 0, // bytes received - "sent": 0, // bytes sent - "requests": 0 // number of HTTP requests processed + "sent": 0, // bytes sent + "requests": 0 // HTTP requests processed }, "upstream": { "received": 0, // bytes received - "sent": 0 // bytes sent + "sent": 0 // bytes sent } }, "stream": { "client": { "received": 0, // bytes received - "sent": 0 // bytes sent + "sent": 0 // bytes sent }, "upstream": { "received": 0, // bytes received - "sent": 0 // bytes sent + "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 -} -``` + "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 +} \ No newline at end of file diff --git a/content/solutions/_index.md b/content/solutions/_index.md index 23b40bf53..1e854be4c 100644 --- a/content/solutions/_index.md +++ b/content/solutions/_index.md @@ -1,12 +1,29 @@ --- -title: Subscription Licensing & Solutions +title: Subscription licensing & solutions nd-docs: null toc: true weight: 1 +nd-content-type: landing-page +nd-landing-page: true --- -This section provides information about managing subscription licenses for NGINX products. Learn about license requirements, how to handle common issues, and ensure compliance to keep systems running smoothly. +## Subscription licensing + +{{}} + {{}} + Learn how NGINX Plus subscription licensing works, what’s required, and how to set up your environment. + {{}} +{{}} + +{{}} + {{}} + View flowcharts that show license validation and usage reporting checks at startup, renewal, and during operation. + {{}} + {{}} + Watch step-by-step videos on sending usage reports and installing or upgrading NGINX Plus. + {{}} +{{}} + + -### Topics in this section: -- [About subscription licenses]({{< ref "solutions/about-subscription-licenses.md" >}}) \ No newline at end of file diff --git a/content/solutions/about-subscription-licenses.md b/content/solutions/about-subscription-licenses.md deleted file mode 100644 index caee94931..000000000 --- a/content/solutions/about-subscription-licenses.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: About subscription licenses -toc: true -weight: 2 -type: -- reference -product: Solutions -nd-docs: DOCS-1780 ---- - -## 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]({{< ref "nim/disconnected/report-usage-disconnected-deployment.md" >}}). - -## 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](#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](#download-jwt)** to each NGINX Plus instance. -- **[Set up your environment](#set-up-environment)** to allow NGINX Plus to send usage reports. - ---- - -## Download the license from MyF5 {#download-jwt} - -{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} - ---- - -## 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. - -### Deploy with a Config Sync Group (Recommended) - -If you're using the [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}), the easiest way to manage your JWT license is with a [Config Sync Group]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}). 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: - -{{< include "/licensing-and-reporting/deploy-jwt-with-csgs.md" >}} - -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. - -{{< call-out "note" "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]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}). -{{< /call-out >}} - -### Copy the license manually - -If you're not using the NGINX One Console, copy the JWT license file to each NGINX Plus instance manually. - -{{< include "/licensing-and-reporting/apply-jwt.md" >}} - -### Custom paths {#custom-paths} - -{{< include "licensing-and-reporting/custom-paths-jwt.md" >}} - ---- - -## Prepare your environment for reporting {#set-up-environment} - -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 address ranges are allowed: - - - `3.135.72.139/32` - - `3.133.232.50/32` - - `52.14.85.249/32` - - `2600:1f16:19c8:d400::/62` - -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`](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 the NGINX configuration (`/etc/nginx/nginx.conf`) to point to the company's outbound proxy server: - - - ```nginx - 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: - -{{< include "licensing-and-reporting/configure-nginx-plus-report-to-nim.md" >}} - -To send NGINX Plus usage reports to F5, follow the instructions in [Submit usage reports to F5 from NGINX Instance Manager](#submit-usage-reports-from-nim). - -### Postpone reporting enforcement {#postpone-reporting-enforcement} - -To give yourself more time to submit the initial usage report, you can postpone reporting by setting [`enforce_initial_report`](https://nginx.org/en/docs/ngx_mgmt_module.html#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. - - -```nginx -# Modify this directive to start the 180-day grace period for initial reporting. -mgmt { - enforce_initial_report off; -} -``` - -{{< call-out "important" >}}After 180 days, if usage reporting still hasn’t been established, NGINX Plus will stop processing traffic.{{< /call-out >}} - - -## Update the JWT license {#update-jwt} - -Updating the JWT license after renewing your F5 NGINX subscription is a simple and seamless process that does not require manually downloading the JWT or reloading/restarting the NGINX service. This procedure applies both to subscriptions nearing expiration (within 30 days) and to those that have expired but are still within the 90-day grace period. - -The update process will work automatically provided that license reporting has been configured and at least one report has been successfully transmitted. If this setup is not configured, follow the [Deploy the JWT license](#deploy-the-jwt-license) steps instead. - -The updated JWT license is saved directly as a state file at the path specified by the [`state_path`](https://nginx.org/en/docs/ngx_mgmt_module.html#state_path) directive. The existing JWT license file located at `/etc/nginx/license.jwt` (or a custom path specified by the [`license_token`](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive) will remain unchanged during this process and will not impact the performance or functionality of NGINX Plus in the future. If necessary, you may replace it manually with the updated license from MyF5. - -### For internet-connected environments - -Once your subscription has been successfully renewed by F5 Sales, all NGINX Plus instances will automatically receive and apply the updated JWT license — no manual action is required. - -### For network-restricted environments - -In network-restricted environments, there is no change in the JWT update process. It follows the same steps as [adding a new JWT](#for-network-restricted-environments). - ---- - -## Error log location and monitoring {#log-monitoring} - -{{< include "licensing-and-reporting/log-location-and-monitoring.md" >}} - ---- - -## Understand reported usage metrics {#usage-metrics} - -{{< include "licensing-and-reporting/reported-usage-data.md" >}} - ---- - -## 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]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). - -#### `mgmt` module and directives - -For full details about the `mgmt` module and its directives, visit the [Module ngx_mgmt_module reference guide](https://nginx.org/en/docs/ngx_mgmt_module.html). - -### 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]({{< ref "nim/admin-guide/add-license.md" >}}). -- **Network-restricted**: Follow the steps in [Add a license in a disconnected environment]({{< ref "nim/disconnected/add-license-disconnected-deployment.md" >}}). - -#### Submit usage reports to F5 from NGINX Instance Manager {#submit-usage-reports-from-nim} - -- **Internet-connected**: Follow the steps in [Report usage to F5]({{< ref "nim/admin-guide/report-usage-connected-deployment.md" >}}). -- **Network-restricted**: Follow the steps in [Report usage to F5 in a disconnected environment]({{< ref "nim/disconnected/report-usage-disconnected-deployment.md" >}}). - -### F5 WAF for NGINX - -For details on installing or upgrading F5 WAF for NGINX, visit the guide for the respective version: - -- [F5 WAF for NGINX v4 installation guide]({{< ref "/nap-waf/v4/admin-guide/install.md" >}}) -- [F5 WAF for NGINX v5 installation guide]({{< ref "/nap-waf/v5/admin-guide/install.md" >}}) - -### F5 DoS for NGINX - -For detailed instructions on installing or upgrading F5 DoS for NGINX, visit the [F5 DoS for NGINX installation guide]({{< ref "/nap-dos/deployment-guide/learn-about-deployment.md" >}}). - -## Watch instructional videos - -### Submit usage reports in a connected environment -{{< youtube id="PDnacyh2RUw" >}} - -### Submit usage reports in a disconnected environment -{{< youtube id="4wIM21bR9-g" >}} - -### Install or upgrade to NGINX Plus R33 -{{< youtube id="zHd7btagJRM" >}} diff --git a/content/solutions/about-subscription-licenses/_index.md b/content/solutions/about-subscription-licenses/_index.md new file mode 100644 index 000000000..f11b27276 --- /dev/null +++ b/content/solutions/about-subscription-licenses/_index.md @@ -0,0 +1,33 @@ +--- +title: About subscription licenses +nd-docs: null +weight: 1 +nd-content-type: landing-page +nd-landing-page: true +url: /solutions/about-subscription-licenses/ +--- + +## Overview + +Starting with NGINX Plus R33, subscription licenses use JSON Web Tokens (JWTs) and require usage reporting. + +To get up and running, you’ll need to add a valid license to each instance and make sure usage data can be reported. + +The resources below walk you through upgrading, setting up your environment, and understanding how licensing and reporting work in NGINX Plus. + +## Featured content + +{{}} + {{}} + Learn how NGINX Plus subscription licensing works, what’s required, and how to set up your environment. + {{}} +{{}} + +{{}} + {{}} + View flowcharts that show license validation and usage reporting checks at startup, renewal, and during operation. + {{}} + {{}} + Watch step-by-step videos on sending usage reports and installing or upgrading NGINX Plus. + {{}} +{{}} diff --git a/content/solutions/about-subscription-licenses/getting-started.md b/content/solutions/about-subscription-licenses/getting-started.md new file mode 100644 index 000000000..2dfcef013 --- /dev/null +++ b/content/solutions/about-subscription-licenses/getting-started.md @@ -0,0 +1,259 @@ +--- +title: Getting started +toc: true +weight: 200 +nd-content-type: + - tutorial +nd-product: Solutions +nd-docs: DOCS-1780 +nd-resource: + - https://lucid.app/lucidchart/0abcb9d3-b36e-40af-b56a-e74771b384d5/edit?invitationId=inv_8ccda3dc-2306-468c-9cb6-b4684be1360f&page=0_0# +--- + +Starting with NGINX Plus R33, NGINX Plus instances 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]({{< ref "nim/disconnected/report-usage-disconnected-deployment.md" >}}). + +{{< call-out "note" "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**. +{{}} + +--- + +## 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 "note" "Licensing workflows" >}} +For flowcharts that show how these requirements work in practice, see [NGINX Plus licensing workflows]({{< ref "/solutions/about-subscription-licenses/nginx-plus-licensing-workflows.md" >}}). +{{< /call-out >}} + +### Starting NGINX Plus + +Starting NGINX Plus requires: + +- A valid license. +- A license that has not been expired for more than 90 days. + +### Processing traffic + +Processing traffic requires: + +- A successful initial usage report. If the initial report isn’t sent, NGINX Plus won’t process traffic until the report is sent successfully. 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} + +{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} + +--- + +## 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]({{< ref "/nginx-one/getting-started.md" >}}), use a **Config Sync Group** to keep instances consistent, avoid manual copying, and apply license updates automatically. + - In [NGINX Instance Manager]({{< ref "/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. + +Both methods ensure your NGINX Plus instances have access to the required license file. + +Choose the option that fits your environment: + +
+Deploy with a group sync feature (recommended) + +### Deploy with a group sync feature + +
+ +{{< include "/licensing-and-reporting/deploy-jwt-with-csgs.md" >}} + +{{< call-out "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]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}) for setup instructions. +{{< /call-out >}} + +
+ +
+Deploy manually + +### Deploy manually + +
+ +Copy the JWT license file to each NGINX Plus instance. + +{{< include "/licensing-and-reporting/apply-jwt.md" >}} + +
+ +
+Use custom paths + +### Custom paths {#custom-paths} + +
+ +{{< include "licensing-and-reporting/custom-paths-jwt.md" >}} + +
+ +--- + +## 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`). Make sure the following IP addresses are allowed: + + - `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: + +{{< include "/licensing-and-reporting/configure-nginx-plus-report-to-nim.md" >}} + +
+ +{{< call-out "note" "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)]({{< ref "/nim/disconnected/report-usage-disconnected-deployment.md" >}}).{{< /call-out >}} + + +
+ +### 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; +} +``` + +{{< call-out "important" "Important" >}} +After 180 days, if usage reporting still hasn’t been established, +NGINX Plus will stop processing traffic. +{{< /call-out >}} + +--- + +## 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. + +
+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. + +{{< call-out "important" "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](#manually-update-license). +{{< /call-out >}} + +
+ +
+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. +2. [Deploy the JWT license](#deploy-jwt) to your NGINX Plus instances. + +
+ +--- + +## Error log location and monitoring {#log-monitoring} + +{{< include "licensing-and-reporting/log-location-and-monitoring.md" >}} + +--- + +## Reported usage metrics {#usage-metrics} + +{{< include "licensing-and-reporting/reported-usage-data.md" >}} + +--- + +## What's Next + +- [Watch instructional videos]({{< ref "/solutions/about-subscription-licenses/instructional-videos.md" >}}) on how to upgrade to R33 or later, and how to submit usage reports \ No newline at end of file diff --git a/content/solutions/about-subscription-licenses/images/nginx-plus-license-expiration-check.png b/content/solutions/about-subscription-licenses/images/nginx-plus-license-expiration-check.png new file mode 100644 index 000000000..2dc91c230 Binary files /dev/null and b/content/solutions/about-subscription-licenses/images/nginx-plus-license-expiration-check.png differ diff --git a/content/solutions/about-subscription-licenses/images/nginx-plus-startup-check.png b/content/solutions/about-subscription-licenses/images/nginx-plus-startup-check.png new file mode 100644 index 000000000..65594c0af Binary files /dev/null and b/content/solutions/about-subscription-licenses/images/nginx-plus-startup-check.png differ diff --git a/content/solutions/about-subscription-licenses/images/nginx-plus-usage-check-connected.png b/content/solutions/about-subscription-licenses/images/nginx-plus-usage-check-connected.png new file mode 100644 index 000000000..5e694eede Binary files /dev/null and b/content/solutions/about-subscription-licenses/images/nginx-plus-usage-check-connected.png differ diff --git a/content/solutions/about-subscription-licenses/images/nginx-plus-usage-check-disconnected.png b/content/solutions/about-subscription-licenses/images/nginx-plus-usage-check-disconnected.png new file mode 100644 index 000000000..f41adc406 Binary files /dev/null and b/content/solutions/about-subscription-licenses/images/nginx-plus-usage-check-disconnected.png differ diff --git a/content/solutions/about-subscription-licenses/instructional-videos.md b/content/solutions/about-subscription-licenses/instructional-videos.md new file mode 100644 index 000000000..59fe7cdac --- /dev/null +++ b/content/solutions/about-subscription-licenses/instructional-videos.md @@ -0,0 +1,41 @@ +--- +linkTitle: "Instructional videos" +title: "NGINX Plus subscription licensing videos" +weight: 300 +toc: false +nd-content-type: reference +nd-product: Solutions +--- + +These videos show how to set up usage reporting in internet-connected and network-restricted environments, and how to install or upgrade to NGINX Plus R33 or later. + +## Submit usage reports in an internet-connected environment + +{{< youtube id="PDnacyh2RUw" >}} + +See how to configure NGINX Plus to send usage reports directly to the F5 licensing endpoint. + +See also: + +- [Prepare your environment for reporting]({{< ref "solutions/about-subscription-licenses/getting-started.md#set-up-environment" >}}) + +## Submit usage reports in a network-restricted environment + +{{< youtube id="4wIM21bR9-g" >}} + +See how to configure NGINX Plus to send usage reports to NGINX Instance Manager. NGINX Instance Manager collects the reports and forwards them to the F5 licensing endpoint. + +See also: + +- [Prepare your environment for reporting]({{< ref "solutions/about-subscription-licenses/getting-started.md#set-up-environment" >}}) +- [Submit usage reports to F5 from NGINX Instance Manager]({{< ref "/nim/disconnected/report-usage-disconnected-deployment.md" >}}) + +## Install or upgrade to NGINX Plus R33 or later + +{{< youtube id="zHd7btagJRM" >}} + +See how to install or upgrade to NGINX Plus R33 or later. + +See also: + +- [NGINX Plus installation guide]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) \ No newline at end of file diff --git a/content/solutions/about-subscription-licenses/nginx-plus-licensing-workflows.md b/content/solutions/about-subscription-licenses/nginx-plus-licensing-workflows.md new file mode 100644 index 000000000..53d5931be --- /dev/null +++ b/content/solutions/about-subscription-licenses/nginx-plus-licensing-workflows.md @@ -0,0 +1,24 @@ +--- +title: NGINX Plus licensing workflows +toc: true +weight: 100 +nd-content-type: +- reference +nd-product: Solutions +nd-docs: +--- + +These workflows show how NGINX Plus validates licenses and usage reports. They cover startup, license expiration, and reporting in both connected and disconnected environments. + +Use the workflows to see what happens if a license is missing, expired, or not reporting, and the steps you can take to fix it. + +Select an image to enlarge. + + +[{{< img src="solutions/about-subscription-licenses/images/nginx-plus-startup-check.png" alt="Flowchart showing the NGINX Plus startup check. If no license is installed, the user must sign in to MyF5, download the license, and copy it to the NGINX instance. If a license is present, NGINX checks whether it has been expired for more than 90 days. If not, NGINX starts normally. If yes, NGINX fails to start, logs EMERGENCY messages in the error log, and requires a license update to restore service." >}}](../images/nginx-plus-startup-check.png) + +[{{< img src="solutions/about-subscription-licenses/images/nginx-plus-license-expiration-check.png" alt="Flowchart showing the NGINX Plus license expiration check that runs daily after install. If the license is expired, NGINX checks whether more than 90 days have passed. If yes, NGINX logs EMERGENCY messages and cannot restart or apply changes until the license is updated. If no, NGINX logs ALERT messages and requires an update to avoid disruption. If the license is not yet expired but will expire within 30 days, NGINX logs WARN messages. If the license is valid for more than 30 days, NGINX operates normally. In R35, if the instance is internet-connected, the renewed license is updated automatically." >}}](../images/nginx-plus-license-expiration-check.png) + +[{{< img src="solutions/about-subscription-licenses/images/nginx-plus-usage-check-connected.png" alt="Flowchart showing the NGINX Plus licensing reporting check, which runs by default every hour. If NGINX is connected and reporting to the F5 licensing endpoint or to NGINX Instance Manager, it operates normally. If not, NGINX checks whether fewer than 180 days have passed since the directive was set or the last successful report. If the grace period directive is set to off, NGINX continues. If the initial report has never been sent successfully, or more than 180 days have passed, NGINX stops processing traffic." >}}](../images/nginx-plus-usage-check-connected.png) + +[{{< img src="solutions/about-subscription-licenses/images/nginx-plus-usage-check-disconnected.png" alt="Flowchart showing the NGINX Plus licensing reporting check for offline or air-gapped environments, which runs every hour by default. If NGINX reports to Instance Manager, it operates normally, and usage data can be exported and sent to F5. If not, NGINX checks whether the grace period directive is set to off. If the directive is off or the initial report has been sent successfully, and fewer than 180 days have passed since the last successful report, NGINX continues to operate. If the initial report has never been sent or more than 180 days have passed, NGINX stops processing traffic." >}}](../images/nginx-plus-usage-check-disconnected.png) \ No newline at end of file diff --git a/content/solutions/nginx-one-subscription.md b/content/solutions/nginx-one-subscription.md deleted file mode 100644 index 9b52dd809..000000000 --- a/content/solutions/nginx-one-subscription.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -description: '' -nd-docs: null -title: NGINX One subscription -toc: true -weight: 100 -draft: true ---- - -## Overview - -Welcome to F5 NGINX One! Your subscription provides access to the following F5 NGINX solutions: - -- **Kubernetes Ingress Controller:** Manage and secure Kubernetes traffic efficiently. -- **API gateway:** Control API traffic with advanced gateway features. -- **Caching:** Improve performance with content caching. -- **Load balancing:** Distribute traffic effectively across your infrastructure. -- **Policy enforcement:** Ensure compliance and security with policy enforcement. - -### Deployment Options - -You can deploy these components in various environments: - -- Public or private clouds -- Virtual machines -- Bare metal -- Containers -- Kubernetes - -### Management and Monitoring - -Monitor and manage your NGINX data planes through the NGINX One service in F5 Distributed Cloud. - -## Access to NGINX One - -After your NGINX One subscription is activated, the contact provided to F5 will receive an email invitation to MyF5 and your tenant in F5 Distributed Cloud. Within [F5 Distributed Cloud](https://console.ves.volterra.io/), you can access the NGINX One Cloud Console and explore other F5 Distributed Cloud services. In [MyF5](https://my.f5.com/), you’ll find all the licensing and fulfillment objects needed to access and deploy NGINX One software components. - -## NGINX One in F5 Distributed Cloud - -Manage configurations, monitor your infrastructure, address security vulnerabilities, and assess the health of your NGINX fleet—all from a single console in F5 Distributed Cloud. - -- [Learn more about NGINX One Cloud Console](https://docs.nginx.com/nginx-one/about/) -- [Get started with NGINX One Cloud Console](https://docs.nginx.com/nginx-one/getting-started/) -- [Log in to F5 Distributed Cloud](https://console.ves.volterra.io/) - -## F5 NGINX Plus - -NGINX Plus is an all-in-one load balancer, reverse proxy, web server, content cache, and API gateway, built on the world’s most popular web server, NGINX. - -- [Install NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/) - -## F5 NGINX Ingress Controller - -NGINX Ingress Controller helps you manage Kubernetes traffic with advanced API gateway, identity, and observability features. - -- [Learn more about NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/overview/about/) -- [Install NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/installation/) - -## Enterprise Support for NGINX Open Source - -Get enterprise-level support for NGINX, the open-source all-in-one load balancer, content cache, and web server. - -- [Install F5 supported NGINX packages](https://nginx.org/en/linux_packages.html) - -## F5 NGINX Gateway Fabric - -Utilize next-generation Kubernetes connectivity with the Gateway API using NGINX Gateway Fabric. - -- [Learn more about NGINX Gateway Fabric](https://docs.nginx.com/nginx-gateway-fabric/overview/) -- [Install NGINX Gateway Fabric](https://docs.nginx.com/nginx-gateway-fabric/installation/) - -## F5 NGINX Instance Manager - -For dark or air-gapped environments, deploy NGINX Instance Manager to configure, manage, and monitor NGINX Open Source, NGINX Plus, and NGINX App Protect instances. - -## Additional resources - -**Support** - -- [F5 Support Information](https://my.f5.com/manage/s/article/K000140156) -- [F5 Support Portal](https://my.f5.com/) - -**Open Source** - -- [NGINX Open Source Home Page](https://nginx.org/) -- [NGINX GitHub](https://github.com/nginx) - -**Official F5 NGINX Technical Communities** - -- [F5 NGINX GitHub](https://github.com/nginxinc) -- [F5 DevCentral](https://community.f5.com/) diff --git a/content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md b/content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md deleted file mode 100644 index b3b09a6e7..000000000 --- a/content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: R33 pre-release guidance for automatic upgrades -weight: 1 -toc: true -noindex: true -type: -- reference -draft: true -type: concept -product: Solutions -nd-docs: DOCS-000 ---- - -{{}} -NGINX Plus R33 requires a valid JSON Web Token (JWT) to start and accept new connections. -
-If automatic upgrades are enabled, apply the JWT and configure your network now to avoid downtime when R33 is released. -{{}} - -## What to know before upgrading to NGINX Plus R33 - -### What's new - -Starting with NGINX Plus R33, expected in **Q4 of 2024**, all **NGINX Plus instances will require a valid JSON Web Token (JWT)**. The JWT is tied to your subscription, not individual instances, and is used to **validate your subscription** and **report telemetry data**. In internet-connected environments, telemetry is sent to F5’s licensing endpoint. In offline environments, telemetry is routed through [NGINX Instance Manager]({{< ref "/nim" >}}). - -This change is part of F5's broader licensing program, designed to make subscription renewals and usage reporting easier. The [telemetry data](#telemetry) helps us improve our products and services to better meet your needs. - -##### What this means for you - -If you’ve enabled automatic upgrades, you need to act **before** NGINX Plus R33 releases to ensure a smooth upgrade: - -- [**Download and apply a valid JSON Web Token (JWT)**](#jwt) to each NGINX Plus instance. - **Without this token, NGINX Plus won’t start**, and the upgrade won’t complete. - -- [**Configure your network**](#configure-network) to allow NGINX Plus to report telemetry data. - **If telemetry reporting fails, NGINX Plus will stop accepting new connections**. - There’s an exception for previously reported instances — refer to [handling outages](#handling-outages) for more details. - -Follow the [pre-release steps](#steps) below to complete the process. - -##### Impacts to NGINX Ingress Controller - -- **Don’t upgrade to NGINX Plus R33 until the next version of NGINX Ingress Controller is released.** - NGINX Plus R33 isn’t compatible with NGINX Ingress Controller v3.7.0. - -##### Impacts to previous NGINX Plus versions - -- **No action needed**: - If you use NGINX Plus before R33 and haven’t enabled automatic upgrades, no action is required. ---- - -## Pre-release action items for NGINX Plus R33 {#steps} - -Complete these steps **before** NGINX R33 releases to prepare your systems. - -### Download the JWT from MyF5 {#jwt} - -{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} - -### Apply the JWT - -{{< include "licensing-and-reporting/apply-jwt.md" >}} - -##### Custom paths: - -{{< include "licensing-and-reporting/custom-paths-jwt.md" >}} - - -### Set up your network for reporting {#configure-network} - -To ensure NGINX Plus R33 can report telemetry data, follow these steps based on your environment: - -#### For internet-connected environments: - -1. **Open port 443**: - Allow outbound HTTPS traffic on TCP port 443 to communicate with F5's licensing endpoint (`product.connect.nginx.com`). Ensure that the following IP address ranges are allowed: - - - `3.135.72.139/32` - - `3.133.232.50/32` - - `52.14.85.249/32` - - `2600:1f16:19c8:d400::/62` - -#### For partially connected environments: - -1. On each NGINX Plus instance, update the `usage_report` directive in the [`mgmt`](https://nginx.org/en/docs/ngx_mgmt_module.html) block of the NGINX configuration (**/etc/nginx/nginx.conf**) to point to your NGINX Instance Manager host: - - ``` nginx - usage_report endpoint= interval=1hr; - ``` - -1. **Open port 443 for NGINX Instance Manager**: - Ensure NGINX Plus can connect to NGINX Instance Manager to report usage data. - -If NGINX Instance Manager has internet access, it will automatically report usage data to F5. If it doesn't doesn't have internet access, you can manually [submit usage reports to F5 for verification and acknowledgement]({{< ref "nim/disconnected/report-usage-disconnected-deployment.md" >}}). - - -#### For fully disconnected environments: - -Starting with **NGINX Instance Manager 2.18** (**coming soon**), you’ll be able to manually export usage reports for fully disconnected environments. You will need to: - -1. **Export the usage report**: Manually export the usage report from NGINX Instance Manager. -2. **Send the report to F5**: Submit the report to F5 for verification from a location with internet access. -3. **Upload the acknowledgment**: After verification, upload the acknowledgment from F5 to NGINX Instance Manager. - -### Handling outages - -If a temporary outage occurs, either on your side or F5’s: - -- As long as your instance has successfully reported at least once, you’ll have a **180-day grace period** to resolve the issue. - During this grace period, NGINX Plus will continue running without any restrictions. - ---- - -## What’s reported and how it’s protected {#telemetry} - -{{< include "licensing-and-reporting/reported-usage-data.md" >}} - -### Security and privacy of reported data - -All communication between your NGINX Plus instances, NGINX Instance Manager, and F5’s licensing endpoint (`product.connect.nginx.com`) is protected using **SSL/TLS** encryption. - -Only **operational metrics** are reported — no **personally identifiable information (PII)** or **sensitive customer data** is transmitted.