fix: Update cert instructions for NGINX One Console (#82)

mjang · web-flow · commit e85ddd946cbb · 2025-02-05T13:25:54.000-08:00
* Update cert instructions for NGINX One Console
diff --git a/content/includes/nginx-one/add-file/edit-config-tip.md b/content/includes/nginx-one/add-file/edit-config-tip.md
@@ -0,0 +1,10 @@
+---
+docs:
+---
+
+From this window, select the file of your choice. If you want to delete this
+file, Select **Edit Configuration** and select the Trash icon.
+
+If this was a mistake, a revert button appears. But do not wait. As noted in
+one of the UI messages, "This action cannot be undone once you publish the
+configuration."
diff --git a/content/includes/nginx-one/add-file/existing-ssl-bundle.md b/content/includes/nginx-one/add-file/existing-ssl-bundle.md
@@ -0,0 +1,16 @@
+---
+docs:
+---
+
+With this option, You can incorporate [Managed certificates]({{< relref "/nginx-one/how-to/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.
+1. Enter the **Certificate File Path**, such as `/etc/ssl/nginx/mycert.crt` or `/etc/ssl/nginx/mycert.pem`.
+1. If you selected a key pair, you'll also enter the **Key File Path**, such as `/etc/ssl/nginx/mycert.key`.
+1. If you select **Add Item**, you can add the same certificate or key to another directory.
+1. Select **Add**. You should now be returned to the **Edit Configuration** window.
+   You should now see the files you specified in the directory tree.
+1. Select **Next** and then **Save and Publish**.
+   You may see a message that suggests publication is in progress.
+1. When publication is complete, you're taken back to the **Configuration** tab. You should see the updated configuration in the window.
diff --git a/content/includes/nginx-one/add-file/new-ssl-bundle.md b/content/includes/nginx-one/add-file/new-ssl-bundle.md
@@ -0,0 +1,32 @@
+---
+docs:
+---
+
+First you can select the toggle to allow NGINX One Console to manaage the new certificate or bundle.
+
+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 may need to scroll down. 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
+
+Select **Save and Continue**. You're taken to another screen where you can specify the locations for your files, which may be:
+
+- **Certificate File Path**
+  - Enter the full path to your certificate, such as
+    - /etc/nginx/server.crt
+    - /etc/nginx/server.pem
+
+- **Key File Path**
+  - Enter the full path to your certificate key, such as
+    - /etc/nginx/server.key
+
+With the **Add Item** button, you can add the file to additional directories.
+
+When complete, select **Add** to include the certificate files that you've configured to desired directories.
diff --git a/content/includes/nginx-one/add-file/overview.md b/content/includes/nginx-one/add-file/overview.md
@@ -0,0 +1,5 @@
+---
+docs:
+---
+
+This guide explains how to add files in the F5 NGINX One Console. While you can manage files in the CLI, the NGINX One Console supports editing in a UI that resembles an Integrated Development Environment (IDE), with recommendations.
diff --git a/content/nginx-one/how-to/certificates/manage-certificates.md b/content/nginx-one/how-to/certificates/manage-certificates.md
@@ -14,13 +14,31 @@ weight: 100
 
 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: 
+
+{{<bootstrap-table "table table-striped table-bordered">}}
+| Functionality     | Typical file names                                                 | Notes                                                                                  |
+|-------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------|
+| Website traffic   | /etc/nginx/ssl/example.com.crt <br> /etc/nginx/ssl/example.com.key | Typically purchased from a Certificate Authority (CA)                                 |
+| Repository access | /etc/ssl/nginx/nginx-repo.crt <br> /etc/ssl/nginx/nginx-repo.key   | Supports access to repositories to download and install NGINX packages                |
+| NGINX Licensing   | /etc/ssl/nginx/server.crt <br> /etc/ssl/nginx/server.key   | Supports access to repositories. Based on licenses downloaded from https://my.f5.com/ |
+{{</bootstrap-table>}}
+
+Allowed directories depend on the [NGINX Agent]({{< relref "/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.
 
-For more information on how you can use these certificates to secure your servers, refer to the section on [NGINX SSL termination]({{< relref "/nginx/admin-guide/security-controls/terminating-ssl-http.md" >}}).
+You can manage the certificates for:
+
+- [Unique instances]({{< relref "/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]({{< relref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups/#configuration-management" >}})
+
 
 {{< tip >}}
 
@@ -33,23 +51,36 @@ If you are managing the certificate from NGINX One Console, we recommend that yo
 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]({{< relref "../../api/authentication.md" >}}) guide, to manage SSL/TLS certificates
+- You have access through the F5 Distributed Cloud role, as described in the [Authentication]({{< relref "/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 (with a `.cer` or `.pem` file extension)
-- Privacy certificate (with a `.pem` file extension)
+- 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 .crt and .key file extensions).
+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
-- ECDSA
+- 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-----
+<BASE64 ENCODED 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.
@@ -141,11 +172,11 @@ To delete a certificate, find the name in the **Certificates** screen. Find the
 
 If that certificate is managed and is part of a Config Sync Group, that change affects all instances in that group.
 
-{{< warning >}} Do not 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 >}}
+{{< 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]({{< relref "../../getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), and the associated SSL/TLS certificates:
+If you register an instance to NGINX One Console, as described in [Add your NGINX instances to NGINX One]({{< relref "/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
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
@@ -0,0 +1,70 @@
+---
+docs: 
+doctypes:
+    - task
+tags:
+    - docs
+title: Add a file to a Config Sync Group
+toc: true
+weight: 400
+---
+
+
+## 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]({{< relref "/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]({{< relref "/nginx-one/how-to/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}).
+
+## See also
+
+- [Create and manage data plane keys]({{< relref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}})
+- [View and edit NGINX configurations]({{< relref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}})
+- [Manage certificates]({{< relref "/nginx-one/how-to/certificates/manage-certificates.md" >}})
diff --git a/content/nginx-one/how-to/nginx-configs/add-file.md b/content/nginx-one/how-to/nginx-configs/add-file.md
@@ -4,16 +4,15 @@ doctypes:
     - task
 tags:
     - docs
-title: Add a file in a configuration
+title: Add a file to an instance
 toc: true
 weight: 400
 ---
 
 
 ## Overview
 
-This guide explains how to add files in the F5 NGINX One Console. While you can manage files in the CLI, the NGINX One Console supports editing in
-a UI that resembles an Integrated Development Environment (IDE), with recommendations.
+{{< include "nginx-one/add-file/overview.md" >}}
 
 ## Before you start
 
@@ -36,12 +35,7 @@ You can use the NGINX One Console to add a file to a specific instance. To do so
 
    {{< tip >}}
 
-   From this window, select the file of your choice. If you want to delete this
-   file, Select **Edit Configuration** and select the Trash icon.
-
-   If this was a mistake, a revert button appears. But do not wait. As noted in
-   one of the UI messages, "This action cannot be undone once you publish the
-   configuration."
+   {{< include "nginx-one/add-file/edit-config-tip.md" >}}
 
    {{< /tip >}}
 
@@ -56,43 +50,18 @@ Enter the name of the desired configuration file, such as `abc.conf` and select
 
 ### New SSL Certificate or CA Bundle
 
-First you can select the toggle to allow NGINX One Console to manaage the new certificate or bundle.
-
-<!-- Candidate for an "include". Common content with add-file.md -->
-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
+{{< 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 >}}
-<!-- end potential "include" -->
 
 ### Existing SSL Certificate or CA Bundle
 
-With this option, You can incorporate [Managed certificates]({{< relref "/nginx-one/how-to/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.
-1. Enter the **Certificate File Path**, such as `/etc/ssl/nginx/mycert.crt`.
-1. If you selected a key pair, you'll also enter the **Key File Path**, such as `/etc/ssl/nginx/mycert.key`.
-1. Select **Add**. You should now be returned to the **Edit Configuration** window.
-   You should now see the files you specified in the directory tree.
-1. Select **Next** and then **Save and Publish**.
-   You may see a message that suggests publication is in progress.
-   - If the instance is offline, **Save and Publish** does not work.
-1. When publication is complete, you're taken back to the **Configuration** tab. You should see the updated configuration in the window.
+{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}}
 
 ## See also
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +docs:
 +---
++
 +This guide explains how to add files in the F5 NGINX One Console. While you can manage files in the CLI, the NGINX One Console supports editing in a UI that resembles an Integrated Development Environment (IDE), with recommendations.