From 9d6f868aeb5289dc23c3a110045eaeb2f0585f3f Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 10:28:57 -0700 Subject: [PATCH 01/25] Draft: new N1C doc homepage --- .../agent/installation/install-agent-api.md | 83 +- .../includes/nap-waf/build-nginx-image-cmd.md | 2 +- .../nginx-one/add-file/existing-ssl-bundle.md | 2 +- .../learn-about-deployment.md | 6 +- content/nap-waf/v4/admin-guide/install.md | 4 +- content/nap-waf/v5/admin-guide/compiler.md | 2 +- content/ngf/overview/custom-policies.md | 9 +- content/ngf/overview/product-telemetry.md | 3 +- content/nginx-one/about.md | 2 +- content/nginx-one/api/_index.md | 4 +- content/nginx-one/certificates/_index.md | 6 + .../certificates/manage-certificates.md | 197 +++++ content/nginx-one/changelog.md | 10 +- .../nginx-one/config-sync-groups/_index.md | 6 + .../config-sync-groups/add-file-csg.md | 67 ++ .../manage-config-sync-groups.md | 261 ++++++ content/nginx-one/glossary.md | 4 +- content/nginx-one/how-to/_index.md | 2 +- content/nginx-one/nginx-configs/_index.md | 6 + content/nginx-one/nginx-configs/add-file.md | 67 ++ .../nginx-one/nginx-configs/add-instance.md | 75 ++ .../clean-up-unavailable-instances.md | 40 + .../manage-config-sync-groups.md | 239 ++++++ .../view-edit-nginx-configurations.md | 41 + content/nginx-one/rbac/_index.md | 4 +- content/nginx-one/staged-configs/_index.md | 6 + .../staged-configs/add-staged-config.md | 88 ++ .../staged-configs/api-staged-config.md | 20 + .../staged-configs/edit-staged-config.md | 38 + .../load-balancer/tcp-udp-load-balancer.md | 40 +- .../load-balancer/udp-health-check.md | 160 +--- .../manage-waf-security-policies.md | 763 ++++++++++++------ .../overview-nap-waf-config-management.md | 72 +- .../waf-config-management.md | 30 + layouts/partials/list-main.html | 30 +- 35 files changed, 1855 insertions(+), 534 deletions(-) create mode 100644 content/nginx-one/certificates/_index.md create mode 100644 content/nginx-one/certificates/manage-certificates.md create mode 100644 content/nginx-one/config-sync-groups/_index.md create mode 100644 content/nginx-one/config-sync-groups/add-file-csg.md create mode 100644 content/nginx-one/config-sync-groups/manage-config-sync-groups.md create mode 100644 content/nginx-one/nginx-configs/_index.md create mode 100644 content/nginx-one/nginx-configs/add-file.md create mode 100644 content/nginx-one/nginx-configs/add-instance.md create mode 100644 content/nginx-one/nginx-configs/clean-up-unavailable-instances.md create mode 100644 content/nginx-one/nginx-configs/manage-config-sync-groups.md create mode 100644 content/nginx-one/nginx-configs/view-edit-nginx-configurations.md create mode 100644 content/nginx-one/staged-configs/_index.md create mode 100644 content/nginx-one/staged-configs/add-staged-config.md create mode 100644 content/nginx-one/staged-configs/api-staged-config.md create mode 100644 content/nginx-one/staged-configs/edit-staged-config.md create mode 100644 content/nim/nginx-app-protect/waf-config-management.md diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 15009d21f..95a9650aa 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -1,75 +1,74 @@ ---- -docs: DOCS-1031 -files: - - content/nim/nginx-app-protect/setup-waf-config-management.md ---- - -{{}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{}} - -If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands: +**Note**: To complete this step, make sure that `gpg` is installed on your system. You can install NGINX Agent using various command-line tools like `curl` or `wget`. If your NGINX Instance Manager host is not set up with valid TLS certificates, you can use the insecure flags provided by those tools. See the following examples: {{}} {{%tab name="curl"%}} -- **Secure:** +- Secure: ```bash - curl https:///install/nginx-agent | sudo sh + curl https:///install/nginx-agent | sudo sh ``` -- **Insecure:** +- Insecure: ```bash - curl --insecure https:///install/nginx-agent | sudo sh + curl --insecure https:///install/nginx-agent | sudo sh ``` -To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag: + You can add your NGINX instance to an existing instance group or create one using `--instance-group` or `-g` flag when installing NGINX Agent. + + The following example shows how to download and run the script with the optional `--instance-group` flag adding the NGINX instance to the instance group **my-instance-group**: + + ```bash + curl https:///install/nginx-agent > install.sh; chmod u+x install.sh + sudo ./install.sh --instance-group my-instance-group + ``` -```shell -curl https:///install/nginx-agent -o install.sh -chmod u+x install.sh -sudo ./install.sh --instance-group -``` + By default, the install script attempts to use a secure connection when downloading packages. If, however, the script cannot create a secure connection, it uses an insecure connection instead and logs the following warning message: -By default, the install script uses a secure connection to download packages. If it can’t establish one, it falls back to an insecure connection and logs this message: + ``` text + Warning: An insecure connection will be used during this nginx-agent installation + ``` -```text -Warning: An insecure connection will be used during this nginx-agent installation -``` + To require a secure connection, you can set the optional flag `skip-verify` to `false`. -To enforce a secure connection, set the `--skip-verify` flag to false: + The following example shows how to download and run the script with an enforced secure connection: -```shell -curl https:///install/nginx-agent -o install.sh -chmod u+x install.sh -sudo ./install.sh --skip-verify false -``` + ```bash + curl https:///install/nginx-agent > install.sh chmod u+x install.sh; chmod u+x install.sh + sudo sh ./install.sh --skip-verify false + ``` {{%/tab%}} {{%tab name="wget"%}} -- **Secure:** - ```shell - wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false +- Secure: + + ```bash + wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false ``` -- **Insecure:** +- Insecure: - ```shell - wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh + ```bash + wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh ``` -To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag: + When you install the NGINX Agent, you can use the `--instance-group` or `-g` flag to add your NGINX instance to an existing instance group or to a new group that you specify. -```shell -wget https:///install/nginx-agent -O install.sh -chmod u+x install.sh -sudo ./install.sh --instance-group -``` + The following example downloads and runs the NGINX Agent install script with the optional `--instance-group` flag, adding the NGINX instance to the instance group **my-instance-group**: + + ```bash + wget https://gnms1.npi.f5net.com/install/nginx-agent -O install.sh ; chmod u+x install.sh + sudo ./install.sh --instance-group my-instance-group + ``` -{{%/tab%}} +{{%/tab%}} {{}} + + + diff --git a/content/includes/nap-waf/build-nginx-image-cmd.md b/content/includes/nap-waf/build-nginx-image-cmd.md index fcb89d363..41bf90d03 100644 --- a/content/includes/nap-waf/build-nginx-image-cmd.md +++ b/content/includes/nap-waf/build-nginx-image-cmd.md @@ -10,7 +10,7 @@ To build the image, execute the following command in the directory containing th ```shell -sudo docker build --no-cache --platform linux/amd64 \ +sudo docker build --no-cache \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t nginx-app-protect-5 . diff --git a/content/includes/nginx-one/add-file/existing-ssl-bundle.md b/content/includes/nginx-one/add-file/existing-ssl-bundle.md index e6a8c59a4..250669d3e 100644 --- a/content/includes/nginx-one/add-file/existing-ssl-bundle.md +++ b/content/includes/nginx-one/add-file/existing-ssl-bundle.md @@ -2,7 +2,7 @@ docs: --- -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). +With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). In the **Choose Certificate** drop-down, select the managed certificate of your choice, and select **Add**. You can then: 1. Review details of the certificate. The next steps depend on whether the certificate is a CA bundle or a certificate / key pair. diff --git a/content/nap-dos/deployment-guide/learn-about-deployment.md b/content/nap-dos/deployment-guide/learn-about-deployment.md index 430fd9e2e..df137bd2e 100644 --- a/content/nap-dos/deployment-guide/learn-about-deployment.md +++ b/content/nap-dos/deployment-guide/learn-about-deployment.md @@ -1405,7 +1405,7 @@ You need root permissions to execute the following steps. 6. Create a Docker image: ```shell - docker build --no-cache --platform linux/amd64 -t app-protect-dos . + docker build --no-cache -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. @@ -1966,13 +1966,13 @@ Make sure to replace upstream and proxy pass directives in this example with rel For CentOS: ```shell - docker build --no-cache --platform linux/amd64 -t app-protect-dos . + docker build --no-cache -t app-protect-dos . ``` For RHEL: ```shell - docker build --platform linux/amd64 --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . + docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. diff --git a/content/nap-waf/v4/admin-guide/install.md b/content/nap-waf/v4/admin-guide/install.md index c3e0575dc..3158ac9d3 100644 --- a/content/nap-waf/v4/admin-guide/install.md +++ b/content/nap-waf/v4/admin-guide/install.md @@ -939,7 +939,7 @@ If a user other than **nginx** is to be used, note the following: - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . + DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). @@ -1289,7 +1289,7 @@ You need root permissions to execute the following steps. - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . + DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). diff --git a/content/nap-waf/v5/admin-guide/compiler.md b/content/nap-waf/v5/admin-guide/compiler.md index ea0f28500..dd0e828e4 100644 --- a/content/nap-waf/v5/admin-guide/compiler.md +++ b/content/nap-waf/v5/admin-guide/compiler.md @@ -98,7 +98,7 @@ curl -s https://private-registry.nginx.com/v2/nap/waf-compiler/tags/list --key < Run the command below to build your image, where `waf-compiler-:custom` is an example of the image tag: ```shell - sudo docker build --no-cache --platform linux/amd64 \ + sudo docker build --no-cache \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t waf-compiler-:custom . diff --git a/content/ngf/overview/custom-policies.md b/content/ngf/overview/custom-policies.md index 5aeb99fce..c7e5a785d 100644 --- a/content/ngf/overview/custom-policies.md +++ b/content/ngf/overview/custom-policies.md @@ -17,11 +17,10 @@ The following table summarizes NGINX Gateway Fabric custom policies: {{< bootstrap-table "table table-striped table-bordered" >}} -| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | -|---------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| -| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | -| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | -| [UpstreamSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/upstream-settings.md" >}}) | Configure connection behavior between NGINX and backend | Direct | Service | Yes | Yes | v1alpha1 | +| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | +|---------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| +| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | +| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha1 | {{< /bootstrap-table >}} diff --git a/content/ngf/overview/product-telemetry.md b/content/ngf/overview/product-telemetry.md index 3c73a4cb5..cd9f7a20f 100644 --- a/content/ngf/overview/product-telemetry.md +++ b/content/ngf/overview/product-telemetry.md @@ -32,8 +32,7 @@ Telemetry data is collected once every 24 hours and sent to a service managed by - **Image Build Source:** whether the image was built by GitHub or locally (values are `gha`, `local`, or `unknown`). The source repository of the images is **not** collected. - **Deployment Flags:** a list of NGINX Gateway Fabric Deployment flags that are specified by a user. The actual values of non-boolean flags are **not** collected; we only record that they are either `true` or `false` for boolean flags and `default` or `user-defined` for the rest. - **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected. -- **SnippetsFilters Info:** a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. - +- **SnippetsFilters Info**a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. This data is used to identify the following information: - The flavors of Kubernetes environments that are most popular among our users. diff --git a/content/nginx-one/about.md b/content/nginx-one/about.md index f20c40bea..6d0dd4594 100644 --- a/content/nginx-one/about.md +++ b/content/nginx-one/about.md @@ -1,7 +1,7 @@ --- description: '' docs: DOCS-1392 -title: About +title: Manage your NGINX fleet toc: true weight: 10 type: diff --git a/content/nginx-one/api/_index.md b/content/nginx-one/api/_index.md index e1f50db88..1fe244a36 100644 --- a/content/nginx-one/api/_index.md +++ b/content/nginx-one/api/_index.md @@ -1,6 +1,6 @@ --- -title: API +title: NGINX One API description: weight: 1000 url: /nginx-one/api ---- \ No newline at end of file +--- diff --git a/content/nginx-one/certificates/_index.md b/content/nginx-one/certificates/_index.md new file mode 100644 index 000000000..0ea28d683 --- /dev/null +++ b/content/nginx-one/certificates/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Monitor your certificates +weight: 400 +url: /nginx-one/certificates +--- diff --git a/content/nginx-one/certificates/manage-certificates.md b/content/nginx-one/certificates/manage-certificates.md new file mode 100644 index 000000000..13c532e38 --- /dev/null +++ b/content/nginx-one/certificates/manage-certificates.md @@ -0,0 +1,197 @@ +--- +docs: null +title: Manage certificates +toc: true +weight: 100 +type: +- how-to +--- + +## Overview + +This guide explains how you can manage SSL/TLS certificates with the F5 NGINX One Console. Valid certificates support encrypted connections between NGINX and your users. + +You may have separate sets of SSL/TLS certificates, as described in the following table: + +{{}} +| Functionality | Typical file names | Notes | +|-------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------| +| Website traffic | /etc/nginx/ssl/example.com.crt
/etc/nginx/ssl/example.com.key | Typically purchased from a Certificate Authority (CA) | +| Repository access | /etc/ssl/nginx/nginx-repo.crt
/etc/ssl/nginx/nginx-repo.key | Supports access to repositories to download and install NGINX packages | +| NGINX Licensing | /etc/ssl/nginx/server.crt
/etc/ssl/nginx/server.key | Supports access to repositories. Based on licenses downloaded from https://my.f5.com/ | +{{}} + +Allowed directories depend on the [NGINX Agent]({{< ref "/nginx-one/getting-started/#install-nginx-agent" >}}). Look for the `/etc/nginx-agent/nginx-agent.conf` file. +Find the `config_dirs` parameter in that file, as described in the NGINX Agent [Basic configuration](https://docs.nginx.com/nginx-agent/configuration/configuration-overview/#cli-flags--environment-variables). +You may need to add a directory like `/etc/ssl` to that parameter. + +From the NGINX One Console you can: + +- Monitor all certificates configured for use by your connected NGINX Instances. +- Ensure that your certificates are current and correct. +- Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. + +You can manage the certificates for: + +- [Unique instances]({{< ref "/nginx-one/nginx-configs/add-file.md#new-ssl-certificate-or-ca-bundle" >}}) +- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) + + +{{< tip >}} + +If you are managing the certificate from NGINX One Console, we recommend that you avoid directly manipulating the files on the data plane. + +{{< /tip >}} + +## Before you start + +Before you add and manage certificates with the NGINX One Console make sure: + +- You have access to the NGINX One Console +- You have access through the F5 Distributed Cloud role, as described in the [Authentication]({{< ref "/nginx-one/api/authentication.md" >}}) guide, to manage SSL/TLS certificates + - You have the `f5xc-nginx-one-user` role for your account +- Your SSL/TLS certificates and keys match + +### SSL/TLS certificates and more + +NGINX One Console supports certificates for access to repositories. You may need a copy of these files from your Certificate Authority (CA) to upload them to NGINX One Console: + +- SSL Certificate + - Example file extensions: .crt, .pem +- Privacy certificate + - Example file extensions: .key, .pem + +The NGINX One Console allows you to upload these certificates as text and as files. You can also upload your own certificate files (with file extensions such as .crt and .key). + +Make sure your certificates, keys, and pem files are encrypted to one of the following standards: + +- RSA +- ECC/ECDSA + +In other words, any private key of this type should be supported, regardless of the curve types or hashing algorithm. + +For exmaple, if you use ECDSA private keys in PEM format, the PEM headers should contain: + +``` +-----BEGIN EC PRIVATE KEY----- + +-----END EC PRIVATE KEY----- + +``` + +If you use one of these keys, the US National Institute of Standards and Technology, in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf), recommends a key size of at least +2048 bits. It also has recommnedations for ECDSA. + +### Include certificates in NGINX configuration + +For NGINX configuration, these files are typically associated with the following NGINX directives: + +- [`ssl_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate) +- [`ssl_certificate_key`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate_key) +- [`ssl_trusted_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_trusted_certificate) +- [`ssl_client_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) +- [`proxy_ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate) +- [`proxy_ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate_key) + +## Important considerations + +Most websites include valid information from public keys and certificates or CA bundles. However, the NGINX One Console accepts, but provides warnings for these use cases: + +- When the public certificate is expired +- When the leaf certificate part of a certificate chain is expired +- When any of the components of a CA bundle are expired +- When the public key does not match the private certificate + +In such cases, you may get websites that present "Your connection is not private" warning messages in client web browsers. + +## Review existing certificates + +Follow these steps to review existing certificates for your instances. + +On the left-hand pane, select **Certificates**. In the window that appears, you see: + +{{}} +| Term | Definition | +|-------------|-------------| +| **Total** | Total number of certificates available to NGINX One Console | +| **Valid (31+ days)** | Number of certificates that expire in 31 or more days | +| **Expires Soon (<31 days)** | Number of certificates that expire in less than 31 days | +| **Expired** | Number of exprired certificates | +| **Not Ready** | Certificates with a start date in the future | +| **Managed** | Managed by and stored in the NGINX One Console | +| **Unmanaged** | Detected by, and not managed by NGINX One Console. To convert to managed, you may need to upload the certificate and key during the process. | +{{}} + +You can **Add Filter** to filter certificates by: + +- Name +- Status +- Subject Name +- Type + +The Export option supports exports of basic certification file information to a CSV file. It does _not_ include the content of the public certificate or the private key. + +## Add a new certificate or bundle + +To add a new certificate, select **Add Certificate**. + + +In the screen that appears, you can add a certificate name. If you don't add a name, NGINX One will add a name for you, based on the expiration date for the certificate. + +You can add certificates in the following formats: + +- **SSL Certificate and Key** +- **CA Certificate Bundle** + +In each case, you can upload files directly, or enter the content of the certificates in a text box. Once you upload these certificates, you'll see: + +- **Certificate Details**, with the Subject Name, start and end dates. +- **Key Details**, with the encryption key size and algorithm, such as RSA + + +## Edit an existing certificate or bundle + +You can modify existing certificates from the **Certificates** screen. Select the certificate of your choice. Depending on the type of certificate, you'll then see either a **Edit Certificate** or **Edit CA Bundle** option. The NGINX One Console then presents a window with the same options as shown when you [Add a new certificate](#add-a-new-certificate-or-bundle). + +If that certificate is already managed as part of a Config Sync Group, the changes you make affect all instances in that group. + +## Remove a deployed certificate + +You can remove a deployed certificate from an independent instance or from a Config Sync Group. This will remove the certificate's association with the instance or group, but it does not delete the certificate files from the instance(s). + +Every instance with a deployed certificate includes paths to certificates in their configuration files. If you remove the deployed file path to one certificate, that change is limited to that one instance. + +Every Config Sync Group also includes paths to certificates in its configuration files. If you remove the deployed path to one certificate, that change affects all instances which belong to that Config Sync Group. + +## Delete a deployed certificate + +To delete a certificate, find the name in the **Certificates** screen. Find the **Actions** column associated with the certificate. Select the ellipsis (`...`) and then select **Delete**. Before deleting that certificate, you should see a warning. + +If that certificate is managed and is part of a Config Sync Group, that change affects all instances in that group. + +{{< warning >}} Be cautious if you want to delete certificates that are being used by an instance or a Config Sync Group. Deleting such certificates leads to failure in affected NGINX deployments. {{< /warning >}} + +## Managed and unmanaged certificates + +If you register an instance to NGINX One Console, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), and the associated SSL/TLS certificates: + +- Are used in their NGINX configuration +- Do _not_ match an existing managed SSL certificate/CA bundle + +These certificates appear in the list of unmanaged certificates. + +We recommend that you convert your unmanaged certificates. Converting to a managed certificate allows you to centrally manage, update, and deploy a certificate to your data plane from the NGINX One Console. + +To convert these cerificates to managed, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + + + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Add a file in a configuration]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) diff --git a/content/nginx-one/changelog.md b/content/nginx-one/changelog.md index e41c765f8..a16fd1f5d 100644 --- a/content/nginx-one/changelog.md +++ b/content/nginx-one/changelog.md @@ -83,8 +83,8 @@ You can: - Remove a deployed certificate from a Config Sync Group For more information, including warnings about risks, see our documentation on how you can: -- [Add a file]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}) +- [Add a file]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) ### Revert a configuration @@ -108,7 +108,7 @@ From the NGINX One Console you can now: - Ensure that your certificates are current and correct. - Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. -For more information, see the full documentation on how you can [Manage Certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}). +For more information, see the full documentation on how you can [Manage Certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). ## August 22, 2024 @@ -116,7 +116,7 @@ For more information, see the full documentation on how you can [Manage Certific Config Sync Groups are now available in the F5 NGINX One Console. This feature allows you to manage and synchronize NGINX configurations across multiple instances as a single entity, ensuring consistency and simplifying the management of your NGINX environment. -For more information, see the full documentation on [Managing Config Sync Groups]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}). +For more information, see the full documentation on [Managing Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}). ## August 8, 2024 @@ -136,7 +136,7 @@ Select the link for each CVE to see the details, including the CVE's publish dat ### Edit NGINX configurations -You can now make configuration changes to your NGINX instances. For more details, see [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}). +You can now make configuration changes to your NGINX instances. For more details, see [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}). ## May 28, 2024 diff --git a/content/nginx-one/config-sync-groups/_index.md b/content/nginx-one/config-sync-groups/_index.md new file mode 100644 index 000000000..db1ee5560 --- /dev/null +++ b/content/nginx-one/config-sync-groups/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Organize in groups +weight: 400 +url: /nginx-one/config-sync-groups +--- diff --git a/content/nginx-one/config-sync-groups/add-file-csg.md b/content/nginx-one/config-sync-groups/add-file-csg.md new file mode 100644 index 000000000..9b6905aea --- /dev/null +++ b/content/nginx-one/config-sync-groups/add-file-csg.md @@ -0,0 +1,67 @@ +--- +docs: null +title: Add a file to a Config Sync Group +toc: true +weight: 400 +type: +- how-to +--- + +## Overview + +{{< include "nginx-one/add-file/overview.md" >}} + +## Before you start + +Before you add files in your configuration, ensure: + +- You have access to the NGINX One Console. +- Config Sync Groups are properly registered with NGINX One Console + +## Important considerations + +This page applies when you want to add a file to a Config Sync Group. Any changes you make here apply to all [Instances]({{< ref "/nginx-one/glossary.md" >}}) of that Config Sync Group. + +## Add a file + +You can use the NGINX One Console to add a file to a specific Config Sync Group. To do so: + +1. Select the Config Sync Group to manage. +1. Select the **Configuration** tab. + + {{< tip >}} + + {{< include "nginx-one/add-file/edit-config-tip.md" >}} + + {{< /tip >}} + +1. Select **Edit Configuration**. +1. In the **Edit Configuration** window that appears, select **Add File**. + +You now have multiple options, described in the sections which follow. + +### New Configuration File + +Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. + +### New SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} + + {{< tip >}} + + Make sure to specify the path to your certificate in your NGINX configuration, + with the `ssl_certificate` and `ssl_certificate_key` directives. + + {{< /tip >}} + +### Existing SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} +With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md new file mode 100644 index 000000000..8b24001cd --- /dev/null +++ b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md @@ -0,0 +1,261 @@ +--- +docs: null +title: Manage Config Sync Groups +toc: true +weight: 300 +type: +- how-to +--- + +## Overview + +If you work with several instances of NGINX, it can help to organize these instances in Config Sync Groups. Each instance in a Config Sync Group has the same configuration. + +This guide explains how to create and manage Config Sync Groups in the F5 NGINX One Console. Config Sync Groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. + +If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find Config Sync Groups in NGINX One similar, though the steps and terminology differ slightly. + +Config Sync Groups are functionally different from syncing instances in a cluster. They let you to manage and synchronize configurations across multiple NGINX instances, all at once. + +This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While Config Sync Groups focus on configuration management, cluster syncing supports failover and data consistency. + +## Before you start + +Before you create and manage Config Sync Groups, ensure: + +- You have access to the NGINX One Console. +- You have the necessary permissions to create and manage Config Sync Groups. +- If you plan to add existing instances to a Config Sync Group, make sure those NGINX instances are properly registered with NGINX One. + +## Configuration management + +Config Sync Groups support configuration inheritance and persistance. If you've just created a Config Sync Group, you can define the configuration for that group in the following ways: + +- Before adding an instance to a group, you can [Define the Config Sync Group configuration manually](#define-the-config-sync-group-configuration-manually). +- When you add the first instance to a group, that instance defines the configuration for that Config Sync Group. +- Afterwards, you can modify the configuration of the Config Sync Group. That modifies the configuration of all member instances. Future members of that group inherit that modified configuration. + +On the other hand, if you remove all instances from a Config Sync Group, the original configuration persists. In other words, the group retains the configuration from that first instance (or the original configuration). Any new instance that you add later still inherits that configuration. + +{{< tip >}}You can use _unmanaged_ certificates. Your actions can affect the [Config Sync Group status](#config-sync-group-status). For future instances on the data plane, if it: + +- Has unmanaged certificates in the same file paths as defined by the NGINX configuration as the Config Sync Group, that instance will be [**In Sync**](#config-sync-group-status). +- Will be [**Out of Sync**](#config-sync-group-status) if the instance: + - Does not have unmanaged certificates in the same file paths + - Has unmanaged certificates in a different directory from the Config Sync Group +{{< /tip >}} + +### Risk when adding multiple instances to a Config Sync Group + +If you add multiple instances to a single Config Sync Group, simultaneously (with automation), there's a risk that the instance selects a random configuration. To prevent this problem, you should: + +1. Create a Config Sync Group. +1. Add a configuration to the Config Sync Group, so all instances inherit it. +1. Add the instances in a separate operation. + +Your instances should synchronize with your desired configuration within 30 seconds. + +### Use an instance to define the Config Sync Group configuration + +1. Follow the steps in the [**Add an existing instance to a Config Sync Group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a Config Sync Group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. +2. The NGINX configuration from this instance will automatically become the group's configuration. +3. You can further edit and publish this configuration by following the steps in the [**Publish the Config Sync Group configuration**](#publish-the-config-sync-group-configuration) section. + +### Define the Config Sync Group configuration manually + +You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. + +To manually set the group configuration: + +1. Follow steps 1–4 in the [**Create a Config Sync Group**](#create-a-config-sync-group) section to create your Config Sync Group. +2. After creating the group, select the **Configuration** tab. +3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. +4. To add a configuration, select **Edit Configuration**. +5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. +6. After making your changes, select **Next** to view a split screen showing your changes. +7. If you're satisfied with the configuration, select **Save and Publish**. + +## Important considerations + +When you plan Config Sync Groups, consider the following factors: + +- **Single Config Sync Group membership**: You can add an instance to only one Config Sync Group. + +- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified Config Sync Group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. + +- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same Config Sync Group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. + +## Create a Config Sync Group + +When you create a Config Sync Group, you can manage the configurations of multiple NGINX instances as a single entity. + +1. On the left menu, select **Config Sync Groups**. +2. Select **Add Config Sync Group**. +3. In the **Name** field, type a name for your Config Sync Group. +4. Select **Create** to add the Config Sync Group. + +## Manage Config Sync Group membership + +Now that you created a Config Sync Group, you can add instances to that group. As described in [Configuration management](#configuration-management), the first instance you add to a group, when you add it, defines the initial configuration for the group. You can update the configuration for the entire Config Sync Group. + +Any instance that joins the group afterwards inherits that configuration. + +### Add an existing instance to a Config Sync Group {#add-an-existing-instance-to-a-config-sync-group} + +You can add existing NGINX instances that are already registered with NGINX One to a Config Sync Group. + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. At the end of the file, add a new line beginning with `instance_group:`, followed by the Config Sync Group name. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent: + + ``` shell + sudo systemctl restart nginx-agent + ``` + +### Add a new instance to a Config Sync Group {#add-a-new-instance-to-a-config-sync-group} + +When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. + +1. On the left menu, select **Config Sync Groups**. +2. Select the Config Sync Group in the list. +3. In the **Instances** pane, select **Add Instance to Config Sync Group**. +4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to Config Sync Group**. +5. Select **Next**. +6. **Generate a new data plane key** (choose this option if you don't have an existing key): + + - Select **Generate new key** to create a new data plane key for the instance. + - Select **Generate Data Plane Key**. + - Copy and securely store the generated key, as it is displayed only once. + +7. **Use an existing data plane key** (choose this option if you already have a key): + + - Select **Use existing key**. + - In the **Data Plane Key** field, enter the existing data plane key. + +{{}} + +{{%tab name="Virtual Machine or Bare Metal"%}} + +8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. +9. Select **Done** to complete the process. + +{{%/tab%}} + +{{%tab name="Docker Container"%}} + +8. **Log in to the NGINX private registry**: + + - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) license from [MyF5](https://my.f5.com/manage/s/). + + ```shell + sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none + ``` + +9. **Pull the Docker image**: + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + +10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. + +11. Select **Done** to complete the process. + +{{%/tab%}} + +{{}} + +{{}} + +Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. + +For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). + +{{}} + +### Move an instance to a different Config Sync Group + +If you need to move an NGINX instance to a different Config Sync Group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and change it to the name of the new Config Sync Group. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent by running the following command: + + ```shell + sudo systemctl restart nginx-agent + ``` + +If you move an instance with certificates from one Config Sync Group to another, NGINX One adds or removes those certificates from the data plane, to synchronize with the deployed certificates of the group. + +### Remove an instance from a Config Sync Group + +If you need to remove an NGINX instance from a Config Sync Group without adding it to another group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. + + ```text + # instance_group: + ``` + +4. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +By removing or commenting out this line, the instance will no longer be associated with any Config Sync Group. + +## Publish the Config Sync Group configuration {#publish-the-config-sync-group-configuration} + +After the Config Sync Group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. + +1. On the left menu, select **Config Sync Groups**. +2. Select the Config Sync Group in the list. +3. Select the **Configuration** tab to view the group's NGINX configuration. +4. To modify the group's configuration, select **Edit Configuration**. +5. Make the necessary changes to the configuration. +6. When you're finished, select **Next**. A split view displays the changes. +7. If you're satisfied with the changes, select **Save and Publish**. + +Publishing the group configuration ensures that all instances within the Config Sync Group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. + +## Config Sync Group status + +The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. + +{{}} +| **Status** | **Description** | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| **In Sync** | All instances within the Config Sync Group have configurations that match the group configuration. No action is required. | +| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | +| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | +| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | +{{}} + +Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index c315d35ef..187c8585d 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -3,7 +3,7 @@ description: '' docs: DOCS-1396 title: Glossary toc: true -weight: 1000 +weight: 2000 type: - reference --- @@ -14,7 +14,7 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed {{}} | Term | Definition | |-------------|-------------| -| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | +| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | | **Data Plane** | The data plane is the part of a network architecture that carries user traffic. It handles tasks like forwarding data packets between devices and managing network communication. In the context of NGINX, the data plane is responsible for tasks such as load balancing, caching, and serving web content. | | **Instance** | An instance is an individual system with NGINX installed. You can group the instances of your choice in a Config Sync Group. When you add an instance to NGINX One, you need to use a data plane key. | | **Namespace** | In F5 Distributed Cloud, a namespace groups a tenant’s configuration objects, similar to administrative domains. Every object in a namespace must have a unique name, and each namespace must be unique to its tenant. This setup ensures isolation, preventing cross-referencing of objects between namespaces. You'll see the namespace in the NGINX One Console URL as `/namespaces//` | diff --git a/content/nginx-one/how-to/_index.md b/content/nginx-one/how-to/_index.md index 3e88ec7ae..e7b505736 100644 --- a/content/nginx-one/how-to/_index.md +++ b/content/nginx-one/how-to/_index.md @@ -1,6 +1,6 @@ --- description: title: How-to guides -weight: 200 +weight: 700 url: /nginx-one/how-to/ --- diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md new file mode 100644 index 000000000..d36819e7b --- /dev/null +++ b/content/nginx-one/nginx-configs/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Organize your NGINX instances +weight: 300 +url: /nginx-one/nginx-configs +--- diff --git a/content/nginx-one/nginx-configs/add-file.md b/content/nginx-one/nginx-configs/add-file.md new file mode 100644 index 000000000..4549647f5 --- /dev/null +++ b/content/nginx-one/nginx-configs/add-file.md @@ -0,0 +1,67 @@ +--- +docs: null +title: Add a file to an instance +toc: true +weight: 400 +type: +- how-to +--- + +## Overview + +{{< include "nginx-one/add-file/overview.md" >}} + +## Before you start + +Before you add files in your configuration, ensure: + +- You have access to the NGINX One Console. +- NGINX instances are properly registered with NGINX One Console + +## Important considerations + +If your instance is a member of a Config Sync Group, changes that you make may be synchronized to other instances in that group. +For more information, see how you can [Manage Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}). + +## Add a file + +You can use the NGINX One Console to add a file to a specific instance. To do so: + +1. Select the instance to manage. +1. Select the **Configuration** tab. + + {{< tip >}} + + {{< include "nginx-one/add-file/edit-config-tip.md" >}} + + {{< /tip >}} + +1. Select **Edit Configuration**. +1. In the **Edit Configuration** window that appears, select **Add File**. + +You now have multiple options, described in the sections which follow. + +### New Configuration File + +Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. + +### New SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} + + {{< tip >}} + + Make sure to specify the path to your certificate in your NGINX configuration, + with the `ssl_certificate` and `ssl_certificate_key` directives. + + {{< /tip >}} + +### Existing SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md new file mode 100644 index 000000000..ddf5eb095 --- /dev/null +++ b/content/nginx-one/nginx-configs/add-instance.md @@ -0,0 +1,75 @@ +--- +description: '' +title: Add an NGINX instance +toc: true +weight: 100 +type: +- how-to +--- + +## Overview + +This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need +to set up a data plane key to connect your instances to NGINX One. + +## Before you start + +Before you add an instance to NGINX One Console, ensure: + +- You have administrator access to NGINX One Console. +- You have configured instances of NGINX that you want to manage through NGINX One Console. +- You have or are ready to configure a data plane key. +- You have or are ready to set up managed certificates. + +{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} + +## Add an instance + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. + +Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. + +```bash +curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Once the process is complete, you can configure that instance in your NGINX One Console. + +## Managed and Unmanaged Certificates + +If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. + +### If the certificate is already managed + +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One], these certificates are added to your list of **Managed Certificates**. + +NGINX One Console can manage your instances along with those certificates. + +### If the certificate is not managed + +These certificates appear in the list of **Unmanaged Certificates**. + +To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. + +To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + +Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. + +## Add an instance to a Config Sync Group + +When you [Manage Config Sync Group membership]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. +That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md new file mode 100644 index 000000000..6a119617d --- /dev/null +++ b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md @@ -0,0 +1,40 @@ +--- +description: '' +docs: null +title: Clean up unavailable NGINX instances +toc: true +weight: 200 +type: +- how-to +--- + +## Overview + +This guide explains how to set up automatic cleanup for NGINX instances in NGINX One. The cleanup process removes instances that have been unavailable for a specified duration. By default, this period is 24 hours from the time the NGINX instance was last updated. Administrators can change or disable the cleanup duration in **Settings > Instance Settings**. Events will be generated for NGINX instances that have been automatically cleaned up; you can see these events on the **Overview > Events** page. + +## Before you start + +Before you set up automatic cleanup for NGINX instances, ensure: + +- You have administrator access to NGINX One. +- You understand that this action will delete instances permanently after they are unavailable for the specified duration. + +## Configure instance cleanup + +Follow these steps to set up automatic cleanup for NGINX instances in NGINX One: + +1. On the left menu, select **Instance Settings**. +1. On the **Instance Settings** page, in the **Unavailable Instance Cleanup** section, select **Edit Duration**. +1. Choose the cleanup duration. + - Select one of the predefined durations (None, 1 day, 7 days, 30 days) or set a custom duration. Selecting **None** disables automatic cleanup. + - If you choose **Custom**, enter the duration in hours or days. +1. Select **Save** to apply the changes. + +## Event log details + +When instances are cleaned up automatically, an event log entry is created. You can find these events on the **Overview > Events** page. The event log includes the following details: + +- **Impacted Object ID**: The unique identifier of the NGINX instance that was cleaned up. +- **Type**: The type of event, which will be "Automated Object Cleanup". +- **Timestamp**: The date and time when the instance was cleaned up. +- **Message**: A description indicating that the instance was unavailable for the configured duration before being cleaned up. diff --git a/content/nginx-one/nginx-configs/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/manage-config-sync-groups.md new file mode 100644 index 000000000..41589dadd --- /dev/null +++ b/content/nginx-one/nginx-configs/manage-config-sync-groups.md @@ -0,0 +1,239 @@ +--- +docs: null +title: Manage config sync groups +toc: true +weight: 300 +type: +- how-to +--- + +## Overview + +This guide explains how to create and manage config sync groups in the F5 NGINX One Console. Config sync groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. + +If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find config sync groups in NGINX One similar, though the steps and terminology differ slightly. + +## Before you start + +Before you create and manage config sync groups, ensure: + +- You have access to the NGINX One Console. +- You have the necessary permissions to create and manage config sync groups. +- NGINX instances are properly registered with NGINX One if you plan to add existing instances to a config sync group. + +## Important considerations + +- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified config sync group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. + +- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same config sync group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. + +- **Single config sync group membership**: An instance can join only one config sync group at a time. + +- **Configuration inheritance**: If the config sync group already has a configuration defined, that configuration will be pushed to instances when they join. + +- **Using an instance's configuration for the group configuration**: If an instance is the first to join a config sync group and the group's configuration hasn't been defined, the instance’s configuration will become the group’s configuration. Any instances added later will automatically inherit this configuration. + + {{< note >}} If you add multiple instances to a single config sync group, simultaneously (with automation), follow these steps. Your instances will inherit your desired configuration: + + 1. Create a config sync group. + 1. Add a configuration to the config sync group, so all instances inherit it. + 1. Add the instances in a separate operation. + + Your instances should synchronize with your desired configuration within 30 seconds. {{< /note >}} + +- **Persistence of a config sync group's configuration**: The configuration for a config sync group persists until you delete the group. Even if you remove all instances, the group's configuration stays intact. Any new instances that join later will automatically inherit this configuration. + +- **Config sync groups vs. cluster syncing**: Config sync groups are not the same as cluster syncing. Config sync groups let you to manage and synchronize configurations across multiple NGINX instances as a single entity. This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While config sync groups focus on configuration management, cluster syncing supports failover and data consistency. + +## Create a config sync group + +Creating a config sync group allows you to manage the configurations of multiple NGINX instances as a single entity. + +1. On the left menu, select **Config Sync Groups**. +2. Select **Add Config Sync Group**. +3. In the **Name** field, type a name for your config sync group. +4. Select **Create** to add the config sync group. + +## Manage config sync group membership + +### Add an existing instance to a config sync group {#add-an-existing-instance-to-a-config-sync-group} + +You can add existing NGINX instances that are already registered with NGINX One to a config sync group. + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. At the end of the file, add a new line beginning with `instance_group:`, followed by the config sync group name. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent: + + ``` shell + sudo systemctl restart nginx-agent + ``` + +### Add a new instance to a config sync group {#add-a-new-instance-to-a-config-sync-group} + +When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. + +1. On the left menu, select **Config Sync Groups**. +2. Select the config sync group in the list. +3. In the **Instances** pane, select **Add Instance to Config Sync Group**. +4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to config sync group**. +5. Select **Next**. +6. **Generate a new data plane key** (choose this option if you don't have an existing key): + + - Select **Generate new key** to create a new data plane key for the instance. + - Select **Generate Data Plane Key**. + - Copy and securely store the generated key, as it is displayed only once. + +7. **Use an existing data plane key** (choose this option if you already have a key): + + - Select **Use existing key**. + - In the **Data Plane Key** field, enter the existing data plane key. + +{{}} + +{{%tab name="Virtual Machine or Bare Metal"%}} + +8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. +9. Select **Done** to complete the process. + +{{%/tab%}} + +{{%tab name="Docker Container"%}} + +8. **Log in to the NGINX private registry**: + + - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) from [MyF5](https://my.f5.com/manage/s/). + + ```shell + sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none + ``` + +9. **Pull the Docker image**: + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + +10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. + +11. Select **Done** to complete the process. + +{{%/tab%}} + +{{}} + +{{}} + +Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. + +For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). + +{{}} + +### Change the config sync group for an instance + +If you need to move an NGINX instance to a different config sync group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and change it to the name of the new config sync group. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent by running the following command: + + ```shell + sudo systemctl restart nginx-agent + ``` + +**Important:** If the instance is the first to join the new config sync group and a group configuration hasn’t been added manually beforehand, the instance’s configuration will automatically become the group’s configuration. Any instances added to this group later will inherit this configuration. + +### Remove an instance from a config sync group + +If you need to remove an NGINX instance from a config sync group without adding it to another group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. + + ```text + # instance_group: + ``` + +4. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +By removing or commenting out this line, the instance will no longer be associated with any config sync group. + +## Add the config sync group configuration + +You can set the configuration for a config sync group in two ways: + +### Define the group configuration manually + +You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. + +To manually set the group configuration: + +1. Follow steps 1–4 in the [**Create a config sync group**](#create-a-config-sync-group) section to create your config sync group. +2. After creating the group, select the **Configuration** tab. +3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. +4. To add a configuration, select **Edit Configuration**. +5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. +6. After making your changes, select **Next** to view a split screen showing your changes. +7. If you're satisfied with the configuration, select **Save and Publish**. + +### Use an instance's configuration + +If you don't manually define a group config, the NGINX configuration of the first instance added to a config sync group becomes the group's configuration. Any additional instances added afterward inherit this group configuration. + +To set the group configuration by adding an instance: + +1. Follow the steps in the [**Add an existing instance to a config sync group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a config sync group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. +2. The NGINX configuration from this instance will automatically become the group's configuration. +3. You can further edit and publish this configuration by following the steps in the [**Publish the config sync group configuration**](#publish-the-config-sync-group-configuration) section. + +## Publish the config sync group configuration {#publish-the-config-sync-group-configuration} + +After the config sync group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. + +1. On the left menu, select **Config Sync Groups**. +2. Select the config sync group in the list. +3. Select the **Configuration** tab to view the group's NGINX configuration. +4. To modify the group's configuration, select **Edit Configuration**. +5. Make the necessary changes to the configuration. +6. When you're finished, select **Next**. A split view displays the changes. +7. If you're satisfied with the changes, select **Save and Publish**. + +Publishing the group configuration ensures that all instances within the config sync group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. + +## Understanding config sync statuses + +The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. + +{{}} +| **Status** | **Description** | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| **In Sync** | All instances within the config sync group have configurations that match the group configuration. No action is required. | +| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | +| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | +| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | +{{}} + +Monitoring the **Config Sync Status** helps ensure that your configurations are consistently applied across all instances in a group, reducing the risk of configuration drift. + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md new file mode 100644 index 000000000..9b742104c --- /dev/null +++ b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md @@ -0,0 +1,41 @@ +--- +# We use sentence case and present imperative tone +title: View and edit NGINX configurations +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + + +## Overview + +This guide explains how to add a **Instances** to your NGINX One Console. + +## Before you start + +Before you add **Instances** to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions.``` + +Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. + +To view and edit an NGINX configuration, follow these steps: + +1. On the left menu, select **Instances**. +2. Select the instance you want to view the configuration for. +3. Select the **Configuration** tab to see the current configuration for the NGINX instance. +4. Select **Edit Configuration** to make changes to the current configuration. +5. Make your changes to the configuration files. The config analyzer will let you know if there are any errors. +6. When you are satisfied with the changes, select **Next**. +7. Compare and verify your changes before selecting **Save and Publish** to publish the edited configuration. + +Alternatively, you can select **Save Changes As**. In the window that appears, you can set up this instance as a [**Staged Configuration**]({{< ref "/nginx-one/staged-configs/_index.md" >}}). + +## See also + +- [Manage Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}) diff --git a/content/nginx-one/rbac/_index.md b/content/nginx-one/rbac/_index.md index a1f7050ff..36c5b464d 100644 --- a/content/nginx-one/rbac/_index.md +++ b/content/nginx-one/rbac/_index.md @@ -1,6 +1,6 @@ --- -title: Role-based access control +title: Organize your administrators with RBAC description: -weight: 300 +weight: 500 url: /nginx-one/rbac --- diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md new file mode 100644 index 000000000..4186aa21b --- /dev/null +++ b/content/nginx-one/staged-configs/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Set up new instances +weight: 200 +url: /nginx-one/how-to/staged-configs +--- diff --git a/content/nginx-one/staged-configs/add-staged-config.md b/content/nginx-one/staged-configs/add-staged-config.md new file mode 100644 index 000000000..94007c407 --- /dev/null +++ b/content/nginx-one/staged-configs/add-staged-config.md @@ -0,0 +1,88 @@ +--- +# We use sentence case and present imperative tone +title: Add a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 100 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +product: +--- + +## Overview + +This guide explains how to add a Staged Configuration to your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you add a Staged Configuration to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions. + +## Add a Staged Configuration + +You can add a Staged Configuration from: + +- Empty files +- An existing Instance +- An existing Config Sync Group +- An existing Staged Configuration + +To start the process from NGINX One Console, select **Manage > Staged Configruations**. Select **Add Staged Configuration**. + +The following sections start from the **Add Staged Configuration** window that appears. + +### Start from an empty file + +To start a new Staged Configuration: + +1. Select **New Configuration**. +1. Enter a name. +1. Select **Next**. + + You will see a new Staged Configuration with the default NGINX configuration file, `/etc/nginx/nginx.conf`, in edit mode. +1. Type or paste content for `/etc/nginx/nginx.conf`. +1. Select **Add File** to add the configuration, certificate, or other file(s) of your choice. +1. When you're done, select **Save**. + +### Start from an existing Instance + +To start from an existing Instance: + +1. Select **Existing Source**. +1. Enter a name for your new Staged Configuration. +1. Select **Instance**. +1. In the Choose Instance menu that appears, select an existing Instance. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Instance. You can now edit the configuration. When you're ready to stop and save your work, select Save. + +### Start from an existing Config Sync Group + +To start from an existing Config Sync Group: + +1. Select **Existing Source**. +1. Select **Config Sync Group**. +1. In the Choose Config Sync Group menu that appears, select an existing Config Sync Group. +1. Enter a name for your new Staged Configuration. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Config Sync Group. You can now edit the configuration. When you're ready to stop and save your work, select Save. + +### Start from an existing Staged Config + +To start from an existing Staged Config: + +1. Select **Existing Source**. +1. Select **Staged Configuration**. +1. In the Choose Staged Configuration menu that appears, select an existing Staged Configuration. +1. Enter a name for your new Staged Configuration. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Staged Configuration. You can now edit the configuration. When you're ready to stop and save your work, select Save. + diff --git a/content/nginx-one/staged-configs/api-staged-config.md b/content/nginx-one/staged-configs/api-staged-config.md new file mode 100644 index 000000000..8eadfdb55 --- /dev/null +++ b/content/nginx-one/staged-configs/api-staged-config.md @@ -0,0 +1,20 @@ +--- +# We use sentence case and present imperative tone +title: Use the API to manage your Staged Configurations +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + +You can use F5 NGINX One Console API to manage your Staged Configurations. With our API, you can: + +- [Create an NGINX Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/createStagedConfig" >}}) + - The details allow you to add existing configuration files. +- [Get a list of existing Staged Configurations]({{< ref "/nginx-one/api/api-reference-guide/#operation/listStagedConfigs" >}}) + - Be sure to record the `object_id` of your target Staged Configuration for your analysis report. +- [Get an analysis report for an existing Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/getStagedConfigReport" >}}) diff --git a/content/nginx-one/staged-configs/edit-staged-config.md b/content/nginx-one/staged-configs/edit-staged-config.md new file mode 100644 index 000000000..8f101a0fd --- /dev/null +++ b/content/nginx-one/staged-configs/edit-staged-config.md @@ -0,0 +1,38 @@ +--- +# We use sentence case and present imperative tone +title: View and edit a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 200 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + +## Overview + +This guide explains how to edit an existing Staged Configuration in your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you edit a Staged Configuration, ensure: + +- You have an NGINX One Console account with staged configuration permissions.``` + +## View and edit a Staged Configuration + + +Once you've registered your NGINX Staged Configs with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Staged Configurations** details page. + +To view and edit an NGINX configuration, follow these steps: + +1. On the left menu, select **Staged Configurations**. +1. Select the staged configuration you want to view or modify. +1. Select **Edit** to make changes to the current configuration. +1. Make your changes to the configuration files. The configuration analyzer will let you know if there are any errors. +1. When you are satisfied with the changes, select **Next**. +1. Compare and verify your changes before selecting **Save** to publish the edited Staged configuration. diff --git a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md index bf40c20be..a7a6a7f61 100644 --- a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md +++ b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md @@ -9,9 +9,10 @@ type: - how-to --- -## Introduction {#intro} + +## Introduction -[Load balancing](https://www.f5.com/glossary/load-balancer) refers to efficiently distributing network traffic across multiple backend servers. +[Load balancing](https://www.nginx.com/solutions/load-balancing/) refers to efficiently distributing network traffic across multiple backend servers. In F5 NGINX Plus [R5]({{< ref "nginx/releases.md#r5" >}}) and later, NGINX Plus can proxy and load balance Transmission Control Protocol) (TCP) traffic. TCP is the protocol for many popular applications and services, such as LDAP, MySQL, and RTMP. @@ -19,13 +20,15 @@ In NGINX Plus [R9]({{< ref "nginx/releases.md#r9" >}}) and later, NGINX Plus can To load balance HTTP traffic, refer to the [HTTP Load Balancing]({{< ref "http-load-balancer.md" >}}) article. + ## Prerequisites - Latest NGINX Plus (no extra build steps required) or latest [NGINX Open Source](https://nginx.org/en/download.html) built with the `--with-stream` configuration flag - An application, database, or service that communicates over TCP or UDP - Upstream servers, each running the same instance of the application, database, or service -## Configuring reverse proxy {#proxy_pass} + +## Configuring Reverse Proxy First, you will need to configure _reverse proxy_ so that NGINX Plus or NGINX Open Source can forward TCP connections or UDP datagrams from clients to an upstream group or a proxied server. @@ -115,7 +118,8 @@ Open the NGINX configuration file and perform the following steps: } ``` -## Configuring TCP or UDP load balancing {#upstream} + +## Configuring TCP or UDP Load Balancing To configure load balancing: @@ -246,7 +250,8 @@ stream { } ``` -## Configuring health checks {#health} + +## Configuring Health Checks NGINX can continually test your TCP or UDP upstream servers, avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. @@ -254,7 +259,8 @@ See [TCP Health Checks]({{< ref "nginx/admin-guide/load-balancer/tcp-health-chec See [UDP Health Checks]({{< ref "nginx/admin-guide/load-balancer/udp-health-check.md" >}}) for instructions how to configure health checks for UDP. -## On-the-fly configuration + +## On-the-Fly Configuration Upstream server groups can be easily reconfigured on-the-fly using NGINX Plus REST API. Using this interface, you can view all servers in an upstream group or a particular server, modify server parameters, and add or remove upstream servers. @@ -349,7 +355,8 @@ To enable on-the-fly configuration: } ``` -### On-the-fly configuration example + +### On-the-Fly Configuration Example ```nginx stream { @@ -396,22 +403,23 @@ For example, to add a new server to the server group, send a `POST` request: curl -X POST -d '{ \ "server": "appserv3.example.com:12345", \ "weight": 4 \ - }' -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers' + }' -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers' ``` To remove a server from the server group, send a `DELETE` request: ```shell -curl -X DELETE -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers/0' +curl -X DELETE -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers/0' ``` To modify a parameter for a specific server, send a `PATCH` request: ```shell -curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/9/http/upstreams/appservers/servers/0' +curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/6/http/upstreams/appservers/servers/0' ``` -## Example of TCP and UDP load-balancing configuration {#example} + +## Example of TCP and UDP Load-Balancing Configuration This is a configuration example of TCP and UDP load balancing with NGINX: @@ -463,13 +471,3 @@ The three [`server`](https://nginx.org/en/docs/stream/ngx_stream_upstream_module - The second server listens on port 53 and proxies all UDP datagrams (the `udp` parameter to the `listen` directive) to an upstream group called **dns_servers**. If the `udp` parameter is not specified, the socket listens for TCP connections. - The third virtual server listens on port 12346 and proxies TCP connections to **backend4.example.com**, which can resolve to several IP addresses that are load balanced with the Round Robin method. - -## See also - -- [TCP Health Checks]({{< relref "tcp-health-check.md" >}}) - -- [UDP Health Checks]({{< relref "udp-health-check.md" >}}) - -- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) - -- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks) diff --git a/content/nginx/admin-guide/load-balancer/udp-health-check.md b/content/nginx/admin-guide/load-balancer/udp-health-check.md index 7885d032a..bb4818fd4 100644 --- a/content/nginx/admin-guide/load-balancer/udp-health-check.md +++ b/content/nginx/admin-guide/load-balancer/udp-health-check.md @@ -9,11 +9,10 @@ type: - how-to --- -NGINX Plus can continually test your upstream servers that handle UDP network traffic (DNS, RADIUS, syslog), avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. + +## Prerequisites -## Prerequisites {#prereq} - -- You have [configured an upstream group of servers]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) that handles UDP network traffic in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: +- You have configured an upstream group of servers that handles UDP network traffic (DNS, RADIUS, syslog) in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: ```nginx stream { @@ -45,7 +44,8 @@ NGINX Plus can continually test your upstream servers that handle UDP network tr See [TCP and UDP Load Balancing]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) for details. -## Passive UDP health checks {#hc_passive} + +## Passive UDP Health Checks NGINX Open Source or F5 NGINX Plus can mark the server as unavailable and stop sending UDP datagrams to it for some time if the server replies with an error or times out. @@ -62,7 +62,8 @@ upstream dns_upstream { } ``` -## Active UDP health checks {#hc_active} + +## Active UDP Health Checks Active Health Checks allow testing a wider range of failure types and are available only for NGINX Plus. For example, instead of waiting for an actual TCP request from a DNS client to fail before marking the DNS server as down (as in passive health checks), NGINX Plus will send special health check requests to each upstream server and check for a response that satisfies certain conditions. If a connection to the server cannot be established, the health check fails, and the server is considered unhealthy. NGINX Plus does not proxy client connections to unhealthy servers. If more than one health check is defined, the failure of any check is enough to consider the corresponding upstream server unhealthy. @@ -99,7 +100,8 @@ To enable active health checks: A basic UDP health check assumes that NGINX Plus sends the “nginx health check” string to an upstream server and expects the absence of ICMP “Destination Unreachable” message in response. You can configure your own health check tests in the `match {}` block. See [The “match {}” Configuration Block](#hc_active_match) for details. -### Fine-Tuning UDP Health Checks {#hc_active_finetune} + +### Fine-Tuning UDP Health Checks You can fine‑tune the health check by specifying the following parameters to the [`health_check`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check) directive: @@ -117,9 +119,10 @@ server { In the example, the time between UDP health checks is increased to 20 seconds, the server is considered unhealthy after 2 consecutive failed health checks, and the server needs to pass 2 consecutive checks to be considered healthy again. -### The “match {}” configuration block {#hc_active_match} + +### The “match {}” Configuration Block -A basic UDP health check assumes that NGINX Plus sends the “nginx health check” string to an upstream server and expects the absence of ICMP “Destination Unreachable” message in response. You can configure your own health check tests that will verify server responses. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. +You can verify server responses to health checks by configuring a number of tests. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. 1. In the top‑level `stream {}` context, specify the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) block and set its name, for example, `udp_test`: @@ -152,9 +155,8 @@ A basic UDP health check assumes that NGINX Plus sends the “nginx health check These parameters can be used in different combinations, but no more than one `send` and one `expect` parameter can be specified at a time. -## Usage scenarios - -### NTP health checks {#example_ntp} + +#### Example Test for NTP To fine‑tune health checks for NTP, you should specify both `send` and `expect` parameters with the following text strings: @@ -165,138 +167,14 @@ match ntp { } ``` -#### Complete NTP health check configuration example - -```nginx - -stream { - upstream ntp_upstream { - zone ntp_zone 64k; - server 192.168.136.130:53; - server 192.168.136.131:53; - server 192.168.136.132:53; -} - server { - listen 53 udp; - proxy_pass ntp_upstream; - health_check match=ntp udp; - proxy_timeout 1s; - proxy_responses 1; - error_log logs/ntp.log; - } - - match ntp { - send \xe3\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00; - expect ~* \x24; - } -} -``` - -### DNS health checks {#example_dns} - -[DNS health checks](#hc_active) can be enhanced to perform real DNS lookup queries. You can craft a valid DNS query packet, send it to the upstream server, and inspect the response to determine health. - -The process includes three steps: -- [Creating a CNAME test record](#create-a-cname-record) on your DNS server. -- [Crafting a raw DNS query packet](#construct-a-raw-dns-query-packet) to be sent by NGINX Plus. -- [Validating the expected response](#configure-the-match-block-for-dns-lookup) using the `match` block, where the `send` parameter represents a raw DNS query packet, and `expect` represents the value of the CNAME record. - -#### Create a CNAME record - -First, create a CNAME record on your DNS server for a health check that points to the target website. - -For example, if you are using BIND self-hosted DNS solution on a Linux server: - -- Open the zone file in a text editor: - -```shell -sudo nano /etc/bind/zones/db.example.com -``` -- Add a CNAME record, making `healthcheck.example.com` resolve to `healthy.svcs.example.com`: - -```none -healthcheck IN CNAME healthy.svcs.example.com. -``` - -- Save the file and reload the DNS service: - -```shell -sudo systemctl reload bind9 -``` - -Once the CNAME record is live and resolvable, you can craft a DNS query packet that represents a DNS lookup and can be used in the `send` directive. - -#### Construct a raw DNS query packet - -The `send` parameter of the `match` block allows you to send raw UDP packets for health checks. To query your CNAME record, you need to construct a valid DNS query packet according to the [DNS protocol message format](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1), including a header and question section. + +#### Example Test for DNS -The DNS Query packet can be created using DNS packet builders, such as Python Scapy or dnslib, or packet analyzers, such as tcpdump or Wireshark. If using a packet analyzer, extract only the DNS layer, removing Ethernet, IP, and UDP-related headers. - -This is the raw DNS query of `healthcheck.example.com`, represented as one line in Hex with `\x` prefixes: - -```none -\x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01 -``` -where: - -{{}} -| HEX | Description | -|------------------|------------------------| -| \x00\x01 | Transaction ID: 0x0001 | -| \x01\x00 | Flags: Standard query, recursion desired | -| \x00\x01 | Questions: 1 | -| \x00\x00 | Answer RRs: 0 | -| \x00\x00 | Authority RRs: 0 | -| \x00\x00 | Additional RRs: 0 | -| \x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b | "healthcheck" | -| \x07\x65\x78\x61\x6d\x70\x6c\x65 | "example" | -| \x03\x63\x6f\x6d | "com" | -| \x00 | end of name | -| \x00\x01 | Type: A | -| \x00\x01 | Class: IN | -{{}} - -#### Configure the match block for DNS lookup - -Finally, specify the `match` block in the NGINX configuration file to pair the raw query with an expected response. The `send` directive should contain the DNS query packet, while `expect` directive should contain a matching DNS record in the DNS server's response: +To fine‑tune health checks for DNS, you should also specify both `send` and `expect` parameters with the following text strings: ```nginx match dns { - send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; - expect ~* "healthy.svcs.example.com"; -} -``` - -#### Complete DNS health check configuration example - -```nginx - -stream { - upstream dns_upstream { - zone dns_zone 64k; - server 192.168.136.130:53; - server 192.168.136.131:53; - server 192.168.136.132:53; -} - server { - listen 53 udp; - proxy_pass dns_upstream; - health_check match=dns udp; - proxy_timeout 1s; - proxy_responses 1; - error_log logs/dns.log; - } - - match dns { - # make sure appropriate CNAME record exists - send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; - expect ~* "healthy.svcs.example.com"; - } + send \x00\x2a\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x03\x73\x74\x6c\x04\x75\x6d\x73\x6c\x03\x65\x64\x75\x00\x00\x01\x00\x01; + expect ~* "health.is.good"; } ``` - -## See also - -- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) - -- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks#activeHealthCheck) 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 5c0e5ebf3..71684b133 100644 --- a/content/nim/nginx-app-protect/manage-waf-security-policies.md +++ b/content/nim/nginx-app-protect/manage-waf-security-policies.md @@ -1,7 +1,8 @@ --- -title: Manage and deploy WAF policies and log profiles -description: Learn how to use F5 NGINX Instance Manager to manage NGINX App Protect WAF security policies and security log profiles. -weight: 300 +title: Manage WAF Security Policies and Security Log Profiles +description: Learn how to use F5 NGINX Management Suite Instance Manager to manage NGINX + App Protect WAF security policies and security log profiles. +weight: 200 toc: true type: how-to product: NIM @@ -10,76 +11,83 @@ docs: DOCS-1105 ## Overview -F5 NGINX Instance Manager lets you manage NGINX App Protect WAF configurations using either the web interface or REST API. You can edit, update, and deploy security policies, log profiles, attack signatures, and threat campaigns to individual instances or instance groups. +F5 NGINX Management Suite Instance Manager provides the ability to manage the configuration of NGINX App Protect WAF instances either by the user interface or the REST API. This includes editing, updating, and deploying security policies, log profiles, attack signatures, and threat campaigns to individual instances and/or instance groups. -You can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. The bundle includes all necessary components for a specific NGINX App Protect WAF version. Precompiling the bundle improves performance by avoiding separate compilation of each component during deployment. +In Instance Manager v2.14.0 and later, you can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. A security policy bundle consists of the security policy, the attack signatures, and threat campaigns for a particular version of NGINX App Protect WAF, and additional supporting files that make it possible for NGINX App Protect WAF to use the bundle. Because the security policy bundle is pre-compiled, the configuration gets applied faster than when you individually reference the security policy, attack signature, and threat campaign files. {{}} -The following capabilities are available only through the Instance Manager REST API: +The following capabilities are only available via the Instance Manager REST API: - Update security policies - Create, read, and update security policy bundles -- Create, read, update, and delete security log profiles -- Publish security policies, log profiles, attack signatures, and threat campaigns to instances and instance groups +- Create, read, update, and delete Security Log Profiles +- Publish security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups {{}} --- -## Before you begin +## Before You Begin -Before continuing, complete the following steps: +Complete the following prerequisites before proceeding with this guide: -- [Set up App Protect WAF configuration management]({{< ref "setup-waf-config-management" >}}) -- Make sure your user account has the [required permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the REST API: +- [Set Up App Protect WAF Configuration Management]({{< ref "setup-waf-config-management" >}}) +- Verify that your user account has the [necessary permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the Instance Manager REST API: - - **Module**: Instance Manager - - **Feature**: Instance Management → `READ` - - **Feature**: Security Policies → `READ`, `CREATE`, `UPDATE`, `DELETE` + - **Module**: Instance Manager + - **Feature**: Instance Management + - **Access**: `READ` + - **Feature**: Security Policies + - **Access**: `READ`, `CREATE`, `UPDATE`, `DELETE` -To use policy bundles, you also need to: +The following are required to use support policy bundles: -- Have `UPDATE` permissions for each referenced security policy -- [Install the correct `nms-nap-compiler` package]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}) for your App Protect WAF version -- [Install the required attack signatures and threat campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}) +- You must have `UPDATE` permissions for the security policies specified in the request. +- The correct `nms-nap-compiler` packages for the NGINX App Protect WAF version you're using are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}). +- The attack signatures and threat campaigns that you want to use are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}). -### Access the web interface +### How to Access the Web Interface -To access the web interface, open a browser and go to the fully qualified domain name (FQDN) of your NGINX Instance Manager. Log in, then select **Instance Manager** from the Launchpad. +To access the web interface, go to the FQDN for your NGINX Instance Manager host in a web browser and log in. Once you're logged in, select "Instance Manager" from the Launchpad menu. -### Access the REST API +### How to Access the REST API {{< include "nim/how-to-access-nim-api.md" >}} --- -## Create a security policy {#create-security-policy} +## Create a Security Policy {#create-security-policy} {{}} {{%tab name="web interface"%}} -To create a security policy using the NGINX Instance Manager web interface: +
+ +To create a security policy using the Instance Manager web interface: + +1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. +2. On the left menu, select **App Protect**. +3. On the *Security Policies* page, select **Create**. +4. On the *Create Policy* page, fill out the necessary fields: -1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. From the Launchpad menu, select **Instance Manager**. -3. In the left menu, select **App Protect**. -4. On the *Security Policies* page, select **Create**. -5. On the *Create Policy* page, enter the required information: - - **Name**: Enter a name for the policy. - - **Description**: (Optional) Add a brief description. - - **Enter Policy**: Paste or type the JSON-formatted policy into the editor. The interface automatically validates the JSON. + - **Name**: Provide a name for the policy. + - **Description**: (Optional) Add a short description for the policy. + - **Enter Policy**: Type or paste the policy in JSON format into the form provided. The editor will validate the JSON for accuracy. - For help writing custom policies, see the [NGINX App Protect WAF Declarative Policy guide](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) and the [Policy Authoring and Tuning section](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) in the configuration guide. + For more information about creating custom policies, refer to the [NGINX App Protect WAF Declarative Policy](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) guide and the [Policy Authoring and Tuning](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) section of the config guide. -6. Select **Save**. +5. Select **Save**. {{%/tab%}} {{%tab name="API"%}} -To upload a new security policy using the REST API, send a `POST` request to the Security Policies API endpoint. +To upload a new security policy, send an HTTP `POST` request to the Security Policies API endpoint. + +{{}}Before sending a security policy to Instance Manager, you need to encode it using `base64`. Submitting a policy in its original JSON format will result in an error.{{}} + +
-You must encode the JSON policy using `base64`. If you send the policy in plain JSON, the request will fail. {{}} @@ -93,7 +101,7 @@ You must encode the JSON policy using `base64`. If you send the policy in plain For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ -H "Authorization: Bearer " \ -d @ignore-xss-example.json ``` @@ -126,7 +134,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ "modified": "2022-04-12T23:19:58.502Z", "name": "ignore-cross-site-scripting", "revisionTimestamp": "2022-04-12T23:19:58.502Z", - "uid": "" + "uid": "21daa130-4ba4-442b-bc4e-ab294af123e5" }, "selfLink": { "rel": "/api/platform/v1/services/environments/prod" @@ -140,13 +148,11 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ --- -## Update a security policy - +## Update a Security Policy -To update a security policy, send a `POST` or `PUT` request to the Security Policies API. +To update a security policy, send an HTTP `POST` request to the Security Policies API endpoint, `/api/platform/v1/security/policies`. -- 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. +You can use the optional `isNewRevision` parameter to indicate whether the updated policy is a new version of an existing policy. {{}} @@ -159,35 +165,33 @@ To update a security policy, send a `POST` or `PUT` request to the Security Poli {{}} -To use `POST`, include the policy metadata and content in your request: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-xss-policy.json ``` -To use PUT, first retrieve the policy’s unique identifier (UID). You can do this by sending a GET request to the policies endpoint: +You can update a specific policy by sending an HTTP `PUT` request to the Security Policies API endpoint that includes the policy's unique identifier (UID). -```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " -``` +To find the UID, send an HTTP `GET` request to the Security Policies API endpoint. This returns a list of all Security Policies that contains the unique identifier for each policy. + +Include the UID for the security policy in your `PUT` request to update the policy. Once the policy update is accepted, the WAF compiler will create a new, updated bundle. -Then include the UID in your PUT request: +For example: ```shell -curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ +curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ -H "Authorization: Bearer " \ - --Content-Type application/json \ - -d @update-xss-policy.json + --Content-Type application/json -d @update-xss-policy.json ``` -After updating the policy, you can [publish it](#publish-policy) to selected instances or instance groups. +After you have pushed an updated security policy, you can [publish it](#publish-policy) to selected instances or instance groups. --- -## Delete a security policy +## Delete a Security Policy {{}} @@ -195,29 +199,17 @@ After updating the policy, you can [publish it](#publish-policy) to selected ins
-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. -2. From the Launchpad menu, select **Instance Manager**. -3. In the left menu, select **App Protect**. -4. On the *Security Policies* page, find the policy you want to delete. -5. Select the **Actions** menu (**...**) and choose **Delete**. +To delete a security policy using the Instance Manager web interface: +1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. +2. On the left menu, select **App Protect**. +3. On the *Security Policies* page, select the **Actions** menu (represented by an ellipsis, **...**) for the policy you want to delete. Select **Delete** to remove the policy. {{%/tab%}} {{%tab name="API"%}} -To delete a security policy using the REST API: - -1. Retrieve the UID for the policy by sending a `GET` request to the policies endpoint: - - ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " - ``` - -2. Send a `DELETE` request using the policy UID: +To delete a security policy, send an HTTP `DELETE` request to the Security Policies API endpoint that includes the unique identifier for the policy that you want to delete. {{}} @@ -229,10 +221,10 @@ To delete a security policy using the REST API: {{}} -Example: +For example: ```shell -curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ +curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ -H "Authorization: Bearer " ``` @@ -240,42 +232,36 @@ curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/}} ---- +{{%comment%}}TO DO: Add sections for managing attack signatures and threat campaigns{{%/comment%}} -## 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: +## Create Security Policy Bundles {#create-security-policy-bundles} -- A security policy -- Attack signatures -- Threat campaigns -- A version of NGINX App Protect WAF -- Supporting files required to compile and deploy the bundle +To create security policy bundles, send an HTTP `POST` request to the Security Policies Bundles API endpoint. The specified security policies you'd like to compile into security policy bundles must already exist in Instance Manager. -### Required fields +### Required Fields -- `appProtectWAFVersion`: The version of NGINX App Protect WAF to target. -- `policyName`: The name of the policy to include. Must reference an existing policy. -- `policyUID`: Optional. If omitted, the latest revision of the specified policy is used. This field does **not** accept the keyword `latest`. +- `appProtectWAFVersion`: The version of NGINX App Protect WAF being used. +- `policyName`: The name of security policy to include in the bundle. This must reference an existing security policy; refer to the [Create a Security Policy](#create-security-policy) section above for instructions. -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. +### Notes +- If you do not specify a value for the `attackSignatureVersionDateTime` and/or `threatCampaignVersionDateTime` fields, the latest version of each will be used by default. You can also explicitly state that you want to use the most recent version by specifying the keyword `latest` as the value. +- If the `policyUID` field is not defined, the latest version of the specified security policy will be used. This field **does not allow** use of the keyword `latest`. {{}} -| Method | Endpoint | -|--------|----------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | POST | `/api/platform/v1/security/policies/bundles` | {{}} -Example: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " \ -d @security-policy-bundles.json ``` @@ -288,7 +274,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "bundles": [{ "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18" }, @@ -319,10 +305,10 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "" + "uid": "dceb8254-9a90-4e77-87ac-73070f821412" }, "content": "", "compilationStatus": { @@ -335,11 +321,11 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", - "policyName": "default-enforcement", - "policyUID": "", + "policyName": "defautl-enforcement", + "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" }, "content": "", "compilationStatus": { @@ -353,10 +339,10 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "", + "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" }, "content": "", "compilationStatus": { @@ -368,38 +354,39 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` + --- -## List security policy bundles {#list-security-policy-bundles} +## List Security Policy Bundles {#list-security-policy-bundles} -To list all security policy bundles, send a `GET` request to the Security Policy Bundles API. +To list security policy bundles, send an HTTP `GET` request to the Security Policies Bundles API endpoint. -You’ll only see bundles you have `"READ"` permissions for. +{{}}The list will only contain the security policy bundles that you have "READ" permissions for in Instance Manager.{{}} -You can use the following query parameters to filter results: +You can filter the results by using the following query parameters: -- `includeBundleContent`: Whether to include base64-encoded content in the response. Defaults to `false`. -- `policyName`: Return only bundles that match this policy name. -- `policyUID`: Return only bundles that match this policy UID. -- `startTime`: Return only bundles modified at or after this time. -- `endTime`: Return only bundles modified before this time. +- `includeBundleContent`: Boolean indicating whether to include the security policy bundle content for each bundle when getting a list of bundles or not. If not provided, defaults to `false`. Please note that the content returned is `base64 encoded`. +- `policyName`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy name will be returned. If not provided, it will not filter based on `policyName`. +- `policyUID`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy UID will be returned. If not provided, it will not filter based on `policyUID`. +- `startTime`: The security policy bundle's "modified time" has to be equal to or greater than this time value. If no value is supplied, it defaults to 24 hours from the current time. `startTime` has to be less than `endTime`. +- `endTime`: Indicates the time that the security policy bundles modified time has to be less than. If no value is supplied, it defaults to current time. `endTime` has to be greater than `startTime`. -If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. +
{{}} -| Method | Endpoint | -|--------|----------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | GET | `/api/platform/v1/security/policies/bundles` | {{}} -Example: +For example: ```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " ``` @@ -414,10 +401,10 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "" + "uid": "dceb8254-9a90-4e77-87ac-73070f821412" }, "content": "", "compilationStatus": { @@ -431,10 +418,10 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", "policyName": "defautl-enforcement", - "policyUID": "", + "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" }, "content": "", "compilationStatus": { @@ -448,10 +435,10 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "", + "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" }, "content": "", "compilationStatus": { @@ -465,35 +452,35 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ --- -## Get a security policy bundle {#get-security-policy-bundle} +## Get a Security Policy Bundle {#get-security-policy-bundle} -To retrieve a specific security policy bundle, send a `GET` request to the Security Policy Bundles API using the policy UID and bundle UID in the URL path. +To get a specific security policy bundle, send an HTTP `GET` request to the Security Policies Bundles API endpoint that contains the security policy UID and security policy bundle UID in the path. -You must have `"READ"` permission for the bundle to retrieve it. +{{}}You must have "READ" permission for the security policy bundle to be able to retrieve information about a bundle by using the REST API.{{}} + +
{{}} -| Method | Endpoint | -|--------|-------------------------------------------------------------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | {{}} -Example: + +For example: ```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ +curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/29d86fe8-612a-5c69-895a-04fc5b9849a6/bundles/trs35lv2-9a90-4e77-87ac-ythn4967 \ -H "Authorization: Bearer " ``` -The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tgz` file. - -Example: +The JSON response, shown in the example below, includes a `content` field that is base64 encoded. After you retrieve the information from the API, you will need to base64 decode the content field. You can include this in your API call, as shown in the following example cURL request: ```bash -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ - -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz +curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz ```
@@ -505,10 +492,10 @@ curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies/ "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" }, "content": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==", "compilationStatus": { @@ -520,25 +507,28 @@ curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies/ --- -## Create a security log profile {#create-security-log-profile} +## Create a Security Log Profile {#create-security-log-profile} + +Send an HTTP `POST` request to the Security Log Profiles API endpoint to upload a new security log profile. -To upload a new security log profile, send a `POST` request to the Security Log Profiles API endpoint. +{{}}Before sending a security log profile to Instance Manager, you need to encode it using `base64`. Submitting a log profile in its original JSON format will result in an error.{{}} + +
-You must encode the log profile in `base64` before sending it. If you send plain JSON, the request will fail. {{}} -| Method | Endpoint | -|--------|-----------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | POST | `/api/platform/v1/security/logprofiles` | {{}} -Example: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles \ -H "Authorization: Bearer " \ -d @default-log-example.json ``` @@ -568,100 +558,87 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ "modified": "2023-07-05T22:09:19.634358096Z", "name": "default-log-example", "revisionTimestamp": "2023-07-05T22:09:19.634358096Z", - "uid": "" + "uid": "54c35ad7-e082-4dc5-bb5d-2640a17d5620" }, "selfLink": { - "rel": "/api/platform/v1/security/logprofiles/" + "rel": "/api/platform/v1/security/logprofiles/54c35ad7-e082-4dc5-bb5d-2640a17d5620" } } ``` --- -## Update a security log profile {#update-security-log-profile} +## Update a Security Log Profile + +To update a security log profile, send an HTTP `POST` request to the Security Log Profiles API endpoint, `/api/platform/v1/security/logprofiles`. -To update a security log profile, you can either: +You can use the optional `isNewRevision` parameter to indicate whether the updated log profile is a new version of an existing log profile. -- 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` | +| 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: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-default-log.json ``` -To overwrite an existing security log profile: +You can update a specific log profile by sending an HTTP `PUT` request to the Security Log Profiles API endpoint that includes the log profile's unique identifier (UID). + +To find the UID, send an HTTP `GET` request to the Security Log Profiles API endpoint. This returns a list of all Security Log Profiles that contains the unique identifier for each log profile. -1. Retrieve the profile’s UID: +Include the UID for the security log profile in your `PUT` request to update the log profile. - ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " \ - --Content-Type application/json \ - -d @update-log-profile.json - ``` +For example: -2. Use the UID in your PUT request: - - ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " \ - --Content-Type application/json \ - -d @update-log-profile.json - ``` +```shell +curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ + -H "Authorization: Bearer " \ + --Content-Type application/json -d @update-default-log.json +``` -After updating the security log profile, you can [publish it](#publish-policy) to specific instances or instance groups. +After you have pushed an updated security log profile, you can [publish it](#publish-policy) to selected instances or instance groups. --- -## Delete a security log profile {#delete-security-log-profile} +## Delete a Security Log Profile -To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. +To delete a security log profile, send an HTTP `DELETE` request to the Security Log Profiles API endpoint that includes the unique identifier for the log profile that you want to delete. {{}} -| Method | Endpoint | -|--------|--------------------------------------------------------------------| +| Method | Endpoint | +|--------|------------------------------------------------------------| | DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -1. Retrieve the UID: - - ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ - -H "Authorization: Bearer " - ``` - -2. Send the delete request: +For example: - ```shell - curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " - ``` +```shell +curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ + -H "Authorization: Bearer " +``` --- -## Publish updates to instances {#publish-policy} +## 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. +The Publish API lets you distribute security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups. -Call this endpoint *after* you've created or updated the resources you want to deploy. +{{}}Use this endpoint *after* you've added or updated security policies, security log profiles, attack signatures, and/or threat campaigns.{{}} {{}} @@ -673,20 +650,18 @@ Call this endpoint *after* you've created or updated the resources you want to d {{}} -Include the following information in your request, depending on what you're publishing: +When making a request to the Publish API, make sure to include all the necessary information for your specific use case: -- Instance and instance group UIDs -- Policy UID and name -- Log profile UID and name -- Attack signature library UID and version -- Threat campaign UID and version +- Instance and/or Instance Group UID(s) to push the bundle to +- Threat Campaign version and UID +- Attack Signature version and UID +- Security Policy UID(s) +- Security Log Profile UID(s) -Example: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ - -H "Authorization: Bearer " \ - -d @publish-request.json +curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorization: Bearer " ```
@@ -696,27 +671,27 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ { "publications": [ { - "instances": [ - "" - ], + "attackSignatureLibrary": { + "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "versionDateTime": "2022.10.02" + }, "instanceGroups": [ - "" + "3fa85f64-5717-4562-b3fc-2c963f66afa6" + ], + "instances": [ + "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], - "policyContent": { - "name": "example-policy", - "uid": "" - }, "logProfileContent": { - "name": "example-log-profile", - "uid": "" + "name": "default-log", + "uid": "ffdbda39-88be-420a-b673-19d4183b7e4c" }, - "attackSignatureLibrary": { - "uid": "", - "versionDateTime": "2023.10.02" + "policyContent": { + "name": "default-enforcement", + "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "threatCampaign": { - "uid": "", - "versionDateTime": "2023.10.01" + "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "versionDateTime": "2022.10.01" } } ] @@ -746,91 +721,357 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ --- -## Check security policy and security log profile publication status {#check-publication-status} - -After publishing updates, you can check deployment status using the NGINX Instance Manager REST API. +## Check Security Policy and Security Log Profile Publication Status +When publishing an NGINX configuration that references a security policy and secuity log profile, the Instance Manager REST APIs can provide further details about the status of the configuration publications. To access this information, use the Instance Manager API endpoints and method as indicated. -Use the following endpoints to verify whether the configuration updates were successfully deployed to instances or instance groups. +To retrieve the details for the different configuration publication statuses for a particular security policy, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security policy. -### Check publication status for a security policy +| Method | Endpoint | +|--------|-----------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/associations/{security-policy-name}` | -To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. +You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: -{{}} +- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails +- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails -| Method | Endpoint | -|--------|--------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | - -{{}} - -Example: +The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ - -H "Authorization: Bearer " +curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/associations/ignore-xss" -H "Authorization: Bearer " ``` -In the response, look for the `lastDeploymentDetails` field under instance or `instanceGroup.instances`. +
+JSON Response +```json +{ + "associations": [ + { + "attackSignatureLibrary": { + "uid": "c69460cc-6b59-4813-8d9c-76e4a6c56b4b", + "versionDateTime": "2023.02.16" + }, + "instance": { + "hostName": "ip-172-16-0-99", + "lastDeploymentDetails": { + "createTime": "2023-04-11T21:36:11.519174534Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-99" + } + ] + }, + "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-04-11T21:36:14.008108979Z" + }, + "systemUid": "0435a5de-41c1-3754-b2e8-9d9fe946bafe", + "uid": "29d86fe8-612a-5c69-895a-04fc5b9849a6" + }, + "instanceGroup": { + "displayName": "inst_group_1", + "instances": [ + { + "hostName": "hostname1", + "systemUid": "49d143c2-f556-4cd7-8658-76fff54fb861", + "uid": "c8e15dcf-c504-4b7f-b52d-def7b8fd2f64", + "lastDeploymentDetails": { + "createTime": "2023-04-11T21:36:11.519174534Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-99" + } + ] + }, + "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-04-11T21:36:14.008108979Z" + }, + }, + { + "hostName": "hostname2", + "systemUid": "88a99ab0-15bb-4719-9107-daf5007c33f7", + "uid": "ed7e9173-794f-41af-80d9-4ed37d593247", + "lastDeploymentDetails": { + "createTime": "2023-04-11T21:36:11.519174534Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-99" + } + ] + }, + "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-04-11T21:36:14.008108979Z" + }, + } + ], + "uid": "51f8addc-c0e9-438b-b0b6-3e4f1aa8202d" + }, + "policyUid": "9991f237-d9c7-47b7-98aa-faa836838f38", + "policyVersionDateTime": "2023-04-11T21:18:19.183Z", + "threatCampaign": { + "uid": "eab683fe-c2f1-4910-a88c-8bfbc6363164", + "versionDateTime": "2023.02.15" + } + } + ] +} +``` -### Check publication status for a security log profile +
-{{}} +To retrieve the details for the different configuration publication statuses for a particular security log profile, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security log profile. -| Method | Endpoint | -|--------|-------------------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | +| Method | Endpoint | +|--------|-----------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{security-log-profile-name}` | -{{}} +You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: -Example: +- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails +- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails + +The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ - -H "Authorization: Bearer " +curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/logprofiles/associations/default-log" -H "Authorization: Bearer " ``` -The response also contains `lastDeploymentDetails` for each instance or group. +
+JSON Response -### Check status for a specific instance +```json +{ + "associations": [ + { + "instance": { + "hostName": "", + "systemUid": "", + "uid": "" + }, + "instanceGroup": { + "displayName": "ig1", + "instances": [ + { + "hostName": "ip-172-16-0-142", + "systemUid": "1d1f03ff-02de-32c5-8dfd-902658aada4c", + "uid": "18d074e6-3868-51ba-9999-b7466a936815" + } + ], + "lastDeploymentDetails": { + "createTime": "2023-07-05T23:01:06.679136973Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-142" + } + ] + }, + "id": "9bfc9db7-877d-4e8e-a43d-9660a6cd11cc", + "message": "Instance Group config successfully published to ig1", + "status": "successful", + "updateTime": "2023-07-05T23:01:06.790802157Z" + }, + "uid": "0df0386e-82f7-4efc-863e-5d7cfbc3f7df" + }, + "logProfileUid": "b680f7c3-6fc0-4c6b-889a-3025580c7fcb", + "logProfileVersionDateTime": "2023-07-05T22:08:47.371Z" + }, + { + "instance": { + "hostName": "ip-172-16-0-5", + "lastDeploymentDetails": { + "createTime": "2023-07-05T21:45:08.698646791Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-5" + } + ] + }, + "id": "73cf670a-738a-4a74-b3fb-ac9771e89814", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-07-05T21:45:08.698646791Z" + }, + "systemUid": "0afe5ac2-43aa-36c8-bcdc-7f88cdd35ab2", + "uid": "9bb4e2ef-3746-5d79-b526-e545fad27e90" + }, + "instanceGroup": { + "displayName": "", + "instances": [], + "uid": "" + }, + "logProfileUid": "bb3badb2-f8f5-4b95-9428-877fc208e2f1", + "logProfileVersionDateTime": "2023-07-03T21:46:17.006Z" + } + ] +} +``` -You can also view the deployment status for a specific instance by providing the system UID and instance UID. +
-{{}} +To retrieve the configuration publication status details for a particular instance, send an HTTP `GET` request to the Instances API endpoint, providing the unique system and instance identifiers. -| Method | Endpoint | -|--------|------------------------------------------------------------------| -| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | +| Method | Endpoint | +|--------|-----------------------------------------------------------------| +| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-id}` | -{{}} +You can locate the configuration publication status in the the response within the `lastDeploymentDetails` field, which contains additional fields that provide more context around the status. -Example: +The example below shows a call to the `instances` endpoint and the corresponding JSON response containing a compiler related error message. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ - -H "Authorization: Bearer " +curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b" -H "Authorization: Bearer " ``` -In the response, look for the `lastDeploymentDetails` field, which shows the deployment status and any related errors. +
+JSON Response -### Check deployment result by deployment ID +```json +{ + "build": { + "nginxPlus": true, + "release": "nginx-plus-r28", + "version": "1.23.2" + }, + "configPath": "/etc/nginx/nginx.conf", + "configVersion": { + "instanceGroup": { + "createTime": "0001-01-01T00:00:00Z", + "uid": "", + "versionHash": "" + }, + "versions": [ + { + "createTime": "2023-01-14T10:48:46.319Z", + "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", + "versionHash": "922e9d40fa6d4dd3a4b721295b8ecd95f73402644cb8d234f9f4f862b8a56bfc" + } + ] + }, + "displayName": "ip-192-0-2-27", + "links": [ + { + "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73", + "name": "system" + }, + { + "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", + "name": "self" + }, + { + "rel": "/api/platform/v1/systems/instances/deployments/b31c6ab1-4a46-4c81-a065-204575145e8e", + "name": "deployment" + } + ], + "processPath": "/usr/sbin/nginx", + "registrationTime": "2023-01-14T10:12:31.000Z", + "startTime": "2023-01-14T10:09:43Z", + "status": { + "lastStatusReport": "2023-01-14T11:11:49.323495017Z", + "state": "online" + }, + "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", + "version": "1.23.2", + "appProtect": { + "attackSignatureVersion": "Available after publishing Attack Signatures from Instance Manager", + "status": "active", + "threatCampaignVersion": "Available after publishing Threat Campaigns from Instance Manager", + "version": "4.2.0" + }, + "configureArgs": [ + ... + ], + "lastDeploymentDetails": { + "createTime": "2023-01-14T11:10:25.096812852Z", + "details": { + "error": "{\"instance:b9df6377-2c4f-3266-a64a-e064b0371c73\":\"failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.\"}", + "failure": [ + { + "failMessage": "failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.", + "name": "ip-192-0-2-27" + } + ], + "pending": [], + "success": [] + }, + "id": "b31c6ab1-4a46-4c81-a065-204575145e8e", + "message": "Instance config failed to publish to", + "status": "failed", + "updateTime": "2023-01-14T11:10:25.175145693Z" + }, + "loadableModules": [ + ... + ], + "packages": [ + ... + ], + "processId": "10345", + "ssl": { + "built": null, + "runtime": null + } +} +``` -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. +
-{{}} +When you use the Publish API (`/security/publish`) to [publish a security policy and security log profile](#publish-policy), Instance Manager creates a deployment ID for the request. To view the status of the update, or to check for any errors, use the endpoint and method shown below and reference the deployment ID. | Method | Endpoint | |--------|------------------------------------------------------------------| | GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | -{{}} +You can locate the configuration publication status in the the response within the `details` field, which contains additional fields that provide more context around the status. -Example: +The example below shows a call to the `deployments` endpoint and the corresponding JSON response containing a compiler error message. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ +curl -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/instances/deployments/d38a8e5d-2312-4046-a60f-a30a4aea1fbb" \ -H "Authorization: Bearer " ``` -The response includes the full deployment status, success or failure details, and any compiler error messages. +
+JSON Response + +```json +{ + "createTime": "2023-01-14T04:35:47.566082799Z", + "details": { + "error": "{\"instance:8a2092aa-5612-370d-bff0-5d7521e206d6\":\"failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again\"}", + "failure": [ + { + "failMessage": "failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again", + "name": "ip-192-0-2-243" + } + ], + "pending": [], + "success": [] + }, + "id": "d38a8e5d-2312-4046-a60f-a30a4aea1fbb", + "message": "Instance config failed to publish to", + "status": "failed", + "updateTime": "2023-01-14T04:35:47.566082799Z" +} +``` + +
diff --git a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md index b0d31319f..92287079d 100644 --- a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md +++ b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md @@ -1,76 +1,68 @@ --- -description: Learn how to use F5 NGINX Instance Manager to set up and manage NGINX App Protect WAF security policies. +description: Learn how you can use F5 NGINX Management Suite Instance Manager to configure + NGINX App Protect WAF security policies. docs: DOCS-992 -title: "How WAF policy management works" +title: NGINX App Protect WAF configuration management toc: true -weight: 100 +weight: 500 type: - reference --- ## Overview -F5 NGINX Instance Manager helps you manage [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/) security configurations. +F5 NGINX Management Suite Instance Manager provides configuration management for [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/). -Use NGINX Instance Manager with NGINX App Protect WAF to inspect incoming traffic, detect threats, and block malicious requests. You can define policies in one place and push them to some or all of your NGINX App Protect WAF instances. +You can use NGINX App Protect WAF with Instance Manager to inspect incoming traffic, identify potential threats, and block malicious traffic. With Configuration Management for App Protect WAF, you can configure WAF security policies in a single location and push your configurations out to one, some, or all of your NGINX App Protect WAF instances. -### Key features +### Features -- Manage WAF policies using the NGINX Instance Manager web interface or REST API -- Update attack signature and threat campaign packages -- Compile WAF configurations into a binary bundle for deployment +- Manage NGINX App Protect WAF security configurations by using the NGINX Management Suite user interface or REST API +- Update Attack Signatures and Threat Campaign packages +- Compile security configurations into a binary bundle for consumption by NGINX App Protect WAF instances ## Architecture -NGINX Instance Manager lets you define and manage security policies, upload signature packages, and push configurations to your NGINX App Protect WAF instances. It can also compile your security configuration into a bundle before publishing it to the data plane. +As demonstrated in Figure 1, Instance Manager lets you manage security configurations for NGINX App Protect WAF. You can define security policies, upload attack signatures and threat campaign packages, and publish common configurations out to your NGINX App Protect WAF instances. Instance Manager can compile the security configuration into a bundle before pushing the configuration to the NGINX App Protect WAF data plane instances. The NGINX Management Suite Security Monitoring module provides data visualization for NGINX App Protect, so you can monitor, analyze, and refine your policies. -The **Security Monitoring** module shows real-time data from NGINX App Protect WAF so you can track traffic, spot anomalies, and fine-tune policies. +{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Management Suite with NGINX App Protect Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution" width="75%">}} -{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Instance Manager with NGINX App Protect architecture overview" alt="Architecture diagram showing NGINX Instance Manager and Security Monitoring in the control plane pushing security bundles to NGINX App Protect WAF instances in the data plane" >}} +### Security Bundle Compilation {#security-bundle} -### Security bundle compilation {#security-bundle} +Instance Manager provides a compiler that can be configured to bundle the complete security configuration -- including JSON security policies, attack signatures, threat campaigns, and log profiles -- into a single binary in `.tgz` format. This bundle is then pushed out to each selected NGINX App Protect WAF instance. -NGINX Instance Manager includes a compiler that packages your complete WAF configuration — security policies, attack signatures, threat campaigns, and log profiles — into a single `.tgz` file. It then pushes this bundle to the selected NGINX App Protect WAF instances. +Performing the security bundle compilation on Instance Manager (precompiled publication) instead of on the NGINX App Protect WAF instances provides the following benefits: -**Why precompile with NGINX Instance Manager?** +- Eliminates the need to provision system resources on NGINX App Protect WAF instances to perform compilation. +- The bundles produced by Instance Manager can be reused by multiple NGINX App Protect WAF instances, instead of each instance having to perform the compilation separately. -- Saves system resources on WAF instances -- Lets you reuse the same bundle across multiple instances +However, if you prefer to maintain policy compilation on the NGINX App Protect WAF instance, that is supported with the following limitation: -If you choose to compile policies on the WAF instance instead, that works too—but with this limitation: +- Instance Manager does not publish JSON policies to the NGINX App Protect WAF instance. JSON policies referenced in an NGINX configuration must already exist on the NGINX App Protect WAF instance. -- NGINX Instance Manager won’t publish `.json` policies to the WAF instance. These policies must already exist on the instance and be referenced in the NGINX config. +The example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) context below enables NGINX App Protect WAF and tells NGINX where to find the compiled security bundle: -Example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) block to enable WAF and point to the bundle: +## Log Profile Compilation -```nginx -location / { - app_protect_enable on; - app_protect_policy_file /etc/app_protect/policies/policy_bundle.tgz; -} -``` - -## Log profile compilation - -You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on). +Instance Manager can also be configured to compile log profiles when you install a new version of the WAF compiler. When you publish an NGINX configuration with the NGINX App Protect [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, Instance Manager publishes the compiled log profiles to the NGINX App Protect WAF instances when precompiled publication is enabled. {{}} -NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tgz` file extension, not `.json`. +Instance Manager and Security Monitoring both use NGINX App Protect log profiles. The configuration requirements for each are different. When using Instance Manager configuration management, you must reference the log profile in your NGINX configuration using the `.tgz` file extension instead of `.json`. {{}} -## Security management APIs +## Security Management APIs -Use the NGINX Instance Manager REST API to automate updates across your NGINX App Protect WAF instances. You can use the API to manage: +By using the Instance Manager REST API, you can automate configuration updates to be pushed out to all of your NGINX App Protect WAF instances. You can use the Instance Manager API to manage and deploy the following security configurations: -- Security policies -- Log profiles -- Attack signatures -- Threat campaigns +- security policies, +- log profiles, +- attack signatures, and +- threat campaigns. -Just like with the web interface, the compiler creates a binary bundle with your updates that you can push to your WAF instances. +Just as with changes made via the user interface, the Instance Manager compiler bundles all of the config updates into a single binary package that you can push out to your instances. Figure 2 shows an overview of the API endpoints available to support security policy configuration and publishing. -{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Instance Manager with NGINX App Protect WAF architecture overview" alt="Diagram showing how the NGINX Instance Manager REST API is used to create policies, upload signatures and campaigns, and publish compiled security bundles to NGINX App Protect WAF instances">}} +{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Management Suite with NGINX App Protect WAF Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution">}} -For full details, see the API documentation: +More information is available in the Instance Manager API documentation. {{< include "nim/how-to-access-api-docs.md" >}} diff --git a/content/nim/nginx-app-protect/waf-config-management.md b/content/nim/nginx-app-protect/waf-config-management.md new file mode 100644 index 000000000..5e76684d4 --- /dev/null +++ b/content/nim/nginx-app-protect/waf-config-management.md @@ -0,0 +1,30 @@ +--- +description: Learn how to use NGINX Management Suite Instance Manager to publish NGINX + App Protect WAF configurations. +docs: DOCS-1114 +title: WAF Configuration Management +toc: true +weight: 100 +--- + +## Overview + +You can use NGINX Management Suite Instance Manager to publish configurations to your NGINX App Protect WAF data plane instances. + +## Publish WAF Configurations + +1. Set up your NGINX Management Suite Instance Manager instance: + + - [Install the WAF Compiler]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#install-the-waf-compiler" >}}) + + - [Set up the Attack Signatures and Threat Campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#set-up-attack-signatures-and-threat-campaigns" >}}) + +2. In Instance Manager, [onboard the App Protect Instances]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#onboard-nginx-app-protect-waf-instances" >}}) you want to publish policies and log profiles to. + +3. [Create the security policies]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-policy" >}}). + +4. [Create the security log profiles]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-log-profile" >}}). + +5. [Add or edit a WAF Configuration]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to your NGINX Instances, and publish using Instance Manager. + + {{}}Map the App Protect directives on NGINX configuration to `.tgz` file extensions (not `.json`).{{< /note >}} diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index d9e123c6f..e5ecaf984 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -31,6 +31,33 @@

{{ .Title }}

+ {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX fleet")}} +

Use the F5 NGINX One Console to deploy, scale, or migrate your apps

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}} +

See benefits from the NGINX One Console

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}} +

