Refs #37601 - Refresh/deploy CA cert on hosts (#3193)

Co-authored-by: Maximilian Kolb <[email protected]> Co-authored-by: Shimon Shtein <[email protected]> Co-authored-by: Eric Helms <[email protected]>
theforeman · Sep 6, 2024 · 69b0498 · 69b0498
1 parent daa5114
commit 69b0498
Show file tree

Hide file tree

Showing 16 changed files with 206 additions and 16 deletions.
diff --git a/guides/common/assembly_refreshing-the-self-signed-ca-certificate-on-hosts.adoc b/guides/common/assembly_refreshing-the-self-signed-ca-certificate-on-hosts.adoc
@@ -0,0 +1,7 @@
+include::modules/con_refreshing-the-self-signed-ca-certificate-on-hosts.adoc[]
+
+include::modules/proc_deploying-the-ca-certificate-on-a-host-by-using-script-rex.adoc[leveloffset=+1]
+
+include::modules/proc_deploying-the-ca-certificate-on-a-host-by-using-ansible-rex.adoc[leveloffset=+1]
+
+include::modules/proc_deploying-the-ca-certificate-on-a-host-manually.adoc[leveloffset=+1]
diff --git a/...mbly_renewing-custom-ssl-certificate.adoc → ...ommon/assembly_renewing-certificates.adoc b/...mbly_renewing-custom-ssl-certificate.adoc → ...ommon/assembly_renewing-certificates.adoc
@@ -1,4 +1,6 @@
-include::modules/con_renewing-the-custom-ssl-certificate.adoc[]
+include::modules/con_renewing-certificates.adoc[]
+
+include::modules/proc_planning-for-self-signed-ca-certificate-renewal.adoc[leveloffset=+1]
 
 include::modules/proc_renewing-a-custom-ssl-certificate-on-server.adoc[leveloffset=+1]
 

