From b7cf0b3a06990d355a76554cbae7c516e708221b Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Mon, 20 Jan 2025 20:22:19 -0800 Subject: [PATCH 1/3] Update cert instructions for NGINX One Console --- .../nginx-one/add-file/edit-config-tip.md | 10 +++ .../nginx-one/add-file/existing-ssl-bundle.md | 16 +++++ .../nginx-one/add-file/new-ssl-bundle.md | 33 +++++++++ .../includes/nginx-one/add-file/overview.md | 5 ++ .../certificates/manage-certificates.md | 37 ++++++++-- .../how-to/config-sync-groups/add-file-csg.md | 70 +++++++++++++++++++ .../how-to/nginx-configs/add-file.md | 41 ++--------- 7 files changed, 172 insertions(+), 40 deletions(-) create mode 100644 content/includes/nginx-one/add-file/edit-config-tip.md create mode 100644 content/includes/nginx-one/add-file/existing-ssl-bundle.md create mode 100644 content/includes/nginx-one/add-file/new-ssl-bundle.md create mode 100644 content/includes/nginx-one/add-file/overview.md create mode 100644 content/nginx-one/how-to/config-sync-groups/add-file-csg.md diff --git a/content/includes/nginx-one/add-file/edit-config-tip.md b/content/includes/nginx-one/add-file/edit-config-tip.md new file mode 100644 index 000000000..fdb99d1ff --- /dev/null +++ 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 new file mode 100644 index 000000000..e0c5fa219 --- /dev/null +++ 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 new file mode 100644 index 000000000..3c87debd8 --- /dev/null +++ b/content/includes/nginx-one/add-file/new-ssl-bundle.md @@ -0,0 +1,33 @@ +--- +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/ssl/nginx/server.crt + - /etc/ssl/nginx/server.pem + +- **Key File Path** + - Enter the full path to your certificate key, such as + - /etc/ssl/nginx/server.key + - If you're using a `.pem` file, you won't have a separate 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 new file mode 100644 index 000000000..2922d3d07 --- /dev/null +++ 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 index 5d08f6df1..2edfee901 100644 --- 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: + +{{}} +| 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]({{< 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,7 +51,7 @@ 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 @@ -49,7 +67,18 @@ The NGINX One Console allows you to upload these certificates as text and as fil 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. @@ -145,7 +174,7 @@ If that certificate is managed and is part of a Config Sync Group, that change a ## 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 new file mode 100644 index 000000000..82568c8b6 --- /dev/null +++ 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 index 9e7bd9838..dc26074f3 100644 --- a/content/nginx-one/how-to/nginx-configs/add-file.md +++ b/content/nginx-one/how-to/nginx-configs/add-file.md @@ -4,7 +4,7 @@ doctypes: - task tags: - docs -title: Add a file in a configuration +title: Add a file to an instance toc: true weight: 400 --- @@ -12,8 +12,7 @@ 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,20 +50,7 @@ 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. - - -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 >}} @@ -77,22 +58,10 @@ In each case, you can upload files directly, or enter the content of the certifi with the `ssl_certificate` and `ssl_certificate_key` directives. {{< /tip >}} - ### 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 From 62eb72592ab8e30184268963d71d5ce72ad5e4ff Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 5 Feb 2025 12:48:31 -0800 Subject: [PATCH 2/3] Update per PR comments --- .../how-to/certificates/manage-certificates.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/nginx-one/how-to/certificates/manage-certificates.md b/content/nginx-one/how-to/certificates/manage-certificates.md index 2edfee901..f2f026b7d 100644 --- a/content/nginx-one/how-to/certificates/manage-certificates.md +++ b/content/nginx-one/how-to/certificates/manage-certificates.md @@ -59,10 +59,12 @@ Before you add and manage certificates with the NGINX One Console make sure: 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: @@ -75,7 +77,7 @@ For exmaple, if you use ECDSA private keys in PEM format, the PEM headers should ``` -----BEGIN EC PRIVATE KEY----- -<...base64-encoded key> + -----END EC PRIVATE KEY----- ``` @@ -170,7 +172,7 @@ 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 From b85cd1b2991a5cf094c02d18ac04e7239451e759 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 5 Feb 2025 13:13:55 -0800 Subject: [PATCH 3/3] Respond to added comments. --- content/includes/nginx-one/add-file/new-ssl-bundle.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/includes/nginx-one/add-file/new-ssl-bundle.md b/content/includes/nginx-one/add-file/new-ssl-bundle.md index 3c87debd8..4ba76c690 100644 --- a/content/includes/nginx-one/add-file/new-ssl-bundle.md +++ b/content/includes/nginx-one/add-file/new-ssl-bundle.md @@ -20,13 +20,12 @@ Select **Save and Continue**. You're taken to another screen where you can speci - **Certificate File Path** - Enter the full path to your certificate, such as - - /etc/ssl/nginx/server.crt - - /etc/ssl/nginx/server.pem + - /etc/nginx/server.crt + - /etc/nginx/server.pem - **Key File Path** - Enter the full path to your certificate key, such as - - /etc/ssl/nginx/server.key - - If you're using a `.pem` file, you won't have a separate key. + - /etc/nginx/server.key With the **Add Item** button, you can add the file to additional directories.