Manage your work-in-progress

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your NGINX instances")}} +

Keep an inventory of your deployments

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} +

Update them before they expire

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}} +

Secure your systems with role-based access control

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize in groups")}} +

Configure and synchronize groups of NGINX instances simultaneously

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} +

Automate NGINX fleet management

+ {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}} +

Terms unique to NGINX One Console

+ {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "How-to guides") }}
    {{ range .Pages }} @@ -43,6 +70,7 @@

{{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "API")}} +

These are API docs

    {{ range .Pages }}
  • {{ .Title }}
    • @@ -96,4 +124,4 @@

    {{end}} - \ No newline at end of file + From bdd7c1679bfe0518639094b02799283b8944bf4f Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 10:31:10 -0700 Subject: [PATCH 02/25] Less --- .../waf-config-management.md | 30 ------------------- 1 file changed, 30 deletions(-) delete mode 100644 content/nim/nginx-app-protect/waf-config-management.md diff --git a/content/nim/nginx-app-protect/waf-config-management.md b/content/nim/nginx-app-protect/waf-config-management.md deleted file mode 100644 index 5e76684d4..000000000 --- a/content/nim/nginx-app-protect/waf-config-management.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: Learn how to use NGINX Management Suite Instance Manager to publish NGINX - App Protect WAF configurations. -docs: DOCS-1114 -title: WAF Configuration Management -toc: true -weight: 100 ---- - -## Overview - -You can use NGINX Management Suite Instance Manager to publish configurations to your NGINX App Protect WAF data plane instances. - -## Publish WAF Configurations - -1. Set up your NGINX Management Suite Instance Manager instance: - - - [Install the WAF Compiler]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#install-the-waf-compiler" >}}) - - - [Set up the Attack Signatures and Threat Campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#set-up-attack-signatures-and-threat-campaigns" >}}) - -2. In Instance Manager, [onboard the App Protect Instances]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#onboard-nginx-app-protect-waf-instances" >}}) you want to publish policies and log profiles to. - -3. [Create the security policies]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-policy" >}}). - -4. [Create the security log profiles]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-log-profile" >}}). - -5. [Add or edit a WAF Configuration]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to your NGINX Instances, and publish using Instance Manager. - - {{}}Map the App Protect directives on NGINX configuration to `.tgz` file extensions (not `.json`).{{< /note >}} From 1e1939c3e2a7a0e1848b07fb46b1b72bd21cbbb7 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 10:45:08 -0700 Subject: [PATCH 03/25] More --- .../nginx-one/config-sync-groups/_index.md | 2 +- content/nginx-one/how-to/_index.md | 6 - .../nginx-one/how-to/certificates/_index.md | 6 - .../certificates/manage-certificates.md | 197 ------------- .../how-to/config-sync-groups/_index.md | 6 - .../how-to/config-sync-groups/add-file-csg.md | 67 ----- .../manage-config-sync-groups.md | 267 ------------------ content/nginx-one/how-to/containers/_index.md | 6 - ...ginx-plus-container-images-to-nginx-one.md | 113 -------- .../how-to/data-plane-keys/_index.md | 6 - .../create-manage-data-plane-keys.md | 68 ----- .../nginx-one/how-to/nginx-configs/_index.md | 6 - .../how-to/nginx-configs/add-file.md | 67 ----- .../how-to/nginx-configs/add-instance.md | 75 ----- .../clean-up-unavailable-instances.md | 40 --- .../manage-config-sync-groups.md | 239 ---------------- .../view-edit-nginx-configurations.md | 41 --- .../nginx-one/how-to/proxy-setup/_index.md | 6 - .../set-up-nginx-proxy-for-nginx-one.md | 101 ------- content/nginx-one/how-to/settings/_index.md | 7 - .../nginx-one/how-to/staged-configs/_index.md | 6 - .../staged-configs/add-staged-config.md | 88 ------ .../staged-configs/api-staged-config.md | 29 -- .../staged-configs/edit-staged-config.md | 38 --- .../import-export-staged-config.md | 89 ------ content/nginx-one/nginx-configs/_index.md | 2 +- layouts/partials/list-main.html | 4 +- 27 files changed, 4 insertions(+), 1578 deletions(-) delete mode 100644 content/nginx-one/how-to/_index.md delete mode 100644 content/nginx-one/how-to/certificates/_index.md delete mode 100644 content/nginx-one/how-to/certificates/manage-certificates.md delete mode 100644 content/nginx-one/how-to/config-sync-groups/_index.md delete mode 100644 content/nginx-one/how-to/config-sync-groups/add-file-csg.md delete mode 100644 content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md delete mode 100644 content/nginx-one/how-to/containers/_index.md delete mode 100644 content/nginx-one/how-to/containers/connect-nginx-plus-container-images-to-nginx-one.md delete mode 100644 content/nginx-one/how-to/data-plane-keys/_index.md delete mode 100644 content/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md delete mode 100644 content/nginx-one/how-to/nginx-configs/_index.md delete mode 100644 content/nginx-one/how-to/nginx-configs/add-file.md delete mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md delete mode 100644 content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md delete mode 100644 content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md delete mode 100644 content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md delete mode 100644 content/nginx-one/how-to/proxy-setup/_index.md delete mode 100644 content/nginx-one/how-to/proxy-setup/set-up-nginx-proxy-for-nginx-one.md delete mode 100644 content/nginx-one/how-to/settings/_index.md delete mode 100644 content/nginx-one/how-to/staged-configs/_index.md delete mode 100644 content/nginx-one/how-to/staged-configs/add-staged-config.md delete mode 100644 content/nginx-one/how-to/staged-configs/api-staged-config.md delete mode 100644 content/nginx-one/how-to/staged-configs/edit-staged-config.md delete mode 100644 content/nginx-one/how-to/staged-configs/import-export-staged-config.md diff --git a/content/nginx-one/config-sync-groups/_index.md b/content/nginx-one/config-sync-groups/_index.md index db1ee5560..eaefeaea3 100644 --- a/content/nginx-one/config-sync-groups/_index.md +++ b/content/nginx-one/config-sync-groups/_index.md @@ -1,6 +1,6 @@ --- description: -title: Organize in groups +title: Change multiple instances with one push weight: 400 url: /nginx-one/config-sync-groups --- diff --git a/content/nginx-one/how-to/_index.md b/content/nginx-one/how-to/_index.md deleted file mode 100644 index e7b505736..000000000 --- a/content/nginx-one/how-to/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: How-to guides -weight: 700 -url: /nginx-one/how-to/ ---- diff --git a/content/nginx-one/how-to/certificates/_index.md b/content/nginx-one/how-to/certificates/_index.md deleted file mode 100644 index 39e16a174..000000000 --- a/content/nginx-one/how-to/certificates/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Certificates -weight: 400 -url: /nginx-one/how-to/certificates ---- diff --git a/content/nginx-one/how-to/certificates/manage-certificates.md b/content/nginx-one/how-to/certificates/manage-certificates.md deleted file mode 100644 index 0d53b6947..000000000 --- a/content/nginx-one/how-to/certificates/manage-certificates.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -docs: null -title: Manage certificates -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how you can manage SSL/TLS certificates with the F5 NGINX One Console. Valid certificates support encrypted connections between NGINX and your users. - -You may have separate sets of SSL/TLS certificates, as described in the following table: - -{{}} -| Functionality | Typical file names | Notes | -|-------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------| -| Website traffic | /etc/nginx/ssl/example.com.crt
    /etc/nginx/ssl/example.com.key | Typically purchased from a Certificate Authority (CA) | -| Repository access | /etc/ssl/nginx/nginx-repo.crt
    /etc/ssl/nginx/nginx-repo.key | Supports access to repositories to download and install NGINX packages | -| NGINX Licensing | /etc/ssl/nginx/server.crt
    /etc/ssl/nginx/server.key | Supports access to repositories. Based on licenses downloaded from https://my.f5.com/ | -{{    }} - -Allowed directories depend on the [NGINX Agent]({{< ref "/nginx-one/getting-started/#install-nginx-agent" >}}). Look for the `/etc/nginx-agent/nginx-agent.conf` file. -Find the `config_dirs` parameter in that file, as described in the NGINX Agent [Basic configuration](https://docs.nginx.com/nginx-agent/configuration/configuration-overview/#cli-flags--environment-variables). -You may need to add a directory like `/etc/ssl` to that parameter. - -From the NGINX One Console you can: - -- Monitor all certificates configured for use by your connected NGINX Instances. -- Ensure that your certificates are current and correct. -- Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. - -You can manage the certificates for: - -- [Unique instances]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md#new-ssl-certificate-or-ca-bundle" >}}) -- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) - - -{{< tip >}} - -If you are managing the certificate from NGINX One Console, we recommend that you avoid directly manipulating the files on the data plane. - -{{< /tip >}} - -## Before you start - -Before you add and manage certificates with the NGINX One Console make sure: - -- You have access to the NGINX One Console -- You have access through the F5 Distributed Cloud role, as described in the [Authentication]({{< ref "/nginx-one/api/authentication.md" >}}) guide, to manage SSL/TLS certificates - - You have the `f5xc-nginx-one-user` role for your account -- Your SSL/TLS certificates and keys match - -### SSL/TLS certificates and more - -NGINX One Console supports certificates for access to repositories. You may need a copy of these files from your Certificate Authority (CA) to upload them to NGINX One Console: - -- SSL Certificate - - Example file extensions: .crt, .pem -- Privacy certificate - - Example file extensions: .key, .pem - -The NGINX One Console allows you to upload these certificates as text and as files. You can also upload your own certificate files (with file extensions such as .crt and .key). - -Make sure your certificates, keys, and pem files are encrypted to one of the following standards: - -- RSA -- ECC/ECDSA - -In other words, any private key of this type should be supported, regardless of the curve types or hashing algorithm. - -For exmaple, if you use ECDSA private keys in PEM format, the PEM headers should contain: - -``` ------BEGIN EC PRIVATE KEY----- - ------END EC PRIVATE KEY----- - -``` - -If you use one of these keys, the US National Institute of Standards and Technology, in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf), recommends a key size of at least -2048 bits. It also has recommnedations for ECDSA. - -### Include certificates in NGINX configuration - -For NGINX configuration, these files are typically associated with the following NGINX directives: - -- [`ssl_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate) -- [`ssl_certificate_key`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate_key) -- [`ssl_trusted_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_trusted_certificate) -- [`ssl_client_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) -- [`proxy_ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate) -- [`proxy_ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate_key) - -## Important considerations - -Most websites include valid information from public keys and certificates or CA bundles. However, the NGINX One Console accepts, but provides warnings for these use cases: - -- When the public certificate is expired -- When the leaf certificate part of a certificate chain is expired -- When any of the components of a CA bundle are expired -- When the public key does not match the private certificate - -In such cases, you may get websites that present "Your connection is not private" warning messages in client web browsers. - -## Review existing certificates - -Follow these steps to review existing certificates for your instances. - -On the left-hand pane, select **Certificates**. In the window that appears, you see: - -{{}} -| Term | Definition | -|-------------|-------------| -| **Total** | Total number of certificates available to NGINX One Console | -| **Valid (31+ days)** | Number of certificates that expire in 31 or more days | -| **Expires Soon (<31 days)** | Number of certificates that expire in less than 31 days | -| **Expired** | Number of exprired certificates | -| **Not Ready** | Certificates with a start date in the future | -| **Managed** | Managed by and stored in the NGINX One Console | -| **Unmanaged** | Detected by, and not managed by NGINX One Console. To convert to managed, you may need to upload the certificate and key during the process. | -{{}} - -You can **Add Filter** to filter certificates by: - -- Name -- Status -- Subject Name -- Type - -The Export option supports exports of basic certification file information to a CSV file. It does _not_ include the content of the public certificate or the private key. - -## Add a new certificate or bundle - -To add a new certificate, select **Add Certificate**. - - -In the screen that appears, you can add a certificate name. If you don't add a name, NGINX One will add a name for you, based on the expiration date for the certificate. - -You can add certificates in the following formats: - -- **SSL Certificate and Key** -- **CA Certificate Bundle** - -In each case, you can upload files directly, or enter the content of the certificates in a text box. Once you upload these certificates, you'll see: - -- **Certificate Details**, with the Subject Name, start and end dates. -- **Key Details**, with the encryption key size and algorithm, such as RSA - - -## Edit an existing certificate or bundle - -You can modify existing certificates from the **Certificates** screen. Select the certificate of your choice. Depending on the type of certificate, you'll then see either a **Edit Certificate** or **Edit CA Bundle** option. The NGINX One Console then presents a window with the same options as shown when you [Add a new certificate](#add-a-new-certificate-or-bundle). - -If that certificate is already managed as part of a Config Sync Group, the changes you make affect all instances in that group. - -## Remove a deployed certificate - -You can remove a deployed certificate from an independent instance or from a Config Sync Group. This will remove the certificate's association with the instance or group, but it does not delete the certificate files from the instance(s). - -Every instance with a deployed certificate includes paths to certificates in their configuration files. If you remove the deployed file path to one certificate, that change is limited to that one instance. - -Every Config Sync Group also includes paths to certificates in its configuration files. If you remove the deployed path to one certificate, that change affects all instances which belong to that Config Sync Group. - -## Delete a deployed certificate - -To delete a certificate, find the name in the **Certificates** screen. Find the **Actions** column associated with the certificate. Select the ellipsis (`...`) and then select **Delete**. Before deleting that certificate, you should see a warning. - -If that certificate is managed and is part of a Config Sync Group, that change affects all instances in that group. - -{{< warning >}} Be cautious if you want to delete certificates that are being used by an instance or a Config Sync Group. Deleting such certificates leads to failure in affected NGINX deployments. {{< /warning >}} - -## Managed and unmanaged certificates - -If you register an instance to NGINX One Console, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), and the associated SSL/TLS certificates: - -- Are used in their NGINX configuration -- Do _not_ match an existing managed SSL certificate/CA bundle - -These certificates appear in the list of unmanaged certificates. NGINX One Console does not store unmanaged certs or keys, only metadata associated with certs for monitoring. - -We recommend that you convert your unmanaged certificates. Converting to a managed certificate allows you to centrally manage, update, and deploy a certificate to your data plane from the NGINX One Console. - -To convert these cerificates to managed, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - - - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Add a file in a configuration]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md" >}}) diff --git a/content/nginx-one/how-to/config-sync-groups/_index.md b/content/nginx-one/how-to/config-sync-groups/_index.md deleted file mode 100644 index 31f258b69..000000000 --- a/content/nginx-one/how-to/config-sync-groups/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Config Sync Groups -weight: 250 -url: /nginx-one/how-to/config-sync-groups ---- diff --git a/content/nginx-one/how-to/config-sync-groups/add-file-csg.md b/content/nginx-one/how-to/config-sync-groups/add-file-csg.md deleted file mode 100644 index ad8d31ca0..000000000 --- a/content/nginx-one/how-to/config-sync-groups/add-file-csg.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -docs: null -title: Add a file to a Config Sync Group -toc: true -weight: 400 -type: -- how-to ---- - -## Overview - -{{< include "nginx-one/add-file/overview.md" >}} - -## Before you start - -Before you add files in your configuration, ensure: - -- You have access to the NGINX One Console. -- Config Sync Groups are properly registered with NGINX One Console - -## Important considerations - -This page applies when you want to add a file to a Config Sync Group. Any changes you make here apply to all [Instances]({{< ref "/nginx-one/glossary.md" >}}) of that Config Sync Group. - -## Add a file - -You can use the NGINX One Console to add a file to a specific Config Sync Group. To do so: - -1. Select the Config Sync Group to manage. -1. Select the **Configuration** tab. - - {{< tip >}} - - {{< include "nginx-one/add-file/edit-config-tip.md" >}} - - {{< /tip >}} - -1. Select **Edit Configuration**. -1. In the **Edit Configuration** window that appears, select **Add File**. - -You now have multiple options, described in the sections which follow. - -### New Configuration File - -Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. - -### New SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} - - {{< tip >}} - - Make sure to specify the path to your certificate in your NGINX configuration, - with the `ssl_certificate` and `ssl_certificate_key` directives. - - {{< /tip >}} - -### Existing SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md deleted file mode 100644 index d686e713e..000000000 --- a/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -docs: null -title: Manage Config Sync Groups -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -If you work with several instances of NGINX, it can help to organize these instances in Config Sync Groups. Each instance in a Config Sync Group has the same configuration. - -This guide explains how to create and manage Config Sync Groups in the F5 NGINX One Console. Config Sync Groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. - -If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find Config Sync Groups in NGINX One similar, though the steps and terminology differ slightly. - -Config Sync Groups are functionally different from syncing instances in a cluster. They let you to manage and synchronize configurations across multiple NGINX instances, all at once. - -This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While Config Sync Groups focus on configuration management, cluster syncing supports failover and data consistency. - -## Before you start - -Before you create and manage Config Sync Groups, ensure: - -- You have access to the NGINX One Console. -- You have the necessary permissions to create and manage Config Sync Groups. -- If you plan to add existing instances to a Config Sync Group, make sure those NGINX instances are properly registered with NGINX One. - -## Configuration management - -Config Sync Groups support configuration inheritance and persistance. If you've just created a Config Sync Group, you can define the configuration for that group in the following ways: - -- Before adding an instance to a group, you can [Define the Config Sync Group configuration manually](#define-the-config-sync-group-configuration-manually). -- When you add the first instance to a group, that instance defines the configuration for that Config Sync Group. -- Afterwards, you can modify the configuration of the Config Sync Group. That modifies the configuration of all member instances. Future members of that group inherit that modified configuration. - -On the other hand, if you remove all instances from a Config Sync Group, the original configuration persists. In other words, the group retains the configuration from that first instance (or the original configuration). Any new instance that you add later still inherits that configuration. - -{{< tip >}}You can use _unmanaged_ certificates. NGINX One Console does not store unmanaged certs or keys, only metadata associated with the certs or keys for monitoring. Your actions can affect the [Config Sync Group status](#config-sync-group-status). For future instances on the data plane, if it: - -- Has unmanaged certificates in the same file paths as defined by the NGINX configuration as the Config Sync Group, that instance will be [**In Sync**](#config-sync-group-status). -- Will be [**Out of Sync**](#config-sync-group-status) if the instance: - - Does not have unmanaged certificates in the same file paths - - Has unmanaged certificates in a different directory from the Config Sync Group -{{< /tip >}} - -### Risk when adding multiple instances to a Config Sync Group - -If you add multiple instances to a single Config Sync Group, simultaneously (with automation), there's a risk that the instance selects a random configuration. To prevent this problem, you should: - -1. Create a Config Sync Group. -1. Add a configuration to the Config Sync Group, so all instances inherit it. -1. Add the instances in a separate operation. - -Your instances should synchronize with your desired configuration within 30 seconds. - -### Use an instance to define the Config Sync Group configuration - -1. Follow the steps in the [**Add an existing instance to a Config Sync Group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a Config Sync Group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. -2. The NGINX configuration from this instance will automatically become the group's configuration. -3. You can further edit and publish this configuration by following the steps in the [**Publish the Config Sync Group configuration**](#publish-the-config-sync-group-configuration) section. - -### Define the Config Sync Group configuration manually - -You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. - -To manually set the group configuration: - -1. Follow steps 1–4 in the [**Create a Config Sync Group**](#create-a-config-sync-group) section to create your Config Sync Group. -2. After creating the group, select the **Configuration** tab. -3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. -4. To add a configuration, select **Edit Configuration**. -5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. -6. After making your changes, select **Next** to view a split screen showing your changes. -7. If you're satisfied with the configuration, select **Save and Publish**. - -## Important considerations - -When you plan Config Sync Groups, consider the following factors: - -- **Single Config Sync Group membership**: You can add an instance to only one Config Sync Group. - -- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified Config Sync Group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. - -- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same Config Sync Group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. - -## Create a Config Sync Group - -When you create a Config Sync Group, you can manage the configurations of multiple NGINX instances as a single entity. - -1. On the left menu, select **Config Sync Groups**. -2. Select **Add Config Sync Group**. -3. In the **Name** field, type a name for your Config Sync Group. -4. Select **Create** to add the Config Sync Group. - -## Manage Config Sync Group membership - -Now that you created a Config Sync Group, you can add instances to that group. As described in [Configuration management](#configuration-management), the first instance you add to a group, when you add it, defines the initial configuration for the group. You can update the configuration for the entire Config Sync Group. - -Any instance that joins the group afterwards inherits that configuration. - -{{< note >}} If you see the following [Config Sync Group Status](#config-sync-group-status) message: **Out of Sync**: - - - Review the instance details in NGINX One Console to identify any publication problems. - - After you change the configuration of the Config Sync Group, [Publish it](#publish-the-config-sync-group-configuration]. -In that case, review and resolve discrepancies between the Instance and the rest of the Config Sync Group. {{< /note >}} - -### Add an existing instance to a Config Sync Group {#add-an-existing-instance-to-a-config-sync-group} - -You can add existing NGINX instances that are already registered with NGINX One to a Config Sync Group. - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. At the end of the file, add a new line beginning with `instance_group:`, followed by the Config Sync Group name. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent: - - ``` shell - sudo systemctl restart nginx-agent - ``` - -### Add a new instance to a Config Sync Group {#add-a-new-instance-to-a-config-sync-group} - -When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. - -1. On the left menu, select **Config Sync Groups**. -2. Select the Config Sync Group in the list. -3. In the **Instances** pane, select **Add Instance to Config Sync Group**. -4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to Config Sync Group**. -5. Select **Next**. -6. **Generate a new data plane key** (choose this option if you don't have an existing key): - - - Select **Generate new key** to create a new data plane key for the instance. - - Select **Generate Data Plane Key**. - - Copy and securely store the generated key, as it is displayed only once. - -7. **Use an existing data plane key** (choose this option if you already have a key): - - - Select **Use existing key**. - - In the **Data Plane Key** field, enter the existing data plane key. - -{{}} - -{{%tab name="Virtual Machine or Bare Metal"%}} - -8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. -9. Select **Done** to complete the process. - -{{%/tab%}} - -{{%tab name="Docker Container"%}} - -8. **Log in to the NGINX private registry**: - - - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) license from [MyF5](https://my.f5.com/manage/s/). - - ```shell - sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none - ``` - -9. **Pull the Docker image**: - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - -10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. - -11. Select **Done** to complete the process. - -{{%/tab%}} - -{{}} - -{{}} - -Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. - -For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). - -{{}} - -### Move an instance to a different Config Sync Group - -If you need to move an NGINX instance to a different Config Sync Group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and change it to the name of the new Config Sync Group. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent by running the following command: - - ```shell - sudo systemctl restart nginx-agent - ``` - -If you move an instance with certificates from one Config Sync Group to another, NGINX One adds or removes those certificates from the data plane, to synchronize with the deployed certificates of the group. - -### Remove an instance from a Config Sync Group - -If you need to remove an NGINX instance from a Config Sync Group without adding it to another group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. - - ```text - # instance_group: - ``` - -4. Restart NGINX Agent: - - ```shell - sudo systemctl restart nginx-agent - ``` - -By removing or commenting out this line, the instance will no longer be associated with any Config Sync Group. - -## Publish the Config Sync Group configuration {#publish-the-config-sync-group-configuration} - -After the Config Sync Group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. - -1. On the left menu, select **Config Sync Groups**. -2. Select the Config Sync Group in the list. -3. Select the **Configuration** tab to view the group's NGINX configuration. -4. To modify the group's configuration, select **Edit Configuration**. -5. Make the necessary changes to the configuration. -6. When you're finished, select **Next**. A split view displays the changes. -7. If you're satisfied with the changes, select **Save and Publish**. - -Publishing the group configuration ensures that all instances within the Config Sync Group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. - -## Config Sync Group status - -The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. - -{{}} -| **Status** | **Description** | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| **In Sync** | All instances within the Config Sync Group have configurations that match the group configuration. No action is required. | -| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | -| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | -| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | -{{}} - -Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/how-to/containers/_index.md b/content/nginx-one/how-to/containers/_index.md deleted file mode 100644 index c3617fd7d..000000000 --- a/content/nginx-one/how-to/containers/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Containers -weight: 300 -url: /nginx-one/how-to/containers ---- diff --git a/content/nginx-one/how-to/containers/connect-nginx-plus-container-images-to-nginx-one.md b/content/nginx-one/how-to/containers/connect-nginx-plus-container-images-to-nginx-one.md deleted file mode 100644 index daae3af88..000000000 --- a/content/nginx-one/how-to/containers/connect-nginx-plus-container-images-to-nginx-one.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -description: '' -docs: null -title: Connect NGINX Plus container images to NGINX One -toc: true -weight: 400 -type: -- how-to ---- - -## Overview - -This guide explains how to set up an F5 NGINX Plus Docker container with NGINX Agent and connect it to the NGINX One Console. - ---- - -## Before you start - -Before you start, make sure you have: - -- A valid JSON Web Token (JWT) for your NGINX subscription. -- [A data plane key from NGINX One]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}). -- Docker installed and running on your system. - -#### Download your JWT license from MyF5 - -{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} - ---- - -## Process for private registry - -### Log in to the NGINX private registry - -Use your JWT to log in to the NGINX private registry. Replace `YOUR_JWT_HERE` with your JWT. - -```sh -sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none -``` - -{{< include "security/jwt-password-note.md" >}} - -### Pull the NGINX Plus image - -Pull the NGINX Plus image from the private registry. Replace `VERSION_TAG` with the desired version, such as `alpine`, `debian`, or `ubi`. - -```sh -sudo docker pull private-registry.nginx.com/nginx-plus/agent:VERSION_TAG -``` - -You must specify a version tag. The `latest` tag is not supported. Learn more in the [Deploying NGINX and NGINX Plus on Docker]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}) guide. - -
    - -{{}} -To pull the `debian` image: - -```sh -sudo docker pull private-registry.nginx.com/nginx-plus/agent:debian -``` -{{}} - -### Start the NGINX Plus container - -Start the Docker container to connect it to NGINX One. Replace `YOUR_NGINX_ONE_DATA_PLANE_KEY_HERE` with your data plane key and `VERSION_TAG` with the version tag you pulled. - -**For NGINX Plus R33 or later**: - -- Use the `NGINX_LICENSE_JWT` variable to pass your JWT license. Replace `YOUR_JWT_HERE` with your JWT. - -For more details, see [About subscription licenses]({{< ref "solutions/about-subscription-licenses.md" >}}). - -```sh -sudo docker run \ ---env=NGINX_LICENSE_JWT="YOUR_JWT_HERE" \ ---env=NGINX_AGENT_SERVER_GRPCPORT=443 \ ---env=NGINX_AGENT_SERVER_HOST=agent.connect.nginx.com \ ---env=NGINX_AGENT_SERVER_TOKEN="YOUR_NGINX_ONE_DATA_PLANE_KEY_HERE" \ ---env=NGINX_AGENT_TLS_ENABLE=true \ ---restart=always \ ---runtime=runc \ --d private-registry.nginx.com/nginx-plus/agent: -``` - -
    - -{{}} -To start the container with the `debian` image: - -```sh -sudo docker run \ ---env=NGINX_LICENSE_JWT="YOUR_JWT_HERE" \ ---env=NGINX_AGENT_SERVER_GRPCPORT=443 \ ---env=NGINX_AGENT_SERVER_HOST=agent.connect.nginx.com \ ---env=NGINX_AGENT_SERVER_TOKEN="YOUR_NGINX_ONE_DATA_PLANE_KEY_HERE" \ ---env=NGINX_AGENT_TLS_ENABLE=true \ ---restart=always \ ---runtime=runc \ --d private-registry.nginx.com/nginx-plus/agent:debian -``` - -{{}} - ---- - -## References - -For more details, see: - -- [Deploying NGINX and NGINX Plus on Docker](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/) -- [Full List of Agent Environment Variables](https://docs.nginx.com/nginx-agent/configuration/configuration-overview/#nginx-agent-environment-variables) -- [NGINX One Data Plane Keys](https://docs.nginx.com/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys/) -- [My F5 Knowledge Article](https://my.f5.com/manage/s/article/K000090257) diff --git a/content/nginx-one/how-to/data-plane-keys/_index.md b/content/nginx-one/how-to/data-plane-keys/_index.md deleted file mode 100644 index 0aa1ba7bf..000000000 --- a/content/nginx-one/how-to/data-plane-keys/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Data plane keys -weight: 100 -url: /nginx-one/how-to/data-plane-keys ---- diff --git a/content/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md b/content/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md deleted file mode 100644 index 9ac000860..000000000 --- a/content/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -description: '' -docs: DOCS-1395 -title: Create and manage data plane keys -toc: true -weight: 100 -type: -- how-to ---- - - - -## About data plane keys - -Data plane keys are required for registering NGINX instances with the F5 NGINX One Console. These keys serve as secure tokens, ensuring that only authorized NGINX instances can connect to and communicate with NGINX One. You have the flexibility to reuse a key with multiple instances, or to create a unique key for each instance. - -{{}} -Data plane keys are displayed only once and cannot be retrieved later. Be sure to copy and store this key securely. - -Data plane keys expire after one year. You can change this expiration date later by editing the key. - -Revoking a data plane key disconnects all instances that were registered with that key. -{{}} - -## Create a new data plane key - -To create a new key for connecting your NGINX instances to NGINX One, follow these steps: - -1. On the left menu, select **Data Plane Keys**. -2. Select **Add Data Plane Key**. -3. Enter a name for your new key. Optionally, you can set an expiration date for the key. If you don't set a date, the key will automatically expire one year from today. The longest duration for a key is one year. You can change this expiration date later by editing the key. -4. Select **Generate**. -5. A confirmation screen will show your new data plane key. Be sure to copy and store this key securely. It is displayed *only once* and cannot be retrieved later. -6. Select **Close** to complete the process. - -## Change the expiration date {#change-expiration-date} - -To change the expiration date of a data plane key, follow these steps before the key expires. You cannot update the expiration date after the key has expired. - -1. On the left menu, select **Data Plane Keys**. -2. Find the key you want to edit in the list. -3. Next to the key name, in the **Actions** column, select the ellipsis (three dots) and then select **Edit Key**. -4. Set a new expiration date for the key. The longest duration for a key is one year. -5. Select **Save**. - -## Revoke a data plane key {#revoke-data-plane-key} - -If you need to deactivate a data plane key before its expiration date, follow these steps. Once revoked, the key will no longer connect any NGINX instances to NGINX One. The key will still be visible in the console until you delete it. - -1. On the left menu, select **Data Plane Keys**. -2. Find the key you want to revoke in the list. -3. Next to the key name, in the **Actions** column, select the ellipsis (three dots) and then select **Revoke**. -4. A confirmation dialog will appear. Select **Revoke** to confirm. - - -## Delete a data plane key - -Before you can delete a key, it must be expired or revoked. You can revoke a key either through the NGINX One Console, as explained above, or by using the REST API. Once deleted, all information about the data plane key is permanently removed. - -1. On the left menu, select **Data Plane Keys**. -2. Find the key you want to revoke in the list of expired or revoked keys. -3. Next to the key name, select the check box. You can select multiple keys at the same time. -4. Select **Delete selected**. diff --git a/content/nginx-one/how-to/nginx-configs/_index.md b/content/nginx-one/how-to/nginx-configs/_index.md deleted file mode 100644 index b7fa815da..000000000 --- a/content/nginx-one/how-to/nginx-configs/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Instances and Configurations -weight: 200 -url: /nginx-one/how-to/nginx ---- diff --git a/content/nginx-one/how-to/nginx-configs/add-file.md b/content/nginx-one/how-to/nginx-configs/add-file.md deleted file mode 100644 index 7b654d86e..000000000 --- a/content/nginx-one/how-to/nginx-configs/add-file.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -docs: null -title: Add a file to an instance -toc: true -weight: 400 -type: -- how-to ---- - -## Overview - -{{< include "nginx-one/add-file/overview.md" >}} - -## Before you start - -Before you add files in your configuration, ensure: - -- You have access to the NGINX One Console. -- NGINX instances are properly registered with NGINX One Console - -## Important considerations - -If your instance is a member of a Config Sync Group, changes that you make may be synchronized to other instances in that group. -For more information, see how you can [Manage Config Sync Groups]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}). - -## Add a file - -You can use the NGINX One Console to add a file to a specific instance. To do so: - -1. Select the instance to manage. -1. Select the **Configuration** tab. - - {{< tip >}} - - {{< include "nginx-one/add-file/edit-config-tip.md" >}} - - {{< /tip >}} - -1. Select **Edit Configuration**. -1. In the **Edit Configuration** window that appears, select **Add File**. - -You now have multiple options, described in the sections which follow. - -### New Configuration File - -Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. - -### New SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} - - {{< tip >}} - - Make sure to specify the path to your certificate in your NGINX configuration, - with the `ssl_certificate` and `ssl_certificate_key` directives. - - {{< /tip >}} - -### Existing SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md deleted file mode 100644 index 8bae0ef02..000000000 --- a/content/nginx-one/how-to/nginx-configs/add-instance.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: '' -title: Add an NGINX instance -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need -to set up a data plane key to connect your instances to NGINX One. - -## Before you start - -Before you add an instance to NGINX One Console, ensure: - -- You have administrator access to NGINX One Console. -- You have configured instances of NGINX that you want to manage through NGINX One Console. -- You have or are ready to configure a data plane key. -- You have or are ready to set up managed certificates. - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} - -## Add an instance - -You can add an instance to NGINX One Console in the following ways: - -- Directly, under **Instances** -- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** - -In either case, NGINX One Console gives you a choice for data plane keys: - -- Create a new key -- Use an existing key - -NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. - -Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. - -```bash -curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y -``` - -Once the process is complete, you can configure that instance in your NGINX One Console. - -## Managed and Unmanaged Certificates - -If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. - -### If the certificate is already managed - -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. - -NGINX One Console can manage your instances along with those certificates. - -### If the certificate is not managed - -These certificates appear in the list of **Unmanaged Certificates**. - -To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. - -To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - -Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. - -## Add an instance to a Config Sync Group - -When you [Manage Config Sync Group membership]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. -That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md deleted file mode 100644 index 6a119617d..000000000 --- a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: '' -docs: null -title: Clean up unavailable NGINX instances -toc: true -weight: 200 -type: -- how-to ---- - -## Overview - -This guide explains how to set up automatic cleanup for NGINX instances in NGINX One. The cleanup process removes instances that have been unavailable for a specified duration. By default, this period is 24 hours from the time the NGINX instance was last updated. Administrators can change or disable the cleanup duration in **Settings > Instance Settings**. Events will be generated for NGINX instances that have been automatically cleaned up; you can see these events on the **Overview > Events** page. - -## Before you start - -Before you set up automatic cleanup for NGINX instances, ensure: - -- You have administrator access to NGINX One. -- You understand that this action will delete instances permanently after they are unavailable for the specified duration. - -## Configure instance cleanup - -Follow these steps to set up automatic cleanup for NGINX instances in NGINX One: - -1. On the left menu, select **Instance Settings**. -1. On the **Instance Settings** page, in the **Unavailable Instance Cleanup** section, select **Edit Duration**. -1. Choose the cleanup duration. - - Select one of the predefined durations (None, 1 day, 7 days, 30 days) or set a custom duration. Selecting **None** disables automatic cleanup. - - If you choose **Custom**, enter the duration in hours or days. -1. Select **Save** to apply the changes. - -## Event log details - -When instances are cleaned up automatically, an event log entry is created. You can find these events on the **Overview > Events** page. The event log includes the following details: - -- **Impacted Object ID**: The unique identifier of the NGINX instance that was cleaned up. -- **Type**: The type of event, which will be "Automated Object Cleanup". -- **Timestamp**: The date and time when the instance was cleaned up. -- **Message**: A description indicating that the instance was unavailable for the configured duration before being cleaned up. diff --git a/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md b/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md deleted file mode 100644 index 8bc10cce6..000000000 --- a/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -docs: null -title: Manage config sync groups -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -This guide explains how to create and manage config sync groups in the F5 NGINX One Console. Config sync groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. - -If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find config sync groups in NGINX One similar, though the steps and terminology differ slightly. - -## Before you start - -Before you create and manage config sync groups, ensure: - -- You have access to the NGINX One Console. -- You have the necessary permissions to create and manage config sync groups. -- NGINX instances are properly registered with NGINX One if you plan to add existing instances to a config sync group. - -## Important considerations - -- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified config sync group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. - -- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same config sync group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. - -- **Single config sync group membership**: An instance can join only one config sync group at a time. - -- **Configuration inheritance**: If the config sync group already has a configuration defined, that configuration will be pushed to instances when they join. - -- **Using an instance's configuration for the group configuration**: If an instance is the first to join a config sync group and the group's configuration hasn't been defined, the instance’s configuration will become the group’s configuration. Any instances added later will automatically inherit this configuration. - - {{< note >}} If you add multiple instances to a single config sync group, simultaneously (with automation), follow these steps. Your instances will inherit your desired configuration: - - 1. Create a config sync group. - 1. Add a configuration to the config sync group, so all instances inherit it. - 1. Add the instances in a separate operation. - - Your instances should synchronize with your desired configuration within 30 seconds. {{< /note >}} - -- **Persistence of a config sync group's configuration**: The configuration for a config sync group persists until you delete the group. Even if you remove all instances, the group's configuration stays intact. Any new instances that join later will automatically inherit this configuration. - -- **Config sync groups vs. cluster syncing**: Config sync groups are not the same as cluster syncing. Config sync groups let you to manage and synchronize configurations across multiple NGINX instances as a single entity. This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While config sync groups focus on configuration management, cluster syncing supports failover and data consistency. - -## Create a config sync group - -Creating a config sync group allows you to manage the configurations of multiple NGINX instances as a single entity. - -1. On the left menu, select **Config Sync Groups**. -2. Select **Add Config Sync Group**. -3. In the **Name** field, type a name for your config sync group. -4. Select **Create** to add the config sync group. - -## Manage config sync group membership - -### Add an existing instance to a config sync group {#add-an-existing-instance-to-a-config-sync-group} - -You can add existing NGINX instances that are already registered with NGINX One to a config sync group. - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. At the end of the file, add a new line beginning with `instance_group:`, followed by the config sync group name. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent: - - ``` shell - sudo systemctl restart nginx-agent - ``` - -### Add a new instance to a config sync group {#add-a-new-instance-to-a-config-sync-group} - -When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. - -1. On the left menu, select **Config Sync Groups**. -2. Select the config sync group in the list. -3. In the **Instances** pane, select **Add Instance to Config Sync Group**. -4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to config sync group**. -5. Select **Next**. -6. **Generate a new data plane key** (choose this option if you don't have an existing key): - - - Select **Generate new key** to create a new data plane key for the instance. - - Select **Generate Data Plane Key**. - - Copy and securely store the generated key, as it is displayed only once. - -7. **Use an existing data plane key** (choose this option if you already have a key): - - - Select **Use existing key**. - - In the **Data Plane Key** field, enter the existing data plane key. - -{{}} - -{{%tab name="Virtual Machine or Bare Metal"%}} - -8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. -9. Select **Done** to complete the process. - -{{%/tab%}} - -{{%tab name="Docker Container"%}} - -8. **Log in to the NGINX private registry**: - - - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) from [MyF5](https://my.f5.com/manage/s/). - - ```shell - sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none - ``` - -9. **Pull the Docker image**: - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - -10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. - -11. Select **Done** to complete the process. - -{{%/tab%}} - -{{}} - -{{}} - -Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. - -For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). - -{{}} - -### Change the config sync group for an instance - -If you need to move an NGINX instance to a different config sync group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and change it to the name of the new config sync group. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent by running the following command: - - ```shell - sudo systemctl restart nginx-agent - ``` - -**Important:** If the instance is the first to join the new config sync group and a group configuration hasn’t been added manually beforehand, the instance’s configuration will automatically become the group’s configuration. Any instances added to this group later will inherit this configuration. - -### Remove an instance from a config sync group - -If you need to remove an NGINX instance from a config sync group without adding it to another group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. - - ```text - # instance_group: - ``` - -4. Restart NGINX Agent: - - ```shell - sudo systemctl restart nginx-agent - ``` - -By removing or commenting out this line, the instance will no longer be associated with any config sync group. - -## Add the config sync group configuration - -You can set the configuration for a config sync group in two ways: - -### Define the group configuration manually - -You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. - -To manually set the group configuration: - -1. Follow steps 1–4 in the [**Create a config sync group**](#create-a-config-sync-group) section to create your config sync group. -2. After creating the group, select the **Configuration** tab. -3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. -4. To add a configuration, select **Edit Configuration**. -5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. -6. After making your changes, select **Next** to view a split screen showing your changes. -7. If you're satisfied with the configuration, select **Save and Publish**. - -### Use an instance's configuration - -If you don't manually define a group config, the NGINX configuration of the first instance added to a config sync group becomes the group's configuration. Any additional instances added afterward inherit this group configuration. - -To set the group configuration by adding an instance: - -1. Follow the steps in the [**Add an existing instance to a config sync group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a config sync group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. -2. The NGINX configuration from this instance will automatically become the group's configuration. -3. You can further edit and publish this configuration by following the steps in the [**Publish the config sync group configuration**](#publish-the-config-sync-group-configuration) section. - -## Publish the config sync group configuration {#publish-the-config-sync-group-configuration} - -After the config sync group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. - -1. On the left menu, select **Config Sync Groups**. -2. Select the config sync group in the list. -3. Select the **Configuration** tab to view the group's NGINX configuration. -4. To modify the group's configuration, select **Edit Configuration**. -5. Make the necessary changes to the configuration. -6. When you're finished, select **Next**. A split view displays the changes. -7. If you're satisfied with the changes, select **Save and Publish**. - -Publishing the group configuration ensures that all instances within the config sync group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. - -## Understanding config sync statuses - -The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. - -{{}} -| **Status** | **Description** | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| **In Sync** | All instances within the config sync group have configurations that match the group configuration. No action is required. | -| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | -| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | -| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | -{{}} - -Monitoring the **Config Sync Status** helps ensure that your configurations are consistently applied across all instances in a group, reducing the risk of configuration drift. - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md deleted file mode 100644 index 37d4fb6f5..000000000 --- a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: View and edit NGINX configurations -# Weights are assigned in increments of 100: determines sorting order -weight: 300 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: tutorial -# Intended for internal catalogue and search, case sensitive: -product: NGINX One ---- - - -## Overview - -This guide explains how to add a **Instances** to your NGINX One Console. - -## Before you start - -Before you add **Instances** to NGINX One Console, ensure: - -- You have an NGINX One Console account with staged configuration permissions.``` - -Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. - -To view and edit an NGINX configuration, follow these steps: - -1. On the left menu, select **Instances**. -2. Select the instance you want to view the configuration for. -3. Select the **Configuration** tab to see the current configuration for the NGINX instance. -4. Select **Edit Configuration** to make changes to the current configuration. -5. Make your changes to the configuration files. The config analyzer will let you know if there are any errors. -6. When you are satisfied with the changes, select **Next**. -7. Compare and verify your changes before selecting **Save and Publish** to publish the edited configuration. - -Alternatively, you can select **Save Changes As**. In the window that appears, you can set up this instance as a [**Staged Configuration**]({{< ref "/nginx-one/how-to/staged-configs/_index.md" >}}). - -## See also - -- [Manage Config Sync Groups]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}) diff --git a/content/nginx-one/how-to/proxy-setup/_index.md b/content/nginx-one/how-to/proxy-setup/_index.md deleted file mode 100644 index 16f858cc2..000000000 --- a/content/nginx-one/how-to/proxy-setup/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Proxy setup -weight: 600 -url: /nginx-one/how-to/settings/nginx-as-proxy ---- diff --git a/content/nginx-one/how-to/proxy-setup/set-up-nginx-proxy-for-nginx-one.md b/content/nginx-one/how-to/proxy-setup/set-up-nginx-proxy-for-nginx-one.md deleted file mode 100644 index 974f7851c..000000000 --- a/content/nginx-one/how-to/proxy-setup/set-up-nginx-proxy-for-nginx-one.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: '' -docs: null -title: Set up NGINX as a proxy for NGINX One -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -This guide explains how to set up NGINX as a proxy for other NGINX instances to connect to the F5 NGINX One Console. By routing these connections through one proxy, you can minimize the number of external connections to NGINX One from your network. - ---- - -## Before you start - -- [Install NGINX Open Source or NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/" >}}). -- [Get a Data Plane Key from NGINX One]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}). - ---- - -## Configure an NGINX instance to act as a proxy - -In this step, we'll configure an NGINX instance to act as a proxy server for NGINX One. - -1. Open a secure connection to your instance using SSH and log in. -2. Open the NGINX configuration file (**/etc/nginx/nginx.conf**) with a text editor. -3. Add the following configuration to define the upstream server, set up logging, and configure the proxy server: - - ```nginx - stream { - upstream stream_backend { - zone tcp_servers 64k; - server agent.connect.nginx.com:443; - } - - log_format basic '$remote_addr [$time_local] ' - '$protocol $status $bytes_sent $bytes_received ' - '$session_time "$upstream_addr" ' - '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"'; - - access_log /var/log/nginx/nginx1_access.log basic; - error_log /var/log/nginx/nginx1_error.log; - - server { - listen 5000; - status_zone tcp_server; - proxy_pass stream_backend; - proxy_next_upstream on; - } - } - ``` - -4. Reload NGINX to apply the changes: - - ```sh - sudo nginx -s reload - ``` - ---- - -## Configure NGINX Agent to use the proxy instance - -To set up your other NGINX instances to use the proxy instance to connect to NGINX One, update the NGINX Agent configuration on those instances to use the proxy NGINX instance's IP address. See the example NGINX Agent configuration below. - -1. Open a secure connection to your instance using SSH and log in. -2. Open the NGINX Agent configuration file (**/etc/nginx-agent/nginx-agent.conf**) with a text editor. -3. Add the following configuration. Replace `YOUR_DATA_PLANE_KEY_HERE` with your actual data plane key and `YOUR_PROXY_IP_ADDRESS_HERE` with the IP address of the NGINX proxy instance. - - ```yaml - server: - # Replace YOUR_DATA_PLANE_KEY_HERE with your NGINX One Data Plane Key. - token: "YOUR_DATA_PLANE_KEY_HERE" - # Replace YOUR_PROXY_IP_ADDRESS_HERE with the IP address of the NGINX proxy instance. - host: YOUR_PROXY_IP_ADDRESS_HERE - grpcPort: 5000 - command: agent.connect.nginx.com - metrics: agent.connect.nginx.com - tls: - enable: true - skip_verify: false - ``` - -4. Restart NGINX Agent: - - ``` sh - sudo systemctl restart nginx-agent - ``` - ---- - -## References - -For more information, refer to the following resources: - -- [Installing NGINX and NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/" >}}) -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [NGINX Agent Installation and upgrade](https://docs.nginx.com/nginx-agent/installation-upgrade/) -- [NGINX Agent Configuration](https://docs.nginx.com/nginx-agent/configuration/) \ No newline at end of file diff --git a/content/nginx-one/how-to/settings/_index.md b/content/nginx-one/how-to/settings/_index.md deleted file mode 100644 index cdbbc1636..000000000 --- a/content/nginx-one/how-to/settings/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: -title: Settings -weight: 500 -url: /nginx-one/how-to/settings -draft: true ---- diff --git a/content/nginx-one/how-to/staged-configs/_index.md b/content/nginx-one/how-to/staged-configs/_index.md deleted file mode 100644 index 51e07d1aa..000000000 --- a/content/nginx-one/how-to/staged-configs/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Staged Configurations -weight: 800 -url: /nginx-one/how-to/staged-configs ---- diff --git a/content/nginx-one/how-to/staged-configs/add-staged-config.md b/content/nginx-one/how-to/staged-configs/add-staged-config.md deleted file mode 100644 index e69c0da78..000000000 --- a/content/nginx-one/how-to/staged-configs/add-staged-config.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: Add a Staged Configuration -# Weights are assigned in increments of 100: determines sorting order -weight: 100 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -nd-content-type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NGINX One ---- - -## Overview - -This guide explains how to add a Staged Configuration to your NGINX One Console. - -{{< include "nginx-one/staged-config-overview.md" >}} - -## Before you start - -Before you add a Staged Configuration to NGINX One Console, ensure: - -- You have an NGINX One Console account with staged configuration permissions. - -## Add a Staged Configuration - -You can add a Staged Configuration from: - -- Empty files -- An existing Instance -- An existing Config Sync Group -- An existing Staged Configuration - -To start the process from NGINX One Console, select **Manage > Staged Configurations**. Select **Add Staged Configuration**. - -The following sections start from the **Add Staged Configuration** window that appears. - -### Start from an empty file - -To start a new Staged Configuration: - -1. Select **New Configuration**. -1. Enter a name. -1. Select **Next**. - - You will see a new Staged Configuration with the default NGINX configuration file, `/etc/nginx/nginx.conf`, in edit mode. -1. Type or paste content for `/etc/nginx/nginx.conf`. -1. Select **Add File** to add the configuration, certificate, or other file(s) of your choice. -1. When you're done, select **Save**. - -### Start from an existing Instance - -To start from an existing Instance: - -1. Select **Existing Source**. -1. Enter a name for your new Staged Configuration. -1. Select **Instance**. -1. In the Choose Instance menu that appears, select an existing Instance. -1. Select **Next**. - -NGINX One Console imports the configuration from the existing Instance. You can now edit the configuration. When you're ready to stop and save your work, select Save. - -### Start from an existing Config Sync Group - -To start from an existing Config Sync Group: - -1. Select **Existing Source**. -1. Select **Config Sync Group**. -1. In the Choose Config Sync Group menu that appears, select an existing Config Sync Group. -1. Enter a name for your new Staged Configuration. -1. Select **Next**. - -NGINX One Console imports the configuration from the existing Config Sync Group. You can now edit the configuration. When you're ready to stop and save your work, select Save. - -### Start from an existing Staged Config - -To start from an existing Staged Config: - -1. Select **Existing Source**. -1. Select **Staged Configuration**. -1. In the Choose Staged Configuration menu that appears, select an existing Staged Configuration. -1. Enter a name for your new Staged Configuration. -1. Select **Next**. - -NGINX One Console imports the configuration from the existing Staged Configuration. You can now edit the configuration. When you're ready to stop and save your work, select Save. - diff --git a/content/nginx-one/how-to/staged-configs/api-staged-config.md b/content/nginx-one/how-to/staged-configs/api-staged-config.md deleted file mode 100644 index ff559d014..000000000 --- a/content/nginx-one/how-to/staged-configs/api-staged-config.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: Use the API to manage your Staged Configurations -# Weights are assigned in increments of 100: determines sorting order -weight: 500 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: how-to -# Intended for internal catalogue and search, case sensitive: -product: NGINX One ---- - -You can use F5 NGINX One Console API to manage your Staged Configurations. With our API, you can: - -- [Create an NGINX Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/createStagedConfig" >}}) - - Use details to add existing configuration files. -- [Get a list of existing Staged Configurations]({{< ref "/nginx-one/api/api-reference-guide/#operation/listStagedConfigs" >}}) - - Record the `object_id` of your target Staged Configuration for your analysis report. -- [Get an analysis report for an existing Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/getStagedConfigReport" >}}) - - Review the same recommendations found in the UI. -- [Export a Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/exportStagedConfig" >}}) - - Exports an existing Staged Configuration from the console. It sends you an archive of that configuration in `tar.gz` format. -- [Import a Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/importStagedConfig" >}}) - - Imports an existing Staged Configuration from your system and sends it to the console. This REST call assumes that your configuration is archived in `tar.gz` format. -- [Bulk manage multiple Staged Configurations]({{< ref "/nginx-one/api/api-reference-guide/#operation/bulkStagedConfigs" >}}) - - Allows you to delete multiple Staged Configurations. Requires each `object_id`. - - For several API endpoints, we ask for a `conf_path`. Make sure to set an absolute file path. If you make a REST call without an absolute file path, you'll see a 400 error message. diff --git a/content/nginx-one/how-to/staged-configs/edit-staged-config.md b/content/nginx-one/how-to/staged-configs/edit-staged-config.md deleted file mode 100644 index 8f101a0fd..000000000 --- a/content/nginx-one/how-to/staged-configs/edit-staged-config.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: View and edit a Staged Configuration -# Weights are assigned in increments of 100: determines sorting order -weight: 200 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: tutorial -# Intended for internal catalogue and search, case sensitive: -product: NGINX One ---- - -## Overview - -This guide explains how to edit an existing Staged Configuration in your NGINX One Console. - -{{< include "nginx-one/staged-config-overview.md" >}} - -## Before you start - -Before you edit a Staged Configuration, ensure: - -- You have an NGINX One Console account with staged configuration permissions.``` - -## View and edit a Staged Configuration - - -Once you've registered your NGINX Staged Configs with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Staged Configurations** details page. - -To view and edit an NGINX configuration, follow these steps: - -1. On the left menu, select **Staged Configurations**. -1. Select the staged configuration you want to view or modify. -1. Select **Edit** to make changes to the current configuration. -1. Make your changes to the configuration files. The configuration analyzer will let you know if there are any errors. -1. When you are satisfied with the changes, select **Next**. -1. Compare and verify your changes before selecting **Save** to publish the edited Staged configuration. diff --git a/content/nginx-one/how-to/staged-configs/import-export-staged-config.md b/content/nginx-one/how-to/staged-configs/import-export-staged-config.md deleted file mode 100644 index 192fad4c4..000000000 --- a/content/nginx-one/how-to/staged-configs/import-export-staged-config.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: Import and export a Staged Configuration -# Weights are assigned in increments of 100: determines sorting order -weight: 300 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -product: NGINX One ---- - -## Overview - -Many administrators do their work on local systems, virtual machines, Docker containers, and more. F5 NGINX One Console -supports import and export of such configurations. -This guide explains how to import or export a Staged Configuration to your NGINX One Console. - -{{< include "nginx-one/staged-config-overview.md" >}} - -## Before you start - -Before you import or export a Staged Configuration to NGINX One Console, ensure: - -- You have an NGINX One Console account with staged configuration permissions. - -You can also import, export, and manage multiple Staged Configurations through [the API]({{< ref "/nginx-one/how-to/staged-configs/api-staged-config.md" >}}). - -## Considerations - -NGINX One Console supports imports and exports as a compressed archive known as a [tarball](https://en.wikipedia.org/wiki/Tar_(computing)), in `tar.gz` format. -When you work with such archives, consider the following: - -- Do _not_ unpack archives directly to your NGINX configuration directories. You do not want to accidentally overwrite existing configuration files. -- The files are set to a default file permission mode of 0644. -- Do not include files with secrets or personally identifying information. -- We ignore hidden files. - - If you import or export such files in archives, NGINX One Console does not include those files. -- The size of the archive is limited to 5 MB. The size of all uncompressed files in the archive is limited to 10 MB. - -{{< tip >}} - -Before you unpack an archive, run the `tar -tvzf .tar.gz` command. It displays the files and directories in that archive, without overwriting anything. -You'll then know where files are written when you extract an archive with a command like `tar -xvzf .tar.gz`. - -{{< /tip >}} - -## Import a Staged Configuration - -To import a Staged Configuration from your system to the NGINX One Console, you need to: - -- Package your configuration in `tar.gz` format. For example, the following command creates an archive file named for-import.tar.gz` from files in the `/etc/nginx` directory: - ```bash - tar czvf /etc/nginx for-import.tar.gz - ``` - -You would then import that file to the NGINX One Console. To do so, follow these steps: - -1. On the left menu, select **Staged Configurations**. -1. Select **Add Staged Configuration**. -1. Select **Import Configuration**. -1. Add a name for the Staged Configuration to be imported. -1. Select **Import from File**. -1. Choose the file. The process depends on your operating system. -1. If successful, you'll see a success message. - - A typical error suggests that the file is too large. - -## Export a Staged Configuration - -You can export a Staged Configuration from the NGINX One Console, as a download, to your system. To do so, follow these steps: - -1. On the left menu, select **Staged Configurations**. -1. Select the Staged Configuration you want to export. -1. Select the ellipsis (...) on the right side of the row with the Staged Configuration. -1. Select **Export** -1. In the file menu that appears, choose a filename for your archive and save the result -1. Be careful. Do not unpack the archive in a way that overwrites your current NGINX configuration. - -## Manage multiple Staged Configurations - -You can also delete multiple Staged Configurations through the UI: - -1. On the left menu, select **Staged Configurations**. -1. Select the Staged Configuration you want to delete. -1. You can then select the **Delete selected** button. - -You can do more from the API. Specifically, with the `object_id` of each configuration, you can create, modify, or delete multiple staged configurations with the [Bulk Staged Configurations endpoint]({{< ref "/nginx-one/api/api-reference-guide/#operation/bulkStagedConfigs" >}}). diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md index d36819e7b..feffd5d05 100644 --- a/content/nginx-one/nginx-configs/_index.md +++ b/content/nginx-one/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Organize your NGINX instances +title: Watch your NGINX instances weight: 300 url: /nginx-one/nginx-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index e5ecaf984..32f41efa0 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -40,7 +40,7 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}}

    Manage your work-in-progress

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your NGINX instances")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}}

    Keep an inventory of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} @@ -49,7 +49,7 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}}

    Secure your systems with role-based access control

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize in groups")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}}

    Configure and synchronize groups of NGINX instances simultaneously

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} From b9bda1de5a652aa1b845c1ef8b4db1ab33465b63 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 11:11:59 -0700 Subject: [PATCH 04/25] update --- .../agent/installation/install-agent-api.md | 83 +- .../includes/nap-waf/build-nginx-image-cmd.md | 2 +- .../learn-about-deployment.md | 6 +- content/nap-waf/v4/admin-guide/install.md | 4 +- content/nap-waf/v5/admin-guide/compiler.md | 2 +- content/ngf/overview/custom-policies.md | 9 +- content/ngf/overview/product-telemetry.md | 3 +- .../load-balancer/tcp-udp-load-balancer.md | 40 +- .../load-balancer/udp-health-check.md | 160 +++- .../manage-waf-security-policies.md | 763 ++++++------------ .../overview-nap-waf-config-management.md | 72 +- 11 files changed, 519 insertions(+), 625 deletions(-) diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 95a9650aa..15009d21f 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -1,74 +1,75 @@ -**Note**: To complete this step, make sure that `gpg` is installed on your system. You can install NGINX Agent using various command-line tools like `curl` or `wget`. If your NGINX Instance Manager host is not set up with valid TLS certificates, you can use the insecure flags provided by those tools. See the following examples: +--- +docs: DOCS-1031 +files: + - content/nim/nginx-app-protect/setup-waf-config-management.md +--- + +{{}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{}} + +If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands: {{}} {{%tab name="curl"%}} -- Secure: +- **Secure:** ```bash - curl https:///install/nginx-agent | sudo sh + curl https:///install/nginx-agent | sudo sh ``` -- Insecure: +- **Insecure:** ```bash - curl --insecure https:///install/nginx-agent | sudo sh + curl --insecure https:///install/nginx-agent | sudo sh ``` - You can add your NGINX instance to an existing instance group or create one using `--instance-group` or `-g` flag when installing NGINX Agent. - - The following example shows how to download and run the script with the optional `--instance-group` flag adding the NGINX instance to the instance group **my-instance-group**: - - ```bash - curl https:///install/nginx-agent > install.sh; chmod u+x install.sh - sudo ./install.sh --instance-group my-instance-group - ``` +To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag: - By default, the install script attempts to use a secure connection when downloading packages. If, however, the script cannot create a secure connection, it uses an insecure connection instead and logs the following warning message: +```shell +curl https:///install/nginx-agent -o install.sh +chmod u+x install.sh +sudo ./install.sh --instance-group +``` - ``` text - Warning: An insecure connection will be used during this nginx-agent installation - ``` +By default, the install script uses a secure connection to download packages. If it can’t establish one, it falls back to an insecure connection and logs this message: - To require a secure connection, you can set the optional flag `skip-verify` to `false`. +```text +Warning: An insecure connection will be used during this nginx-agent installation +``` - The following example shows how to download and run the script with an enforced secure connection: +To enforce a secure connection, set the `--skip-verify` flag to false: - ```bash - curl https:///install/nginx-agent > install.sh chmod u+x install.sh; chmod u+x install.sh - sudo sh ./install.sh --skip-verify false - ``` +```shell +curl https:///install/nginx-agent -o install.sh +chmod u+x install.sh +sudo ./install.sh --skip-verify false +``` {{%/tab%}} {{%tab name="wget"%}} +- **Secure:** -- Secure: - - ```bash - wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false + ```shell + wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false ``` -- Insecure: +- **Insecure:** - ```bash - wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh + ```shell + wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh ``` - When you install the NGINX Agent, you can use the `--instance-group` or `-g` flag to add your NGINX instance to an existing instance group or to a new group that you specify. - - The following example downloads and runs the NGINX Agent install script with the optional `--instance-group` flag, adding the NGINX instance to the instance group **my-instance-group**: - - ```bash - wget https://gnms1.npi.f5net.com/install/nginx-agent -O install.sh ; chmod u+x install.sh - sudo ./install.sh --instance-group my-instance-group - ``` +To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag: +```shell +wget https:///install/nginx-agent -O install.sh +chmod u+x install.sh +sudo ./install.sh --instance-group +``` {{%/tab%}} -{{}} - - +{{}} diff --git a/content/includes/nap-waf/build-nginx-image-cmd.md b/content/includes/nap-waf/build-nginx-image-cmd.md index 41bf90d03..fcb89d363 100644 --- a/content/includes/nap-waf/build-nginx-image-cmd.md +++ b/content/includes/nap-waf/build-nginx-image-cmd.md @@ -10,7 +10,7 @@ To build the image, execute the following command in the directory containing th ```shell -sudo docker build --no-cache \ +sudo docker build --no-cache --platform linux/amd64 \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t nginx-app-protect-5 . diff --git a/content/nap-dos/deployment-guide/learn-about-deployment.md b/content/nap-dos/deployment-guide/learn-about-deployment.md index df137bd2e..430fd9e2e 100644 --- a/content/nap-dos/deployment-guide/learn-about-deployment.md +++ b/content/nap-dos/deployment-guide/learn-about-deployment.md @@ -1405,7 +1405,7 @@ You need root permissions to execute the following steps. 6. Create a Docker image: ```shell - docker build --no-cache -t app-protect-dos . + docker build --no-cache --platform linux/amd64 -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. @@ -1966,13 +1966,13 @@ Make sure to replace upstream and proxy pass directives in this example with rel For CentOS: ```shell - docker build --no-cache -t app-protect-dos . + docker build --no-cache --platform linux/amd64 -t app-protect-dos . ``` For RHEL: ```shell - docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . + docker build --platform linux/amd64 --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. diff --git a/content/nap-waf/v4/admin-guide/install.md b/content/nap-waf/v4/admin-guide/install.md index 3158ac9d3..c3e0575dc 100644 --- a/content/nap-waf/v4/admin-guide/install.md +++ b/content/nap-waf/v4/admin-guide/install.md @@ -939,7 +939,7 @@ If a user other than **nginx** is to be used, note the following: - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . + DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). @@ -1289,7 +1289,7 @@ You need root permissions to execute the following steps. - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . + DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). diff --git a/content/nap-waf/v5/admin-guide/compiler.md b/content/nap-waf/v5/admin-guide/compiler.md index dd0e828e4..ea0f28500 100644 --- a/content/nap-waf/v5/admin-guide/compiler.md +++ b/content/nap-waf/v5/admin-guide/compiler.md @@ -98,7 +98,7 @@ curl -s https://private-registry.nginx.com/v2/nap/waf-compiler/tags/list --key < Run the command below to build your image, where `waf-compiler-:custom` is an example of the image tag: ```shell - sudo docker build --no-cache \ + sudo docker build --no-cache --platform linux/amd64 \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t waf-compiler-:custom . diff --git a/content/ngf/overview/custom-policies.md b/content/ngf/overview/custom-policies.md index c7e5a785d..5aeb99fce 100644 --- a/content/ngf/overview/custom-policies.md +++ b/content/ngf/overview/custom-policies.md @@ -17,10 +17,11 @@ The following table summarizes NGINX Gateway Fabric custom policies: {{< bootstrap-table "table table-striped table-bordered" >}} -| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | -|---------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| -| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | -| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha1 | +| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | +|---------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| +| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | +| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | +| [UpstreamSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/upstream-settings.md" >}}) | Configure connection behavior between NGINX and backend | Direct | Service | Yes | Yes | v1alpha1 | {{< /bootstrap-table >}} diff --git a/content/ngf/overview/product-telemetry.md b/content/ngf/overview/product-telemetry.md index cd9f7a20f..3c73a4cb5 100644 --- a/content/ngf/overview/product-telemetry.md +++ b/content/ngf/overview/product-telemetry.md @@ -32,7 +32,8 @@ Telemetry data is collected once every 24 hours and sent to a service managed by - **Image Build Source:** whether the image was built by GitHub or locally (values are `gha`, `local`, or `unknown`). The source repository of the images is **not** collected. - **Deployment Flags:** a list of NGINX Gateway Fabric Deployment flags that are specified by a user. The actual values of non-boolean flags are **not** collected; we only record that they are either `true` or `false` for boolean flags and `default` or `user-defined` for the rest. - **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected. -- **SnippetsFilters Info**a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. +- **SnippetsFilters Info:** a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. + This data is used to identify the following information: - The flavors of Kubernetes environments that are most popular among our users. diff --git a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md index a7a6a7f61..bf40c20be 100644 --- a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md +++ b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md @@ -9,10 +9,9 @@ type: - how-to --- - -## Introduction +## Introduction {#intro} -[Load balancing](https://www.nginx.com/solutions/load-balancing/) refers to efficiently distributing network traffic across multiple backend servers. +[Load balancing](https://www.f5.com/glossary/load-balancer) refers to efficiently distributing network traffic across multiple backend servers. In F5 NGINX Plus [R5]({{< ref "nginx/releases.md#r5" >}}) and later, NGINX Plus can proxy and load balance Transmission Control Protocol) (TCP) traffic. TCP is the protocol for many popular applications and services, such as LDAP, MySQL, and RTMP. @@ -20,15 +19,13 @@ In NGINX Plus [R9]({{< ref "nginx/releases.md#r9" >}}) and later, NGINX Plus can To load balance HTTP traffic, refer to the [HTTP Load Balancing]({{< ref "http-load-balancer.md" >}}) article. - ## Prerequisites - Latest NGINX Plus (no extra build steps required) or latest [NGINX Open Source](https://nginx.org/en/download.html) built with the `--with-stream` configuration flag - An application, database, or service that communicates over TCP or UDP - Upstream servers, each running the same instance of the application, database, or service - -## Configuring Reverse Proxy +## Configuring reverse proxy {#proxy_pass} First, you will need to configure _reverse proxy_ so that NGINX Plus or NGINX Open Source can forward TCP connections or UDP datagrams from clients to an upstream group or a proxied server. @@ -118,8 +115,7 @@ Open the NGINX configuration file and perform the following steps: } ``` - -## Configuring TCP or UDP Load Balancing +## Configuring TCP or UDP load balancing {#upstream} To configure load balancing: @@ -250,8 +246,7 @@ stream { } ``` - -## Configuring Health Checks +## Configuring health checks {#health} NGINX can continually test your TCP or UDP upstream servers, avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. @@ -259,8 +254,7 @@ See [TCP Health Checks]({{< ref "nginx/admin-guide/load-balancer/tcp-health-chec See [UDP Health Checks]({{< ref "nginx/admin-guide/load-balancer/udp-health-check.md" >}}) for instructions how to configure health checks for UDP. - -## On-the-Fly Configuration +## On-the-fly configuration Upstream server groups can be easily reconfigured on-the-fly using NGINX Plus REST API. Using this interface, you can view all servers in an upstream group or a particular server, modify server parameters, and add or remove upstream servers. @@ -355,8 +349,7 @@ To enable on-the-fly configuration: } ``` - -### On-the-Fly Configuration Example +### On-the-fly configuration example ```nginx stream { @@ -403,23 +396,22 @@ For example, to add a new server to the server group, send a `POST` request: curl -X POST -d '{ \ "server": "appserv3.example.com:12345", \ "weight": 4 \ - }' -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers' + }' -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers' ``` To remove a server from the server group, send a `DELETE` request: ```shell -curl -X DELETE -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers/0' +curl -X DELETE -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers/0' ``` To modify a parameter for a specific server, send a `PATCH` request: ```shell -curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/6/http/upstreams/appservers/servers/0' +curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/9/http/upstreams/appservers/servers/0' ``` - -## Example of TCP and UDP Load-Balancing Configuration +## Example of TCP and UDP load-balancing configuration {#example} This is a configuration example of TCP and UDP load balancing with NGINX: @@ -471,3 +463,13 @@ The three [`server`](https://nginx.org/en/docs/stream/ngx_stream_upstream_module - The second server listens on port 53 and proxies all UDP datagrams (the `udp` parameter to the `listen` directive) to an upstream group called **dns_servers**. If the `udp` parameter is not specified, the socket listens for TCP connections. - The third virtual server listens on port 12346 and proxies TCP connections to **backend4.example.com**, which can resolve to several IP addresses that are load balanced with the Round Robin method. + +## See also + +- [TCP Health Checks]({{< relref "tcp-health-check.md" >}}) + +- [UDP Health Checks]({{< relref "udp-health-check.md" >}}) + +- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) + +- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks) diff --git a/content/nginx/admin-guide/load-balancer/udp-health-check.md b/content/nginx/admin-guide/load-balancer/udp-health-check.md index bb4818fd4..7885d032a 100644 --- a/content/nginx/admin-guide/load-balancer/udp-health-check.md +++ b/content/nginx/admin-guide/load-balancer/udp-health-check.md @@ -9,10 +9,11 @@ type: - how-to --- - -## Prerequisites +NGINX Plus can continually test your upstream servers that handle UDP network traffic (DNS, RADIUS, syslog), avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. -- You have configured an upstream group of servers that handles UDP network traffic (DNS, RADIUS, syslog) in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: +## Prerequisites {#prereq} + +- You have [configured an upstream group of servers]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) that handles UDP network traffic in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: ```nginx stream { @@ -44,8 +45,7 @@ type: See [TCP and UDP Load Balancing]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) for details. - -## Passive UDP Health Checks +## Passive UDP health checks {#hc_passive} NGINX Open Source or F5 NGINX Plus can mark the server as unavailable and stop sending UDP datagrams to it for some time if the server replies with an error or times out. @@ -62,8 +62,7 @@ upstream dns_upstream { } ``` - -## Active UDP Health Checks +## Active UDP health checks {#hc_active} Active Health Checks allow testing a wider range of failure types and are available only for NGINX Plus. For example, instead of waiting for an actual TCP request from a DNS client to fail before marking the DNS server as down (as in passive health checks), NGINX Plus will send special health check requests to each upstream server and check for a response that satisfies certain conditions. If a connection to the server cannot be established, the health check fails, and the server is considered unhealthy. NGINX Plus does not proxy client connections to unhealthy servers. If more than one health check is defined, the failure of any check is enough to consider the corresponding upstream server unhealthy. @@ -100,8 +99,7 @@ To enable active health checks: A basic UDP health check assumes that NGINX Plus sends the “nginx health check” string to an upstream server and expects the absence of ICMP “Destination Unreachable” message in response. You can configure your own health check tests in the `match {}` block. See [The “match {}” Configuration Block](#hc_active_match) for details. - -### Fine-Tuning UDP Health Checks +### Fine-Tuning UDP Health Checks {#hc_active_finetune} You can fine‑tune the health check by specifying the following parameters to the [`health_check`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check) directive: @@ -119,10 +117,9 @@ server { In the example, the time between UDP health checks is increased to 20 seconds, the server is considered unhealthy after 2 consecutive failed health checks, and the server needs to pass 2 consecutive checks to be considered healthy again. - -### The “match {}” Configuration Block +### The “match {}” configuration block {#hc_active_match} -You can verify server responses to health checks by configuring a number of tests. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. +A basic UDP health check assumes that NGINX Plus sends the “nginx health check” string to an upstream server and expects the absence of ICMP “Destination Unreachable” message in response. You can configure your own health check tests that will verify server responses. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. 1. In the top‑level `stream {}` context, specify the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) block and set its name, for example, `udp_test`: @@ -155,8 +152,9 @@ You can verify server responses to health checks by configuring a number of test These parameters can be used in different combinations, but no more than one `send` and one `expect` parameter can be specified at a time. - -#### Example Test for NTP +## Usage scenarios + +### NTP health checks {#example_ntp} To fine‑tune health checks for NTP, you should specify both `send` and `expect` parameters with the following text strings: @@ -167,14 +165,138 @@ match ntp { } ``` - -#### Example Test for DNS +#### Complete NTP health check configuration example + +```nginx + +stream { + upstream ntp_upstream { + zone ntp_zone 64k; + server 192.168.136.130:53; + server 192.168.136.131:53; + server 192.168.136.132:53; +} + server { + listen 53 udp; + proxy_pass ntp_upstream; + health_check match=ntp udp; + proxy_timeout 1s; + proxy_responses 1; + error_log logs/ntp.log; + } + + match ntp { + send \xe3\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00; + expect ~* \x24; + } +} +``` + +### DNS health checks {#example_dns} + +[DNS health checks](#hc_active) can be enhanced to perform real DNS lookup queries. You can craft a valid DNS query packet, send it to the upstream server, and inspect the response to determine health. + +The process includes three steps: +- [Creating a CNAME test record](#create-a-cname-record) on your DNS server. +- [Crafting a raw DNS query packet](#construct-a-raw-dns-query-packet) to be sent by NGINX Plus. +- [Validating the expected response](#configure-the-match-block-for-dns-lookup) using the `match` block, where the `send` parameter represents a raw DNS query packet, and `expect` represents the value of the CNAME record. + +#### Create a CNAME record + +First, create a CNAME record on your DNS server for a health check that points to the target website. + +For example, if you are using BIND self-hosted DNS solution on a Linux server: + +- Open the zone file in a text editor: + +```shell +sudo nano /etc/bind/zones/db.example.com +``` +- Add a CNAME record, making `healthcheck.example.com` resolve to `healthy.svcs.example.com`: + +```none +healthcheck IN CNAME healthy.svcs.example.com. +``` + +- Save the file and reload the DNS service: + +```shell +sudo systemctl reload bind9 +``` + +Once the CNAME record is live and resolvable, you can craft a DNS query packet that represents a DNS lookup and can be used in the `send` directive. + +#### Construct a raw DNS query packet + +The `send` parameter of the `match` block allows you to send raw UDP packets for health checks. To query your CNAME record, you need to construct a valid DNS query packet according to the [DNS protocol message format](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1), including a header and question section. -To fine‑tune health checks for DNS, you should also specify both `send` and `expect` parameters with the following text strings: +The DNS Query packet can be created using DNS packet builders, such as Python Scapy or dnslib, or packet analyzers, such as tcpdump or Wireshark. If using a packet analyzer, extract only the DNS layer, removing Ethernet, IP, and UDP-related headers. + +This is the raw DNS query of `healthcheck.example.com`, represented as one line in Hex with `\x` prefixes: + +```none +\x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01 +``` +where: + +{{}} +| HEX | Description | +|------------------|------------------------| +| \x00\x01 | Transaction ID: 0x0001 | +| \x01\x00 | Flags: Standard query, recursion desired | +| \x00\x01 | Questions: 1 | +| \x00\x00 | Answer RRs: 0 | +| \x00\x00 | Authority RRs: 0 | +| \x00\x00 | Additional RRs: 0 | +| \x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b | "healthcheck" | +| \x07\x65\x78\x61\x6d\x70\x6c\x65 | "example" | +| \x03\x63\x6f\x6d | "com" | +| \x00 | end of name | +| \x00\x01 | Type: A | +| \x00\x01 | Class: IN | +{{}} + +#### Configure the match block for DNS lookup + +Finally, specify the `match` block in the NGINX configuration file to pair the raw query with an expected response. The `send` directive should contain the DNS query packet, while `expect` directive should contain a matching DNS record in the DNS server's response: ```nginx match dns { - send \x00\x2a\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x03\x73\x74\x6c\x04\x75\x6d\x73\x6c\x03\x65\x64\x75\x00\x00\x01\x00\x01; - expect ~* "health.is.good"; + send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; + expect ~* "healthy.svcs.example.com"; +} +``` + +#### Complete DNS health check configuration example + +```nginx + +stream { + upstream dns_upstream { + zone dns_zone 64k; + server 192.168.136.130:53; + server 192.168.136.131:53; + server 192.168.136.132:53; +} + server { + listen 53 udp; + proxy_pass dns_upstream; + health_check match=dns udp; + proxy_timeout 1s; + proxy_responses 1; + error_log logs/dns.log; + } + + match dns { + # make sure appropriate CNAME record exists + send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; + expect ~* "healthy.svcs.example.com"; + } } ``` + +## See also + +- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) + +- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks#activeHealthCheck) 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 71684b133..5c0e5ebf3 100644 --- a/content/nim/nginx-app-protect/manage-waf-security-policies.md +++ b/content/nim/nginx-app-protect/manage-waf-security-policies.md @@ -1,8 +1,7 @@ --- -title: Manage WAF Security Policies and Security Log Profiles -description: Learn how to use F5 NGINX Management Suite Instance Manager to manage NGINX - App Protect WAF security policies and security log profiles. -weight: 200 +title: Manage and deploy WAF policies and log profiles +description: Learn how to use F5 NGINX Instance Manager to manage NGINX App Protect WAF security policies and security log profiles. +weight: 300 toc: true type: how-to product: NIM @@ -11,83 +10,76 @@ docs: DOCS-1105 ## Overview -F5 NGINX Management Suite Instance Manager provides the ability to manage the configuration of NGINX App Protect WAF instances either by the user interface or the REST API. This includes editing, updating, and deploying security policies, log profiles, attack signatures, and threat campaigns to individual instances and/or instance groups. +F5 NGINX Instance Manager lets you manage NGINX App Protect WAF configurations using either the web interface or REST API. You can edit, update, and deploy security policies, log profiles, attack signatures, and threat campaigns to individual instances or instance groups. -In Instance Manager v2.14.0 and later, you can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. A security policy bundle consists of the security policy, the attack signatures, and threat campaigns for a particular version of NGINX App Protect WAF, and additional supporting files that make it possible for NGINX App Protect WAF to use the bundle. Because the security policy bundle is pre-compiled, the configuration gets applied faster than when you individually reference the security policy, attack signature, and threat campaign files. +You can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. The bundle includes all necessary components for a specific NGINX App Protect WAF version. Precompiling the bundle improves performance by avoiding separate compilation of each component during deployment. {{}} -The following capabilities are only available via the Instance Manager REST API: +The following capabilities are available only through the Instance Manager REST API: - Update security policies - Create, read, and update security policy bundles -- Create, read, update, and delete Security Log Profiles -- Publish security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups +- Create, read, update, and delete security log profiles +- Publish security policies, log profiles, attack signatures, and threat campaigns to instances and instance groups {{}} --- -## Before You Begin +## Before you begin -Complete the following prerequisites before proceeding with this guide: +Before continuing, complete the following steps: -- [Set Up App Protect WAF Configuration Management]({{< ref "setup-waf-config-management" >}}) -- Verify that your user account has the [necessary permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the Instance Manager REST API: +- [Set up App Protect WAF configuration management]({{< ref "setup-waf-config-management" >}}) +- Make sure your user account has the [required permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the REST API: - - **Module**: Instance Manager - - **Feature**: Instance Management - - **Access**: `READ` - - **Feature**: Security Policies - - **Access**: `READ`, `CREATE`, `UPDATE`, `DELETE` + - **Module**: Instance Manager + - **Feature**: Instance Management → `READ` + - **Feature**: Security Policies → `READ`, `CREATE`, `UPDATE`, `DELETE` -The following are required to use support policy bundles: +To use policy bundles, you also need to: -- You must have `UPDATE` permissions for the security policies specified in the request. -- The correct `nms-nap-compiler` packages for the NGINX App Protect WAF version you're using are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}). -- The attack signatures and threat campaigns that you want to use are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}). +- Have `UPDATE` permissions for each referenced security policy +- [Install the correct `nms-nap-compiler` package]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}) for your App Protect WAF version +- [Install the required attack signatures and threat campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}) -### How to Access the Web Interface +### Access the web interface -To access the web interface, go to the FQDN for your NGINX Instance Manager host in a web browser and log in. Once you're logged in, select "Instance Manager" from the Launchpad menu. +To access the web interface, open a browser and go to the fully qualified domain name (FQDN) of your NGINX Instance Manager. Log in, then select **Instance Manager** from the Launchpad. -### How to Access the REST API +### Access the REST API {{< include "nim/how-to-access-nim-api.md" >}} --- -## Create a Security Policy {#create-security-policy} +## Create a security policy {#create-security-policy} {{}} {{%tab name="web interface"%}} -
    - -To create a security policy using the Instance Manager web interface: - -1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. -2. On the left menu, select **App Protect**. -3. On the *Security Policies* page, select **Create**. -4. On the *Create Policy* page, fill out the necessary fields: +To create a security policy using the NGINX Instance Manager web interface: - - **Name**: Provide a name for the policy. - - **Description**: (Optional) Add a short description for the policy. - - **Enter Policy**: Type or paste the policy in JSON format into the form provided. The editor will validate the JSON for accuracy. +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +2. From the Launchpad menu, select **Instance Manager**. +3. In the left menu, select **App Protect**. +4. On the *Security Policies* page, select **Create**. +5. On the *Create Policy* page, enter the required information: + - **Name**: Enter a name for the policy. + - **Description**: (Optional) Add a brief description. + - **Enter Policy**: Paste or type the JSON-formatted policy into the editor. The interface automatically validates the JSON. - For more information about creating custom policies, refer to the [NGINX App Protect WAF Declarative Policy](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) guide and the [Policy Authoring and Tuning](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) section of the config guide. + For help writing custom policies, see the [NGINX App Protect WAF Declarative Policy guide](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) and the [Policy Authoring and Tuning section](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) in the configuration guide. -5. Select **Save**. +6. Select **Save**. {{%/tab%}} {{%tab name="API"%}} -To upload a new security policy, send an HTTP `POST` request to the Security Policies API endpoint. - -{{}}Before sending a security policy to Instance Manager, you need to encode it using `base64`. Submitting a policy in its original JSON format will result in an error.{{}} - -
    +To upload a new security policy using the REST API, send a `POST` request to the Security Policies API endpoint. +You must encode the JSON policy using `base64`. If you send the policy in plain JSON, the request will fail. {{}} @@ -101,7 +93,7 @@ To upload a new security policy, send an HTTP `POST` request to the Security Pol For example: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ -H "Authorization: Bearer " \ -d @ignore-xss-example.json ``` @@ -134,7 +126,7 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ "modified": "2022-04-12T23:19:58.502Z", "name": "ignore-cross-site-scripting", "revisionTimestamp": "2022-04-12T23:19:58.502Z", - "uid": "21daa130-4ba4-442b-bc4e-ab294af123e5" + "uid": "" }, "selfLink": { "rel": "/api/platform/v1/services/environments/prod" @@ -148,11 +140,13 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ --- -## Update a Security Policy +## Update a security policy + -To update a security policy, send an HTTP `POST` request to the Security Policies API endpoint, `/api/platform/v1/security/policies`. +To update a security policy, send a `POST` or `PUT` request to the Security Policies API. -You can use the optional `isNewRevision` parameter to indicate whether the updated policy is a new version of an existing policy. +- 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. {{}} @@ -165,33 +159,35 @@ You can use the optional `isNewRevision` parameter to indicate whether the updat {{}} -For example: +To use `POST`, include the policy metadata and content in your request: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-xss-policy.json ``` -You can update a specific policy by sending an HTTP `PUT` request to the Security Policies API endpoint that includes the policy's unique identifier (UID). +To use PUT, first retrieve the policy’s unique identifier (UID). You can do this by sending a GET request to the policies endpoint: -To find the UID, send an HTTP `GET` request to the Security Policies API endpoint. This returns a list of all Security Policies that contains the unique identifier for each policy. - -Include the UID for the security policy in your `PUT` request to update the policy. Once the policy update is accepted, the WAF compiler will create a new, updated bundle. +```shell +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " +``` -For example: +Then include the UID in your PUT request: ```shell -curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ +curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ -H "Authorization: Bearer " \ - --Content-Type application/json -d @update-xss-policy.json + --Content-Type application/json \ + -d @update-xss-policy.json ``` -After you have pushed an updated security policy, you can [publish it](#publish-policy) to selected instances or instance groups. +After updating the policy, you can [publish it](#publish-policy) to selected instances or instance groups. --- -## Delete a Security Policy +## Delete a security policy {{}} @@ -199,17 +195,29 @@ After you have pushed an updated security policy, you can [publish it](#publish-
    -To delete a security policy using the Instance Manager 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. +2. From the Launchpad menu, select **Instance Manager**. +3. In the left menu, select **App Protect**. +4. On the *Security Policies* page, find the policy you want to delete. +5. Select the **Actions** menu (**...**) and choose **Delete**. -1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. -2. On the left menu, select **App Protect**. -3. On the *Security Policies* page, select the **Actions** menu (represented by an ellipsis, **...**) for the policy you want to delete. Select **Delete** to remove the policy. {{%/tab%}} {{%tab name="API"%}} -To delete a security policy, send an HTTP `DELETE` request to the Security Policies API endpoint that includes the unique identifier for the policy that you want to delete. +To delete a security policy using the REST API: + +1. Retrieve the UID for the policy by sending a `GET` request to the policies endpoint: + + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " + ``` + +2. Send a `DELETE` request using the policy UID: {{}} @@ -221,10 +229,10 @@ To delete a security policy, send an HTTP `DELETE` request to the Security Polic {{}} -For example: +Example: ```shell -curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ +curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ -H "Authorization: Bearer " ``` @@ -232,36 +240,42 @@ curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4 {{    }} -{{%comment%}}TO DO: Add sections for managing attack signatures and threat campaigns{{%/comment%}} - --- -## Create Security Policy Bundles {#create-security-policy-bundles} +## Create security policy bundles {#create-security-policy-bundles} -To create security policy bundles, send an HTTP `POST` request to the Security Policies Bundles API endpoint. The specified security policies you'd like to compile into security policy bundles must already exist in Instance Manager. -### Required Fields +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. -- `appProtectWAFVersion`: The version of NGINX App Protect WAF being used. -- `policyName`: The name of security policy to include in the bundle. This must reference an existing security policy; refer to the [Create a Security Policy](#create-security-policy) section above for instructions. +Each bundle includes: -### Notes +- A security policy +- Attack signatures +- Threat campaigns +- A version of NGINX App Protect WAF +- Supporting files required to compile and deploy the bundle + +### Required fields + +- `appProtectWAFVersion`: The version of NGINX App Protect WAF to target. +- `policyName`: The name of the policy to include. Must reference an existing policy. +- `policyUID`: Optional. If omitted, the latest revision of the specified policy is used. This field does **not** accept the keyword `latest`. + +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. -- If you do not specify a value for the `attackSignatureVersionDateTime` and/or `threatCampaignVersionDateTime` fields, the latest version of each will be used by default. You can also explicitly state that you want to use the most recent version by specifying the keyword `latest` as the value. -- If the `policyUID` field is not defined, the latest version of the specified security policy will be used. This field **does not allow** use of the keyword `latest`. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|----------------------------------------------| | POST | `/api/platform/v1/security/policies/bundles` | {{}} -For example: +Example: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " \ -d @security-policy-bundles.json ``` @@ -274,7 +288,7 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "bundles": [{ "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18" }, @@ -305,10 +319,10 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "dceb8254-9a90-4e77-87ac-73070f821412" + "uid": "" }, "content": "", "compilationStatus": { @@ -321,11 +335,11 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", - "policyName": "defautl-enforcement", - "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", + "policyName": "default-enforcement", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" + "uid": "" }, "content": "", "compilationStatus": { @@ -339,10 +353,10 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" + "uid": "" }, "content": "", "compilationStatus": { @@ -354,39 +368,38 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` - --- -## List Security Policy Bundles {#list-security-policy-bundles} +## List security policy bundles {#list-security-policy-bundles} -To list security policy bundles, send an HTTP `GET` request to the Security Policies Bundles API endpoint. +To list all security policy bundles, send a `GET` request to the Security Policy Bundles API. -{{}}The list will only contain the security policy bundles that you have "READ" permissions for in Instance Manager.{{}} +You’ll only see bundles you have `"READ"` permissions for. -You can filter the results by using the following query parameters: +You can use the following query parameters to filter results: -- `includeBundleContent`: Boolean indicating whether to include the security policy bundle content for each bundle when getting a list of bundles or not. If not provided, defaults to `false`. Please note that the content returned is `base64 encoded`. -- `policyName`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy name will be returned. If not provided, it will not filter based on `policyName`. -- `policyUID`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy UID will be returned. If not provided, it will not filter based on `policyUID`. -- `startTime`: The security policy bundle's "modified time" has to be equal to or greater than this time value. If no value is supplied, it defaults to 24 hours from the current time. `startTime` has to be less than `endTime`. -- `endTime`: Indicates the time that the security policy bundles modified time has to be less than. If no value is supplied, it defaults to current time. `endTime` has to be greater than `startTime`. +- `includeBundleContent`: Whether to include base64-encoded content in the response. Defaults to `false`. +- `policyName`: Return only bundles that match this policy name. +- `policyUID`: Return only bundles that match this policy UID. +- `startTime`: Return only bundles modified at or after this time. +- `endTime`: Return only bundles modified before this time. -
    +If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|----------------------------------------------| | GET | `/api/platform/v1/security/policies/bundles` | {{}} -For example: +Example: ```shell -curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " ``` @@ -401,10 +414,10 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "dceb8254-9a90-4e77-87ac-73070f821412" + "uid": "" }, "content": "", "compilationStatus": { @@ -418,10 +431,10 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", "policyName": "defautl-enforcement", - "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" + "uid": "" }, "content": "", "compilationStatus": { @@ -435,10 +448,10 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" + "uid": "" }, "content": "", "compilationStatus": { @@ -452,35 +465,35 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ --- -## Get a Security Policy Bundle {#get-security-policy-bundle} +## Get a security policy bundle {#get-security-policy-bundle} -To get a specific security policy bundle, send an HTTP `GET` request to the Security Policies Bundles API endpoint that contains the security policy UID and security policy bundle UID in the path. +To retrieve a specific security policy bundle, send a `GET` request to the Security Policy Bundles API using the policy UID and bundle UID in the URL path. -{{}}You must have "READ" permission for the security policy bundle to be able to retrieve information about a bundle by using the REST API.{{}} - -
    +You must have `"READ"` permission for the bundle to retrieve it. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|-------------------------------------------------------------------------------------------------| | GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | {{}} - -For example: +Example: ```shell -curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/29d86fe8-612a-5c69-895a-04fc5b9849a6/bundles/trs35lv2-9a90-4e77-87ac-ythn4967 \ +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ -H "Authorization: Bearer " ``` -The JSON response, shown in the example below, includes a `content` field that is base64 encoded. After you retrieve the information from the API, you will need to base64 decode the content field. You can include this in your API call, as shown in the following example cURL request: +The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tgz` file. + +Example: ```bash -curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ + -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz ```
    @@ -492,10 +505,10 @@ curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-poli "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" + "uid": "" }, "content": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==", "compilationStatus": { @@ -507,28 +520,25 @@ curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-poli --- -## Create a Security Log Profile {#create-security-log-profile} - -Send an HTTP `POST` request to the Security Log Profiles API endpoint to upload a new security log profile. +## Create a security log profile {#create-security-log-profile} -{{}}Before sending a security log profile to Instance Manager, you need to encode it using `base64`. Submitting a log profile in its original JSON format will result in an error.{{}} - -
    +To upload a new security log profile, send a `POST` request to the Security Log Profiles API endpoint. +You must encode the log profile in `base64` before sending it. If you send plain JSON, the request will fail. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|-----------------------------------------| | POST | `/api/platform/v1/security/logprofiles` | {{}} -For example: +Example: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ -H "Authorization: Bearer " \ -d @default-log-example.json ``` @@ -558,87 +568,100 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles \ "modified": "2023-07-05T22:09:19.634358096Z", "name": "default-log-example", "revisionTimestamp": "2023-07-05T22:09:19.634358096Z", - "uid": "54c35ad7-e082-4dc5-bb5d-2640a17d5620" + "uid": "" }, "selfLink": { - "rel": "/api/platform/v1/security/logprofiles/54c35ad7-e082-4dc5-bb5d-2640a17d5620" + "rel": "/api/platform/v1/security/logprofiles/" } } ``` --- -## Update a Security Log Profile - -To update a security log profile, send an HTTP `POST` request to the Security Log Profiles API endpoint, `/api/platform/v1/security/logprofiles`. +## Update a security log profile {#update-security-log-profile} -You can use the optional `isNewRevision` parameter to indicate whether the updated log profile is a new version of an existing log profile. +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` | +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | | PUT | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -For example: +To create a new revision: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-default-log.json ``` -You can update a specific log profile by sending an HTTP `PUT` request to the Security Log Profiles API endpoint that includes the log profile's unique identifier (UID). - -To find the UID, send an HTTP `GET` request to the Security Log Profiles API endpoint. This returns a list of all Security Log Profiles that contains the unique identifier for each log profile. +To overwrite an existing security log profile: -Include the UID for the security log profile in your `PUT` request to update the log profile. +1. Retrieve the profile’s UID: -For example: + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " \ + --Content-Type application/json \ + -d @update-log-profile.json + ``` -```shell -curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ - -H "Authorization: Bearer " \ - --Content-Type application/json -d @update-default-log.json -``` +2. Use the UID in your PUT request: + + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " \ + --Content-Type application/json \ + -d @update-log-profile.json + ``` -After you have pushed an updated security log profile, you can [publish it](#publish-policy) to selected instances or instance groups. +After updating the security log profile, you can [publish it](#publish-policy) to specific instances or instance groups. --- -## Delete a Security Log Profile +## Delete a security log profile {#delete-security-log-profile} -To delete a security log profile, send an HTTP `DELETE` request to the Security Log Profiles API endpoint that includes the unique identifier for the log profile that you want to delete. +To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. {{}} -| Method | Endpoint | -|--------|------------------------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------------------------------------| | DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -For example: +1. Retrieve the UID: -```shell -curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ - -H "Authorization: Bearer " -``` + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ + -H "Authorization: Bearer " + ``` + +2. Send the delete request: + + ```shell + curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " + ``` --- -## Publish Updates to Instances {#publish-policy} +## Publish updates to instances {#publish-policy} -The Publish API lets you distribute security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups. +Use the Publish API to push security policies, log profiles, attack signatures, and threat campaigns to NGINX instances or instance groups. -{{}}Use this endpoint *after* you've added or updated security policies, security log profiles, attack signatures, and/or threat campaigns.{{}} +Call this endpoint *after* you've created or updated the resources you want to deploy. {{}} @@ -650,18 +673,20 @@ The Publish API lets you distribute security policies, security log profiles, at {{}} -When making a request to the Publish API, make sure to include all the necessary information for your specific use case: +Include the following information in your request, depending on what you're publishing: -- Instance and/or Instance Group UID(s) to push the bundle to -- Threat Campaign version and UID -- Attack Signature version and UID -- Security Policy UID(s) -- Security Log Profile UID(s) +- Instance and instance group UIDs +- Policy UID and name +- Log profile UID and name +- Attack signature library UID and version +- Threat campaign UID and version -For example: +Example: ```shell -curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorization: Bearer " +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ + -H "Authorization: Bearer " \ + -d @publish-request.json ```
    @@ -671,27 +696,27 @@ curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorizat { "publications": [ { - "attackSignatureLibrary": { - "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "versionDateTime": "2022.10.02" - }, - "instanceGroups": [ - "3fa85f64-5717-4562-b3fc-2c963f66afa6" - ], "instances": [ - "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "" ], + "instanceGroups": [ + "" + ], + "policyContent": { + "name": "example-policy", + "uid": "" + }, "logProfileContent": { - "name": "default-log", - "uid": "ffdbda39-88be-420a-b673-19d4183b7e4c" + "name": "example-log-profile", + "uid": "" }, - "policyContent": { - "name": "default-enforcement", - "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "attackSignatureLibrary": { + "uid": "", + "versionDateTime": "2023.10.02" }, "threatCampaign": { - "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "versionDateTime": "2022.10.01" + "uid": "", + "versionDateTime": "2023.10.01" } } ] @@ -721,357 +746,91 @@ curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorizat --- -## Check Security Policy and Security Log Profile Publication Status -When publishing an NGINX configuration that references a security policy and secuity log profile, the Instance Manager REST APIs can provide further details about the status of the configuration publications. To access this information, use the Instance Manager API endpoints and method as indicated. +## Check security policy and security log profile publication status {#check-publication-status} -To retrieve the details for the different configuration publication statuses for a particular security policy, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security policy. +After publishing updates, you can check deployment status using the NGINX Instance Manager REST API. -| Method | Endpoint | -|--------|-----------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/associations/{security-policy-name}` | +Use the following endpoints to verify whether the configuration updates were successfully deployed to instances or instance groups. -You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: +### Check publication status for a security policy -- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails -- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails +To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. -The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. +{{}} -```shell -curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/associations/ignore-xss" -H "Authorization: Bearer " -``` +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | -
    -JSON Response +{{}} -```json -{ - "associations": [ - { - "attackSignatureLibrary": { - "uid": "c69460cc-6b59-4813-8d9c-76e4a6c56b4b", - "versionDateTime": "2023.02.16" - }, - "instance": { - "hostName": "ip-172-16-0-99", - "lastDeploymentDetails": { - "createTime": "2023-04-11T21:36:11.519174534Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-99" - } - ] - }, - "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-04-11T21:36:14.008108979Z" - }, - "systemUid": "0435a5de-41c1-3754-b2e8-9d9fe946bafe", - "uid": "29d86fe8-612a-5c69-895a-04fc5b9849a6" - }, - "instanceGroup": { - "displayName": "inst_group_1", - "instances": [ - { - "hostName": "hostname1", - "systemUid": "49d143c2-f556-4cd7-8658-76fff54fb861", - "uid": "c8e15dcf-c504-4b7f-b52d-def7b8fd2f64", - "lastDeploymentDetails": { - "createTime": "2023-04-11T21:36:11.519174534Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-99" - } - ] - }, - "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-04-11T21:36:14.008108979Z" - }, - }, - { - "hostName": "hostname2", - "systemUid": "88a99ab0-15bb-4719-9107-daf5007c33f7", - "uid": "ed7e9173-794f-41af-80d9-4ed37d593247", - "lastDeploymentDetails": { - "createTime": "2023-04-11T21:36:11.519174534Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-99" - } - ] - }, - "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-04-11T21:36:14.008108979Z" - }, - } - ], - "uid": "51f8addc-c0e9-438b-b0b6-3e4f1aa8202d" - }, - "policyUid": "9991f237-d9c7-47b7-98aa-faa836838f38", - "policyVersionDateTime": "2023-04-11T21:18:19.183Z", - "threatCampaign": { - "uid": "eab683fe-c2f1-4910-a88c-8bfbc6363164", - "versionDateTime": "2023.02.15" - } - } - ] -} +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ + -H "Authorization: Bearer " ``` -
    +In the response, look for the `lastDeploymentDetails` field under instance or `instanceGroup.instances`. -To retrieve the details for the different configuration publication statuses for a particular security log profile, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security log profile. -| Method | Endpoint | -|--------|-----------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{security-log-profile-name}` | +### Check publication status for a security log profile -You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: +{{}} -- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails -- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails +| Method | Endpoint | +|--------|-------------------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | -The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. +{{}} + +Example: ```shell -curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/logprofiles/associations/default-log" -H "Authorization: Bearer " +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ + -H "Authorization: Bearer " ``` -
    -JSON Response +The response also contains `lastDeploymentDetails` for each instance or group. -```json -{ - "associations": [ - { - "instance": { - "hostName": "", - "systemUid": "", - "uid": "" - }, - "instanceGroup": { - "displayName": "ig1", - "instances": [ - { - "hostName": "ip-172-16-0-142", - "systemUid": "1d1f03ff-02de-32c5-8dfd-902658aada4c", - "uid": "18d074e6-3868-51ba-9999-b7466a936815" - } - ], - "lastDeploymentDetails": { - "createTime": "2023-07-05T23:01:06.679136973Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-142" - } - ] - }, - "id": "9bfc9db7-877d-4e8e-a43d-9660a6cd11cc", - "message": "Instance Group config successfully published to ig1", - "status": "successful", - "updateTime": "2023-07-05T23:01:06.790802157Z" - }, - "uid": "0df0386e-82f7-4efc-863e-5d7cfbc3f7df" - }, - "logProfileUid": "b680f7c3-6fc0-4c6b-889a-3025580c7fcb", - "logProfileVersionDateTime": "2023-07-05T22:08:47.371Z" - }, - { - "instance": { - "hostName": "ip-172-16-0-5", - "lastDeploymentDetails": { - "createTime": "2023-07-05T21:45:08.698646791Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-5" - } - ] - }, - "id": "73cf670a-738a-4a74-b3fb-ac9771e89814", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-07-05T21:45:08.698646791Z" - }, - "systemUid": "0afe5ac2-43aa-36c8-bcdc-7f88cdd35ab2", - "uid": "9bb4e2ef-3746-5d79-b526-e545fad27e90" - }, - "instanceGroup": { - "displayName": "", - "instances": [], - "uid": "" - }, - "logProfileUid": "bb3badb2-f8f5-4b95-9428-877fc208e2f1", - "logProfileVersionDateTime": "2023-07-03T21:46:17.006Z" - } - ] -} -``` +### Check status for a specific instance -
    +You can also view the deployment status for a specific instance by providing the system UID and instance UID. -To retrieve the configuration publication status details for a particular instance, send an HTTP `GET` request to the Instances API endpoint, providing the unique system and instance identifiers. +{{}} -| Method | Endpoint | -|--------|-----------------------------------------------------------------| -| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-id}` | +| Method | Endpoint | +|--------|------------------------------------------------------------------| +| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | -You can locate the configuration publication status in the the response within the `lastDeploymentDetails` field, which contains additional fields that provide more context around the status. +{{}} -The example below shows a call to the `instances` endpoint and the corresponding JSON response containing a compiler related error message. +Example: ```shell -curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b" -H "Authorization: Bearer " +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ + -H "Authorization: Bearer " ``` -
    -JSON Response +In the response, look for the `lastDeploymentDetails` field, which shows the deployment status and any related errors. -```json -{ - "build": { - "nginxPlus": true, - "release": "nginx-plus-r28", - "version": "1.23.2" - }, - "configPath": "/etc/nginx/nginx.conf", - "configVersion": { - "instanceGroup": { - "createTime": "0001-01-01T00:00:00Z", - "uid": "", - "versionHash": "" - }, - "versions": [ - { - "createTime": "2023-01-14T10:48:46.319Z", - "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", - "versionHash": "922e9d40fa6d4dd3a4b721295b8ecd95f73402644cb8d234f9f4f862b8a56bfc" - } - ] - }, - "displayName": "ip-192-0-2-27", - "links": [ - { - "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73", - "name": "system" - }, - { - "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", - "name": "self" - }, - { - "rel": "/api/platform/v1/systems/instances/deployments/b31c6ab1-4a46-4c81-a065-204575145e8e", - "name": "deployment" - } - ], - "processPath": "/usr/sbin/nginx", - "registrationTime": "2023-01-14T10:12:31.000Z", - "startTime": "2023-01-14T10:09:43Z", - "status": { - "lastStatusReport": "2023-01-14T11:11:49.323495017Z", - "state": "online" - }, - "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", - "version": "1.23.2", - "appProtect": { - "attackSignatureVersion": "Available after publishing Attack Signatures from Instance Manager", - "status": "active", - "threatCampaignVersion": "Available after publishing Threat Campaigns from Instance Manager", - "version": "4.2.0" - }, - "configureArgs": [ - ... - ], - "lastDeploymentDetails": { - "createTime": "2023-01-14T11:10:25.096812852Z", - "details": { - "error": "{\"instance:b9df6377-2c4f-3266-a64a-e064b0371c73\":\"failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.\"}", - "failure": [ - { - "failMessage": "failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.", - "name": "ip-192-0-2-27" - } - ], - "pending": [], - "success": [] - }, - "id": "b31c6ab1-4a46-4c81-a065-204575145e8e", - "message": "Instance config failed to publish to", - "status": "failed", - "updateTime": "2023-01-14T11:10:25.175145693Z" - }, - "loadableModules": [ - ... - ], - "packages": [ - ... - ], - "processId": "10345", - "ssl": { - "built": null, - "runtime": null - } -} -``` +### Check deployment result by deployment ID -
    +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. -When you use the Publish API (`/security/publish`) to [publish a security policy and security log profile](#publish-policy), Instance Manager creates a deployment ID for the request. To view the status of the update, or to check for any errors, use the endpoint and method shown below and reference the deployment ID. +{{}} | Method | Endpoint | |--------|------------------------------------------------------------------| | GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | -You can locate the configuration publication status in the the response within the `details` field, which contains additional fields that provide more context around the status. +{{}} -The example below shows a call to the `deployments` endpoint and the corresponding JSON response containing a compiler error message. +Example: ```shell -curl -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/instances/deployments/d38a8e5d-2312-4046-a60f-a30a4aea1fbb" \ +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ -H "Authorization: Bearer " ``` -
    -JSON Response - -```json -{ - "createTime": "2023-01-14T04:35:47.566082799Z", - "details": { - "error": "{\"instance:8a2092aa-5612-370d-bff0-5d7521e206d6\":\"failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again\"}", - "failure": [ - { - "failMessage": "failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again", - "name": "ip-192-0-2-243" - } - ], - "pending": [], - "success": [] - }, - "id": "d38a8e5d-2312-4046-a60f-a30a4aea1fbb", - "message": "Instance config failed to publish to", - "status": "failed", - "updateTime": "2023-01-14T04:35:47.566082799Z" -} -``` - -
    +The response includes the full deployment status, success or failure details, and any compiler error messages. diff --git a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md index 92287079d..b0d31319f 100644 --- a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md +++ b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md @@ -1,68 +1,76 @@ --- -description: Learn how you can use F5 NGINX Management Suite Instance Manager to configure - NGINX App Protect WAF security policies. +description: Learn how to use F5 NGINX Instance Manager to set up and manage NGINX App Protect WAF security policies. docs: DOCS-992 -title: NGINX App Protect WAF configuration management +title: "How WAF policy management works" toc: true -weight: 500 +weight: 100 type: - reference --- ## Overview -F5 NGINX Management Suite Instance Manager provides configuration management for [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/). +F5 NGINX Instance Manager helps you manage [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/) security configurations. -You can use NGINX App Protect WAF with Instance Manager to inspect incoming traffic, identify potential threats, and block malicious traffic. With Configuration Management for App Protect WAF, you can configure WAF security policies in a single location and push your configurations out to one, some, or all of your NGINX App Protect WAF instances. +Use NGINX Instance Manager with NGINX App Protect WAF to inspect incoming traffic, detect threats, and block malicious requests. You can define policies in one place and push them to some or all of your NGINX App Protect WAF instances. -### Features +### Key features -- Manage NGINX App Protect WAF security configurations by using the NGINX Management Suite user interface or REST API -- Update Attack Signatures and Threat Campaign packages -- Compile security configurations into a binary bundle for consumption by NGINX App Protect WAF instances +- Manage WAF policies using the NGINX Instance Manager web interface or REST API +- Update attack signature and threat campaign packages +- Compile WAF configurations into a binary bundle for deployment ## Architecture -As demonstrated in Figure 1, Instance Manager lets you manage security configurations for NGINX App Protect WAF. You can define security policies, upload attack signatures and threat campaign packages, and publish common configurations out to your NGINX App Protect WAF instances. Instance Manager can compile the security configuration into a bundle before pushing the configuration to the NGINX App Protect WAF data plane instances. The NGINX Management Suite Security Monitoring module provides data visualization for NGINX App Protect, so you can monitor, analyze, and refine your policies. +NGINX Instance Manager lets you define and manage security policies, upload signature packages, and push configurations to your NGINX App Protect WAF instances. It can also compile your security configuration into a bundle before publishing it to the data plane. -{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Management Suite with NGINX App Protect Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution" width="75%">}} +The **Security Monitoring** module shows real-time data from NGINX App Protect WAF so you can track traffic, spot anomalies, and fine-tune policies. -### Security Bundle Compilation {#security-bundle} +{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Instance Manager with NGINX App Protect architecture overview" alt="Architecture diagram showing NGINX Instance Manager and Security Monitoring in the control plane pushing security bundles to NGINX App Protect WAF instances in the data plane" >}} -Instance Manager provides a compiler that can be configured to bundle the complete security configuration -- including JSON security policies, attack signatures, threat campaigns, and log profiles -- into a single binary in `.tgz` format. This bundle is then pushed out to each selected NGINX App Protect WAF instance. +### Security bundle compilation {#security-bundle} -Performing the security bundle compilation on Instance Manager (precompiled publication) instead of on the NGINX App Protect WAF instances provides the following benefits: +NGINX Instance Manager includes a compiler that packages your complete WAF configuration — security policies, attack signatures, threat campaigns, and log profiles — into a single `.tgz` file. It then pushes this bundle to the selected NGINX App Protect WAF instances. -- Eliminates the need to provision system resources on NGINX App Protect WAF instances to perform compilation. -- The bundles produced by Instance Manager can be reused by multiple NGINX App Protect WAF instances, instead of each instance having to perform the compilation separately. +**Why precompile with NGINX Instance Manager?** -However, if you prefer to maintain policy compilation on the NGINX App Protect WAF instance, that is supported with the following limitation: +- Saves system resources on WAF instances +- Lets you reuse the same bundle across multiple instances -- Instance Manager does not publish JSON policies to the NGINX App Protect WAF instance. JSON policies referenced in an NGINX configuration must already exist on the NGINX App Protect WAF instance. +If you choose to compile policies on the WAF instance instead, that works too—but with this limitation: -The example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) context below enables NGINX App Protect WAF and tells NGINX where to find the compiled security bundle: +- NGINX Instance Manager won’t publish `.json` policies to the WAF instance. These policies must already exist on the instance and be referenced in the NGINX config. -## Log Profile Compilation +Example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) block to enable WAF and point to the bundle: -Instance Manager can also be configured to compile log profiles when you install a new version of the WAF compiler. When you publish an NGINX configuration with the NGINX App Protect [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, Instance Manager publishes the compiled log profiles to the NGINX App Protect WAF instances when precompiled publication is enabled. +```nginx +location / { + app_protect_enable on; + app_protect_policy_file /etc/app_protect/policies/policy_bundle.tgz; +} +``` + +## Log profile compilation + +You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on). {{}} -Instance Manager and Security Monitoring both use NGINX App Protect log profiles. The configuration requirements for each are different. When using Instance Manager configuration management, you must reference the log profile in your NGINX configuration using the `.tgz` file extension instead of `.json`. +NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tgz` file extension, not `.json`. {{}} -## Security Management APIs +## Security management APIs -By using the Instance Manager REST API, you can automate configuration updates to be pushed out to all of your NGINX App Protect WAF instances. You can use the Instance Manager API to manage and deploy the following security configurations: +Use the NGINX Instance Manager REST API to automate updates across your NGINX App Protect WAF instances. You can use the API to manage: -- security policies, -- log profiles, -- attack signatures, and -- threat campaigns. +- Security policies +- Log profiles +- Attack signatures +- Threat campaigns -Just as with changes made via the user interface, the Instance Manager compiler bundles all of the config updates into a single binary package that you can push out to your instances. Figure 2 shows an overview of the API endpoints available to support security policy configuration and publishing. +Just like with the web interface, the compiler creates a binary bundle with your updates that you can push to your WAF instances. -{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Management Suite with NGINX App Protect WAF Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution">}} +{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Instance Manager with NGINX App Protect WAF architecture overview" alt="Diagram showing how the NGINX Instance Manager REST API is used to create policies, upload signatures and campaigns, and publish compiled security bundles to NGINX App Protect WAF instances">}} -More information is available in the Instance Manager API documentation. +For full details, see the API documentation: {{< include "nim/how-to-access-api-docs.md" >}} From d86dc5938b58a84bcdac2088efefc3f4507f03e1 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 11:25:38 -0700 Subject: [PATCH 05/25] new messages --- layouts/partials/list-main.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 32f41efa0..cf05906b2 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -44,16 +44,16 @@

    Keep an inventory of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} -

    Update them before they expire

    +

    Detect and resolve expired SSL certs in minutes

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}}

    Secure your systems with role-based access control

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}} -

    Configure and synchronize groups of NGINX instances simultaneously

    +

    Synchronize changes across cloud environments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} -

    Automate NGINX fleet management

    +

    Automate NGINX fleet management from the CLI

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}}

    Terms unique to NGINX One Console

    From fb047baf7efebe312ff48d96f127ac05ba7b9de6 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 15 May 2025 09:48:37 -0700 Subject: [PATCH 06/25] Sync with presentation --- content/nginx-one/secure-your-fleet/_index.md | 6 ++++++ layouts/partials/list-main.html | 13 ++++++++----- 2 files changed, 14 insertions(+), 5 deletions(-) create mode 100644 content/nginx-one/secure-your-fleet/_index.md diff --git a/content/nginx-one/secure-your-fleet/_index.md b/content/nginx-one/secure-your-fleet/_index.md new file mode 100644 index 000000000..3d693a250 --- /dev/null +++ b/content/nginx-one/secure-your-fleet/_index.md @@ -0,0 +1,6 @@ +--- +title: Secure your fleet +description: +weight: 250 +url: /nginx-one/secure-your-fleet +--- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index cf05906b2..4167edd5a 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -19,7 +19,7 @@

    - {{ if or (lt .WordCount 1) (eq $PageTitle "F5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }} + {{ if or (lt .WordCount 1) (eq $PageTitle "fF5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }}
    @@ -32,25 +32,28 @@

    {{ .Title }}

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX fleet")}} -

    Use the F5 NGINX One Console to deploy, scale, or migrate your apps

    +

    Simplify, scale, secure, and collaborate with your NGINX fleet

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}}

    See benefits from the NGINX One Console

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}} -

    Manage your work-in-progress

    +

    Collaborate with Staged Configurations

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Secure your fleet")}} +

    Configure alerts that match your security policies

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}}

    Keep an inventory of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} -

    Detect and resolve expired SSL certs in minutes

    +

    Update your SSL certs before they expire

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}}

    Secure your systems with role-based access control

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}} -

    Synchronize changes across cloud environments

    +

    Simplify changes with Config Sync Groups

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}}

    Automate NGINX fleet management from the CLI

    From 57439463975938e088868b0ee9d625d38cf0c72f Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 21 May 2025 07:28:25 -0700 Subject: [PATCH 07/25] Make more prod ready --- content/nginx-one/secure-your-fleet/_index.md | 6 -- .../import-export-staged-config.md | 89 +++++++++++++++++++ 2 files changed, 89 insertions(+), 6 deletions(-) delete mode 100644 content/nginx-one/secure-your-fleet/_index.md create mode 100644 content/nginx-one/staged-configs/import-export-staged-config.md diff --git a/content/nginx-one/secure-your-fleet/_index.md b/content/nginx-one/secure-your-fleet/_index.md deleted file mode 100644 index 3d693a250..000000000 --- a/content/nginx-one/secure-your-fleet/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Secure your fleet -description: -weight: 250 -url: /nginx-one/secure-your-fleet ---- diff --git a/content/nginx-one/staged-configs/import-export-staged-config.md b/content/nginx-one/staged-configs/import-export-staged-config.md new file mode 100644 index 000000000..68993ee99 --- /dev/null +++ b/content/nginx-one/staged-configs/import-export-staged-config.md @@ -0,0 +1,89 @@ +--- +# We use sentence case and present imperative tone +title: Import and export a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: how-to +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +product: NGINX One +--- + +## Overview + +Many administrators do their work on local systems, virtual machines, Docker containers, and more. F5 NGINX One Console +supports import and export of such configurations. +This guide explains how to import or export a Staged Configuration to your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you import or export a Staged Configuration to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions. + +You can also import, export, and manage multiple Staged Configurations through [the API]({{< ref "/nginx-one/staged-configs/api-staged-config.md" >}}). + +## Considerations + +NGINX One Console supports imports and exports as a compressed archive known as a [tarball](https://en.wikipedia.org/wiki/Tar_(computing)), in `tar.gz` format. +When you work with such archives, consider the following: + +- Do _not_ unpack archives directly to your NGINX configuration directories. You do not want to accidentally overwrite existing configuration files. +- The files are set to a default file permission mode of 0644. +- Do not include files with secrets or personally identifying information. +- We ignore hidden files. + - If you import or export such files in archives, NGINX One Console does not include those files. +- The size of the archive is limited to 5 MB. The size of all uncompressed files in the archive is limited to 10 MB. + +{{< tip >}} + +Before you unpack an archive, run the `tar -tvzf .tar.gz` command. It displays the files and directories in that archive, without overwriting anything. +You'll then know where files are written when you extract an archive with a command like `tar -xvzf .tar.gz`. + +{{< /tip >}} + +## Import a Staged Configuration + +To import a Staged Configuration from your system to the NGINX One Console, you need to: + +- Package your configuration in `tar.gz` format. For example, the following command creates an archive file named for-import.tar.gz` from files in the `/etc/nginx` directory: + ```bash + tar czvf /etc/nginx for-import.tar.gz + ``` + +You would then import that file to the NGINX One Console. To do so, follow these steps: + +1. On the left menu, select **Staged Configurations**. +1. Select **Add Staged Configuration**. +1. Select **Import Configuration**. +1. Add a name for the Staged Configuration to be imported. +1. Select **Import from File**. +1. Choose the file. The process depends on your operating system. +1. If successful, you'll see a success message. + - A typical error suggests that the file is too large. + +## Export a Staged Configuration + +You can export a Staged Configuration from the NGINX One Console, as a download, to your system. To do so, follow these steps: + +1. On the left menu, select **Staged Configurations**. +1. Select the Staged Configuration you want to export. +1. Select the ellipsis (...) on the right side of the row with the Staged Configuration. +1. Select **Export** +1. In the file menu that appears, choose a filename for your archive and save the result +1. Be careful. Do not unpack the archive in a way that overwrites your current NGINX configuration. + +## Manage multiple Staged Configurations + +You can also delete multiple Staged Configurations through the UI: + +1. On the left menu, select **Staged Configurations**. +1. Select the Staged Configuration you want to delete. +1. You can then select the **Delete selected** button. + +You can do more from the API. Specifically, with the `object_id` of each configuration, you can create, modify, or delete multiple staged configurations with the [Bulk Staged Configurations endpoint]({{< ref "/nginx-one/api/api-reference-guide/#operation/bulkStagedConfigs" >}}). From caed9956b100d8958d181ad5b2e2c0553f91f1bb Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 21 May 2025 07:28:51 -0700 Subject: [PATCH 08/25] Make more prod ready --- layouts/partials/list-main.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 4167edd5a..628de73e4 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -40,9 +40,9 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}}

    Collaborate with Staged Configurations

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Secure your fleet")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}}

    Keep an inventory of your deployments

    {{ end }} From f53231365b509a63aa48237cec743c96f0841f2f Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 22 May 2025 11:15:19 -0700 Subject: [PATCH 09/25] More --- .../includes/nginx-one/how-to/add-instance.md | 23 ++++++++++++++ .../nginx-one/nginx-configs/add-instance.md | 30 ++++--------------- 2 files changed, 29 insertions(+), 24 deletions(-) create mode 100644 content/includes/nginx-one/how-to/add-instance.md diff --git a/content/includes/nginx-one/how-to/add-instance.md b/content/includes/nginx-one/how-to/add-instance.md new file mode 100644 index 000000000..f103e085a --- /dev/null +++ b/content/includes/nginx-one/how-to/add-instance.md @@ -0,0 +1,23 @@ +--- +docs: +--- + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. + +Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. + +```bash +curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Once the process is complete, you can configure that instance in your NGINX One Console. \ No newline at end of file diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md index ddf5eb095..fd3b70fd5 100644 --- a/content/nginx-one/nginx-configs/add-instance.md +++ b/content/nginx-one/nginx-configs/add-instance.md @@ -16,34 +16,16 @@ to set up a data plane key to connect your instances to NGINX One. Before you add an instance to NGINX One Console, ensure: -- You have administrator access to NGINX One Console. -- You have configured instances of NGINX that you want to manage through NGINX One Console. -- You have or are ready to configure a data plane key. -- You have or are ready to set up managed certificates. +- You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. +- You have [configured instances of NGINX]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) that you want to manage through NGINX One Console. +- You have or are ready to configure a [data plane key]({{< ref "/nginx-one/getting-started.md#generate-data-plane-key" >}}). +- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). {{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} ## Add an instance -You can add an instance to NGINX One Console in the following ways: - -- Directly, under **Instances** -- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** - -In either case, NGINX One Console gives you a choice for data plane keys: - -- Create a new key -- Use an existing key - -NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. - -Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. - -```bash -curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y -``` - -Once the process is complete, you can configure that instance in your NGINX One Console. +{{< include "/nginx-one/how-to/add-instance.md" >}} ## Managed and Unmanaged Certificates @@ -51,7 +33,7 @@ If you add an instance with SSL/TLS certificates, those certificates can match a ### If the certificate is already managed -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One], these certificates are added to your list of **Managed Certificates**. +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. NGINX One Console can manage your instances along with those certificates. From 93b5e831f425de4f7fc1e08b21c327c57ba04b37 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 22 May 2025 11:48:39 -0700 Subject: [PATCH 10/25] more --- content/nginx-one/api/_index.md | 2 +- content/nginx-one/nginx-configs/_index.md | 2 +- .../manage-config-sync-groups.md | 239 ------------------ content/nginx-one/staged-configs/_index.md | 2 +- layouts/partials/list-main.html | 4 +- 5 files changed, 5 insertions(+), 244 deletions(-) delete mode 100644 content/nginx-one/nginx-configs/manage-config-sync-groups.md diff --git a/content/nginx-one/api/_index.md b/content/nginx-one/api/_index.md index 1fe244a36..bad851831 100644 --- a/content/nginx-one/api/_index.md +++ b/content/nginx-one/api/_index.md @@ -1,5 +1,5 @@ --- -title: NGINX One API +title: Automation with the NGINX One API description: weight: 1000 url: /nginx-one/api diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md index feffd5d05..23c0621a4 100644 --- a/content/nginx-one/nginx-configs/_index.md +++ b/content/nginx-one/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Watch your NGINX instances +title: Access and connect to your NGINX instances weight: 300 url: /nginx-one/nginx-configs --- diff --git a/content/nginx-one/nginx-configs/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/manage-config-sync-groups.md deleted file mode 100644 index 41589dadd..000000000 --- a/content/nginx-one/nginx-configs/manage-config-sync-groups.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -docs: null -title: Manage config sync groups -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -This guide explains how to create and manage config sync groups in the F5 NGINX One Console. Config sync groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. - -If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find config sync groups in NGINX One similar, though the steps and terminology differ slightly. - -## Before you start - -Before you create and manage config sync groups, ensure: - -- You have access to the NGINX One Console. -- You have the necessary permissions to create and manage config sync groups. -- NGINX instances are properly registered with NGINX One if you plan to add existing instances to a config sync group. - -## Important considerations - -- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified config sync group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. - -- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same config sync group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. - -- **Single config sync group membership**: An instance can join only one config sync group at a time. - -- **Configuration inheritance**: If the config sync group already has a configuration defined, that configuration will be pushed to instances when they join. - -- **Using an instance's configuration for the group configuration**: If an instance is the first to join a config sync group and the group's configuration hasn't been defined, the instance’s configuration will become the group’s configuration. Any instances added later will automatically inherit this configuration. - - {{< note >}} If you add multiple instances to a single config sync group, simultaneously (with automation), follow these steps. Your instances will inherit your desired configuration: - - 1. Create a config sync group. - 1. Add a configuration to the config sync group, so all instances inherit it. - 1. Add the instances in a separate operation. - - Your instances should synchronize with your desired configuration within 30 seconds. {{< /note >}} - -- **Persistence of a config sync group's configuration**: The configuration for a config sync group persists until you delete the group. Even if you remove all instances, the group's configuration stays intact. Any new instances that join later will automatically inherit this configuration. - -- **Config sync groups vs. cluster syncing**: Config sync groups are not the same as cluster syncing. Config sync groups let you to manage and synchronize configurations across multiple NGINX instances as a single entity. This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While config sync groups focus on configuration management, cluster syncing supports failover and data consistency. - -## Create a config sync group - -Creating a config sync group allows you to manage the configurations of multiple NGINX instances as a single entity. - -1. On the left menu, select **Config Sync Groups**. -2. Select **Add Config Sync Group**. -3. In the **Name** field, type a name for your config sync group. -4. Select **Create** to add the config sync group. - -## Manage config sync group membership - -### Add an existing instance to a config sync group {#add-an-existing-instance-to-a-config-sync-group} - -You can add existing NGINX instances that are already registered with NGINX One to a config sync group. - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. At the end of the file, add a new line beginning with `instance_group:`, followed by the config sync group name. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent: - - ``` shell - sudo systemctl restart nginx-agent - ``` - -### Add a new instance to a config sync group {#add-a-new-instance-to-a-config-sync-group} - -When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. - -1. On the left menu, select **Config Sync Groups**. -2. Select the config sync group in the list. -3. In the **Instances** pane, select **Add Instance to Config Sync Group**. -4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to config sync group**. -5. Select **Next**. -6. **Generate a new data plane key** (choose this option if you don't have an existing key): - - - Select **Generate new key** to create a new data plane key for the instance. - - Select **Generate Data Plane Key**. - - Copy and securely store the generated key, as it is displayed only once. - -7. **Use an existing data plane key** (choose this option if you already have a key): - - - Select **Use existing key**. - - In the **Data Plane Key** field, enter the existing data plane key. - -{{}} - -{{%tab name="Virtual Machine or Bare Metal"%}} - -8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. -9. Select **Done** to complete the process. - -{{%/tab%}} - -{{%tab name="Docker Container"%}} - -8. **Log in to the NGINX private registry**: - - - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) from [MyF5](https://my.f5.com/manage/s/). - - ```shell - sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none - ``` - -9. **Pull the Docker image**: - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - -10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. - -11. Select **Done** to complete the process. - -{{%/tab%}} - -{{}} - -{{}} - -Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. - -For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). - -{{}} - -### Change the config sync group for an instance - -If you need to move an NGINX instance to a different config sync group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and change it to the name of the new config sync group. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent by running the following command: - - ```shell - sudo systemctl restart nginx-agent - ``` - -**Important:** If the instance is the first to join the new config sync group and a group configuration hasn’t been added manually beforehand, the instance’s configuration will automatically become the group’s configuration. Any instances added to this group later will inherit this configuration. - -### Remove an instance from a config sync group - -If you need to remove an NGINX instance from a config sync group without adding it to another group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. - - ```text - # instance_group: - ``` - -4. Restart NGINX Agent: - - ```shell - sudo systemctl restart nginx-agent - ``` - -By removing or commenting out this line, the instance will no longer be associated with any config sync group. - -## Add the config sync group configuration - -You can set the configuration for a config sync group in two ways: - -### Define the group configuration manually - -You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. - -To manually set the group configuration: - -1. Follow steps 1–4 in the [**Create a config sync group**](#create-a-config-sync-group) section to create your config sync group. -2. After creating the group, select the **Configuration** tab. -3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. -4. To add a configuration, select **Edit Configuration**. -5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. -6. After making your changes, select **Next** to view a split screen showing your changes. -7. If you're satisfied with the configuration, select **Save and Publish**. - -### Use an instance's configuration - -If you don't manually define a group config, the NGINX configuration of the first instance added to a config sync group becomes the group's configuration. Any additional instances added afterward inherit this group configuration. - -To set the group configuration by adding an instance: - -1. Follow the steps in the [**Add an existing instance to a config sync group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a config sync group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. -2. The NGINX configuration from this instance will automatically become the group's configuration. -3. You can further edit and publish this configuration by following the steps in the [**Publish the config sync group configuration**](#publish-the-config-sync-group-configuration) section. - -## Publish the config sync group configuration {#publish-the-config-sync-group-configuration} - -After the config sync group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. - -1. On the left menu, select **Config Sync Groups**. -2. Select the config sync group in the list. -3. Select the **Configuration** tab to view the group's NGINX configuration. -4. To modify the group's configuration, select **Edit Configuration**. -5. Make the necessary changes to the configuration. -6. When you're finished, select **Next**. A split view displays the changes. -7. If you're satisfied with the changes, select **Save and Publish**. - -Publishing the group configuration ensures that all instances within the config sync group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. - -## Understanding config sync statuses - -The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. - -{{}} -| **Status** | **Description** | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| **In Sync** | All instances within the config sync group have configurations that match the group configuration. No action is required. | -| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | -| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | -| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | -{{}} - -Monitoring the **Config Sync Status** helps ensure that your configurations are consistently applied across all instances in a group, reducing the risk of configuration drift. - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md index 4186aa21b..8b67c0a21 100644 --- a/content/nginx-one/staged-configs/_index.md +++ b/content/nginx-one/staged-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Set up new instances +title: Draft new instances weight: 200 url: /nginx-one/how-to/staged-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 628de73e4..e87270bd3 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -38,13 +38,13 @@

    See benefits from the NGINX One Console

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}} -

    Collaborate with Staged Configurations

    +

    Work on new instances with Staged Configurations

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}} -

    Keep an inventory of your deployments

    +

    Monitor all of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}}

    Update your SSL certs before they expire

    From d58cfcb3c37be3a887e7f8ebf9eac67b163b5f3a Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 22 May 2025 12:34:50 -0700 Subject: [PATCH 11/25] based on Jason's feedback --- content/nginx-one/api/_index.md | 2 +- .../nginx-one/certificates/manage-certificates.md | 2 +- .../nginx-one/config-sync-groups/add-file-csg.md | 2 +- .../manage-config-sync-groups.md | 2 +- content/nginx-one/nginx-configs/_index.md | 2 +- content/nginx-one/nginx-configs/add-file.md | 2 +- .../view-edit-nginx-configurations.md | 14 ++------------ content/nginx-one/rbac/_index.md | 2 +- content/nginx-one/staged-configs/_index.md | 2 +- layouts/partials/list-main.html | 12 ++++++------ 10 files changed, 16 insertions(+), 26 deletions(-) diff --git a/content/nginx-one/api/_index.md b/content/nginx-one/api/_index.md index bad851831..9d4e73a0b 100644 --- a/content/nginx-one/api/_index.md +++ b/content/nginx-one/api/_index.md @@ -1,5 +1,5 @@ --- -title: Automation with the NGINX One API +title: Automate with the NGINX One API description: weight: 1000 url: /nginx-one/api diff --git a/content/nginx-one/certificates/manage-certificates.md b/content/nginx-one/certificates/manage-certificates.md index 13c532e38..136a4e299 100644 --- a/content/nginx-one/certificates/manage-certificates.md +++ b/content/nginx-one/certificates/manage-certificates.md @@ -193,5 +193,5 @@ To convert these cerificates to managed, start with the Certificates menu, and s ## See also - [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Add an instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) - [Add a file in a configuration]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) diff --git a/content/nginx-one/config-sync-groups/add-file-csg.md b/content/nginx-one/config-sync-groups/add-file-csg.md index 9b6905aea..c416848a8 100644 --- a/content/nginx-one/config-sync-groups/add-file-csg.md +++ b/content/nginx-one/config-sync-groups/add-file-csg.md @@ -63,5 +63,5 @@ With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one ## See also - [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Add an NGINX instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) - [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md index 8b24001cd..056414a67 100644 --- a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md @@ -258,4 +258,4 @@ Monitor the **Config Sync Status** column. It can help you ensure that your conf ## See also - [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Add an NGINX instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md index 23c0621a4..d4a987147 100644 --- a/content/nginx-one/nginx-configs/_index.md +++ b/content/nginx-one/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Access and connect to your NGINX instances +title: Manage your NGINX instances weight: 300 url: /nginx-one/nginx-configs --- diff --git a/content/nginx-one/nginx-configs/add-file.md b/content/nginx-one/nginx-configs/add-file.md index 4549647f5..01d2008cf 100644 --- a/content/nginx-one/nginx-configs/add-file.md +++ b/content/nginx-one/nginx-configs/add-file.md @@ -63,5 +63,5 @@ Enter the name of the desired configuration file, such as `abc.conf` and select ## See also - [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Add an NGINX instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) - [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md index 9b742104c..2736ba852 100644 --- a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md +++ b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md @@ -1,6 +1,6 @@ --- # We use sentence case and present imperative tone -title: View and edit NGINX configurations +title: View and edit an NGINX instance # Weights are assigned in increments of 100: determines sorting order weight: 300 # Creates a table of contents and sidebar, useful for large documents @@ -12,17 +12,7 @@ product: NGINX One --- -## Overview - -This guide explains how to add a **Instances** to your NGINX One Console. - -## Before you start - -Before you add **Instances** to NGINX One Console, ensure: - -- You have an NGINX One Console account with staged configuration permissions.``` - -Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. +This guide explains how to edit the configuration of an existing **Instance** in your NGINX One Console. To view and edit an NGINX configuration, follow these steps: diff --git a/content/nginx-one/rbac/_index.md b/content/nginx-one/rbac/_index.md index 36c5b464d..6544b2494 100644 --- a/content/nginx-one/rbac/_index.md +++ b/content/nginx-one/rbac/_index.md @@ -1,5 +1,5 @@ --- -title: Organize your administrators with RBAC +title: Organize administrators with RBAC description: weight: 500 url: /nginx-one/rbac diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md index 8b67c0a21..33a0752ed 100644 --- a/content/nginx-one/staged-configs/_index.md +++ b/content/nginx-one/staged-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Draft new instances +title: Draft new instances (Staged Configuration) weight: 200 url: /nginx-one/how-to/staged-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index e87270bd3..b037150b6 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -37,26 +37,26 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}}

    See benefits from the NGINX One Console

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new instances (Staged Configuration)")}}

    Work on new instances with Staged Configurations

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX instances")}}

    Monitor all of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}}

    Update your SSL certs before they expire

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}} -

    Secure your systems with role-based access control

    + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize administrators with RBAC")}} +

    Assign responsibilities with role-based access control

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}}

    Simplify changes with Config Sync Groups

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} -

    Automate NGINX fleet management from the CLI

    + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Automate with the NGINX One API")}} +

    Manage your NGINX fleet over REST

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}}

    Terms unique to NGINX One Console

    From c1945a9aebefa84ba3d75debceca8511490933f1 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 22 May 2025 12:54:03 -0700 Subject: [PATCH 12/25] more --- content/nginx-one/rbac/overview.md | 2 +- content/nginx-one/rbac/rbac-api.md | 2 +- content/nginx-one/rbac/roles.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/nginx-one/rbac/overview.md b/content/nginx-one/rbac/overview.md index ccab68d4b..2bcdfc17b 100644 --- a/content/nginx-one/rbac/overview.md +++ b/content/nginx-one/rbac/overview.md @@ -1,5 +1,5 @@ --- -title: "Role-based access control overview" +title: "Learn about Role-based access control" weight: 400 toc: true type: reference diff --git a/content/nginx-one/rbac/rbac-api.md b/content/nginx-one/rbac/rbac-api.md index 82953365a..11e90cfc3 100644 --- a/content/nginx-one/rbac/rbac-api.md +++ b/content/nginx-one/rbac/rbac-api.md @@ -1,5 +1,5 @@ --- -title: "Custom roles and API groups" +title: "Set up custom roles with API groups" weight: 500 toc: true type: reference diff --git a/content/nginx-one/rbac/roles.md b/content/nginx-one/rbac/roles.md index 646f0d5cb..e2d33a15b 100644 --- a/content/nginx-one/rbac/roles.md +++ b/content/nginx-one/rbac/roles.md @@ -1,5 +1,5 @@ --- -title: "Default roles" +title: "Review default roles" weight: 500 toc: true type: reference From 690d93a7ef9cd9a2014f421a62c5a33208c3b901 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 23 May 2025 14:09:47 -0700 Subject: [PATCH 13/25] typo --- layouts/partials/list-main.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index b037150b6..324c38d66 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -19,7 +19,7 @@

    - {{ if or (lt .WordCount 1) (eq $PageTitle "fF5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }} + {{ if or (lt .WordCount 1) (eq $PageTitle "F5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }}
    From adbfb228eaffc78b4e7b26757eac36b2c276faf6 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 23 May 2025 14:21:29 -0700 Subject: [PATCH 14/25] More --- content/nginx-one/nginx-configs/_index.md | 2 +- content/nginx-one/staged-configs/_index.md | 2 +- layouts/partials/list-main.html | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md index d4a987147..45fb17e97 100644 --- a/content/nginx-one/nginx-configs/_index.md +++ b/content/nginx-one/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Manage your NGINX instances +title: Add and manage your NGINX instances weight: 300 url: /nginx-one/nginx-configs --- diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md index 33a0752ed..46d1b93d3 100644 --- a/content/nginx-one/staged-configs/_index.md +++ b/content/nginx-one/staged-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Draft new instances (Staged Configuration) +title: Draft new instances (Staged Configs) weight: 200 url: /nginx-one/how-to/staged-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 324c38d66..0b81b99c4 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -37,13 +37,13 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}}

    See benefits from the NGINX One Console

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new instances (Staged Configuration)")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new instances (Staged Configs)")}}

    Work on new instances with Staged Configurations

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX instances")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Add and Manage your NGINX instances")}}

    Monitor all of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} From 415df30e5012a76c9e18bdd9a4f7be16d9c9aae4 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 23 May 2025 14:23:34 -0700 Subject: [PATCH 15/25] typo --- layouts/partials/list-main.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 0b81b99c4..15be826f8 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -43,7 +43,7 @@

    - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Add and Manage your NGINX instances")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Add and manage your NGINX instances")}}

    Monitor all of your deployments

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} From 0317b753c8b1bb8c29036409d79e633c13d605e3 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Tue, 27 May 2025 13:56:58 -0700 Subject: [PATCH 16/25] Add redirects --- content/nginx-one/certificates/manage-certificates.md | 1 + content/nginx-one/config-sync-groups/add-file-csg.md | 1 + .../nginx-one/config-sync-groups/manage-config-sync-groups.md | 1 + content/nginx-one/nginx-configs/add-file.md | 1 + content/nginx-one/nginx-configs/add-instance.md | 1 + .../nginx-one/nginx-configs/clean-up-unavailable-instances.md | 1 + .../nginx-one/nginx-configs/view-edit-nginx-configurations.md | 1 + content/nginx-one/rbac/overview.md | 1 + content/nginx-one/rbac/rbac-api.md | 1 + content/nginx-one/rbac/roles.md | 1 + content/nginx-one/staged-configs/add-staged-config.md | 1 + content/nginx-one/staged-configs/api-staged-config.md | 1 + content/nginx-one/staged-configs/edit-staged-config.md | 1 + content/nginx-one/staged-configs/import-export-staged-config.md | 1 + 14 files changed, 14 insertions(+) diff --git a/content/nginx-one/certificates/manage-certificates.md b/content/nginx-one/certificates/manage-certificates.md index 136a4e299..c34c05eee 100644 --- a/content/nginx-one/certificates/manage-certificates.md +++ b/content/nginx-one/certificates/manage-certificates.md @@ -3,6 +3,7 @@ docs: null title: Manage certificates toc: true weight: 100 +aliases: /nginx-one/how-to/certificates/manage-certificates/ type: - how-to --- diff --git a/content/nginx-one/config-sync-groups/add-file-csg.md b/content/nginx-one/config-sync-groups/add-file-csg.md index c416848a8..ee92e6fd0 100644 --- a/content/nginx-one/config-sync-groups/add-file-csg.md +++ b/content/nginx-one/config-sync-groups/add-file-csg.md @@ -3,6 +3,7 @@ docs: null title: Add a file to a Config Sync Group toc: true weight: 400 +aliases: /nginx-one/how-to/config-sync-groups/add-file-csg/ type: - how-to --- diff --git a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md index 056414a67..6ffcf4d06 100644 --- a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md @@ -3,6 +3,7 @@ docs: null title: Manage Config Sync Groups toc: true weight: 300 +aliases: /nginx-one/how-to/config-sync-groups/manage-config-sync-groups/ type: - how-to --- diff --git a/content/nginx-one/nginx-configs/add-file.md b/content/nginx-one/nginx-configs/add-file.md index 01d2008cf..60f355c77 100644 --- a/content/nginx-one/nginx-configs/add-file.md +++ b/content/nginx-one/nginx-configs/add-file.md @@ -3,6 +3,7 @@ docs: null title: Add a file to an instance toc: true weight: 400 +aliases: /nginx-one/how-to/nginx-configs/add-file/ type: - how-to --- diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md index fd3b70fd5..57ecf5fd0 100644 --- a/content/nginx-one/nginx-configs/add-instance.md +++ b/content/nginx-one/nginx-configs/add-instance.md @@ -3,6 +3,7 @@ description: '' title: Add an NGINX instance toc: true weight: 100 +aliases: /nginx-one/how-to/nginx-configs/add-instance/ type: - how-to --- diff --git a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md index 6a119617d..5bb33b4d6 100644 --- a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md +++ b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md @@ -4,6 +4,7 @@ docs: null title: Clean up unavailable NGINX instances toc: true weight: 200 +aliases: /nginx-one/how-to/nginx-configs/clean-up-unavailable-instances/ type: - how-to --- diff --git a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md index 2736ba852..a5460d019 100644 --- a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md +++ b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md @@ -7,6 +7,7 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial +aliases: /nginx-one/how-to/nginx-configs/view-edit-nginx-configurations/ # Intended for internal catalogue and search, case sensitive: product: NGINX One --- diff --git a/content/nginx-one/rbac/overview.md b/content/nginx-one/rbac/overview.md index 2bcdfc17b..91ca52209 100644 --- a/content/nginx-one/rbac/overview.md +++ b/content/nginx-one/rbac/overview.md @@ -4,6 +4,7 @@ weight: 400 toc: true type: reference product: NGINX One +aliases: /nginx-one/how-to/rbac/overview/ docs: DOCS-000 --- diff --git a/content/nginx-one/rbac/rbac-api.md b/content/nginx-one/rbac/rbac-api.md index 11e90cfc3..300009370 100644 --- a/content/nginx-one/rbac/rbac-api.md +++ b/content/nginx-one/rbac/rbac-api.md @@ -4,6 +4,7 @@ weight: 500 toc: true type: reference product: NGINX One +aliases: /nginx-one/how-to/rbac/rbac-api/ docs: DOCS-000 --- diff --git a/content/nginx-one/rbac/roles.md b/content/nginx-one/rbac/roles.md index e2d33a15b..a73916f1d 100644 --- a/content/nginx-one/rbac/roles.md +++ b/content/nginx-one/rbac/roles.md @@ -4,6 +4,7 @@ weight: 500 toc: true type: reference product: NGINX One +aliases: /nginx-one/how-to/rbac/roles/ docs: DOCS-000 --- diff --git a/content/nginx-one/staged-configs/add-staged-config.md b/content/nginx-one/staged-configs/add-staged-config.md index 94007c407..3a9c2e71d 100644 --- a/content/nginx-one/staged-configs/add-staged-config.md +++ b/content/nginx-one/staged-configs/add-staged-config.md @@ -7,6 +7,7 @@ weight: 100 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial +aliases: /nginx-one/how-to/staged-configs/add-staged-config/ # Intended for internal catalogue and search, case sensitive: # Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit product: diff --git a/content/nginx-one/staged-configs/api-staged-config.md b/content/nginx-one/staged-configs/api-staged-config.md index 8eadfdb55..f31ec8684 100644 --- a/content/nginx-one/staged-configs/api-staged-config.md +++ b/content/nginx-one/staged-configs/api-staged-config.md @@ -7,6 +7,7 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial +aliases: /nginx-one/how-to/staged-configs/api-staged-config/ # Intended for internal catalogue and search, case sensitive: product: NGINX One --- diff --git a/content/nginx-one/staged-configs/edit-staged-config.md b/content/nginx-one/staged-configs/edit-staged-config.md index 8f101a0fd..45972645d 100644 --- a/content/nginx-one/staged-configs/edit-staged-config.md +++ b/content/nginx-one/staged-configs/edit-staged-config.md @@ -7,6 +7,7 @@ weight: 200 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial +aliases: /nginx-one/how-to/staged-configs/edit-staged-config/ # Intended for internal catalogue and search, case sensitive: product: NGINX One --- diff --git a/content/nginx-one/staged-configs/import-export-staged-config.md b/content/nginx-one/staged-configs/import-export-staged-config.md index 68993ee99..61b1ee3e5 100644 --- a/content/nginx-one/staged-configs/import-export-staged-config.md +++ b/content/nginx-one/staged-configs/import-export-staged-config.md @@ -7,6 +7,7 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: how-to +aliases: /nginx-one/how-to/staged-configs/import-export-staged-config/ # Intended for internal catalogue and search, case sensitive: # Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit product: NGINX One From db0cc013b235657ae16892d7b5f6f22a4a3bae26 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 28 May 2025 11:14:57 -0700 Subject: [PATCH 17/25] reorg May 28, part 1 --- content/nginx-one/changelog.md | 6 +- content/nginx-one/connect-instances/_index.md | 6 + .../connect-instances/containers/_index.md | 6 + ...ginx-plus-container-images-to-nginx-one.md | 113 ++++++++++++++++++ .../data-plane-keys/_index.md | 6 + .../create-manage-data-plane-keys.md | 68 +++++++++++ .../connect-instances/settings/_index.md | 7 ++ content/nginx-one/getting-started.md | 4 +- content/nginx-one/glossary.md | 2 +- content/nginx-one/nginx-configs/_index.md | 2 +- content/nginx-one/nginx-configs/add-file.md | 7 +- .../nginx-one/nginx-configs/add-instance.md | 7 +- .../certificates/_index.md | 0 .../certificates/manage-certificates.md | 4 +- .../clean-up-unavailable-instances.md | 1 - .../config-sync-groups/_index.md | 0 .../config-sync-groups/add-file-csg.md | 6 +- .../manage-config-sync-groups.md | 5 +- .../view-edit-nginx-configurations.md | 3 +- content/nginx-one/proxy-setup/_index.md | 6 + .../set-up-nginx-proxy-for-nginx-one.md | 101 ++++++++++++++++ content/nginx-one/rbac/_index.md | 2 +- content/nginx-one/rbac/overview.md | 1 - content/nginx-one/rbac/rbac-api.md | 1 - content/nginx-one/rbac/roles.md | 1 - content/nginx-one/staged-configs/_index.md | 2 +- .../staged-configs/add-staged-config.md | 1 - .../staged-configs/api-staged-config.md | 1 - .../staged-configs/edit-staged-config.md | 1 - .../import-export-staged-config.md | 1 - 30 files changed, 336 insertions(+), 35 deletions(-) create mode 100644 content/nginx-one/connect-instances/_index.md create mode 100644 content/nginx-one/connect-instances/containers/_index.md create mode 100644 content/nginx-one/connect-instances/containers/connect-nginx-plus-container-images-to-nginx-one.md create mode 100644 content/nginx-one/connect-instances/data-plane-keys/_index.md create mode 100644 content/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md create mode 100644 content/nginx-one/connect-instances/settings/_index.md rename content/nginx-one/{ => nginx-configs}/certificates/_index.md (100%) rename content/nginx-one/{ => nginx-configs}/certificates/manage-certificates.md (97%) rename content/nginx-one/{ => nginx-configs}/config-sync-groups/_index.md (100%) rename content/nginx-one/{ => nginx-configs}/config-sync-groups/add-file-csg.md (84%) rename content/nginx-one/{ => nginx-configs}/config-sync-groups/manage-config-sync-groups.md (98%) create mode 100644 content/nginx-one/proxy-setup/_index.md create mode 100644 content/nginx-one/proxy-setup/set-up-nginx-proxy-for-nginx-one.md diff --git a/content/nginx-one/changelog.md b/content/nginx-one/changelog.md index a16fd1f5d..ab541049a 100644 --- a/content/nginx-one/changelog.md +++ b/content/nginx-one/changelog.md @@ -84,7 +84,7 @@ You can: For more information, including warnings about risks, see our documentation on how you can: - [Add a file]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}) ### Revert a configuration @@ -108,7 +108,7 @@ From the NGINX One Console you can now: - Ensure that your certificates are current and correct. - Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. -For more information, see the full documentation on how you can [Manage Certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). +For more information, see the full documentation on how you can [Manage Certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}). ## August 22, 2024 @@ -116,7 +116,7 @@ For more information, see the full documentation on how you can [Manage Certific Config Sync Groups are now available in the F5 NGINX One Console. This feature allows you to manage and synchronize NGINX configurations across multiple instances as a single entity, ensuring consistency and simplifying the management of your NGINX environment. -For more information, see the full documentation on [Managing Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}). +For more information, see the full documentation on [Managing Config Sync Groups]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}). ## August 8, 2024 diff --git a/content/nginx-one/connect-instances/_index.md b/content/nginx-one/connect-instances/_index.md new file mode 100644 index 000000000..2bb58215e --- /dev/null +++ b/content/nginx-one/connect-instances/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Connect your instances to the console +weight: 700 +url: /nginx-one/connect-instances/ +--- diff --git a/content/nginx-one/connect-instances/containers/_index.md b/content/nginx-one/connect-instances/containers/_index.md new file mode 100644 index 000000000..c3617fd7d --- /dev/null +++ b/content/nginx-one/connect-instances/containers/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Containers +weight: 300 +url: /nginx-one/how-to/containers +--- diff --git a/content/nginx-one/connect-instances/containers/connect-nginx-plus-container-images-to-nginx-one.md b/content/nginx-one/connect-instances/containers/connect-nginx-plus-container-images-to-nginx-one.md new file mode 100644 index 000000000..6033cff66 --- /dev/null +++ b/content/nginx-one/connect-instances/containers/connect-nginx-plus-container-images-to-nginx-one.md @@ -0,0 +1,113 @@ +--- +description: '' +docs: null +title: Connect NGINX Plus container images to NGINX One +toc: true +weight: 400 +type: +- how-to +--- + +## Overview + +This guide explains how to set up an F5 NGINX Plus Docker container with NGINX Agent and connect it to the NGINX One Console. + +--- + +## Before you start + +Before you start, make sure you have: + +- A valid JSON Web Token (JWT) for your NGINX subscription. +- [A data plane key from NGINX One]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}). +- Docker installed and running on your system. + +#### Download your JWT license from MyF5 + +{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} + +--- + +## Process for private registry + +### Log in to the NGINX private registry + +Use your JWT to log in to the NGINX private registry. Replace `YOUR_JWT_HERE` with your JWT. + +```sh +sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none +``` + +{{< include "security/jwt-password-note.md" >}} + +### Pull the NGINX Plus image + +Pull the NGINX Plus image from the private registry. Replace `VERSION_TAG` with the desired version, such as `alpine`, `debian`, or `ubi`. + +```sh +sudo docker pull private-registry.nginx.com/nginx-plus/agent:VERSION_TAG +``` + +You must specify a version tag. The `latest` tag is not supported. Learn more in the [Deploying NGINX and NGINX Plus on Docker]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}) guide. + +
    + +{{}} +To pull the `debian` image: + +```sh +sudo docker pull private-registry.nginx.com/nginx-plus/agent:debian +``` +{{}} + +### Start the NGINX Plus container + +Start the Docker container to connect it to NGINX One. Replace `YOUR_NGINX_ONE_DATA_PLANE_KEY_HERE` with your data plane key and `VERSION_TAG` with the version tag you pulled. + +**For NGINX Plus R33 or later**: + +- Use the `NGINX_LICENSE_JWT` variable to pass your JWT license. Replace `YOUR_JWT_HERE` with your JWT. + +For more details, see [About subscription licenses]({{< ref "solutions/about-subscription-licenses.md" >}}). + +```sh +sudo docker run \ +--env=NGINX_LICENSE_JWT="YOUR_JWT_HERE" \ +--env=NGINX_AGENT_SERVER_GRPCPORT=443 \ +--env=NGINX_AGENT_SERVER_HOST=agent.connect.nginx.com \ +--env=NGINX_AGENT_SERVER_TOKEN="YOUR_NGINX_ONE_DATA_PLANE_KEY_HERE" \ +--env=NGINX_AGENT_TLS_ENABLE=true \ +--restart=always \ +--runtime=runc \ +-d private-registry.nginx.com/nginx-plus/agent: +``` + +
    + +{{}} +To start the container with the `debian` image: + +```sh +sudo docker run \ +--env=NGINX_LICENSE_JWT="YOUR_JWT_HERE" \ +--env=NGINX_AGENT_SERVER_GRPCPORT=443 \ +--env=NGINX_AGENT_SERVER_HOST=agent.connect.nginx.com \ +--env=NGINX_AGENT_SERVER_TOKEN="YOUR_NGINX_ONE_DATA_PLANE_KEY_HERE" \ +--env=NGINX_AGENT_TLS_ENABLE=true \ +--restart=always \ +--runtime=runc \ +-d private-registry.nginx.com/nginx-plus/agent:debian +``` + +{{}} + +--- + +## References + +For more details, see: + +- [Deploying NGINX and NGINX Plus on Docker](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/) +- [Full List of Agent Environment Variables](https://docs.nginx.com/nginx-agent/configuration/configuration-overview/#nginx-agent-environment-variables) +- [NGINX One Data Plane Keys](https://docs.nginx.com/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys/) +- [My F5 Knowledge Article](https://my.f5.com/manage/s/article/K000090257) diff --git a/content/nginx-one/connect-instances/data-plane-keys/_index.md b/content/nginx-one/connect-instances/data-plane-keys/_index.md new file mode 100644 index 000000000..0aa1ba7bf --- /dev/null +++ b/content/nginx-one/connect-instances/data-plane-keys/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Data plane keys +weight: 100 +url: /nginx-one/how-to/data-plane-keys +--- diff --git a/content/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md b/content/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md new file mode 100644 index 000000000..9ac000860 --- /dev/null +++ b/content/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md @@ -0,0 +1,68 @@ +--- +description: '' +docs: DOCS-1395 +title: Create and manage data plane keys +toc: true +weight: 100 +type: +- how-to +--- + + + +## About data plane keys + +Data plane keys are required for registering NGINX instances with the F5 NGINX One Console. These keys serve as secure tokens, ensuring that only authorized NGINX instances can connect to and communicate with NGINX One. You have the flexibility to reuse a key with multiple instances, or to create a unique key for each instance. + +{{}} +Data plane keys are displayed only once and cannot be retrieved later. Be sure to copy and store this key securely. + +Data plane keys expire after one year. You can change this expiration date later by editing the key. + +Revoking a data plane key disconnects all instances that were registered with that key. +{{}} + +## Create a new data plane key + +To create a new key for connecting your NGINX instances to NGINX One, follow these steps: + +1. On the left menu, select **Data Plane Keys**. +2. Select **Add Data Plane Key**. +3. Enter a name for your new key. Optionally, you can set an expiration date for the key. If you don't set a date, the key will automatically expire one year from today. The longest duration for a key is one year. You can change this expiration date later by editing the key. +4. Select **Generate**. +5. A confirmation screen will show your new data plane key. Be sure to copy and store this key securely. It is displayed *only once* and cannot be retrieved later. +6. Select **Close** to complete the process. + +## Change the expiration date {#change-expiration-date} + +To change the expiration date of a data plane key, follow these steps before the key expires. You cannot update the expiration date after the key has expired. + +1. On the left menu, select **Data Plane Keys**. +2. Find the key you want to edit in the list. +3. Next to the key name, in the **Actions** column, select the ellipsis (three dots) and then select **Edit Key**. +4. Set a new expiration date for the key. The longest duration for a key is one year. +5. Select **Save**. + +## Revoke a data plane key {#revoke-data-plane-key} + +If you need to deactivate a data plane key before its expiration date, follow these steps. Once revoked, the key will no longer connect any NGINX instances to NGINX One. The key will still be visible in the console until you delete it. + +1. On the left menu, select **Data Plane Keys**. +2. Find the key you want to revoke in the list. +3. Next to the key name, in the **Actions** column, select the ellipsis (three dots) and then select **Revoke**. +4. A confirmation dialog will appear. Select **Revoke** to confirm. + + +## Delete a data plane key + +Before you can delete a key, it must be expired or revoked. You can revoke a key either through the NGINX One Console, as explained above, or by using the REST API. Once deleted, all information about the data plane key is permanently removed. + +1. On the left menu, select **Data Plane Keys**. +2. Find the key you want to revoke in the list of expired or revoked keys. +3. Next to the key name, select the check box. You can select multiple keys at the same time. +4. Select **Delete selected**. diff --git a/content/nginx-one/connect-instances/settings/_index.md b/content/nginx-one/connect-instances/settings/_index.md new file mode 100644 index 000000000..cdbbc1636 --- /dev/null +++ b/content/nginx-one/connect-instances/settings/_index.md @@ -0,0 +1,7 @@ +--- +description: +title: Settings +weight: 500 +url: /nginx-one/how-to/settings +draft: true +--- diff --git a/content/nginx-one/getting-started.md b/content/nginx-one/getting-started.md index 9e3a0e8e5..245196a1e 100644 --- a/content/nginx-one/getting-started.md +++ b/content/nginx-one/getting-started.md @@ -43,9 +43,9 @@ To generate a data plane key: {{}} Data plane keys are displayed only once and cannot be retrieved later. Be sure to copy and store this key securely. -Data plane keys expire after one year. You can change this expiration date later by [editing the key]({{< ref "nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md#change-expiration-date" >}}). +Data plane keys expire after one year. You can change this expiration date later by [editing the key]({{< ref "nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md#change-expiration-date" >}}). -[Revoking a data plane key]({{< ref "nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md#revoke-data-plane-key" >}}) disconnects all instances that were registered with that key. +[Revoking a data plane key]({{< ref "nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md#revoke-data-plane-key" >}}) disconnects all instances that were registered with that key. {{}} diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index 187c8585d..4477da2e8 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -14,7 +14,7 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed {{}} | Term | Definition | |-------------|-------------| -| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | +| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | | **Data Plane** | The data plane is the part of a network architecture that carries user traffic. It handles tasks like forwarding data packets between devices and managing network communication. In the context of NGINX, the data plane is responsible for tasks such as load balancing, caching, and serving web content. | | **Instance** | An instance is an individual system with NGINX installed. You can group the instances of your choice in a Config Sync Group. When you add an instance to NGINX One, you need to use a data plane key. | | **Namespace** | In F5 Distributed Cloud, a namespace groups a tenant’s configuration objects, similar to administrative domains. Every object in a namespace must have a unique name, and each namespace must be unique to its tenant. This setup ensures isolation, preventing cross-referencing of objects between namespaces. You'll see the namespace in the NGINX One Console URL as `/namespaces//` | diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md index 45fb17e97..d4a987147 100644 --- a/content/nginx-one/nginx-configs/_index.md +++ b/content/nginx-one/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Add and manage your NGINX instances +title: Manage your NGINX instances weight: 300 url: /nginx-one/nginx-configs --- diff --git a/content/nginx-one/nginx-configs/add-file.md b/content/nginx-one/nginx-configs/add-file.md index 60f355c77..ffbe71922 100644 --- a/content/nginx-one/nginx-configs/add-file.md +++ b/content/nginx-one/nginx-configs/add-file.md @@ -3,7 +3,6 @@ docs: null title: Add a file to an instance toc: true weight: 400 -aliases: /nginx-one/how-to/nginx-configs/add-file/ type: - how-to --- @@ -22,7 +21,7 @@ Before you add files in your configuration, ensure: ## Important considerations If your instance is a member of a Config Sync Group, changes that you make may be synchronized to other instances in that group. -For more information, see how you can [Manage Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}). +For more information, see how you can [Manage Config Sync Groups]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}). ## Add a file @@ -63,6 +62,6 @@ Enter the name of the desired configuration file, such as `abc.conf` and select ## See also -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}) - [Add an NGINX instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md index 57ecf5fd0..328d93724 100644 --- a/content/nginx-one/nginx-configs/add-instance.md +++ b/content/nginx-one/nginx-configs/add-instance.md @@ -3,7 +3,6 @@ description: '' title: Add an NGINX instance toc: true weight: 100 -aliases: /nginx-one/how-to/nginx-configs/add-instance/ type: - how-to --- @@ -20,9 +19,9 @@ Before you add an instance to NGINX One Console, ensure: - You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. - You have [configured instances of NGINX]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) that you want to manage through NGINX One Console. - You have or are ready to configure a [data plane key]({{< ref "/nginx-one/getting-started.md#generate-data-plane-key" >}}). -- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). +- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}). -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} +{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} ## Add an instance @@ -54,5 +53,5 @@ Once you've completed the process, NGINX One reassigns this as a managed certifi ## Add an instance to a Config Sync Group -When you [Manage Config Sync Group membership]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. +When you [Manage Config Sync Group membership]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/certificates/_index.md b/content/nginx-one/nginx-configs/certificates/_index.md similarity index 100% rename from content/nginx-one/certificates/_index.md rename to content/nginx-one/nginx-configs/certificates/_index.md diff --git a/content/nginx-one/certificates/manage-certificates.md b/content/nginx-one/nginx-configs/certificates/manage-certificates.md similarity index 97% rename from content/nginx-one/certificates/manage-certificates.md rename to content/nginx-one/nginx-configs/certificates/manage-certificates.md index c34c05eee..3690eb793 100644 --- a/content/nginx-one/certificates/manage-certificates.md +++ b/content/nginx-one/nginx-configs/certificates/manage-certificates.md @@ -35,7 +35,7 @@ From the NGINX One Console you can: You can manage the certificates for: - [Unique instances]({{< ref "/nginx-one/nginx-configs/add-file.md#new-ssl-certificate-or-ca-bundle" >}}) -- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) +- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) {{< tip >}} @@ -193,6 +193,6 @@ To convert these cerificates to managed, start with the Certificates menu, and s ## See also -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}) - [Add an instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) - [Add a file in a configuration]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) diff --git a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md index 5bb33b4d6..6a119617d 100644 --- a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md +++ b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md @@ -4,7 +4,6 @@ docs: null title: Clean up unavailable NGINX instances toc: true weight: 200 -aliases: /nginx-one/how-to/nginx-configs/clean-up-unavailable-instances/ type: - how-to --- diff --git a/content/nginx-one/config-sync-groups/_index.md b/content/nginx-one/nginx-configs/config-sync-groups/_index.md similarity index 100% rename from content/nginx-one/config-sync-groups/_index.md rename to content/nginx-one/nginx-configs/config-sync-groups/_index.md diff --git a/content/nginx-one/config-sync-groups/add-file-csg.md b/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md similarity index 84% rename from content/nginx-one/config-sync-groups/add-file-csg.md rename to content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md index ee92e6fd0..4ab2f9e18 100644 --- a/content/nginx-one/config-sync-groups/add-file-csg.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md @@ -59,10 +59,10 @@ Enter the name of the desired configuration file, such as `abc.conf` and select ### Existing SSL Certificate or CA Bundle {{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). +With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). ## See also -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}) - [Add an NGINX instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md similarity index 98% rename from content/nginx-one/config-sync-groups/manage-config-sync-groups.md rename to content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md index 6ffcf4d06..6f21d33fd 100644 --- a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -3,7 +3,6 @@ docs: null title: Manage Config Sync Groups toc: true weight: 300 -aliases: /nginx-one/how-to/config-sync-groups/manage-config-sync-groups/ type: - how-to --- @@ -183,7 +182,7 @@ When adding a new NGINX instance that is not yet registered with NGINX One, you Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. -For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). +For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). {{}} @@ -258,5 +257,5 @@ Monitor the **Config Sync Status** column. It can help you ensure that your conf ## See also -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}) - [Add an NGINX instance]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}) diff --git a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md index a5460d019..dcc6ab881 100644 --- a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md +++ b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md @@ -7,7 +7,6 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial -aliases: /nginx-one/how-to/nginx-configs/view-edit-nginx-configurations/ # Intended for internal catalogue and search, case sensitive: product: NGINX One --- @@ -29,4 +28,4 @@ Alternatively, you can select **Save Changes As**. In the window that appears, y ## See also -- [Manage Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}) +- [Manage Config Sync Groups]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}) diff --git a/content/nginx-one/proxy-setup/_index.md b/content/nginx-one/proxy-setup/_index.md new file mode 100644 index 000000000..16f858cc2 --- /dev/null +++ b/content/nginx-one/proxy-setup/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Proxy setup +weight: 600 +url: /nginx-one/how-to/settings/nginx-as-proxy +--- diff --git a/content/nginx-one/proxy-setup/set-up-nginx-proxy-for-nginx-one.md b/content/nginx-one/proxy-setup/set-up-nginx-proxy-for-nginx-one.md new file mode 100644 index 000000000..7b10755cc --- /dev/null +++ b/content/nginx-one/proxy-setup/set-up-nginx-proxy-for-nginx-one.md @@ -0,0 +1,101 @@ +--- +description: '' +docs: null +title: Set up NGINX as a proxy for NGINX One +toc: true +weight: 300 +type: +- how-to +--- + +## Overview + +This guide explains how to set up NGINX as a proxy for other NGINX instances to connect to the F5 NGINX One Console. By routing these connections through one proxy, you can minimize the number of external connections to NGINX One from your network. + +--- + +## Before you start + +- [Install NGINX Open Source or NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/" >}}). +- [Get a Data Plane Key from NGINX One]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}). + +--- + +## Configure an NGINX instance to act as a proxy + +In this step, we'll configure an NGINX instance to act as a proxy server for NGINX One. + +1. Open a secure connection to your instance using SSH and log in. +2. Open the NGINX configuration file (**/etc/nginx/nginx.conf**) with a text editor. +3. Add the following configuration to define the upstream server, set up logging, and configure the proxy server: + + ```nginx + stream { + upstream stream_backend { + zone tcp_servers 64k; + server agent.connect.nginx.com:443; + } + + log_format basic '$remote_addr [$time_local] ' + '$protocol $status $bytes_sent $bytes_received ' + '$session_time "$upstream_addr" ' + '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"'; + + access_log /var/log/nginx/nginx1_access.log basic; + error_log /var/log/nginx/nginx1_error.log; + + server { + listen 5000; + status_zone tcp_server; + proxy_pass stream_backend; + proxy_next_upstream on; + } + } + ``` + +4. Reload NGINX to apply the changes: + + ```sh + sudo nginx -s reload + ``` + +--- + +## Configure NGINX Agent to use the proxy + +To set up your other NGINX instances to use the proxy instance to connect to NGINX One, update the NGINX Agent configuration on those instances to use the proxy NGINX instance's IP address. See the example NGINX Agent configuration below. + +1. Open a secure connection to your instance using SSH and log in. +2. Open the NGINX Agent configuration file (**/etc/nginx-agent/nginx-agent.conf**) with a text editor. +3. Add the following configuration. Replace `YOUR_DATA_PLANE_KEY_HERE` with your actual data plane key and `YOUR_PROXY_IP_ADDRESS_HERE` with the IP address of the NGINX proxy instance. + + ```yaml + server: + # Replace YOUR_DATA_PLANE_KEY_HERE with your NGINX One Data Plane Key. + token: "YOUR_DATA_PLANE_KEY_HERE" + # Replace YOUR_PROXY_IP_ADDRESS_HERE with the IP address of the NGINX proxy instance. + host: YOUR_PROXY_IP_ADDRESS_HERE + grpcPort: 5000 + command: agent.connect.nginx.com + metrics: agent.connect.nginx.com + tls: + enable: true + skip_verify: false + ``` + +4. Restart NGINX Agent: + + ``` sh + sudo systemctl restart nginx-agent + ``` + +--- + +## References + +For more information, refer to the following resources: + +- [Install NGINX and NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/" >}}) +- [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [NGINX Agent Installation and upgrade](https://docs.nginx.com/nginx-agent/installation-upgrade/) +- [NGINX Agent Configuration](https://docs.nginx.com/nginx-agent/configuration/) diff --git a/content/nginx-one/rbac/_index.md b/content/nginx-one/rbac/_index.md index 6544b2494..5cc3d036e 100644 --- a/content/nginx-one/rbac/_index.md +++ b/content/nginx-one/rbac/_index.md @@ -1,5 +1,5 @@ --- -title: Organize administrators with RBAC +title: Organize users with RBAC description: weight: 500 url: /nginx-one/rbac diff --git a/content/nginx-one/rbac/overview.md b/content/nginx-one/rbac/overview.md index 91ca52209..2bcdfc17b 100644 --- a/content/nginx-one/rbac/overview.md +++ b/content/nginx-one/rbac/overview.md @@ -4,7 +4,6 @@ weight: 400 toc: true type: reference product: NGINX One -aliases: /nginx-one/how-to/rbac/overview/ docs: DOCS-000 --- diff --git a/content/nginx-one/rbac/rbac-api.md b/content/nginx-one/rbac/rbac-api.md index 300009370..11e90cfc3 100644 --- a/content/nginx-one/rbac/rbac-api.md +++ b/content/nginx-one/rbac/rbac-api.md @@ -4,7 +4,6 @@ weight: 500 toc: true type: reference product: NGINX One -aliases: /nginx-one/how-to/rbac/rbac-api/ docs: DOCS-000 --- diff --git a/content/nginx-one/rbac/roles.md b/content/nginx-one/rbac/roles.md index a73916f1d..e2d33a15b 100644 --- a/content/nginx-one/rbac/roles.md +++ b/content/nginx-one/rbac/roles.md @@ -4,7 +4,6 @@ weight: 500 toc: true type: reference product: NGINX One -aliases: /nginx-one/how-to/rbac/roles/ docs: DOCS-000 --- diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md index 46d1b93d3..a16a58b7d 100644 --- a/content/nginx-one/staged-configs/_index.md +++ b/content/nginx-one/staged-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Draft new instances (Staged Configs) +title: Draft new configurations weight: 200 url: /nginx-one/how-to/staged-configs --- diff --git a/content/nginx-one/staged-configs/add-staged-config.md b/content/nginx-one/staged-configs/add-staged-config.md index 3a9c2e71d..94007c407 100644 --- a/content/nginx-one/staged-configs/add-staged-config.md +++ b/content/nginx-one/staged-configs/add-staged-config.md @@ -7,7 +7,6 @@ weight: 100 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial -aliases: /nginx-one/how-to/staged-configs/add-staged-config/ # Intended for internal catalogue and search, case sensitive: # Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit product: diff --git a/content/nginx-one/staged-configs/api-staged-config.md b/content/nginx-one/staged-configs/api-staged-config.md index f31ec8684..8eadfdb55 100644 --- a/content/nginx-one/staged-configs/api-staged-config.md +++ b/content/nginx-one/staged-configs/api-staged-config.md @@ -7,7 +7,6 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial -aliases: /nginx-one/how-to/staged-configs/api-staged-config/ # Intended for internal catalogue and search, case sensitive: product: NGINX One --- diff --git a/content/nginx-one/staged-configs/edit-staged-config.md b/content/nginx-one/staged-configs/edit-staged-config.md index 45972645d..8f101a0fd 100644 --- a/content/nginx-one/staged-configs/edit-staged-config.md +++ b/content/nginx-one/staged-configs/edit-staged-config.md @@ -7,7 +7,6 @@ weight: 200 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: tutorial -aliases: /nginx-one/how-to/staged-configs/edit-staged-config/ # Intended for internal catalogue and search, case sensitive: product: NGINX One --- diff --git a/content/nginx-one/staged-configs/import-export-staged-config.md b/content/nginx-one/staged-configs/import-export-staged-config.md index 61b1ee3e5..68993ee99 100644 --- a/content/nginx-one/staged-configs/import-export-staged-config.md +++ b/content/nginx-one/staged-configs/import-export-staged-config.md @@ -7,7 +7,6 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this type: how-to -aliases: /nginx-one/how-to/staged-configs/import-export-staged-config/ # Intended for internal catalogue and search, case sensitive: # Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit product: NGINX One From 5b3d5df5e82d6848cea0cd5cf802a7facc444c03 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 28 May 2025 11:56:58 -0700 Subject: [PATCH 18/25] more edits, may 28 --- .../nginx-one/add-file/existing-ssl-bundle.md | 2 +- .../connect-instances/containers/_index.md | 4 +-- .../data-plane-keys/_index.md | 4 +-- .../proxy-setup/_index.md | 2 +- .../set-up-nginx-proxy-for-nginx-one.md | 0 .../connect-instances/settings/_index.md | 2 +- .../nginx-configs/certificates/_index.md | 2 +- content/nginx-one/staged-configs/_index.md | 2 +- layouts/partials/list-main.html | 30 +++++-------------- 9 files changed, 17 insertions(+), 31 deletions(-) rename content/nginx-one/{ => connect-instances}/proxy-setup/_index.md (51%) rename content/nginx-one/{ => connect-instances}/proxy-setup/set-up-nginx-proxy-for-nginx-one.md (100%) diff --git a/content/includes/nginx-one/add-file/existing-ssl-bundle.md b/content/includes/nginx-one/add-file/existing-ssl-bundle.md index 250669d3e..5d13d28b2 100644 --- a/content/includes/nginx-one/add-file/existing-ssl-bundle.md +++ b/content/includes/nginx-one/add-file/existing-ssl-bundle.md @@ -2,7 +2,7 @@ docs: --- -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). +With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). In the **Choose Certificate** drop-down, select the managed certificate of your choice, and select **Add**. You can then: 1. Review details of the certificate. The next steps depend on whether the certificate is a CA bundle or a certificate / key pair. diff --git a/content/nginx-one/connect-instances/containers/_index.md b/content/nginx-one/connect-instances/containers/_index.md index c3617fd7d..2f6597002 100644 --- a/content/nginx-one/connect-instances/containers/_index.md +++ b/content/nginx-one/connect-instances/containers/_index.md @@ -1,6 +1,6 @@ --- description: -title: Containers +title: Connect your containers weight: 300 -url: /nginx-one/how-to/containers +url: /nginx-one/connect-instances/containers --- diff --git a/content/nginx-one/connect-instances/data-plane-keys/_index.md b/content/nginx-one/connect-instances/data-plane-keys/_index.md index 0aa1ba7bf..38833fc99 100644 --- a/content/nginx-one/connect-instances/data-plane-keys/_index.md +++ b/content/nginx-one/connect-instances/data-plane-keys/_index.md @@ -1,6 +1,6 @@ --- description: -title: Data plane keys +title: Set up data plane keys weight: 100 -url: /nginx-one/how-to/data-plane-keys +url: /nginx-one/connect-instances/data-plane-keys --- diff --git a/content/nginx-one/proxy-setup/_index.md b/content/nginx-one/connect-instances/proxy-setup/_index.md similarity index 51% rename from content/nginx-one/proxy-setup/_index.md rename to content/nginx-one/connect-instances/proxy-setup/_index.md index 16f858cc2..677900c5d 100644 --- a/content/nginx-one/proxy-setup/_index.md +++ b/content/nginx-one/connect-instances/proxy-setup/_index.md @@ -2,5 +2,5 @@ description: title: Proxy setup weight: 600 -url: /nginx-one/how-to/settings/nginx-as-proxy +url: /nginx-one/connect-instances/proxy-setup --- diff --git a/content/nginx-one/proxy-setup/set-up-nginx-proxy-for-nginx-one.md b/content/nginx-one/connect-instances/proxy-setup/set-up-nginx-proxy-for-nginx-one.md similarity index 100% rename from content/nginx-one/proxy-setup/set-up-nginx-proxy-for-nginx-one.md rename to content/nginx-one/connect-instances/proxy-setup/set-up-nginx-proxy-for-nginx-one.md diff --git a/content/nginx-one/connect-instances/settings/_index.md b/content/nginx-one/connect-instances/settings/_index.md index cdbbc1636..3bdb5095b 100644 --- a/content/nginx-one/connect-instances/settings/_index.md +++ b/content/nginx-one/connect-instances/settings/_index.md @@ -2,6 +2,6 @@ description: title: Settings weight: 500 -url: /nginx-one/how-to/settings +url: /nginx-one/connect-instances/settings draft: true --- diff --git a/content/nginx-one/nginx-configs/certificates/_index.md b/content/nginx-one/nginx-configs/certificates/_index.md index 0ea28d683..f4e0962c4 100644 --- a/content/nginx-one/nginx-configs/certificates/_index.md +++ b/content/nginx-one/nginx-configs/certificates/_index.md @@ -2,5 +2,5 @@ description: title: Monitor your certificates weight: 400 -url: /nginx-one/certificates +url: /nginx-one/nginx-configs/certificates --- diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md index a16a58b7d..d041035c2 100644 --- a/content/nginx-one/staged-configs/_index.md +++ b/content/nginx-one/staged-configs/_index.md @@ -2,5 +2,5 @@ description: title: Draft new configurations weight: 200 -url: /nginx-one/how-to/staged-configs +url: /nginx-one/staged-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 15be826f8..f486bff67 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -37,40 +37,26 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}}

    See benefits from the NGINX One Console

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new instances (Staged Configs)")}} -

    Work on new instances with Staged Configurations

    + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new configurations")}} +

    Work with Staged Configurations

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Add and manage your NGINX instances")}} -

    Monitor all of your deployments

    + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX instances")}} +

    Monitor and maintain your deployments

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} -

    Update your SSL certs before they expire

    - {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize administrators with RBAC")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize users with RBAC")}}

    Assign responsibilities with role-based access control

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}} -

    Simplify changes with Config Sync Groups

    - {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Automate with the NGINX One API")}}

    Manage your NGINX fleet over REST

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}} -

    Terms unique to NGINX One Console

    +

    Learn terms unique to NGINX One Console

    {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "How-to guides") }} -
      - {{ range .Pages }} - {{ if eq .Kind "section" }} - {{ range .Pages }} -
    • {{ .Title }}
      • - {{ end }} - {{ end }} - {{ end }} -
    + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Connect your instances to the console") }} +

    Work with data plane keys, containers, and proxy servers

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "API")}}

    These are API docs

    From 338eb92c7ab9fd55383a913a0066b19d59326388 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 28 May 2025 14:01:28 -0700 Subject: [PATCH 19/25] May 28 updates part 3 --- .../monitoring/n1c-dashboard-overview.md | 39 ++++++++++++++++ content/nginx-one/getting-started.md | 45 ++++++------------- content/nginx-one/metrics/_index.md | 6 +++ content/nginx-one/metrics/enable-metrics.md | 23 ++++++++++ content/nginx-one/metrics/review-metrics.md | 23 ++++++++++ layouts/partials/list-main.html | 3 ++ 6 files changed, 107 insertions(+), 32 deletions(-) create mode 100644 content/includes/use-cases/monitoring/n1c-dashboard-overview.md create mode 100644 content/nginx-one/metrics/_index.md create mode 100644 content/nginx-one/metrics/enable-metrics.md create mode 100644 content/nginx-one/metrics/review-metrics.md diff --git a/content/includes/use-cases/monitoring/n1c-dashboard-overview.md b/content/includes/use-cases/monitoring/n1c-dashboard-overview.md new file mode 100644 index 000000000..3018b83d8 --- /dev/null +++ b/content/includes/use-cases/monitoring/n1c-dashboard-overview.md @@ -0,0 +1,39 @@ +--- +docs: +files: + - content/nginx-one/metrics/enable-metrics.md + - content/nginx-one/getting-started.md +--- + +Navigating the dashboard: + +- **Drill down into specifics**: For in-depth information on a specific metric, like expiring certificates, click on the relevant link in the metric's card to go to a detailed overview page. +- **Refine metric timeframe**: Metrics show the last hour's data by default. To view data from a different period, select the time interval you want from the drop-down menu. + + +{{< img src="nginx-one/images/nginx-one-dashboard.png">}} + + +{{}} +**NGINX One dashboard metrics** +| Metric | Description | Details | +|---|---|---| +| **Instance availability** | Understand the operational status of your NGINX instances. | - **Online**: The NGINX instance is actively connected and functioning properly.
    - **Offline**: NGINX Agent is connected but the NGINX instance isn't running, isn't installed, or can't communicate with NGINX Agent.
    - **Unavailable**: The connection between NGINX Agent and NGINX One has been lost or the instance has been decommissioned.
    - **Unknown**: The current state can't be determined at the moment. | +| **NGINX versions by instance** | See which NGINX versions are in use across your instances. | | +| **Operating systems** | Find out which operating systems your instances are running on. | | +| **Certificates** | Monitor the status of your SSL certificates to know which are expiring soon and which are still valid. | | +| **Config recommendations** | Get configuration recommendations to optimize your instances' settings. | | +| **CVEs (Common Vulnerabilities and Exposures)** | Evaluate the severity and number of potential security threats in your instances. | - **Major**: Indicates a high-severity threat that needs immediate attention.
    - **Medium**: Implies a moderate threat level.
    - **Minor** and **Low**: Represent less critical issues that still require monitoring.
    - **Other**: Encompasses any threats that don't fit the standard categories. | +| **CPU utilization** | Track CPU usage trends and pinpoint instances with high CPU demand. | | +| **Memory utilization** | Watch memory usage patterns to identify instances using significant memory. | | +| **Disk space utilization** | Monitor how much disk space your instances are using and identify those nearing capacity. | | +| **Unsuccessful response codes** | Look for instances with a high number of HTTP server errors and investigate their error codes. | | +| **Top network usage** | Review the network usage and bandwidth consumption of your instances. | | + +{{    }} + + + + + + diff --git a/content/nginx-one/getting-started.md b/content/nginx-one/getting-started.md index 245196a1e..920f3a526 100644 --- a/content/nginx-one/getting-started.md +++ b/content/nginx-one/getting-started.md @@ -24,12 +24,10 @@ To get started using NGINX One, enable the service on F5 Distributed Cloud. Next, add your NGINX instances to NGINX One. You'll need to create a data plane key and then install NGINX Agent on each instance you want to monitor. -### Add an instance - -Depending on whether this is your first time using NGINX One Console or you've used it before, follow the appropriate steps to add an instance: +The following instructions include minimal information, sufficient to "get started." See the following links for detailed instructions: -- **For first-time users:** On the welcome screen, select **Add Instance**. -- **For returning users:** If you've added instances previously and want to add more, select **Instances** on the left menu, then select **Add Instance**. +- [Create and manage data plane keys]({{< ref "nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [Add an NGINX instance]({{< ref "nginx-one/nginx-configs/add-instance.md" >}}) ### Generate a data plane key {#generate-data-plane-key} @@ -48,6 +46,13 @@ Data plane keys expire after one year. You can change this expiration date later [Revoking a data plane key]({{< ref "nginx-one/connect-instances/data-plane-keys/create-manage-data-plane-keys.md#revoke-data-plane-key" >}}) disconnects all instances that were registered with that key. {{}} +### Add an instance + +Depending on whether this is your first time using NGINX One Console or you've used it before, follow the appropriate steps to add an instance: + +- **For first-time users:** On the welcome screen, select **Add Instance**. +- **For returning users:** If you've added instances previously and want to add more, select **Instances** on the left menu, then select **Add Instance**. + ### Install NGINX Agent @@ -134,37 +139,11 @@ If you followed the [Installation and upgrade](https://docs.nginx.com/nginx-agen --- -## Enable NGINX metrics reporting - The NGINX One Console dashboard relies on APIs for NGINX Plus and NGINX Open Source Stub Status to report traffic and system metrics. The following sections show you how to enable those metrics. ### Enable NGINX Plus API - -To collect metrics for NGINX Plus, add the following to your NGINX Plus configuration file: - -```nginx -# Enable the /api/ location with appropriate access control -# to use the NGINX Plus API. -# -location /api/ { - api write=on; - allow 127.0.0.1; - deny all; -} -``` - -This configuration: - -- Enables the NGINX Plus API. -- Allows requests only from `127.0.0.1` (localhost). -- Blocks all other requests for security. - -After saving the changes, reload NGINX to apply the new configuration: - -```shell -nginx -s reload -``` +{{< include "/use-cases/monitoring/enable-nginx-plus-api.md" >}} ### Enable NGINX Open Source Stub Status API @@ -183,6 +162,8 @@ After connecting your NGINX instances to NGINX One, you can monitor their perfor ### Overview of the NGINX One dashboard +{{< include "/use-cases/monitoring/n1c-dashboard-overview.md" >}} + Navigating the dashboard: - **Drill down into specifics**: For in-depth information on a specific metric, like expiring certificates, click on the relevant link in the metric's card to go to a detailed overview page. diff --git a/content/nginx-one/metrics/_index.md b/content/nginx-one/metrics/_index.md new file mode 100644 index 000000000..767a578d9 --- /dev/null +++ b/content/nginx-one/metrics/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Set up metrics +weight: 300 +url: /nginx-one/metrics/ +--- diff --git a/content/nginx-one/metrics/enable-metrics.md b/content/nginx-one/metrics/enable-metrics.md new file mode 100644 index 000000000..653effc19 --- /dev/null +++ b/content/nginx-one/metrics/enable-metrics.md @@ -0,0 +1,23 @@ +--- +# We use sentence case and present imperative tone +title: "Enable metrics" +# Weights are assigned in increments of 100: determines sorting order +weight: i00 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +nd-content-type: tutorial +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +nd-product: NGINX One +--- + +The NGINX One Console dashboard relies on APIs for NGINX Plus and NGINX Open Source Stub Status to report traffic and system metrics. The following sections show you how to enable those metrics. + +### Enable NGINX Plus API + +{{< include "/use-cases/monitoring/enable-nginx-plus-api.md" >}} + +### Enable NGINX Open Source Stub Status API + +{{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} diff --git a/content/nginx-one/metrics/review-metrics.md b/content/nginx-one/metrics/review-metrics.md new file mode 100644 index 000000000..eb9184b75 --- /dev/null +++ b/content/nginx-one/metrics/review-metrics.md @@ -0,0 +1,23 @@ +--- +# We use sentence case and present imperative tone +title: "Review metrics on the NGINX One dashboard" +# Weights are assigned in increments of 100: determines sorting order +weight: i00 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +nd-content-type: how-to +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +nd-product: NGINX One +--- + +After connecting your NGINX instances to NGINX One, you can monitor their performance and health. The NGINX One dashboard is designed for this purpose, offering an easy-to-use interface. + +### Log in to NGINX One + +1. Log in to [F5 Distributed Console](https://www.f5.com/cloud/products/distributed-cloud-console). +1. Select **NGINX One > Visit Service**. + +{{< include "/use-cases/monitoring/n1c-dashboard-overview.md" >}} + diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index f486bff67..1354f65d5 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -58,6 +58,9 @@

    {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Connect your instances to the console") }}

    Work with data plane keys, containers, and proxy servers

    {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up metrics") }} +

    Review your deployments in a dashboard

    + {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "API")}}

    These are API docs

      From 6b71c88073ac4604b25245cedd70f29ef7acf069 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 28 May 2025 14:14:36 -0700 Subject: [PATCH 20/25] typos --- content/includes/nginx-one/add-file/existing-ssl-bundle.md | 2 +- .../nginx-one/nginx-configs/config-sync-groups/add-file-csg.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/includes/nginx-one/add-file/existing-ssl-bundle.md b/content/includes/nginx-one/add-file/existing-ssl-bundle.md index 5d13d28b2..9afcf9137 100644 --- a/content/includes/nginx-one/add-file/existing-ssl-bundle.md +++ b/content/includes/nginx-one/add-file/existing-ssl-bundle.md @@ -2,7 +2,7 @@ docs: --- -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). +With this option, you can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). In the **Choose Certificate** drop-down, select the managed certificate of your choice, and select **Add**. You can then: 1. Review details of the certificate. The next steps depend on whether the certificate is a CA bundle or a certificate / key pair. diff --git a/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md b/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md index 4ab2f9e18..1e3cc60e4 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md @@ -59,7 +59,7 @@ Enter the name of the desired configuration file, such as `abc.conf` and select ### Existing SSL Certificate or CA Bundle {{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). +With this option, you can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). ## See also From 58bed48ab9c5f4aa505b16eb5ee7f6446f8e7bb4 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 29 May 2025 07:04:02 -0700 Subject: [PATCH 21/25] reorder sections --- content/nginx-one/api/_index.md | 2 +- content/nginx-one/connect-instances/_index.md | 2 +- content/nginx-one/glossary.md | 2 +- content/nginx-one/metrics/_index.md | 2 +- content/nginx-one/rbac/_index.md | 2 +- content/nginx-one/staged-configs/_index.md | 2 +- layouts/partials/list-main.html | 30 +++++++------------ 7 files changed, 17 insertions(+), 25 deletions(-) diff --git a/content/nginx-one/api/_index.md b/content/nginx-one/api/_index.md index 9d4e73a0b..5b3284d5e 100644 --- a/content/nginx-one/api/_index.md +++ b/content/nginx-one/api/_index.md @@ -1,6 +1,6 @@ --- title: Automate with the NGINX One API description: -weight: 1000 +weight: 700 url: /nginx-one/api --- diff --git a/content/nginx-one/connect-instances/_index.md b/content/nginx-one/connect-instances/_index.md index 2bb58215e..193e440c5 100644 --- a/content/nginx-one/connect-instances/_index.md +++ b/content/nginx-one/connect-instances/_index.md @@ -1,6 +1,6 @@ --- description: title: Connect your instances to the console -weight: 700 +weight: 200 url: /nginx-one/connect-instances/ --- diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index 4477da2e8..33b817f55 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -3,7 +3,7 @@ description: '' docs: DOCS-1396 title: Glossary toc: true -weight: 2000 +weight: 800 type: - reference --- diff --git a/content/nginx-one/metrics/_index.md b/content/nginx-one/metrics/_index.md index 767a578d9..9602b6a8b 100644 --- a/content/nginx-one/metrics/_index.md +++ b/content/nginx-one/metrics/_index.md @@ -1,6 +1,6 @@ --- description: title: Set up metrics -weight: 300 +weight: 500 url: /nginx-one/metrics/ --- diff --git a/content/nginx-one/rbac/_index.md b/content/nginx-one/rbac/_index.md index 5cc3d036e..447611e56 100644 --- a/content/nginx-one/rbac/_index.md +++ b/content/nginx-one/rbac/_index.md @@ -1,6 +1,6 @@ --- title: Organize users with RBAC description: -weight: 500 +weight: 600 url: /nginx-one/rbac --- diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md index d041035c2..1305546f1 100644 --- a/content/nginx-one/staged-configs/_index.md +++ b/content/nginx-one/staged-configs/_index.md @@ -1,6 +1,6 @@ --- description: title: Draft new configurations -weight: 200 +weight: 400 url: /nginx-one/staged-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 1354f65d5..7e077a26f 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -37,38 +37,30 @@

      {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}}

      See benefits from the NGINX One Console

      {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new configurations")}} -

      Work with Staged Configurations

      + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Connect your instances to the console") }} +

      Work with data plane keys, containers, and proxy servers

      {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX instances")}}

      Monitor and maintain your deployments

      {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Draft new configurations")}} +

      Work with Staged Configurations

      + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up metrics") }} +

      Review your deployments in a dashboard

      + {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize users with RBAC")}}

      Assign responsibilities with role-based access control

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Automate with the NGINX One API")}}

      Manage your NGINX fleet over REST

      {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}}

      Learn terms unique to NGINX One Console

      {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Connect your instances to the console") }} -

      Work with data plane keys, containers, and proxy servers

      - {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up metrics") }} -

      Review your deployments in a dashboard

      - {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "API")}} -

      These are API docs

      - - {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Changelog") }} {{ partial "changelog-date.html" . }} {{ end }} From 1026634ea4525d90aaca67eefbf25644fa95916f Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 29 May 2025 06:48:50 -0700 Subject: [PATCH 22/25] Draft ToC. NAP and NIC integration. Built from new-homepage branch --- .../nginx-one/nginx-configs/nap-integration/_index.md | 6 ++++++ .../nginx-configs/nap-integration/add-policy.md | 9 +++++++++ .../nginx-configs/nap-integration/delete-policy.md | 9 +++++++++ .../nginx-configs/nap-integration/deploy-policy.md | 9 +++++++++ .../nginx-one/nginx-configs/nap-integration/overview.md | 9 +++++++++ .../nginx-configs/nap-integration/review-policy.md | 9 +++++++++ .../nginx-configs/nap-integration/security-policy-api.md | 9 +++++++++ 7 files changed, 60 insertions(+) create mode 100644 content/nginx-one/nginx-configs/nap-integration/_index.md create mode 100644 content/nginx-one/nginx-configs/nap-integration/add-policy.md create mode 100644 content/nginx-one/nginx-configs/nap-integration/delete-policy.md create mode 100644 content/nginx-one/nginx-configs/nap-integration/deploy-policy.md create mode 100644 content/nginx-one/nginx-configs/nap-integration/overview.md create mode 100644 content/nginx-one/nginx-configs/nap-integration/review-policy.md create mode 100644 content/nginx-one/nginx-configs/nap-integration/security-policy-api.md diff --git a/content/nginx-one/nginx-configs/nap-integration/_index.md b/content/nginx-one/nginx-configs/nap-integration/_index.md new file mode 100644 index 000000000..eee17ce2e --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/_index.md @@ -0,0 +1,6 @@ +--- +title: Security with NGINX App Protect +description: +weight: 400 +url: /nginx-one/nap-integration +--- diff --git a/content/nginx-one/nginx-configs/nap-integration/add-policy.md b/content/nginx-one/nginx-configs/nap-integration/add-policy.md new file mode 100644 index 000000000..861c2f30e --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/add-policy.md @@ -0,0 +1,9 @@ +--- +title: "Add a security policy" +weight: 500 +toc: true +type: how-to +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nap-integration/delete-policy.md b/content/nginx-one/nginx-configs/nap-integration/delete-policy.md new file mode 100644 index 000000000..c7ea83594 --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/delete-policy.md @@ -0,0 +1,9 @@ +--- +title: "Delete a security policy" +weight: 700 +toc: true +type: how-to +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nap-integration/deploy-policy.md b/content/nginx-one/nginx-configs/nap-integration/deploy-policy.md new file mode 100644 index 000000000..afc2cdbf2 --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/deploy-policy.md @@ -0,0 +1,9 @@ +--- +title: "Deploy a security policy" +weight: 600 +toc: true +type: how-to +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nap-integration/overview.md b/content/nginx-one/nginx-configs/nap-integration/overview.md new file mode 100644 index 000000000..a7afebdfa --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/overview.md @@ -0,0 +1,9 @@ +--- +title: "NGINX App Protect integration overview" +weight: 400 +toc: true +type: reference +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nap-integration/review-policy.md b/content/nginx-one/nginx-configs/nap-integration/review-policy.md new file mode 100644 index 000000000..39c98269a --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/review-policy.md @@ -0,0 +1,9 @@ +--- +title: "Review security policies" +weight: 600 +toc: true +type: how-to +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nap-integration/security-policy-api.md b/content/nginx-one/nginx-configs/nap-integration/security-policy-api.md new file mode 100644 index 000000000..9b2341782 --- /dev/null +++ b/content/nginx-one/nginx-configs/nap-integration/security-policy-api.md @@ -0,0 +1,9 @@ +--- +title: "Set security policies through the API" +weight: 700 +toc: true +type: reference +product: NGINX One +docs: DOCS-000 +--- + From a75f57ac3c13aa43f8f513f98c61792efca5aa48 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 29 May 2025 06:52:23 -0700 Subject: [PATCH 23/25] More --- content/nginx-one/nginx-configs/nic-ngf/_index.md | 6 ++++++ content/nginx-one/nginx-configs/nic-ngf/overview.md | 9 +++++++++ 2 files changed, 15 insertions(+) create mode 100644 content/nginx-one/nginx-configs/nic-ngf/_index.md create mode 100644 content/nginx-one/nginx-configs/nic-ngf/overview.md diff --git a/content/nginx-one/nginx-configs/nic-ngf/_index.md b/content/nginx-one/nginx-configs/nic-ngf/_index.md new file mode 100644 index 000000000..21271c88b --- /dev/null +++ b/content/nginx-one/nginx-configs/nic-ngf/_index.md @@ -0,0 +1,6 @@ +--- +title: Integrate Kubernetes-based solutions +description: +weight: 400 +url: /nginx-one/nic-ngf +--- diff --git a/content/nginx-one/nginx-configs/nic-ngf/overview.md b/content/nginx-one/nginx-configs/nic-ngf/overview.md new file mode 100644 index 000000000..a7afebdfa --- /dev/null +++ b/content/nginx-one/nginx-configs/nic-ngf/overview.md @@ -0,0 +1,9 @@ +--- +title: "NGINX App Protect integration overview" +weight: 400 +toc: true +type: reference +product: NGINX One +docs: DOCS-000 +--- + From 5d92bcf2fa279287fe06e7a8b5918083df3cf7d9 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 29 May 2025 07:13:44 -0700 Subject: [PATCH 24/25] More --- content/nginx-one/nginx-configs/add-file.md | 2 +- content/nginx-one/nginx-configs/certificates/_index.md | 2 +- .../nginx-configs/clean-up-unavailable-instances.md | 2 +- .../nginx-one/nginx-configs/nap-integration/_index.md | 4 ++-- content/nginx-one/nginx-configs/nic-ngf/_index.md | 4 ++-- content/nginx-one/nginx-configs/nic-ngf/api-metadata.md | 9 +++++++++ content/nginx-one/nginx-configs/nic-ngf/control-plane.md | 9 +++++++++ content/nginx-one/nginx-configs/nic-ngf/cve.md | 9 +++++++++ content/nginx-one/nginx-configs/nic-ngf/overview.md | 2 +- .../nginx-configs/view-edit-nginx-configurations.md | 2 +- 10 files changed, 36 insertions(+), 9 deletions(-) create mode 100644 content/nginx-one/nginx-configs/nic-ngf/api-metadata.md create mode 100644 content/nginx-one/nginx-configs/nic-ngf/control-plane.md create mode 100644 content/nginx-one/nginx-configs/nic-ngf/cve.md diff --git a/content/nginx-one/nginx-configs/add-file.md b/content/nginx-one/nginx-configs/add-file.md index ffbe71922..bbe2f1cf8 100644 --- a/content/nginx-one/nginx-configs/add-file.md +++ b/content/nginx-one/nginx-configs/add-file.md @@ -2,7 +2,7 @@ docs: null title: Add a file to an instance toc: true -weight: 400 +weight: 300 type: - how-to --- diff --git a/content/nginx-one/nginx-configs/certificates/_index.md b/content/nginx-one/nginx-configs/certificates/_index.md index f4e0962c4..b97d42034 100644 --- a/content/nginx-one/nginx-configs/certificates/_index.md +++ b/content/nginx-one/nginx-configs/certificates/_index.md @@ -1,6 +1,6 @@ --- description: title: Monitor your certificates -weight: 400 +weight: 500 url: /nginx-one/nginx-configs/certificates --- diff --git a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md index 6a119617d..9e7979e34 100644 --- a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md +++ b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md @@ -3,7 +3,7 @@ description: '' docs: null title: Clean up unavailable NGINX instances toc: true -weight: 200 +weight: 1000 type: - how-to --- diff --git a/content/nginx-one/nginx-configs/nap-integration/_index.md b/content/nginx-one/nginx-configs/nap-integration/_index.md index eee17ce2e..25361e7e9 100644 --- a/content/nginx-one/nginx-configs/nap-integration/_index.md +++ b/content/nginx-one/nginx-configs/nap-integration/_index.md @@ -1,6 +1,6 @@ --- -title: Security with NGINX App Protect +title: Add security with NGINX App Protect description: -weight: 400 +weight: 600 url: /nginx-one/nap-integration --- diff --git a/content/nginx-one/nginx-configs/nic-ngf/_index.md b/content/nginx-one/nginx-configs/nic-ngf/_index.md index 21271c88b..9177a83a9 100644 --- a/content/nginx-one/nginx-configs/nic-ngf/_index.md +++ b/content/nginx-one/nginx-configs/nic-ngf/_index.md @@ -1,6 +1,6 @@ --- title: Integrate Kubernetes-based solutions description: -weight: 400 -url: /nginx-one/nic-ngf +weight: 700 +url: /nginx-one/nginx-configs/nic-ngf --- diff --git a/content/nginx-one/nginx-configs/nic-ngf/api-metadata.md b/content/nginx-one/nginx-configs/nic-ngf/api-metadata.md new file mode 100644 index 000000000..2b477635d --- /dev/null +++ b/content/nginx-one/nginx-configs/nic-ngf/api-metadata.md @@ -0,0 +1,9 @@ +--- +title: "Find API metadata" +weight: 400 +toc: true +type: reference +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nic-ngf/control-plane.md b/content/nginx-one/nginx-configs/nic-ngf/control-plane.md new file mode 100644 index 000000000..0bfcd24c3 --- /dev/null +++ b/content/nginx-one/nginx-configs/nic-ngf/control-plane.md @@ -0,0 +1,9 @@ +--- +title: "NIC/NGF Control Plane" +weight: 200 +toc: true +type: reference +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nic-ngf/cve.md b/content/nginx-one/nginx-configs/nic-ngf/cve.md new file mode 100644 index 000000000..68e6cfe4e --- /dev/null +++ b/content/nginx-one/nginx-configs/nic-ngf/cve.md @@ -0,0 +1,9 @@ +--- +title: "Review your CVEs" +weight: 300 +toc: true +type: reference +product: NGINX One +docs: DOCS-000 +--- + diff --git a/content/nginx-one/nginx-configs/nic-ngf/overview.md b/content/nginx-one/nginx-configs/nic-ngf/overview.md index a7afebdfa..e8ba1f247 100644 --- a/content/nginx-one/nginx-configs/nic-ngf/overview.md +++ b/content/nginx-one/nginx-configs/nic-ngf/overview.md @@ -1,6 +1,6 @@ --- title: "NGINX App Protect integration overview" -weight: 400 +weight: 100 toc: true type: reference product: NGINX One diff --git a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md index dcc6ab881..f775520f8 100644 --- a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md +++ b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md @@ -2,7 +2,7 @@ # We use sentence case and present imperative tone title: View and edit an NGINX instance # Weights are assigned in increments of 100: determines sorting order -weight: 300 +weight: 200 # Creates a table of contents and sidebar, useful for large documents toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this From 2b420b2cf24b7fb2aec2390d6b81c54aeb65cb43 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 29 May 2025 08:17:58 -0700 Subject: [PATCH 25/25] test --- content/nginx-one/nginx-configs/nic-ngf/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/nginx-configs/nic-ngf/overview.md b/content/nginx-one/nginx-configs/nic-ngf/overview.md index e8ba1f247..eda9e34ac 100644 --- a/content/nginx-one/nginx-configs/nic-ngf/overview.md +++ b/content/nginx-one/nginx-configs/nic-ngf/overview.md @@ -1,5 +1,5 @@ --- -title: "NGINX App Protect integration overview" +title: "Integrate Kubernetes deployments" weight: 100 toc: true type: reference