diff --git a/guides/common/modules/con_refreshing-the-self-signed-ca-certificate-on-hosts.adoc b/guides/common/modules/con_refreshing-the-self-signed-ca-certificate-on-hosts.adoc
@@ -0,0 +1,14 @@
+[id="refreshing-the-self-signed-ca-certificate-on-hosts"]
+= Refreshing the self-signed CA certificate on hosts
+
+When you change the CA certificate on your {ProjectServer}, you must refresh the CA certificate on your hosts.
+
+Ensure that you use a temporary dual CA certificate file for uninterrupted operation.
+For more information, see {AdministeringDocURL}planning-for-self-signed-ca-certificate-renewal[Planning for self-signed CA certificate renewal] in _{AdministeringDocTitle}_.
+
+If you have already changed the CA certificate on {ProjectServer} without using the temporary dual CA certificate file, you must refresh the certificate on hosts manually because the scripted variant will not recognize {ProjectServer}.
+
+[IMPORTANT]
+====
+You only must redeploy the CA certificate if you use a self-signed CA certificate.
+====
diff --git a/guides/common/modules/con_renewing-certificates.adoc b/guides/common/modules/con_renewing-certificates.adoc
@@ -0,0 +1,4 @@
+[id="renewing-certificates"]
+= Renewing certificates
+
+You can renew the CA certificate on {ProjectServer} or the {customssl} certificate on {ProjectServer} as well as on {SmartProxyServer}.
diff --git a/guides/common/modules/con_renewing-the-custom-ssl-certificate.adoc b/guides/common/modules/con_renewing-the-custom-ssl-certificate.adoc
diff --git a/...n/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-ansible-rex.adoc b/...n/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-ansible-rex.adoc
@@ -0,0 +1,32 @@
+[id="deploying-the-ca-certificate-on-a-host-by-using-ansible-rex"]
+= Deploying the CA certificate on a host by using Ansible REX
+
+You can use remote execution (REX) with the Ansible provider to deploy the CA certificate.
+
+include::snip_prerequisites-deploying-ca-cert-rex.adoc[]
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Monitor* > *Jobs*.
+. Click *Run Job*.
+. From the *Job category* list, select `Ansible Commands`.
+. From the *Job template* list, select `Download and execute a script`.
+. Click *Next*.
+. Select hosts on which you want to execute the job.
+. In the *url* field, enter the following URL:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+https://_{foreman-example-com}_/unattended/public/foreman_ca_refresh
+----
++
+include::snip_replace-fqdn-projectserver.adoc[]
++
+You can use HTTP when the CA certificate is expired.
+. Optional: Click *Next* and configure advanced fields and scheduling as you require.
+. Click *Run on selected hosts*.
+
+include::snip_verification-ca-set-correctly.adoc[]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:executing-a-remote-job_managing-hosts[]
diff --git a/...on/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-script-rex.adoc b/...on/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-script-rex.adoc
@@ -0,0 +1,32 @@
+[id="deploying-the-ca-certificate-on-a-host-by-using-script-rex"]
+= Deploying the CA certificate on a host by using Script REX
+
+You can use remote execution (REX) with the Script provider to deploy the CA certificate.
+
+include::snip_prerequisites-deploying-ca-cert-rex.adoc[]
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Monitor* > *Jobs*.
+. Click *Run Job*.
+. From the *Job category* list, select `Commands`.
+. From the *Job template* list, select `Download and run a script`.
+. Click *Next*.
+. Select hosts on which you want to execute the job.
+. In the *url* field, enter the following URL:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+https://_{foreman-example-com}_/unattended/public/foreman_ca_refresh
+----
++
+include::snip_replace-fqdn-projectserver.adoc[]
++
+You can use HTTP when the CA certificate is expired.
+. Optional: Click *Next* and configure advanced fields and scheduling as you require.
+. Click *Run on selected hosts*.
+
+include::snip_verification-ca-set-correctly.adoc[]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:executing-a-remote-job_managing-hosts[]
diff --git a/guides/common/modules/proc_deploying-the-ca-certificate-on-a-host-manually.adoc b/guides/common/modules/proc_deploying-the-ca-certificate-on-a-host-manually.adoc
@@ -0,0 +1,59 @@
+[id="deploying-the-ca-certificate-on-a-host-manually"]
+= Deploying the CA certificate on a host manually
+
+You can deploy the CA certificate on the host manually by rendering a public provisioning template, which provides the CA certificate.
+
+.Prerequisites
+* You have root access on both your {ProjectServer} and your host.
+
+.Procedure
+. Download the certificate on your {ProjectServer}:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# curl -o "{project-context}_ca_cert.crt" https://_{foreman-example-com}_/unattended/public/foreman_raw_ca
+----
++
+include::snip_replace-fqdn-projectserver.adoc[]
+. Transfer the CA certificate to your host securely, for example by using `scp`.
+. Login to your host by using SSH.
+. Copy the certificate to the truststore:
+ifdef::client-content-dnf[]
+ifndef::satellite[]
+* On {EL}:
+endif::[]
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# cp {project-context}_ca_cert.crt /etc/pki/ca-trust/source/anchors
+----
+endif::[]
+ifdef::client-content-apt[]
+* On {DL}:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# cp {project-context}_ca_cert.crt /usr/local/share/ca-certificates/
+----
+endif::[]
+. Update the truststore:
+ifdef::client-content-dnf[]
+ifndef::satellite[]
+* On {EL}:
+endif::[]
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# update-ca-trust
+----
+endif::[]
+ifdef::client-content-apt[]
+* On {DL}:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# update-ca-certificates
+----
+endif::[]
+
+include::snip_verification-ca-set-correctly.adoc[]
diff --git a/guides/common/modules/proc_planning-for-self-signed-ca-certificate-renewal.adoc b/guides/common/modules/proc_planning-for-self-signed-ca-certificate-renewal.adoc
@@ -0,0 +1,16 @@
+[id="planning-for-self-signed-ca-certificate-renewal"]
+= Planning for self-signed CA certificate renewal
+
+If you need to update the Certification Authority (CA) certificate on your {ProjectServer}, add the new CA certificate and use a temporary dual CA certificate file to retain the HTTPS connections to your {ProjectServer} during the renewal.
+
+.Procedure
+. Add the new SSL certificate to the CA certificate file on {ProjectServer} and keep the old SSL certificate.
+. Renew the certificates on {ProjectServer} and any {SmartProxyServers}.
+. Deploy the dual CA certificate on hosts.
+. Remove the old certificate from the CA certificates file on {ProjectServer}, so the CA certificate file contains only the new SSL certificate.
+. Renew the certificates on {ProjectServer} and any {SmartProxyServers}.
+. Deploy the new CA certificate on hosts.
+
+[role="_additional-resources"]
+.Additional resources
+* {ManagingHostsDocURL}refreshing-the-self-signed-ca-certificate-on-hosts[Refreshing the self-signed CA certificate on hosts] in _{ManagingHostsDocTitle}_
diff --git a/guides/common/modules/proc_renewing-a-custom-ssl-certificate-on-server.adoc b/guides/common/modules/proc_renewing-a-custom-ssl-certificate-on-server.adoc
@@ -39,12 +39,11 @@ Do not delete the certificate files after you deploy the certificate.
 They are required when upgrading {ProjectServer}.
 ====
 
