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 new file mode 100644 index 00000000000..8577194f6b3 --- /dev/null +++ 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/guides/common/assembly_renewing-custom-ssl-certificate.adoc b/guides/common/assembly_renewing-certificates.adoc similarity index 56% rename from guides/common/assembly_renewing-custom-ssl-certificate.adoc rename to guides/common/assembly_renewing-certificates.adoc index 42ee1ca9c72..53ae746e78b 100644 --- a/guides/common/assembly_renewing-custom-ssl-certificate.adoc +++ b/guides/common/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 new file mode 100644 index 00000000000..8370f2c6091 --- /dev/null +++ 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 new file mode 100644 index 00000000000..c9fc2568983 --- /dev/null +++ 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 deleted file mode 100644 index 5466b49f4cf..00000000000 --- a/guides/common/modules/con_renewing-the-custom-ssl-certificate.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[id="renewing-the-custom-ssl-certificate_{context}"] -= Renewing the {customssl} certificate - -This chapter provides information on how to renew the {customssl} certificate on {ProjectServer} as well as on {SmartProxyServer}. diff --git a/guides/common/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-ansible-rex.adoc b/guides/common/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-ansible-rex.adoc new file mode 100644 index 00000000000..4960c091155 --- /dev/null +++ b/guides/common/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/guides/common/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-script-rex.adoc b/guides/common/modules/proc_deploying-the-ca-certificate-on-a-host-by-using-script-rex.adoc new file mode 100644 index 00000000000..6d8a204b699 --- /dev/null +++ b/guides/common/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 new file mode 100644 index 00000000000..fe024d1e649 --- /dev/null +++ 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 new file mode 100644 index 00000000000..97dc866d4a5 --- /dev/null +++ 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 index a990911d43b..032f1000fe7 100644 --- 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 index 2bd37228b68..d2b09afcad7 100644 --- 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 new file mode 100644 index 00000000000..37bb65acd6b --- /dev/null +++ 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 new file mode 100644 index 00000000000..8fc03fb73b0 --- /dev/null +++ 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 new file mode 100644 index 00000000000..08354a36f86 --- /dev/null +++ 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 index 8dd16ec73ff..50bf480d32f 100644 --- 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 index 91163f00d5b..28800fdf913 100644 --- 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]