diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f08087005..a74e38c32 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -26,8 +26,8 @@ content/nginx/nms/agent/* @nginx/nginx-agent content/nap-dos/* @nginx/dos-docs-approvers # F5 WAF for NGINX -content/nap-waf/* @nginx/nap-docs-approvers -data/nap-waf/* @nginx/nap-docs-approvers +content/waf/* @nginx/waf +content/includes/waf/* @nginx/waf # NGINXaaS for Azure content/nginxaas-azure/* @nginx/n4a-docs-approvers diff --git a/content/agent/configuration/configuration-overview.md b/content/agent/configuration/configuration-overview.md index 0a85eede6..22a602330 100644 --- a/content/agent/configuration/configuration-overview.md +++ b/content/agent/configuration/configuration-overview.md @@ -3,8 +3,9 @@ title: Basic configuration draft: false weight: 100 toc: true -nd-docs: DOCS-1229 nd-content-type: how-to +nd-product: Agent +nd-docs: DOCS-1229 --- The following sections explain how to configure NGINX Agent using configuration files, CLI flags, and environment variables. @@ -27,8 +28,7 @@ The default locations of configuration files for NGINX Agent are `/etc/nginx-age Examples of the configuration files are provided below: -
- example nginx-agent.conf +{{< details summary="Open nginx-agent.conf example">}} {{< call-out "note" >}} In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control plane. @@ -112,11 +112,9 @@ nginx_app_protect: precompiled_publication: true ``` -
- +{{< /details >}} -
- example dynamic-agent.conf +{{< details summary="Open dynamic-agent.conf example">}} {{< call-out "note" >}} Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` @@ -146,7 +144,7 @@ tags: - qa ``` -
+{{< /details >}} ## CLI Flags & Environment Variables @@ -239,8 +237,7 @@ Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.con By default, NGINX Agent rotates logs daily using logrotate with the following configuration: -
- NGINX Agent Logrotate Configuration +{{< details summary="Logrotate configuration example" >}} ``` yaml /var/log/nginx-agent/*.log @@ -263,7 +260,7 @@ By default, NGINX Agent rotates logs daily using logrotate with the following co notifempty } ``` -
+{{< /details >}} If you need to change the default configuration, update the file at `/etc/logrotate.d/nginx-agent`. diff --git a/content/includes/nim/disconnected/license-usage-offline-script.md b/content/includes/nim/disconnected/license-usage-offline-script.md index 72a5e49e0..5fd325aee 100644 --- a/content/includes/nim/disconnected/license-usage-offline-script.md +++ b/content/includes/nim/disconnected/license-usage-offline-script.md @@ -2,10 +2,9 @@ nd-docs: "DOCS-1662" --- -
-View the full contents of the license_usage_offline.sh script +{{< details summary="Full license_usage_offline.sh script" >}} -``` bash +```shell #!/bin/bash # Function to encode the username and password to base64 @@ -413,4 +412,4 @@ curl --insecure --location "https://$ip_address/api/platform/v1/report/upload" \ echo "Report acknowledgement successfully uploaded to NGINX Instance Manager $ip_address." ``` -
+{{< /details >}} diff --git a/content/ngf/install/helm.md b/content/ngf/install/helm.md index a7e08fe01..0daf283e5 100644 --- a/content/ngf/install/helm.md +++ b/content/ngf/install/helm.md @@ -22,8 +22,7 @@ To complete this guide, you will need: {{< call-out "important" >}} If you’d like to use NGINX Plus, some additional setup is also required: {{< /call-out >}} -
-NGINX Plus JWT setup +{{< details summary="NGINX Plus JWT setup" >}} {{< include "/ngf/installation/jwt-password-note.md" >}} @@ -41,7 +40,7 @@ To complete this guide, you will need: {{< call-out "note" >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< ref "/ngf/install/nginx-plus.md" >}}) document. {{< /call-out >}} -
+{{< /details >}} ## Deploy NGINX Gateway Fabric diff --git a/content/ngf/install/manifests.md b/content/ngf/install/manifests.md index 3a7552e6d..c656b3798 100644 --- a/content/ngf/install/manifests.md +++ b/content/ngf/install/manifests.md @@ -20,8 +20,7 @@ To complete this guide, you'll need to install: {{< call-out "important" >}} If you’d like to use NGINX Plus, some additional setup is also required: {{< /call-out >}} -
-NGINX Plus JWT setup +{{< details summary="NGINX Plus JWT setup" >}} {{< include "/ngf/installation/jwt-password-note.md" >}} @@ -39,7 +38,7 @@ To complete this guide, you'll need to install: {{< call-out "note" >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< ref "/ngf/install/nginx-plus.md" >}}) document. {{< /call-out >}} -
+{{< /details >}} ## Deploy NGINX Gateway Fabric diff --git a/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md index f0bf93874..1fa08aaf7 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md +++ b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md @@ -29,59 +29,53 @@ Before you install NGINX Agent for the first time on your system, you need to se up the `nginx-agent` packages repository. Afterward, you can install and update NGINX Agent from the repository. -
-Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux - -### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux +### Install NGINX Agent on Alpine Linux -{{< include "/agent/installation/oss/oss-rhel.md" >}} +{{< details summary="Expand instructions" >}} -
+{{< include "/agent/installation/oss/oss-alpine.md" >}} -
-Install NGINX Agent on Ubuntu +{{< /details >}} -### Install NGINX Agent on Ubuntu +### Install NGINX Agent on Amazon Linux -{{< include "/agent/installation/oss/oss-ubuntu.md" >}} +{{< details summary="Expand instructions" >}} -
+{{< include "/agent/installation/oss/oss-amazon-linux.md" >}} -
-Install NGINX Agent on Debian +{{< /details >}} ### Install NGINX Agent on Debian +{{< details summary="Expand instructions" >}} + {{< include "/agent/installation/oss/oss-debian.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on SLES +### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux -### Install NGINX Agent on SLES +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/oss/oss-sles.md" >}} +{{< include "/agent/installation/oss/oss-rhel.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on Alpine Linux +### Install NGINX Agent on SLES -### Install NGINX Agent on Alpine Linux +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/oss/oss-alpine.md" >}} +{{< include "/agent/installation/oss/oss-sles.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on Amazon Linux +### Install NGINX Agent on Ubuntu -### Install NGINX Agent on Amazon Linux +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/oss/oss-amazon-linux.md" >}} +{{< include "/agent/installation/oss/oss-ubuntu.md" >}} -
+{{< /details >}} ### Manually connect NGINX Agent to NGINX One Console diff --git a/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md index 726814b19..939f16a4f 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md +++ b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md @@ -2,7 +2,8 @@ title: Install from NGINX Plus repo toc: true weight: 200 -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGINX One nd-docs: DOCS-1877 --- @@ -16,7 +17,7 @@ For a quick guide on how to connect your instance to NGINX One Console see: [Con ## Overview -Follow the steps in this guide to install NGINX Agent in your NGINX instance using +Follow the steps in this guide to install F5 NGINX Agent in your NGINX instance using the NGINX Plus repository. ## Before you begin @@ -29,59 +30,53 @@ Before you install NGINX Agent for the first time on your system, you need to set up the `nginx-agent` packages repository. Afterward, you can install and update NGINX Agent from the repository. +### Install NGINX Agent on Alpine Linux -
-Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux +{{< details summary="Expand instructions" >}} -### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux - -{{< include "/agent/installation/plus/plus-rhel.md" >}} +{{< include "/agent/installation/plus/plus-alpine.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on Ubuntu +### Install NGINX Agent on Amazon Linux -### Install NGINX Agent on Ubuntu +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/plus/plus-ubuntu.md" >}} +{{< include "/agent/installation/plus/plus-amazon-linux.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on Debian +### Install NGINX Agent on Debian -### Install NGINX Agent on Debian +{{< details summary="Expand instructions" >}} {{< include "/agent/installation/plus/plus-debian.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on SLES +### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux -### Install NGINX Agent on SLES +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/plus/plus-sles.md" >}} +{{< include "/agent/installation/plus/plus-rhel.md" >}} -
+{{< /details >}} -
-Install NGINX Agent on Alpine Linux +### Install NGINX Agent on SLES -### Install NGINX Agent on Alpine Linux +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/plus/plus-alpine.md" >}} +{{< include "/agent/installation/plus/plus-sles.md" >}} -
-
-Install NGINX Agent on Amazon Linux +{{< /details >}} -### Install NGINX Agent on Amazon Linux +### Install NGINX Agent on Ubuntu -{{< include "/agent/installation/plus/plus-amazon-linux.md" >}} +{{< details summary="Expand instructions" >}} + +{{< include "/agent/installation/plus/plus-ubuntu.md" >}} -
+{{< /details >}} ### Manually connect NGINX Agent to NGINX One Console diff --git a/content/nginx-one/agent/install-upgrade/uninstall.md b/content/nginx-one/agent/install-upgrade/uninstall.md index 0a4137c09..27330e0ce 100644 --- a/content/nginx-one/agent/install-upgrade/uninstall.md +++ b/content/nginx-one/agent/install-upgrade/uninstall.md @@ -1,8 +1,9 @@ --- title: Uninstall NGINX Agent -toc: true +toc: false weight: 500 -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGINX One nd-docs: DOCS-1874 --- @@ -18,56 +19,52 @@ The user following performing the uninstall steps needs to have `root` privilege Complete the following steps on each host where you've installed NGINX Agent -
-Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux - -### Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux +### Uninstall NGINX Agent on Alpine Linux -{{< include "/agent/installation/uninstall/uninstall-rhel.md" >}} +{{< details summary="Expand instructions" >}} -
+{{< include "/agent/installation/uninstall/uninstall-alpine.md" >}} -
-Uninstall NGINX Agent on Ubuntu +{{< /details >}} -### Uninstall NGINX Agent on Ubuntu +### Uninstall NGINX Agent on Amazon Linux -{{< include "/agent/installation/uninstall/uninstall-ubuntu.md" >}} +{{< details summary="Expand instructions" >}} -
+{{< include "/agent/installation/uninstall/uninstall-amazon-linux.md" >}} -
-Uninstall NGINX Agent on Debian +{{< /details >}} ### Uninstall NGINX Agent on Debian +{{< details summary="Expand instructions" >}} + {{< include "/agent/installation/uninstall/uninstall-debian.md" >}} -
+{{< /details >}} -
-Uninstall NGINX Agent on SLES +### Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux -### Uninstall NGINX Agent on SLES +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/uninstall/uninstall-sles.md" >}} +{{< include "/agent/installation/uninstall/uninstall-rhel.md" >}} -
+{{< /details >}} -
-Uninstall NGINX Agent on Alpine Linux +### Uninstall NGINX Agent on SLES -### Uninstall NGINX Agent on Alpine Linux +{{< details summary="Expand instructions" >}} -{{< include "/agent/installation/uninstall/uninstall-alpine.md" >}} +{{< include "/agent/installation/uninstall/uninstall-sles.md" >}} -
+{{< /details >}} -
-Uninstall NGINX Agent on Amazon Linux +### Uninstall NGINX Agent on Ubuntu -### Uninstall NGINX Agent on Amazon Linux +{{< details summary="Expand instructions" >}} + +{{< include "/agent/installation/uninstall/uninstall-ubuntu.md" >}} + +{{< /details >}} -{{< include "/agent/installation/uninstall/uninstall-amazon-linux.md" >}} -
diff --git a/content/nginx-one/getting-started.md b/content/nginx-one/getting-started.md index e21753600..ca2d4a061 100644 --- a/content/nginx-one/getting-started.md +++ b/content/nginx-one/getting-started.md @@ -2,8 +2,8 @@ title: Get started toc: true weight: 100 -type: how-to -product: NGINX One +nd-content-type: how-to +nd-product: NGINX One --- The F5 NGINX One Console makes it easy to manage NGINX instances across locations and environments. The console lets you monitor and control your NGINX fleet from one place—you can check configurations, track performance metrics, identify security vulnerabilities, manage SSL certificates, and more. @@ -26,12 +26,10 @@ NGINX One offers the following key benefits: If you already have accessed F5 Distributed Cloud and have NGINX instances available, you can skip these sections and start to [Add your NGINX instances to NGINX One](#add-your-nginx-instances-to-nginx-one). Otherwise, take these steps to "onboard" yourself to NGINX One Console. -
-If you want to register for a trial +{{< details summary="Register for a trial" >}} ### Register for a trial subscription - If you want to register for a trial, navigate to https://account.f5.com/myf5. If needed, select **Sign up** to get an account. Then follow these steps: 1. Navigate to https://account.f5.com/myf5 and log in. @@ -39,44 +37,36 @@ If you want to register for a trial, navigate to https://account.f5.com/myf5. If 1. Find **F5 NGINX**. Sign up for the trial. 1. The trial may require approval. -
+{{< /details >}} -
-Confirm access to the F5 Distributed Cloud +{{< details summary="Confirm access to the F5 Distributed Cloud" >}} ### Confirm access to the F5 Distributed Cloud {{< include "/nginx-one/cloud-access.md" >}} -
+{{< /details >}} -
-Confirm access to NGINX One Console +{{< details summary="Confirm access to NGINX One Console" >}} ### Confirm access to NGINX One Console {{< include "/nginx-one/cloud-access-nginx.md" >}} -
+{{< /details >}} -
-Install an instance of NGINX +{{< details summary="Install an NGINX instance" >}} ### Install an instance of NGINX {{< include "/nginx-one/install-nginx.md" >}} -
+{{< /details >}} -
-Make sure you're running a supported Linux distribution - -NGINX Agent sets up communication between your NGINX Instance and NGINX One Console. Make sure your Linux operating system is listed below. The installation script for NGINX Agent is compatible with these distributions and versions. +{{< details summary="Check you're running a supported Linux distribution" >}} ### NGINX Agent installation script: supported distributions -{{}} - | Distribution | Version | Architecture | |------------------------------|----------------------|-----------------| | AlmaLinux | 8, 9 | x86_64, aarch64 | @@ -90,13 +80,7 @@ NGINX Agent sets up communication between your NGINX Instance and NGINX One Cons | Rocky Linux | 8, 9 | x86_64, aarch64 | | Ubuntu | 20.04 LTS, 22.04 LTS | x86_64, aarch64 | -{{}} - - - -
- ---- +{{< /details >}} ## Add your NGINX instances to NGINX One diff --git a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md index 4a174b64b..02dea81e7 100644 --- a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md +++ b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md @@ -1,12 +1,12 @@ --- +title: Installing NGINX Plus description: Install and upgrade F5 NGINX Plus with step-by-step instructions for the base package and dynamic modules on all supported Linux distributions. -nd-docs: DOCS-414 -title: Installing NGINX Plus toc: true weight: 100 -type: -- how-to +nd-content-type: how-to +nd-product: NGINX+ +nd-docs: DOCS-414 --- This article explains how to install NGINX Plus on different operating systems, upgrade existing NGINX Plus installation, install and enable dynamic modules, install in rootless mode or when offline. @@ -98,10 +98,13 @@ This article explains how to install NGINX Plus on different operating systems, sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-8.repo ``` -
- Learn how to pin NGINX Plus to a specific version - {{}}{{< include "nginx-plus/install/pin-to-version/pin-rhel8-R32.md" >}}{{}} -
+ {{< details summary="Pin NGINX Plus to a specific version" >}} + + {{< call-out "note">}} + {{< include "nginx-plus/install/pin-to-version/pin-rhel8-R32.md" >}} + {{< /call-out >}} + + {{< /details >}} 1. {{< include "nginx-plus/install/install-nginx-plus-package-dnf.md" >}} @@ -135,10 +138,13 @@ This article explains how to install NGINX Plus on different operating systems, sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/plus-9.repo ``` -
- Learn how to pin NGINX Plus to a specific version - {{}}{{< include "nginx-plus/install/pin-to-version/pin-rhel9-R32.md" >}}{{}} -
+ {{< details summary="Pin NGINX Plus to a specific version" >}} + + {{< call-out "note">}} + {{< include "nginx-plus/install/pin-to-version/pin-rhel9-R32.md" >}} + {{< /call-out >}} + + {{< /details >}} 1. {{< include "nginx-plus/install/install-nginx-plus-package-dnf.md" >}} @@ -216,10 +222,13 @@ NGINX Plus can be installed on the following versions of Debian or Ubuntu: | sudo tee /etc/apt/sources.list.d/nginx-plus.list ``` -
- Learn how to pin NGINX Plus to a specific version - {{}}{{< include "nginx-plus/install/pin-to-version/pin-debian-ubuntu-R32.md" >}}{{}} -
+ {{< details summary="Pin NGINX Plus to a specific version" >}} + + {{< call-out "note">}} + {{< include "nginx-plus/install/pin-to-version/pin-debian-ubuntu-R32.md" >}} + {{< /call-out >}} + + {{< /details >}} 1. Download the **nginx-plus** apt configuration to **/etc/apt/apt.conf.d**: diff --git a/content/nginxaas-azure/disaster-recovery.md b/content/nginxaas-azure/disaster-recovery.md index afa5d8927..675ca4c06 100644 --- a/content/nginxaas-azure/disaster-recovery.md +++ b/content/nginxaas-azure/disaster-recovery.md @@ -1,29 +1,23 @@ --- title: Disaster recovery -weight: 650 -toc: true url: /nginxaas/azure/disaster-recovery/ -type: -- how-to +toc: true +weight: 650 +nd-content-type: how-to +nd-product: N4Azure --- - This guide describes how to configure disaster recovery (DR) for F5 NGINXaaS for Azure deployments in separate (ideally [paired](https://learn.microsoft.com/en-us/azure/reliability/regions-paired)) Azure regions, ensuring upstream access remains available even if the primary NGINXaaS deployment in a region fails. The deployment architecture ensures users can access backend application servers (upstreams) continuously from an alternative region if the primary NGINXaaS deployment becomes unavailable. The solution leverages Terraform, Azure Traffic Manager, Azure Virtual Network (VNet) peering, and unique subnets to support failover. ---- - **Architecture Overview** {{< img src="nginxaas-azure/n4a-dr-topology.png" alt="The diagram illustrates the configuration of F5 NGINXaaS for Azure deployments for disaster recovery. It shows how the end users can still access the applications provided by AppServer - Primary1 and AppServer - Primary2 if the primary NGINXaaS deployment goes down." >}} - - Each region has its own VNet, subnet, and NGINXaaS for Azure deployment. - The NGINXaaS for Azure deployment needs to have a public frontend to leverage Azure Traffic Manager. - Cross region connectivity ensures that upstreams are reachable from either deployment. We use VNet peering in this guide to establish that connectivity. - Upstreams (for example, VMs) are accessible from either NGINX deployment. ---- - ## Prerequisites - Two Azure regions selected for DR. @@ -36,8 +30,6 @@ This guide describes how to configure disaster recovery (DR) for F5 NGINXaaS for - Secondary Region Virtual Network Address Space: `172.16.0.0/16` {{< /call-out >}} ---- - ## Configure disaster recovery ### Step 1: Terrraform setup @@ -65,8 +57,7 @@ terraform apply --auto-approve Each region requires its own VNet, subnet(s), public IP and network security group. -
-This sample Terraform code creates the prerequisite resources. +{{< details summary="Terraform code for necessary resources" >}} ```hcl # Primary Region @@ -168,16 +159,14 @@ resource "azurerm_subnet_network_security_group_association" "secondary_virtual_ network_security_group_id = azurerm_network_security_group.secondary_virtual_network_nsg.id } ``` -
---- +{{< /details >}} ### Step 3: Configure app servers (upstreams) You may already have upstreams in the primary region that you wish to reverse proxy using NGINXaaS. For the sake of completion, the following example shows creation of Primary Subnet 2, NICs for the upstreams and the upstreams themselves. The upstream VMs need to be in a subnet separate from the NGINXaaS deployment subnet in the **primary region**. -
-This sample Terraform code creates and configures the upstreams. +{{< details summary="Terraform code for creating and configuring upstreams" >}} ```hcl resource "azurerm_subnet" "primary_subnet_2" { @@ -228,19 +217,20 @@ resource "azurerm_linux_virtual_machine" "nginx_upstream_vm" { ) } ``` -
-
-> **Note**: As a best practice, maintain identical upstream resources in your secondary region as in your primary region to ensure full protection and availability in the event of a region-wide outage or disaster. +{{< /details >}} ---- +{{< call-out "note" >}} + +As a best practice, maintain identical upstream resources in your secondary region as in your primary region to ensure full protection and availability in the event of a region-wide outage or disaster. + +{{< /call-out >}} ### Step 4: Peer the VNets Peer the virtual networks so that the upstream app servers are accessible from either primary or secondary NGINXaaS deployment. -
-This sample Terraform code configures peering for the virtual networks. +{{< details summary="Terraform code for configuring virtual network peeting" >}} ```hcl resource "azurerm_virtual_network_peering" "primary_vnet_to_secondary_vnet" { @@ -257,22 +247,20 @@ resource "azurerm_virtual_network_peering" "secondary_vnet_to_primary_vnet" { remote_virtual_network_id = azurerm_virtual_network.primary_virtual_network.id } ``` -
-
+ +{{< /details >}} - **Subnet Peering for Overlapping VNets:** If overlapping address spaces are unavoidable, use subnet-level peering to selectively peer only the required subnets. {{< call-out "note" >}}As of May 2025, subnet peering is not available by default for all subscriptions. To use this feature, you must have the subscription on which you want to configure subnet peering be registered with Azure. Please review the configuration details and limitations in this [document](https://learn.microsoft.com/en-us/azure/virtual-network/how-to-configure-subnet-peering).{{< /call-out >}} ---- ### Step 5: Deploy NGINXaaS for Azure in each region Reverse proxy your upstreams using NGINXaaS. Since the virtual networks are peered, both deployments would be able to access the upstreams. -
-This sample Terraform code deploys and configures both primary and secondary NGINXaaS deployments. +{{< details summary="Terraform code for deploying and configuring primary and secondary NGINXaaS deployments" >}} ```hcl resource "azurerm_nginx_deployment" "primary_nginxaas_deployment" { @@ -391,17 +379,15 @@ EOT } } ``` -
---- +{{< /details >}} ### Step 6: DNS and failover - Use Azure Traffic Manager to direct traffic to the primary NGINXaaS deployment. - When the primary deployment is detected as being unhealthy, Azure Traffic Manager updates the public DNS record of your service to point to the public IP of the NGINXaaS deployment in the secondary region. -
-This sample Terraform code configures Azure Traffic Manager to point to both NGINXaaS deployments. +{{< details summary="Terraform code for configuring Azure Traffic Manager to point to both NGINXaaS deployments" >}} ```hcl resource "azurerm_traffic_manager_profile" "nginxaas_failover_monitor" { @@ -439,9 +425,8 @@ resource "azurerm_traffic_manager_external_endpoint" "secondary" { target = azurerm_nginx_deployment.secondary_nginxaas_deployment.ip_address } ``` -
---- +{{< /details >}} ## Failover process @@ -449,8 +434,6 @@ resource "azurerm_traffic_manager_external_endpoint" "secondary" { 1. **Failover**: If the primary region deployment is deemed unhealthy, Azure Traffic Manager updates the DNS record for the service to route traffic to the secondary region's NGINXaaS deployment. 1. **Recovery**: Once the primary region deployment recovers, Azure Traffic Manager automatically restores DNS records to the primary endpoint when its health probes detect recovery and confirm the primary endpoint is healthy again. ---- - ## Summary By deploying NGINXaaS in separate regions with unique subnets and peered VNets, and configuring upstreams and DNS for failover, this topology ensures high availability and DR for your applications. Lastly, always monitor and test your failover paths. diff --git a/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md b/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md index a18e13ad4..d5cc3cf92 100644 --- a/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md +++ b/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md @@ -1,11 +1,11 @@ --- title: Deploy using the Azure portal -weight: 100 +url: /nginxaas/azure/getting-started/create-deployment/deploy-azure-portal/ toc: true +weight: 100 +nd-content-type: how-to +nd-product: N4Azure nd-docs: DOCS-878 -url: /nginxaas/azure/getting-started/create-deployment/deploy-azure-portal/ -type: -- how-to --- ## Overview @@ -20,7 +20,6 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( 1. Use the search field to find "NGINXaaS" in the Azure Portal. In the Services results, select **NGINXaaS**. 1. Select **+ Create** on the **NGINXaaS** page to start the deployment process. - ## Create a deployment ### Basics tab @@ -66,9 +65,7 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( - If you plan on using an IPv6 address on the frontend, make sure the subnet is dual-stack, i.e., the subnet has both IPv4 and IPv6 address spaces. Attempting to use a subnet that is not dual-stack will cause deployment creation to fail. - Changes to a virtual network's DNS settings will not be applied automatically to your NGINXaaS deployment. To ensure DNS settings are applied, you must add any custom DNS servers to the VNET's DNS settings before creating an NGINXaaS deployment. As a workaround for existing deployments, we recommend using the [`resolver` directive](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) to explicitly specify your name server(s) and the [`resolve` parameter](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve) to automatically re-resolve the domain name of the server without restarting NGINX. -
- Example of using the resolver directive - For example, + {{< details summary="Resolver directive example" >}} ```nginx resolver 10.0.0.2 valid=10s; @@ -83,7 +80,7 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( } } ``` -
+ {{< /details >}} 1. Next, select **Tags**. diff --git a/content/nginxaas-azure/getting-started/nginx-configuration/overview.md b/content/nginxaas-azure/getting-started/nginx-configuration/overview.md index 1ac6ff7ad..b8028aaa0 100644 --- a/content/nginxaas-azure/getting-started/nginx-configuration/overview.md +++ b/content/nginxaas-azure/getting-started/nginx-configuration/overview.md @@ -88,11 +88,10 @@ Some directives cannot be overridden by the user provided configuration. ## Configuration directives list -
-Alphabetical index of directives - NGINXaaS for Azure supports a limited set of NGINX directives. +{{< details summary="Alphabetical index of directives">}} + [absolute_redirect](https://nginx.org/en/docs/http/ngx_http_core_module.html#absolute_redirect)\ [accept_mutex](https://nginx.org/en/docs/ngx_core_module.html#accept_mutex)\ [accept_mutex_delay](https://nginx.org/en/docs/ngx_core_module.html#accept_mutex_delay)\ @@ -925,10 +924,10 @@ NGINXaaS for Azure supports a limited set of NGINX directives. [zone_sync_ssl_verify](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_verify)\ [zone_sync_ssl_verify_depth](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_verify_depth)\ [zone_sync_timeout](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_timeout) -
-
-Lua dynamic module directives +{{< /details >}} + +{{< details summary="Lua dynamic module directives">}} [lua_load_resty_core](https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#lua_load_resty_core)\ [lua_use_default_type](https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#lua_use_default_type)\ @@ -1005,14 +1004,14 @@ NGINXaaS for Azure supports a limited set of NGINX directives. [lua_max_running_timers](https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#lua_max_running_timers)\ [lua_sa_restart](https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#lua_sa_restart)\ [lua_worker_thread_vm_pool_size](https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#lua_worker_thread_vm_pool_size) -
+{{< /details >}} -
-GeoIP2 dynamic module directives +{{< details summary="GeoIP2 dynamic module directives">}} [geoip2 (ngx_http_geo2_module)](https://github.com/leev/ngx_http_geoip2_module#user-content-download-maxmind-geolite2-database-optional)\ [geoip2 (ngx_stream_geo2_module)](https://github.com/leev/ngx_http_geoip2_module#user-content-download-maxmind-geolite2-database-optional)\ [geoip2_proxy (ngx_http_geo2_module)](https://github.com/leev/ngx_http_geoip2_module#user-content-download-maxmind-geolite2-database-optional)\ [geoip2_proxy_recursive (ngx_http_geo2_module)](https://github.com/leev/ngx_http_geoip2_module#user-content-download-maxmind-geolite2-database-optional)\ -
+ +{{< /details >}} \ No newline at end of file diff --git a/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md b/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md index f4b4a0693..2e340c567 100644 --- a/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md +++ b/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md @@ -1,10 +1,10 @@ --- title: Overview -weight: 50 -toc: true url: /nginxaas/azure/getting-started/ssl-tls-certificates/overview/ -type: -- how-to +toc: true +weight: 50 +nd-content-type: how-to +nd-product: N4Azure --- F5 NGINXaaS for Azure (NGINXaaS) enables customers to secure traffic by adding SSL/TLS certificates to a deployment. NGINXaaS can fetch certificates directly from Azure Key Vault, rotate certificates, and provide observability on the status of your certificates. @@ -62,25 +62,24 @@ For Azure client tools, such as the Azure CLI or Azure Resource Manager, the cer To view the status of your SSL/TLS certificates, [enable monitoring]({{< ref "/nginxaas-azure/monitoring/enable-monitoring.md" >}}) for your NGINXaaS deployment and navigate to the **Metrics** tab in the Azure portal. View the `nginxaas.certificates` metric under the `nginxaas statistics` metric namespace. The `nginxaas.certificates` metric allows you to filter by certificate name and the status of the certificate. The status dimension reports the health of your certificates through the following values: - {{< table >}} +{{< table >}} - | Status | Description | - | ------------- | ------------- | - | `active` | The certificate was successfully fetched from AKV. | - | `unauthorized`| Azure returned a 401/403 error when fetching the certificate from AKV, which usually indicates an issue with the deployment's [Managed Identity]({{< ref "/nginxaas-azure/getting-started/managed-identity-portal.md" >}}). | - | `not found` | Azure returned a 404 error when fetching the certificate from AKV. | - | `incompatible`| An error occurred while fetching or processing the certificate from AKV.

The possible reasons include:

| +| Status | Description | +| ------------- | ------------- | +| `active` | The certificate was successfully fetched from AKV. | +| `unauthorized`| Azure returned a 401/403 error when fetching the certificate from AKV, which usually indicates an issue with the deployment's [Managed Identity]({{< ref "/nginxaas-azure/getting-started/managed-identity-portal.md" >}}). | +| `not found` | Azure returned a 404 error when fetching the certificate from AKV. | +| `incompatible`| An error occurred while fetching or processing the certificate from AKV.

The possible reasons include:

| - {{< /table >}} +{{< /table >}} - {{< img src="nginxaas-azure/azure-metrics-nginxaas.certificates.png" alt="Interface screenshot showing the Azure metric nginxaas.certificates" >}} +{{< img src="nginxaas-azure/azure-metrics-nginxaas.certificates.png" alt="Interface screenshot showing the Azure metric nginxaas.certificates" >}} ## Common certificate errors The following section describes common errors you might encounter while adding SSL/TLS certificates to your NGINXaaS deployment and how to resolve them. -
-Expand to view common certificate errors +{{< details summary="Common certificate errors" >}} #### Error code: `ForbiddenByRbac` @@ -88,8 +87,7 @@ The following section describes common errors you might encounter while adding S **Resolution:** Assign the [Key Vault Secrets User](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#key-vault-secrets-user) role to the managed identity associated with your NGINXaaS deployment. -
-Create a role assignment - Azure CLI +{{< details summary="Create a role assignment using the CLI" >}} 1. Get the principal ID of the user or system assigned managed identity. @@ -130,7 +128,8 @@ The following section describes common errors you might encounter while adding S --role "Key Vault Secrets User" \ --scope $key_vault_id ``` -
+ +{{< /details >}} #### Error code: `AccessDenied` @@ -138,8 +137,7 @@ The following section describes common errors you might encounter while adding S **Resolution:** Assign an access policy to the managed identity associated with your NGINXaaS deployment with *Get secrets* permissions or higher. If you are using the Azure portal, assign an additional access policy to your user with *List certificates* permissions or higher. -
-Create an access policy - Azure CLI +{{< details summary="Create an access policy using the CLI" >}} 1. Get the principal ID of the user or system assigned managed identity. @@ -176,7 +174,8 @@ The following section describes common errors you might encounter while adding S --object-id $mi_principal_id \ --secret-permissions get ``` -
+ +{{< /details >}} #### Error code: `ForbiddenByFirewall` or `ForbiddenByConnection` @@ -187,8 +186,8 @@ The following section describes common errors you might encounter while adding S Allow NGINXaaS to access the key vault through one of these mechanisms: 1. [Configure Network Security Perimeter]({{< ref "/nginxaas-azure/quickstart/security-controls/certificates.md#configure-network-security-perimeter-nsp" >}}) to allow the subscription of the NGINXaaS deployment to access the key vault. -
-Create a network security perimeter - Azure CLI + +{{< details summary="Create a network security perimeter using the CLI" >}} 1. Create a network security perimeter. @@ -243,11 +242,12 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: --resource-group $NSP_RESOURCE_GROUP \ --subscriptions [0].id="/subscriptions/$DEP_SUBSCRIPTION_ID" ``` -
+ +{{< /details >}} 2. Integrate with a Private Endpoint to allow NGINXaaS to fetch certificates via Azure Private Link. -
-Create a Private Link - Azure CLI + +{{< details summary="Create a private link using the CLI" >}} 1. Get the resource ID of the key vault. @@ -314,12 +314,12 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: --private-dns-zone $ZONE_NAME \ --zone-name $ZONE_NAME ``` -
+ +{{< /details >}} 3. Allow access from Virtual Network delegated to NGINXaaS. -
-Allow Virtual Network access - Azure CLI +{{< details summary="Allow Virtual Network access using the CLI" >}} 1. Get the resource ID of the virtual network. @@ -355,7 +355,8 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: ``` {{< call-out "note" >}} Ensure that the Network Security Group on the subnet delegated to the NGINXaaS deployment allows outbound traffic to the internet{{< /call-out >}} -
+ +{{< /details >}} #### Error code: `AnotherOperationInProgress` @@ -381,8 +382,7 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: **Resolution:** Assign an access policy to the managed identity associated with your NGINXaaS deployment with *Get secrets* permissions or higher. If you are using the Azure portal, assign an additional access policy to your user with *List certificates* permissions or higher. -
-Create an access policy - Azure CLI +{{< details summary="Create an access policy using the CLI" >}} 1. Get the principal ID of the user or system assigned managed identity. @@ -419,7 +419,8 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: --object-id $mi_principal_id \ --secret-permissions get ``` -
+ +{{< /details >}} #### Error code: `DuplicateFilePathError` @@ -433,8 +434,7 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: **Resolution:** Enable the certificate in the key vault. -
-Enable a certificate in key vault - Azure CLI +{{< details summary="Enable a certificate in the key vault using the CLI" >}} 1. Get the resource ID of the certificate. @@ -451,7 +451,8 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: ```shell az keyvault certificate set-attributes --enabled true --id $certificate_id ``` -
+ +{{< /details >}} #### Error code: `NoCertificateContent` @@ -482,4 +483,5 @@ Allow NGINXaaS to access the key vault through one of these mechanisms: **Description:** The PEM certificate could not be parsed. **Resolution:** Ensure the file is not empty and contains properly formatted PEM certificate data. -
\ No newline at end of file + +{{< /details >}} \ No newline at end of file diff --git a/content/nginxaas-azure/quickstart/security-controls/oidc.md b/content/nginxaas-azure/quickstart/security-controls/oidc.md index 92fd47306..9dde16912 100644 --- a/content/nginxaas-azure/quickstart/security-controls/oidc.md +++ b/content/nginxaas-azure/quickstart/security-controls/oidc.md @@ -1,11 +1,11 @@ --- title: Set up OIDC authentication -weight: 300 +url: /nginxaas/azure/quickstart/security-controls/oidc/ toc: true +weight: 300 +nd-content-type: how-to +nd-product: N4Azure nd-docs: DOCS-1646 -url: /nginxaas/azure/quickstart/security-controls/oidc/ -type: -- how-to --- ## Overview @@ -26,7 +26,6 @@ These prerequisites are used for both methods of configuring NGINXaaS for Azure 2. Enable [Runtime State Sharing]({{< ref "/nginxaas-azure/quickstart/runtime-state-sharing.md" >}}) on the NGINXaaS deployment. - ## Configure NGINXaaS for Azure with IdP using Native OIDC This method applies to NGINX Plus Release 34 and later. In earlier versions, NGINX Plus relied on an njs-based solution, which required NGINX JavaScript files, key-value stores, and advanced OpenID Connect logic. In the latest NGINX Plus version, the new [OpenID Connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) simplifies this process to just a few directives. @@ -132,9 +131,7 @@ With your IdP configured, you can enable OIDC on NGINXaaS for Azure. ``` - -
- Complete configuration example of nginx.conf using the localhost as a upstream server + {{< details summary="Configuration example with localhost as an upstream server" >}} ```nginx http { @@ -208,7 +205,7 @@ With your IdP configured, you can enable OIDC on NGINXaaS for Azure. } } ``` -
+ {{< /details >}} 1. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details. @@ -293,8 +290,7 @@ Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus]( b. Add `include conf.d/openid_connect_configuration.conf;` in the http block before the server block. -
- Example of nginx.conf using the localhost as a upstream server + {{< details summary="Configuration example with localhost as an upstream server" >}} ```nginx load_module modules/ngx_http_js_module.so; @@ -370,7 +366,7 @@ Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus]( } } ``` -
+ {{< /details >}} 3. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details. diff --git a/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md b/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md index 69089b5b3..e5ee31ac4 100644 --- a/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md +++ b/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md @@ -1,10 +1,10 @@ --- title: Connect to upstreams with Azure Private Link -weight: 400 -toc: true url: /nginxaas/azure/quickstart/security-controls/private-link-to-upstreams/ -type: -- how-to +toc: true +weight: 400 +nd-content-type: how-to +nd-product: N4Azure --- [Azure Private Link](https://learn.microsoft.com/en-us/azure/private-link/private-link-overview) eliminates exposure to the public internet by handling traffic over Microsoft's backbone network. This is especially useful if your NGINXaaS deployment and your upstreams are in different virtual networks. @@ -26,8 +26,7 @@ A Private Link service is an Azure resource that enables Private Link access to The following example demonstrates this process using an existing virtual machine as the upstream. -
-Create a Private Link service - Azure CLI +{{< details summary="Create a Private Link service with the CLI" >}} ### Prerequisites @@ -137,7 +136,7 @@ $ az network private-link-service create \ --location $APP_LOCATION ``` -
+{{< /details >}} ## Create a private endpoint @@ -149,8 +148,7 @@ A private endpoint is a network interface that connects to a service powered by The following example demonstrates this process using an existing NGINXaaS deployment and a Private Link service. -
-Create a private endpoint - Azure CLI +{{< details summary="Create a private endpoint with the CLI" >}} ### Prerequisites @@ -220,14 +218,12 @@ upstream { } ``` -
- +{{< /details >}} ## Additional Resources The following guides provide step-by-step instructions to create a Private Link service and a private endpoint with your preferred client tool: - * [Azure portal](https://learn.microsoft.com/en-us/azure/private-link/create-private-link-service-portal?tabs=dynamic-ip) * [Azure CLI](https://learn.microsoft.com/en-us/azure/private-link/create-private-link-service-cli) * [ARM template](https://learn.microsoft.com/en-us/azure/private-link/create-private-link-service-template) diff --git a/content/nginxaas-google/getting-started/nginx-configuration/overview.md b/content/nginxaas-google/getting-started/nginx-configuration/overview.md index f237a7fcd..ed35664be 100644 --- a/content/nginxaas-google/getting-started/nginx-configuration/overview.md +++ b/content/nginxaas-google/getting-started/nginx-configuration/overview.md @@ -3,11 +3,10 @@ title: Overview weight: 50 toc: true url: /nginxaas/google/getting-started/nginx-configuration/overview/ -type: -- how-to +nd-content-type: reference +nd-product: N4GC --- - This document provides details about using NGINX configuration files with your F5 NGINXaaS for Google Cloud deployment, restrictions, and available directives. @@ -80,14 +79,13 @@ If you need access to additional directories, please [contact us]({{< ref "/ngin The following directives are not supported because of specific limitations. If you include any of these directives in your NGINX configuration, you'll get an error. - {{< table >}} - | Disallowed Directive | Reason | - |------------------ | ----------------- | - | ssl_engine | No hardware SSL accelerator is available. | - | debug_points | NGINXaaS does not provide access to NGINX processes for debugging. | - | fastcgi_bind
grpc_bind
memcached_bind
proxy_bind
scgi_bind
uwsgi_bind | Source IP specification for active-active deployments is not allowed. | - | quic_bpf | QUIC connection migration is not currently supported for active-active deployments. | - +{{< table >}} +| Disallowed Directive | Reason | +|------------------ | ----------------- | +| ssl_engine | No hardware SSL accelerator is available. | +| debug_points | NGINXaaS does not provide access to NGINX processes for debugging. | +| fastcgi_bind
grpc_bind
memcached_bind
proxy_bind
scgi_bind
uwsgi_bind | Source IP specification for active-active deployments is not allowed. | +| quic_bpf | QUIC connection migration is not currently supported for active-active deployments. | {{< /table >}} You may find a few directives are not listed here as either allowed or disallowed. Our team is working on getting these directives supported soon. @@ -96,25 +94,23 @@ You may find a few directives are not listed here as either allowed or disallowe The following directives cannot be overridden by the user provided configuration. - {{< table >}} - | Persistent Directive | Value | Reason | - |------------------ | ----------------------- | -----------------| - | `user` | `nginx` | The `nginx` user has the correct permissions for accessing certificates, policy files and other auxfiles. | - | `worker_processes` | `auto` | Set to `auto` to automatically set `worker_processes` to the number of CPU cores. | - | `pid` | `/run/nginx/nginx.pid` | Set to this value to allow NGINXaaS to automatically manage the NGINX master process. | - | `daemon` | `on` | Automatically set to `on` to allow NGINXaaS to manage the NGINX master process. | - | `master_process` | `on` | This directive is intended for NGINX developers. | - | `worker_cpu_affinity` | `auto` | The value `auto` allows binding worker processes automatically to available CPUs based on the current capacity of the deployment. | - +{{< table >}} +| Persistent Directive | Value | Reason | +|------------------ | ----------------------- | -----------------| +| `user` | `nginx` | The `nginx` user has the correct permissions for accessing certificates, policy files and other auxfiles. | +| `worker_processes` | `auto` | Set to `auto` to automatically set `worker_processes` to the number of CPU cores. | +| `pid` | `/run/nginx/nginx.pid` | Set to this value to allow NGINXaaS to automatically manage the NGINX master process. | +| `daemon` | `on` | Automatically set to `on` to allow NGINXaaS to manage the NGINX master process. | +| `master_process` | `on` | This directive is intended for NGINX developers. | +| `worker_cpu_affinity` | `auto` | The value `auto` allows binding worker processes automatically to available CPUs based on the current capacity of the deployment. | {{< /table >}} ## Configuration directives list -
-Alphabetical index of directives - NGINXaaS supports a limited set of NGINX directives. +{{< details summary="Alphabetical index of directives">}} + [absolute_redirect](https://nginx.org/en/docs/http/ngx_http_core_module.html#absolute_redirect)\ [accept_mutex](https://nginx.org/en/docs/ngx_core_module.html#accept_mutex)\ [accept_mutex_delay](https://nginx.org/en/docs/ngx_core_module.html#accept_mutex_delay)\ @@ -915,4 +911,5 @@ NGINXaaS supports a limited set of NGINX directives. [xslt_types](https://nginx.org/en/docs/http/ngx_http_xslt_module.html#xslt_types)\ [zone (ngx_http_upstream_module)](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone)\ [zone (ngx_stream_upstream_module)](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone)\ -
+ +{{< /details >}} diff --git a/content/nim/admin-guide/authentication/oidc/microsoft-entra-setup.md b/content/nim/admin-guide/authentication/oidc/microsoft-entra-setup.md index 66ef26b36..d493bbb38 100644 --- a/content/nim/admin-guide/authentication/oidc/microsoft-entra-setup.md +++ b/content/nim/admin-guide/authentication/oidc/microsoft-entra-setup.md @@ -1,10 +1,10 @@ --- -nd-docs: DOCS-795 title: 'Microsoft Entra: Set up OIDC authentication' toc: true weight: 100 -type: -- tutorial +nd-content-type: how-to +nd-product: NIM +nd-docs: DOCS-795 --- ## Overview @@ -18,21 +18,21 @@ To configure Microsoft Entra as an OIDC IdP, follow these steps: **Configure Microsoft Entra:** 1. Create an Application Registration for NGINX Instance Manager. -2. Add owners (users) and their email addresses to Microsoft Entra. -3. Create groups in Microsoft Entra and assign user membership. +1. Add owners (users) and their email addresses to Microsoft Entra. +1. Create groups in Microsoft Entra and assign user membership. **Configure NGINX Instance Manager:** 1. Add user groups to NGINX Instance Manager, using the same group names as in Microsoft Entra. -2. Configure NGINX Plus in NGINX Instance Manager to use Microsoft Entra as the designated identity provider. +1. Configure NGINX Plus in NGINX Instance Manager to use Microsoft Entra as the designated identity provider. -## Requirements +## Before you begin To successfully follow the instructions in this guide, you must complete the following requirements: 1. Create a [Microsoft Entra premium account](https://azure.microsoft.com/en-us/pricing/details/active-directory/). If you have a standard account, you'll need to upgrade. -2. [Install Instance Manager]({{< ref "/nim/deploy/vm-bare-metal/install.md" >}}) on a server that also has [NGINX Plus R25 or a newer version installed]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). Make sure the server hosting NGINX Plus has a fully qualified domain name (FQDN). -3. [Install the NGINX JavaScript module (njs)](https://www.nginx.com/blog/introduction-nginscript/) on the same server as Instance Manager. This module is necessary for managing communications between NGINX Plus and the identity provider. +1. [Install Instance Manager]({{< ref "/nim/deploy/vm-bare-metal/install.md" >}}) on a server that also has [NGINX Plus R25 or a newer version installed]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). Make sure the server hosting NGINX Plus has a fully qualified domain name (FQDN). +1. [Install the NGINX JavaScript module (njs)](https://www.nginx.com/blog/introduction-nginscript/) on the same server as Instance Manager. This module is necessary for managing communications between NGINX Plus and the identity provider. ## Configure Microsoft Entra {#configur-entra} @@ -43,18 +43,18 @@ Complete the steps in the section to configure Microsoft Entra for use with NGIN To register an application with Microsoft Entra: 1. Go to the [Azure portal](https://portal.azure.com/#home) and log in. -2. Select **Microsoft Entra** from the list of Azure services. -3. On the left navigation menu, under the **Manage** section, select **App registrations**. -4. Select **New registration**. -5. Provide the following details: +1. Select **Microsoft Entra** from the list of Azure services. +1. On the left navigation menu, under the **Manage** section, select **App registrations**. +1. Select **New registration**. +1. Provide the following details: - Enter a name for the application in the **Name** field, such as "NGINX Instance Manager". - Select **Account in this organizational directory only** from the list of account types. - Under the **Redirect URI** section, choose **Web** and enter the redirect URI, for example, `https:///_codexch`. {{< img src="/security/oidc/azure-register-app.png" alt="Azure: register an application." width="600" height="415" >}} -6. Select **Register**. -7. On the confirmation page, make a note of the following information. You'll need to provide this information later to complete the setup: +1. Select **Register**. +1. On the confirmation page, make a note of the following information. You'll need to provide this information later to complete the setup: - Application (client) ID - Directory (tenant) ID @@ -65,10 +65,10 @@ To register an application with Microsoft Entra: To create a client secret: 1. On the left navigation menu, under the **Manage** section, select **Certificates & secrets**. -2. Select **New client secret**. -3. In the **Description** box, type a description for the client secret. -4. Select **Add**. The client secret will be added to the list with a unique secret string value and ID. -5. Copy the value for the client secret. +1. Select **New client secret**. +1. In the **Description** box, type a description for the client secret. +1. Select **Add**. The client secret will be added to the list with a unique secret string value and ID. +1. Copy the value for the client secret. ### Add Owners {#az-ad-owners} @@ -87,9 +87,9 @@ To add owners (users): To include the user's group membership information in the token for authentication and authorization, follow these steps: 1. On the left navigation menu, under the **Manage** section, select **Token configuration**. -2. Select **Add groups claim**. -3. Select **Groups assigned to the application**. -4. Select **Add**. +1. Select **Add groups claim**. +1. Select **Groups assigned to the application**. +1. Select **Add**. ### Assign Group to Application {#az-ad-group} @@ -98,13 +98,13 @@ To include the user's group membership information in the token for authenticati Adding a group to the registered application will give all group members the same access. 1. On the left navigation menu, under the **Manage** section, select **Overview**. -2. In the **Essentials** section, select the link next to **Managed application in local directory**. -3. In the **Getting Started** section, select **Assign users and groups**. -4. Select **Add user/group**. -5. On the **Add Assignment** form, under the **Users and groups** section, select **None Selected**. -6. In the search box in the **Users and groups** drawer, type the name of the group you want to associate with the application. -7. Select the group from the list, and select **Select**. -8. Finally, select **Assign**. +1. In the **Essentials** section, select the link next to **Managed application in local directory**. +1. In the **Getting Started** section, select **Assign users and groups**. +1. Select **Add user/group**. +1. On the **Add Assignment** form, under the **Users and groups** section, select **None Selected**. +1. In the search box in the **Users and groups** drawer, type the name of the group you want to associate with the application. +1. Select the group from the list, and select **Select**. +1. Finally, select **Assign**. ## Configure NGINX Instance Manager {#configure-nginx-instance-manager} @@ -123,12 +123,12 @@ Configure NGINX Plus to use Microsoft Entra as the identity provider. 1. Install the NGINX JavaScript module (njs) on your NGINX Instance Manager server by running the appropriate command. This module is required for handling the interaction between NGINX Plus and Microsoft Entra (IdP). - CentOS, RHEL: - ```bash + ```shell sudo yum install nginx-plus-module-njs ``` - Debian, Ubuntu: - ```bash + ```shell sudo apt install nginx-plus-module-njs ``` @@ -142,8 +142,7 @@ Configure NGINX Plus to use Microsoft Entra as the identity provider. - `{tenant_key}`: Replace with the **Directory (tenant) ID** obtained when [registering the application](#az-ad-register-app). - `{client_secret}`: Replace with the encoded client secret that was generated when [creating the client secret](#az-ad-client-secret). -
- Example openid_configuration.conf + {{< details summary="Example openid_configuration.conf" >}} ```yaml # NGINX Instance Manager - OpenID Connect configuration @@ -174,12 +173,11 @@ Configure NGINX Plus to use Microsoft Entra as the identity provider. } ``` -
+ {{< /details >}} 4. Using a text editor, open the `/etc/nginx/conf.d/nms-http.conf` configuration file and uncomment the OIDC settings starting with `#OIDC`. Comment out the Basic Authentication settings. Save the changes. -
- Example nms-http.conf + {{< details summary="Example nms-http.conf" >}} ```yaml # NGINX Instance Manager - Instance Manager configuration @@ -195,19 +193,19 @@ Configure NGINX Plus to use Microsoft Entra as the identity provider. include /etc/nms/nginx/oidc/openid_connect.conf; ``` -
+ {{< /details >}} 5. Verify that the configuration file does not contain any errors: - ```bash + ```shell sudo nginx -t ``` 6. Reload NGINX and apply the configuration: - ```bash + ```shell sudo nginx -s reload ``` -## Try It Out +## Test Entrana OIDC 1. Open a web browser and go to the FQDN of your NGINX Instance Manager host. You will be redirected to the Microsoft Entra login page. -2. Enter your Microsoft Entra email address and password to log in. +1. Enter your Microsoft Entra email address and password to log in. diff --git a/content/nim/deploy/vm-bare-metal/install-nim-manual.md b/content/nim/deploy/vm-bare-metal/install-nim-manual.md index f486ee71b..9793e656d 100644 --- a/content/nim/deploy/vm-bare-metal/install-nim-manual.md +++ b/content/nim/deploy/vm-bare-metal/install-nim-manual.md @@ -1,12 +1,11 @@ --- -description: '' -nd-docs: DOCS-1211 title: Manually install any version of NGINX Instance Manager toc: true weight: 10 noindex: true -type: -- tutorial +nd-content-type: how-to +nd-product: NIM +nd-docs: DOCS-1211 --- ## Overview @@ -29,15 +28,13 @@ To install NGINX Instance Manager, you need the following: Allow external systems access by opening network firewalls. NGINX Instance Manager uses port `443` for both gRPC and API/web interfaces. ---- - ## Download Certificate and Key {#download-cert-key} Follow these steps to download the certificate and private key for NGINX Instance Manager. You'll need these files when adding the official repository for installing NGINX Instance Manager. You can also use the certificate and key when installing NGINX Plus. 1. On the host where you're installing NGINX Instance Manager, create the `/etc/ssl/nginx/` directory: - ``` bash + ```shell sudo mkdir -p /etc/ssl/nginx ``` @@ -45,43 +42,35 @@ Follow these steps to download the certificate and private key for NGINX Instanc 3. Move and rename the `.crt` and `.key` files: - ```bash + ```shell sudo mv /etc/ssl/nginx/nginx-repo.crt sudo mv /etc/ssl/nginx/nginx-repo.key ``` The downloaded filenames may vary depending on your subscription type. Modify the commands above accordingly to match the actual filenames. ---- - ## Install NGINX {#install-nginx} Install NGINX Open Source or NGINX Plus on the host where you'll install NGINX Instance Manager. NGINX Instance Manager uses NGINX as a front-end proxy and for managing user access. - [Installing NGINX and NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) -
- If you're installing NGINX Plus, you can use the `nginx-repo.key` and `nginx-repo.crt` that you added in the [previous section](#download-cert-key). -
- Supported NGINX versions +{{< details summary="Supported NGINX versions">}} {{< include "nim/tech-specs/supported-nginx-versions.md" >}} -
+{{< /details >}} -
- Supported Linux distributions +{{< details summary="Supported Linux distributions">}} {{< include "nim/tech-specs/supported-distros.md" >}} -
+{{< /details >}} Make sure to review the [Technical Specifications]({{< ref "/nim/fundamentals/tech-specs" >}}) guide for sizing requirements and other recommended specs. ---- - ## Configure metrics collection ### Disable metrics collection @@ -104,16 +93,12 @@ NGINX Instance Manager uses the following default values for ClickHouse. To chan {{< include "nim/clickhouse/clickhouse-defaults.md" >}} ---- - ## Add NGINX Instance Manager Repository {#add-nms-repo} To install NGINX Instance Manager, you need to add the official repository to pull the pre-compiled `deb` and `rpm` packages from. {{< include "installation/add-nms-repo.md" >}} ---- - ## Install Instance Manager {{}} @@ -122,11 +107,13 @@ To install NGINX Instance Manager, you need to add the official repository to pu 1. To install the latest version of Instance Manager, run the following command: - ```bash + ```shell sudo yum install -y nms-instance-manager ``` - > **IMPORTANT!** The Instance Manager's administrator username (default is `admin`) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely. + {{< call-out "warning" >}} + NGINX Instance Manager's administrator username (default is `admin`) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely. + {{< /call-out >}} {{%/tab%}} @@ -134,12 +121,14 @@ To install NGINX Instance Manager, you need to add the official repository to pu 1. To install the latest version of Instance Manager, run the following commands: - ```bash + ```shell sudo apt-get update sudo apt-get install -y nms-instance-manager ``` - > **IMPORTANT!** The Instance Manager's administrator username (default is `admin`) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely. + {{< call-out "warning" >}} + NGINX Instance Manager's administrator username (default is `admin`) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely. + {{< /call-out >}} {{%/tab%}} @@ -147,7 +136,7 @@ To install NGINX Instance Manager, you need to add the official repository to pu 2. Enable and start the NGINX Instance Manager platform services: - ```bash + ```shell sudo systemctl enable nms nms-core nms-dpm nms-ingestion nms-integrations --now ``` @@ -155,7 +144,7 @@ To install NGINX Instance Manager, you need to add the official repository to pu 3. Restart the NGINX web server: - ```bash + ```shell sudo systemctl restart nginx ``` @@ -169,7 +158,6 @@ To install NGINX Instance Manager, you need to add the official repository to pu {{< include "nim/installation/optional-steps/install-configure-vault.md" >}} - ### Configure SELinux {{< include "nim/installation/optional-steps/configure-selinux.md" >}} @@ -178,13 +166,10 @@ To install NGINX Instance Manager, you need to add the official repository to pu {{< include "installation/access-web-ui.md" >}} - ## Add License {{< include "nim/admin-guide/license/connected-install-license-note.md" >}} ---- - ## Upgrade Instance Manager {#upgrade-nim} {{}} @@ -192,7 +177,7 @@ To install NGINX Instance Manager, you need to add the official repository to pu 1. To upgrade to the latest version of the Instance Manager, run the following command: - ```bash + ```shell sudo yum update -y nms-instance-manager ``` @@ -202,7 +187,7 @@ To install NGINX Instance Manager, you need to add the official repository to pu 1. To upgrade to the latest version of the Instance Manager, run the following command: - ```bash + ```shell sudo apt-get update && \ sudo apt-get install -y --only-upgrade nms-instance-manager ``` @@ -212,7 +197,7 @@ To install NGINX Instance Manager, you need to add the official repository to pu 2. Restart the NGINX Instance Manager platform services: - ```bash + ```shell sudo systemctl restart nms ``` @@ -220,14 +205,12 @@ To install NGINX Instance Manager, you need to add the official repository to pu 3. Restart the NGINX web server: - ```bash + ```shell sudo systemctl restart nginx ``` 4. (Optional) If you use SELinux, follow the steps in the [Configure SELinux]({{< ref "nim/system-configuration/configure-selinux.md" >}}) guide to restore the default SELinux labels (`restorecon`) for the files and directories related to NGINX Management suite. ---- - ## Next steps - [Add NGINX Open Source and NGINX Plus instances to NGINX Instance Manager]({{< ref "nim/nginx-instances/add-instance.md" >}}) diff --git a/content/nim/monitoring/view-events-metrics.md b/content/nim/monitoring/view-events-metrics.md index 34a60bc7d..af9561e15 100644 --- a/content/nim/monitoring/view-events-metrics.md +++ b/content/nim/monitoring/view-events-metrics.md @@ -1,11 +1,11 @@ --- -description: Learn how to view events and metrics in F5 NGINX Instance Manager. -nd-docs: DOCS-847 title: View events and metrics +description: Learn how to view events and metrics in F5 NGINX Instance Manager. toc: true weight: 300 -type: -- how-to +nd-content-type: how-to +nd-product: NIM +nd-docs: DOCS-847 --- ## Overview @@ -19,9 +19,9 @@ F5 NGINX Instance Manager provides events and metrics data for your instances. Y To view events in the NGINX Instance Manager user interface, take the following steps: 1. In a web browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. In the **Platform** section, select **Events**. The **Events** overview page lists the events from the last six hours, with the most recent event listed first. -3. You can use the filters to filter events by level and time range, and sort events by selecting the column heading. -4. Select an event from the list to view the details. +1. In the **Platform** section, select **Events**. The **Events** overview page lists the events from the last six hours, with the most recent event listed first. +1. You can use the filters to filter events by level and time range, and sort events by selecting the column heading. +1. Select an event from the list to view the details. ## Access Events data by using the REST API @@ -37,8 +37,7 @@ To query the Events API, send a GET request similar to the following example to curl -X GET --url "https:///api/platform/v1/analytics/events" -H "Authorization: Bearer " ``` -
-Example Response +{{< details summary="Example response" >}} ```json { @@ -112,7 +111,7 @@ curl -X GET --url "https:///api/platform/v1/analytics/events" -H "Auth } ``` -
+{{< /details >}} ### Filter Events with Query Parameters @@ -234,8 +233,7 @@ Querying for a unique event requires only the event's UUID. curl -X GET --url "https:///api/platform/v1/analytics/events/7cb91de6-49ae-4ddc-a8b3-3255e00b9346" -H "Authorization: Bearer " ``` -
-Example response +{{< details summary="Example response" >}} ```json { @@ -255,8 +253,7 @@ curl -X GET --url "https:///api/platform/v1/analytics/events/7cb91de6- } ``` -
---- +{{< /details >}} ## View Metrics in the User Interface @@ -267,10 +264,10 @@ The **Metrics Summary** page includes a highlights section of the most important To view the metrics summary for an NGINX instance, take the following steps: 1. In a web browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. Under **Modules**, select the **Instance Manager**. -3. Select an instance on the **Instances** detail page. -4. Select the **Metrics Summary** tab. -5. To view detailed metrics as graphs, select the **Metrics** tab. +1. Under **Modules**, select the **Instance Manager**. +1. Select an instance on the **Instances** detail page. +1. Select the **Metrics Summary** tab. +1. To view detailed metrics as graphs, select the **Metrics** tab. {{< call-out "note" >}} Select a time range to change the period for the metrics display. The metrics data refreshes every 30 seconds. diff --git a/content/nim/nginx-app-protect/manage-waf-security-policies.md b/content/nim/nginx-app-protect/manage-waf-security-policies.md index 925543c31..ed70b069e 100644 --- a/content/nim/nginx-app-protect/manage-waf-security-policies.md +++ b/content/nim/nginx-app-protect/manage-waf-security-policies.md @@ -3,8 +3,8 @@ title: Manage and deploy WAF policies and log profiles description: Learn how to use F5 NGINX Instance Manager to manage F5 WAF for NGINX security policies and security log profiles. weight: 300 toc: true -type: how-to -product: NIM +nd-content-type: how-to +nd-product: NIM nd-docs: DOCS-1105 --- @@ -23,8 +23,6 @@ The following capabilities are available only through the Instance Manager REST - Publish security policies, log profiles, attack signatures, and threat campaigns to instances and instance groups {{< /call-out >}} ---- - ## Before you begin Before continuing, complete the following steps: @@ -50,8 +48,6 @@ To access the web interface, open a browser and go to the fully qualified domain {{< include "nim/how-to-access-nim-api.md" >}} ---- - ## Create a security policy {#create-security-policy} {{}} @@ -81,15 +77,10 @@ To upload a new security policy using the REST API, send a `POST` request to the You must encode the JSON policy using `base64`. If you send the policy in plain JSON, the request will fail. -{{}} - | Method | Endpoint | |--------|--------------------------------------| | POST | `/api/platform/v1/security/policies` | -{{}} - - For example: ```shell @@ -98,8 +89,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ -d @ignore-xss-example.json ``` -
-JSON Request +{{< details summary="JSON request" >}} ```json { @@ -112,10 +102,9 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ } ``` -
+{{< /details >}} -
-JSON Response +{{< details summary="JSON response" >}} ```json { @@ -134,31 +123,24 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ } ``` +{{< /details >}} + {{%/tab%}} {{}} ---- - ## Update a security policy - To update a security policy, send a `POST` or `PUT` request to the Security Policies API. - Use `POST` with the `isNewRevision=true` parameter to add a new version of an existing policy. - Use `PUT` with the policy UID to overwrite the existing version. - -{{}} - | Method | Endpoint | |--------|---------------------------------------------------------| | POST | `/api/platform/v1/security/policies?isNewRevision=true` | | PUT | `/api/platform/v1/security/policies/{system_id_string}` | -{{}} - - To use `POST`, include the policy metadata and content in your request: ```shell @@ -185,16 +167,12 @@ curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ After updating the policy, you can [publish it](#publish-policy) to selected instances or instance groups. ---- - ## Delete a security policy {{}} {{%tab name="web interface"%}} -
- To delete a security policy using the NGINX Instance Manager web interface: 1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. @@ -219,16 +197,10 @@ To delete a security policy using the REST API: 2. Send a `DELETE` request using the policy UID: - -{{}} - | Method | Endpoint | |--------|------------------------------------------------------------| | DELETE | `/api/platform/v1/security/policies/{security-policy-uid}` | -{{}} - - Example: ```shell @@ -240,11 +212,8 @@ curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/}} ---- - ## Create security policy bundles {#create-security-policy-bundles} - To create a security policy bundle, send a `POST` request to the Security Policy Bundles API. The policies you want to include in the bundle must already exist in NGINX Instance Manager. Each bundle includes: @@ -263,15 +232,10 @@ Each bundle includes: If you don’t include `attackSignatureVersionDateTime` or `threatCampaignVersionDateTime`, the latest versions are used by default. You can also set them explicitly by using `"latest"` as the value. - -{{}} - | Method | Endpoint | |--------|----------------------------------------------| | POST | `/api/platform/v1/security/policies/bundles` | -{{}} - Example: ```shell @@ -280,8 +244,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ -d @security-policy-bundles.json ``` -
-JSON Request +{{< details summary="JSON request" >}} ```json { @@ -306,10 +269,9 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` -
+{{< /details >}} -
-JSON Response +{{< details summary="JSON response" >}} ```json { @@ -368,7 +330,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` ---- +{{< /details >}} ## List security policy bundles {#list-security-policy-bundles} @@ -386,16 +348,10 @@ You can use the following query parameters to filter results: If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. - -{{}} - | Method | Endpoint | |--------|----------------------------------------------| | GET | `/api/platform/v1/security/policies/bundles` | -{{}} - - Example: ```shell @@ -403,8 +359,7 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " ``` -
-JSON Response +{{< details summary="JSON response" >}} ```json { @@ -463,7 +418,7 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` ---- +{{< /details >}} ## Get a security policy bundle {#get-security-policy-bundle} @@ -471,15 +426,10 @@ To retrieve a specific security policy bundle, send a `GET` request to the Secur You must have `"READ"` permission for the bundle to retrieve it. - -{{}} - | Method | Endpoint | |--------|-------------------------------------------------------------------------------------------------| | GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | -{{}} - Example: ```shell @@ -491,13 +441,12 @@ The response includes a content field that contains the bundle in base64 format. Example: -```bash +```shell curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz ``` -
-JSON Response +{{< details summary="JSON response" >}} ```json { @@ -518,7 +467,7 @@ curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies/ } ``` ---- +{{< /details >}} ## Create a security log profile {#create-security-log-profile} @@ -526,15 +475,10 @@ To upload a new security log profile, send a `POST` request to the Security Log You must encode the log profile in `base64` before sending it. If you send plain JSON, the request will fail. -{{}} - | Method | Endpoint | |--------|-----------------------------------------| | POST | `/api/platform/v1/security/logprofiles` | -{{}} - - Example: ```shell @@ -543,8 +487,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ -d @default-log-example.json ``` -
-JSON Request +{{< details summary="JSON request" >}} ```json { @@ -555,10 +498,9 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ } ``` -
+{{< /details >}} -
-JSON Response +{{< details summary="JSON response" >}} ```json { @@ -576,7 +518,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ } ``` ---- +{{< /details >}} ## Update a security log profile {#update-security-log-profile} @@ -585,16 +527,11 @@ To update a security log profile, you can either: - Use `POST` with the `isNewRevision=true` parameter to add a new version. - Use `PUT` with the log profile UID to overwrite the existing version. -{{}} - | Method | Endpoint | |--------|--------------------------------------------------------------------| | POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | | PUT | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | -{{}} - - To create a new revision: ```shell @@ -625,21 +562,14 @@ To overwrite an existing security log profile: After updating the security log profile, you can [publish it](#publish-policy) to specific instances or instance groups. ---- - ## Delete a security log profile {#delete-security-log-profile} To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. - -{{}} - | Method | Endpoint | |--------|--------------------------------------------------------------------| | DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | -{{}} - 1. Retrieve the UID: @@ -655,24 +585,16 @@ To delete a security log profile, send a `DELETE` request to the Security Log Pr -H "Authorization: Bearer " ``` ---- - ## Publish updates to instances {#publish-policy} Use the Publish API to push security policies, log profiles, attack signatures, and threat campaigns to NGINX instances or instance groups. Call this endpoint *after* you've created or updated the resources you want to deploy. - -{{}} - | Method | Endpoint | |--------|-------------------------------------| | POST | `/api/platform/v1/security/publish` | -{{}} - - Include the following information in your request, depending on what you're publishing: - Instance and instance group UIDs @@ -689,8 +611,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ -d @publish-request.json ``` -
-JSON Request +{{< details summary="JSON request" >}} ```json { @@ -723,10 +644,9 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ } ``` -
+{{< /details >}} -
-JSON Response +{{< details summary="JSON response" >}} ```json { @@ -742,9 +662,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ } ``` -
- ---- +{{< /details >}} ## Check security policy and security log profile publication status {#check-publication-status} @@ -756,14 +674,10 @@ Use the following endpoints to verify whether the configuration updates were suc To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. -{{}} - | Method | Endpoint | |--------|--------------------------------------------------------------------| | GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | -{{}} - Example: ```shell @@ -776,14 +690,10 @@ In the response, look for the `lastDeploymentDetails` field under instance or `i ### Check publication status for a security log profile -{{}} - | Method | Endpoint | |--------|-------------------------------------------------------------------------------------| | GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | -{{}} - Example: ```shell @@ -797,14 +707,10 @@ The response also contains `lastDeploymentDetails` for each instance or group. You can also view the deployment status for a specific instance by providing the system UID and instance UID. -{{}} - | Method | Endpoint | |--------|------------------------------------------------------------------| | GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | -{{}} - Example: ```shell @@ -818,14 +724,10 @@ In the response, look for the `lastDeploymentDetails` field, which shows the dep When you use the Publish API to [publish security content](#publish-policy), NGINX Instance Manager creates a deployment ID for the request. You can use this ID to check the result of the publication. -{{}} - | Method | Endpoint | |--------|------------------------------------------------------------------| | GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | -{{}} - Example: ```shell diff --git a/content/nim/nginx-app-protect/setup-waf-config-management.md b/content/nim/nginx-app-protect/setup-waf-config-management.md index 9f38ad6cc..0f6b8c678 100644 --- a/content/nim/nginx-app-protect/setup-waf-config-management.md +++ b/content/nim/nginx-app-protect/setup-waf-config-management.md @@ -1,10 +1,10 @@ --- title: Set up WAF configuration management -weight: 200 -toc: true description: Learn how to set up F5 NGINX Instance Manager to manage F5 WAF for NGINX configurations, including compiler installation, security policy onboarding, and threat update management. -type: how-to -product: NIM +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM nd-docs: DOCS-996 --- @@ -31,8 +31,6 @@ NGINX Instance Manager doesn’t support the following F5 WAF for NGINX features - [Policies with external references]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#external-references" >}}) - Custom signatures ---- - ## Install the WAF compiler NGINX Instance Manager can use the WAF compiler to precompile security configurations before deploying them to F5 WAF for NGINX instances. Precompiling configurations improves performance and reduces the risk of runtime errors. @@ -472,24 +470,23 @@ Follow these steps to get and upload the certificate and key: - `nginx-repo.key` (private key) 4. Create a JSON file that includes the contents of both files. Replace newlines (`\n`) in each file with literal `\n` characters so the certificate and key can be formatted correctly inside the JSON. -
- Example request - - ```json - { - "name": "nginx-repo", - "nginxResourceType": "NginxRepo", - "certPEMDetails": { - "caCerts": [], - "password": "", - "privateKey": "-----BEGIN PRIVATE KEY-----\n[content snipped]\n-----END PRIVATE KEY-----\n", - "publicCert": "-----BEGIN CERTIFICATE-----\n[content snipped]\n-----END CERTIFICATE-----", - "type": "PEM" - } + {{< details summary="Example request" >}} + + ```json + { + "name": "nginx-repo", + "nginxResourceType": "NginxRepo", + "certPEMDetails": { + "caCerts": [], + "password": "", + "privateKey": "-----BEGIN PRIVATE KEY-----\n[content snipped]\n-----END PRIVATE KEY-----\n", + "publicCert": "-----BEGIN CERTIFICATE-----\n[content snipped]\n-----END CERTIFICATE-----", + "type": "PEM" } - ``` + } + ``` -
+ {{< /details >}} 5. Upload the file to NGINX Instance Manager using the REST API: @@ -502,48 +499,49 @@ Follow these steps to get and upload the certificate and key: 6. If successful, you should see a response similar to this: -
- Example response + {{< details summary="Example response" >}} + + ```json + { + "certAssignmentDetails": [], + "certMetadata": [ + { + "authorityKeyIdentifier": "", + "commonName": "", + "expired": false, + "expiry": 59789838, + "issuer": "C=US, ST=Washington, L=Seattle, Inc., O=F5 Networks\\, OU=Certificate Authority, CN=F5 PRD Issuing Certificate Authority TEEM V1", + "publicKeyType": "RSA (2048 bit)", + "serialNumber": "", + "signatureAlgorithm": "SHA256-RSA", + "subject": "CN=", + "subjectAlternativeName": "", + "subjectKeyIdentifier": "", + "thumbprint": "", + "thumbprintAlgorithm": "SHA256-RSA", + "validFrom": "2021-12-21T16:57:55Z", + "validTo": "2024-12-20T00:00:00Z", + "version": 3 + } + ], + "certPEMDetails": { + "caCerts": [], + "password": "**********", + "privateKey": "**********", + "publicCert": "[content snipped]", + "type": "PEM" + }, + "created": "2023-01-27T23:42:41.587760092Z", + "modified": "2023-01-27T23:42:41.587760092Z", + "name": "nginx-repo", + "serialNumber": "", + "uid": "d08d9f54-58dd-447a-a71d-6fa5aa0d880c", + "validFrom": "2021-12-21T16:57:55Z", + "validTo": "2024-12-20T00:00:00Z" + } + ``` - ```json - { - "certAssignmentDetails": [], - "certMetadata": [ - { - "authorityKeyIdentifier": "", - "commonName": "", - "expired": false, - "expiry": 59789838, - "issuer": "C=US, ST=Washington, L=Seattle, Inc., O=F5 Networks\\, OU=Certificate Authority, CN=F5 PRD Issuing Certificate Authority TEEM V1", - "publicKeyType": "RSA (2048 bit)", - "serialNumber": "", - "signatureAlgorithm": "SHA256-RSA", - "subject": "CN=", - "subjectAlternativeName": "", - "subjectKeyIdentifier": "", - "thumbprint": "", - "thumbprintAlgorithm": "SHA256-RSA", - "validFrom": "2021-12-21T16:57:55Z", - "validTo": "2024-12-20T00:00:00Z", - "version": 3 - } - ], - "certPEMDetails": { - "caCerts": [], - "password": "**********", - "privateKey": "**********", - "publicCert": "[content snipped]", - "type": "PEM" - }, - "created": "2023-01-27T23:42:41.587760092Z", - "modified": "2023-01-27T23:42:41.587760092Z", - "name": "nginx-repo", - "serialNumber": "", - "uid": "d08d9f54-58dd-447a-a71d-6fa5aa0d880c", - "validFrom": "2021-12-21T16:57:55Z", - "validTo": "2024-12-20T00:00:00Z" - } - ``` + {{< /details >}} #### Enable automatic downloads diff --git a/content/nim/nginx-instances/scan-instances.md b/content/nim/nginx-instances/scan-instances.md index dab74144e..64ce534eb 100644 --- a/content/nim/nginx-instances/scan-instances.md +++ b/content/nim/nginx-instances/scan-instances.md @@ -1,18 +1,13 @@ --- -description: Follow the steps in this guide to scan for and discover NGINX instances. -nd-docs: DOCS-828 title: Scan and discover NGINX instances +description: Follow the steps in this guide to scan for and discover NGINX instances. toc: true weight: 110 -type: -- tutorial +nd-content-type: how-to +nd-product: NIM +nd-docs: DOCS-828 --- - - {{< shortversions "2.0.0" "latest" "nimvers" >}} ## Prerequisites {#prerequisites} @@ -48,8 +43,6 @@ To scan a single address, use the netmask of `/32` after the IP. This is the equ There's a CVE that's not reported for NGINX that involves [unfiltered logging](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-4487). This CVE won't be fixed, has a severity of "None," and is excluded from our scans' CVE list. {{< /call-out >}} ---- - ## Scan using the API {#scan-api} To start a scan using the Instance Manager API, send a POST request similar to the following example to the Scan endpoint, `https:///api/platform/v1/servers/scan`. @@ -92,9 +85,7 @@ curl -X GET "https:///api/v1/servers" -H "accept: The result looks similar to the following: -
- - Scan JSON response +{{< details summary="Scan JSON response" >}} ```json { @@ -271,9 +262,7 @@ The result looks similar to the following: } ``` -
- ---- +{{< /details >}} ## Troubleshooting diff --git a/content/nim/releases/release-notes.md b/content/nim/releases/release-notes.md index ce4fe33b5..23053188f 100644 --- a/content/nim/releases/release-notes.md +++ b/content/nim/releases/release-notes.md @@ -2,22 +2,18 @@ title: Release notes weight: 100 toc: true -type: reference -product: NIM +nd-content-type: reference +nd-product: NIM nd-docs: DOCS-938 --- The release notes for F5 NGINX Instance Manager highlight the latest features, improvements, and bug fixes in each release. This document helps you stay up to date with the changes and enhancements introduced to improve stability, performance, and usability. For each version, you’ll find details about new features, known issues, and resolved problems, ensuring you get the most out of your NGINX instance management experience. -
- Support for F5 WAF for NGINX +{{< details summary="Support for F5 WAF for NGINX" >}} {{< include "nim/tech-specs/nim-app-protect-support.md" >}} -
- - ---- +{{< /details >}} ## 2.20.0 diff --git a/content/nim/system-configuration/secure-traffic.md b/content/nim/system-configuration/secure-traffic.md index 4dbfd64e4..8612bd6dd 100644 --- a/content/nim/system-configuration/secure-traffic.md +++ b/content/nim/system-configuration/secure-traffic.md @@ -1,10 +1,10 @@ --- -nd-docs: DOCS-794 title: Secure client access and network traffic toc: true weight: 600 -type: -- tutorial +nd-content-type: how-to +nd-product: NIM +nd-docs: DOCS-794 --- {{< include "nim/decoupling/note-legacy-nms-references.md" >}} @@ -17,12 +17,10 @@ With NGINX Plus R33, telemetry data must be reported to a usage reporting endpoi {{< call-out "important" >}}Never expose your management server to the public internet. The settings in this guide reduce risk, but they can't replace keeping your server inaccessible to unauthorized users.{{< /call-out >}} -{{< call-out "tip" "See also:" "fa-solid fa-book" >}} +{{< call-out "tip" "See also:" >}} - To learn how to secure traffic for NGINX Agent, see [NGINX Agent TLS Settings](https://docs.nginx.com/nginx-agent/configuration/encrypt-communication/). - For details on NGINX Plus entitlement and usage reporting, see [About subscription licenses]({{< ref "solutions/about-subscription-licenses.md" >}}).{{< /call-out >}} ---- - ## NGINX Proxy SSL Termination SSL termination is the process where SSL-encrypted traffic is decrypted at the proxy, in this case, NGINX Instance Manager. Once decrypted, the traffic can be sent to its destination unencrypted or re-encrypted, depending on the configuration. @@ -33,8 +31,7 @@ Starting with NGINX Plus R33, you must also enable `ssl_verify` to verify the SS The example below shows how to set up SSL termination for NGINX Instance Manager: -
- /etc/nginx/conf.d/nms-http.conf +{{< details summary="/etc/nginx/conf.d/nms-http.conf" >}} ```nginx # Main external HTTPS server, needs port 443 @@ -55,11 +52,7 @@ server { ssl_client_certificate /etc/nms/certs/ca.pem; ``` -
- -
- ---- +{{< /details >}} ## Mutual Client Certificate Authentication Setup (mTLS) @@ -86,15 +79,15 @@ Follow these steps to set up mTLS using a Public Key Infrastructure (PKI) system To generate the necessary certificates, follow these steps. You can modify these instructions to suit your specific environment. 1. **Install OpenSSL** (if it isn't installed already). -2. **Create the certificate generation script**: +1. **Create the certificate generation script**: - Use the following example script to generate the certificates for your CA, server, and client. Save the script as `make_certs.sh`. -
- make_certs.sh + {{< details summary="make_certs.sh" >}} + - ```bash - #!/bin/bash + ```shell + #!/bin/shell set -e make_ca() { @@ -186,13 +179,12 @@ To generate the necessary certificates, follow these steps. You can modify these make_agent ``` -

+ {{< /details >}} 3. **Place the configuration files**: - Put the following OpenSSL `.cnf` files in the same directory as the `make_certs.sh` script. These files are needed to configure the certificate authority and generate the appropriate certificates. -
- ca.cnf + {{< details summary="ca.cnf" >}} {{}} {{}} @@ -218,10 +210,9 @@ To generate the necessary certificates, follow these steps. You can modify these subjectKeyIdentifier = hash ``` -
+ {{< /details >}} -
- ca-intermediate.cnf + {{< details summary="intermediate.cnf" >}} ``` yaml [req] @@ -245,10 +236,9 @@ To generate the necessary certificates, follow these steps. You can modify these subjectKeyIdentifier = hash ``` -
+ {{< /details >}} -
- server.cnf + {{< details summary="server.cnf" >}} ``` yaml [req] @@ -279,10 +269,9 @@ To generate the necessary certificates, follow these steps. You can modify these IP.1 = ``` -
+ {{< /details >}} -
- agent.cnf + {{< details summary="agent.cnf" >}} ``` yaml [req] @@ -307,12 +296,12 @@ To generate the necessary certificates, follow these steps. You can modify these extendedKeyUsage = critical, clientAuth ``` -

+ {{< /details >}} 4. **Run the script**: - After saving the script, make it executable and run it to generate the certificates. - ```bash + ```shell sudo chmod +x ./make_certs.sh sudo ./make_certs.sh ``` @@ -320,7 +309,7 @@ To generate the necessary certificates, follow these steps. You can modify these 5. **Copy the certificates to the NGINX instance**: - Once generated, copy the ca.pem, agent.crt, and agent.key files to the NGINX instance where the NGINX Agent certificates will be installed. - ```bash + ```shell sudo mkdir -p /etc/nms/certs sudo cp ca.pem /etc/nms/certs/ sudo cp agent.crt /etc/nms/certs/ @@ -334,8 +323,7 @@ To generate the necessary certificates, follow these steps. You can modify these {{< call-out "note" >}}For additional information about TLS configurations for the NGINX Agent, refer to the [NGINX Agent TLS Settings](https://docs.nginx.com/nginx-agent/configuration/encrypt-communication/) topic. {{< /call-out>}} -
- /etc/nginx-agent/nginx-agent.conf + {{< details summary="/etc/nginx-agent/nginx-agent.conf" >}} ```yaml {hl_lines=[8,22,23,24,25]} # @@ -383,7 +371,7 @@ To generate the necessary certificates, follow these steps. You can modify these bulk_size: 20 # specify metrics poll interval report_interval: 1m - collection_interval: 15s + collection_interval: 15s mode: aggregated # OSS NGINX default config path @@ -391,11 +379,11 @@ To generate the necessary certificates, follow these steps. You can modify these config_dirs: "/etc/nginx:/usr/local/etc/nginx" ``` -
+ {{< /details >}} 7. Copy `ca.pem`, `server.crt`, and `server.key` to NGINX Instance Manager. - ```bash + ```shell sudo cp ca.pem /etc/nms/certs/ sudo cp server.crt /etc/nms/certs/ sudo cp server.key /etc/nms/certs/ @@ -452,19 +440,17 @@ To generate the necessary certificates, follow these steps. You can modify these 9. **Reload NGINX proxy configuration**: - Apply the new settings by reloading NGINX proxy configuration. - ```bash + ```shell sudo nginx -s reload ``` 10. **Restart NGINX Agent**: - Start or restart NGINX Agent to apply the changes. - ```bash + ```shell sudo systemctl restart nginx-agent ``` ---- - ## Configure SSL verification for usage reporting with self-signed certificates {#configure-ssl-verify} {{}} @@ -509,8 +495,6 @@ mgmt { } ``` ---- - ## Troubleshooting If NGINX Agent and NGINX Instance Manager are having communication issues, follow these steps to troubleshoot: diff --git a/content/ossc.md b/content/ossc.md index 0a20c3ae0..eacd2e504 100644 --- a/content/ossc.md +++ b/content/ossc.md @@ -1,45 +1,31 @@ --- +title: Open source components +nd-content-type: reference nd-docs: DOCS-1343 -title: Open Source Components --- The F5 NGINX Docs website is made possible thanks to many contributors, which also includes the tools used to build it. We would like to draw attention to the maintainers of the following libraries, which are used to create the NGINX Docs: ---- - -## [Kube theme for Hugo](https://github.com/jeblister/kube) -Copyright © 2017 mohamed jebli -
- The MIT License (MIT) - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -
- ## [Redoc](https://github.com/Redocly/redoc) Copyright © 2015-present, Rebilly, Inc. -
- The MIT License (MIT) +{{< details summary="The MIT License (MIT)" >}} Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -
+ +{{< /details >}} ## [Lucide](https://lucide.dev/) Copyright © 2025 Lucide Contributors Copyright (c) 2013-2023 Cole Bemis -
- ISC License (ISC) +{{< details summary="ISC License (ISC)">}} Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2023 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2025. @@ -47,14 +33,14 @@ Permission to use, copy, modify, and/or distribute this software for any purpose THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -
+{{< /details >}} -
- The MIT License (MIT) +{{< details summary="The MIT License (MIT)" >}} Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -
\ No newline at end of file + +{{< /details >}} \ No newline at end of file diff --git a/content/solutions/about-subscription-licenses/getting-started.md b/content/solutions/about-subscription-licenses/getting-started.md index 2dfcef013..7d3374bc0 100644 --- a/content/solutions/about-subscription-licenses/getting-started.md +++ b/content/solutions/about-subscription-licenses/getting-started.md @@ -2,12 +2,10 @@ title: Getting started toc: true weight: 200 -nd-content-type: - - tutorial +nd-content-type: how-to nd-product: Solutions +nd-resource: https://lucid.app/lucidchart/0abcb9d3-b36e-40af-b56a-e74771b384d5/edit?invitationId=inv_8ccda3dc-2306-468c-9cb6-b4684be1360f&page=0_0# 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. @@ -24,8 +22,6 @@ If you have multiple subscriptions, you’ll also have multiple JWT licenses. Yo 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. @@ -48,14 +44,10 @@ 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: @@ -69,13 +61,10 @@ Both methods ensure your NGINX Plus instances have access to the required licens Choose the option that fits your environment: -
-Deploy with a group sync feature (recommended) +{{< details summary="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" "" >}} @@ -83,33 +72,25 @@ In NGINX Instance Manager, *instance groups* provide the same sync functionality See [Manage instance groups]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}) for setup instructions. {{< /call-out >}} -
+{{< /details >}} -
-Deploy manually +{{< details summary="Deploy manually" >}} ### Deploy manually -
- Copy the JWT license file to each NGINX Plus instance. {{< include "/licensing-and-reporting/apply-jwt.md" >}} -
+{{< /details >}} -
-Use custom paths +{{< details summary="Use custom paths" >}} ### Custom paths {#custom-paths} -
- {{< include "licensing-and-reporting/custom-paths-jwt.md" >}} -
- ---- +{{< /details >}} ## Prepare your environment for reporting {#set-up-environment} @@ -117,17 +98,12 @@ NGINX Plus R33 and later must send usage reports. Choose the setup steps that match your environment: -
-Configure reporting in internet-connected environments +{{< details summary="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: @@ -146,29 +122,21 @@ Allow the necessary outbound traffic so reports can reach F5. } ``` -
+{{< /details >}} -
-Configure reporting in network-restricted environments +{{< details summary="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 >}} - -
+{{< /details >}} ### Postpone reporting enforcement {#postpone-reporting-enforcement} @@ -188,8 +156,6 @@ 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: @@ -197,13 +163,10 @@ How you update the JWT license depends on your NGINX Plus release and environmen - 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) +{{< details summary="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: @@ -224,36 +187,27 @@ Automatic updates only work if: If these conditions aren’t met, you must [update the JWT license manually](#manually-update-license). {{< /call-out >}} -
+{{< /details >}} -
-Update the license manually (all releases) +{{< details summary="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. +1. [Deploy the JWT license](#deploy-jwt) to your NGINX Plus instances. -
- ---- +{{< /details >}} ## 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