-[NOTE]
-====
-If a new consumer package `katello-ca-consumer-latest.noarch.rpm` is generated due to a different Certificate Signing Authority, all the clients registered to {ProjectServer} must be updated.
-====
-
 .Verification
 . Access the {ProjectWebUI} from your local machine.
-For example, https://{foreman-example-com}.
+For example, `https://{foreman-example-com}`.
 . In your browser, view the certificate details to verify the deployed certificate.
+
+.Next steps
+* If you have changed the CA certificate on {ProjectServer}, refresh the CA certificate on your hosts.
+For more information, see {ManagingHostsDocURL}refreshing-the-self-signed-ca-certificate-on-hosts[Refreshing the self-signed CA certificate on hosts] in _{ManagingHostsDocTitle}_.
diff --git a/guides/common/modules/proc_renewing-a-custom-ssl-certificate-on-smart-proxy.adoc b/guides/common/modules/proc_renewing-a-custom-ssl-certificate-on-smart-proxy.adoc
@@ -58,7 +58,6 @@ Do not delete the certificate archive file on the {SmartProxyServer} after you d
 They are required when upgrading {SmartProxyServer}.
 ====
 
-[NOTE]
-====
-If a new consumer package `katello-ca-consumer-latest.noarch.rpm` is generated due to a different Certificate Signing Authority, all the clients registered to {SmartProxyServer} must be updated.
-====
+.Next steps
+* If you have changed the CA certificate on {ProjectServer}, refresh the CA certificate on your hosts.
+For more information, see {ManagingHostsDocURL}refreshing-the-self-signed-ca-certificate-on-hosts[Refreshing the self-signed CA certificate on hosts] in _{ManagingHostsDocTitle}_.
diff --git a/guides/common/modules/snip_prerequisites-deploying-ca-cert-rex.adoc b/guides/common/modules/snip_prerequisites-deploying-ca-cert-rex.adoc
@@ -0,0 +1,5 @@
+.Prerequisites
+* The host is registered to {Project}.
+* Remote execution is enabled on the host.
+* The CA certificate has been changed on {ProjectServer}.
+For more information, see {AdministeringDocURL}planning-for-self-signed-ca-certificate-renewal[Planning for self-signed CA certificate renewal] in _{AdministeringDocTitle}_.
diff --git a/guides/common/modules/snip_replace-fqdn-projectserver.adoc b/guides/common/modules/snip_replace-fqdn-projectserver.adoc
@@ -0,0 +1 @@
+Replace _{foreman-example-com}_ with the FQDN of your {ProjectServer}.
diff --git a/guides/common/modules/snip_verification-ca-set-correctly.adoc b/guides/common/modules/snip_verification-ca-set-correctly.adoc
@@ -0,0 +1,20 @@
+.Verification
+* If the host can access {ProjectServer}, the following command succeeds on your host:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+$ curl --head https://_{foreman-example-com}_
+----
++
+include::snip_replace-fqdn-projectserver.adoc[]
+* If the host can access {SmartProxyServer}, the following command succeeds on your host:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+$ curl --head https://_{smartproxy-example-com}:{smartproxy_port}_/features
+----
++
+Replace _{smartproxy-example-com}_ with the FQDN of your {SmartProxyServer}.
+ifndef::satellite[]
+Replace the port number with the port number you use.
+endif::[]
diff --git a/guides/doc-Administering_Project/master.adoc b/guides/doc-Administering_Project/master.adoc
@@ -53,7 +53,7 @@ endif::[]
 include::common/assembly_maintaining-server.adoc[leveloffset=+1]
 
 ifdef::katello,orcharhino,satellite[]
-include::common/assembly_renewing-custom-ssl-certificate.adoc[leveloffset=+1]
+include::common/assembly_renewing-certificates.adoc[leveloffset=+1]
 endif::[]
 
 include::common/assembly_synchronizing-template-repositories.adoc[leveloffset=+1]

diff --git a/guides/doc-Managing_Hosts/master.adoc b/guides/doc-Managing_Hosts/master.adoc
@@ -25,6 +25,10 @@ include::common/assembly_registering-hosts.adoc[leveloffset=+1]
 
 include::common/assembly_managing-network-interfaces.adoc[leveloffset=+1]
 
+ifdef::katello,orcharhino,satellite[]
+include::common/assembly_refreshing-the-self-signed-ca-certificate-on-hosts.adoc[leveloffset=+1]
+endif::[]
+
 include::common/modules/proc_upgrading-hosts-to-next-major-release.adoc[leveloffset=+1]
 
 include::common/assembly_converting-a-host-to-rhel.adoc[leveloffset=+1]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Replace _{foreman-example-com}_ with the FQDN of your {ProjectServer}.