For 4.3: ssl certs cleanup #1216968 keichwa (#3562)

.changelog

@@ -4,7 +4,9 @@
 # - Fixed error in Bat section of Upgrade Guide (bsc#1234567)
 # For guidelines: https://en.opensuse.org/openSUSE:Creating_a_changes_file_(RPM)#Changelog_section_.28.25changelog.29
 
-- Added external link for creating virtual network peer for Azure in 
+- Improved SSL certificate setup description in Administration Guide
+  (bsc#1216968)
+- Added external link for creating virtual network peer for Azure in
   Specialized Gudes (bsc#1234441)
 - Documented onboarding SSH connected Ubuntu clients with install-created
   user in Client Configuration Guide (bsc#1213437)

modules/administration/pages/ssl-certs-imported.adoc

@@ -15,9 +15,9 @@ Before you begin, ensure you have:
 
 All files must be in PEM format.
 
-The host name of the SSL server certificate must match the fully qualified host name of the machine you deploy them on.
-You can set the host names in the [literal]``X509v3 Subject Alternative Name`` section of the certificate.
-You can also list multiple host names if your environment requires it.
+The hostname of the SSL server certificate must match the fully qualified hostname of the machine you deploy them on.
+You can set the hostnames in the [literal]``X509v3 Subject Alternative Name`` section of the certificate.
+You can also list multiple hostnames if your environment requires it.
 Supported Key types are [literal]``RSA`` and [literal]``EC`` (Elliptic Curve).
 
 Third-party authorities commonly use intermediate CAs to sign requested server certificates.
@@ -50,6 +50,8 @@ export SERVER_CERT=<path_to_web_server_certificate>
 yast susemanager_setup
 ----
 +
+// FIXME: where "at the command prompt"?
++
 When you are prompted for certificate details during setup, fill in random values.
 The values are overridden by the values you specified at the command prompt.
 
@@ -77,31 +79,36 @@ After you have completed the initial setup, you can replace the default certific
 ----
 configure-proxy.sh
 ----
+
 . At the ``Do you want to import existing certificates?`` prompt, type kbd:[y].
 . Follow the prompts to complete setup.
 
 
 [NOTE]
 ====
-Use the same certificate authority to sign all server certificates for servers and proxies.
+Use the same certificate authority (CA) to sign all server certificates for servers and proxies.
 Certificates signed with different CAs do not match.
 ====
 
 
 
+[[ssl-certs-import-replace]]
 == Replace Certificates
 
 You can replace active certificates on your {productname} installation with a new certificate.
 To replace the certificates, you can replace the installed CA certificate with the new CA, and then update the database.
 
 
 
+=== On the Server
+
 .Procedure: Replacing Existing Certificates
 
-. On the {productname} Server, at the command prompt, call the command `mgr-ssl-cert-setup` and provide the certificates as parameters:
+. On the {productname} Server, at the command prompt, call the command [command]``mgr-ssl-cert-setup`` with the certificates as parameters:
 +
 ----
-mgr-ssl-cert-setup --root-ca-file=<Path_to_Root_CA_Certificate> --server-cert-file=<Server_Cert_File> --server-key-file=<Server_Key_File>
+mgr-ssl-cert-setup --root-ca-file=<Path_to_Root_CA_Certificate> \
+  --server-cert-file=<Server_Cert_File> --server-key-file=<Server_Key_File>
 ----
 
 
@@ -117,12 +124,25 @@ systemctl restart postgresql.service
 spacewalk-service start
 ----
 
-If you are using a proxy, you need to generate a server certificate RPM for each proxy, using their host names and cnames.
-You should use [command]``mgr-ssl-cert-setup`` also on a {productname} Proxy to replace the certificates.
-Because the {productname} Proxy does not have a postgreSQL database, only [command]``spacewalk-service restart`` is sufficient.
 
-If the Root CA was changed, it needs to get deployed to all the clients connected to {productname}.
 
+=== On the Proxy
+
+
+If you are using a proxy, you need to generate a server certificate for the proxy on the {productname} server and copy the files to the proxy.
+Alternatively, you let your own Certificate Authority generate these files and provide them on the proxy.
+After the files are availableon the proxy, use [command]``mgr-ssl-cert-setup`` also on a {productname} Proxy to replace the certificates.
+Because the {productname} Proxy does not have a postgreSQL database, the dedicated proxy restart command is sufficient:
+
+----
+spacewalk-proxy restart
+----
+
+
+
+=== Deploy the Root CA on Salt Clients
+
+If the Root CA was changed, it needs to get deployed to all the clients connected to {productname}.
 
 
 .Procedure: Deploying the Root CA on Salt Clients

modules/administration/pages/ssl-certs-selfsigned.adoc

@@ -4,12 +4,14 @@
 By default, {productname} uses a self-signed certificate.
 In this case, the certificate is created and signed by {productname}.
 This method does not use an independent certificate authority to guarantee that the details of the certificate are correct.
-Third party CAs perform checks to ensure that the information contained in the certificate is correct.
-For more on third party CAs, see xref:administration:ssl-certs-imported.adoc[].
+Third-party CAs perform checks to ensure that the information contained in the certificate is correct.
+
+* For more information on third-party CAs, see xref:administration:ssl-certs-imported.adoc[].
+* For more information on replacing certificates, see xref:administration:ssl-certs-imported.adoc#ssl-certs-import-replace[].
 
 This section covers how to create or re-create your self-signed certificates on new or existing installation.
 
-The host name of the SSL keys and certificates must match the fully qualified host name of the machine you deploy them on.
+The hostname of the SSL keys and certificates must match the fully qualified hostname of the machine you deploy them on.
 
 
 == Re-Create Existing Server Certificates
@@ -27,11 +29,12 @@ rhn-ssl-tool --gen-server --dir="/root/ssl-build" --set-country="COUNTRY" \
 --set-hostname="susemanager.example.com" --set-cname="example.com"
 ----
 Ensure that the [systemitem]``set-cname`` parameter is the fully qualified domain name of your {productname} Server.
-You can use the the [systemitem]``set-cname`` parameter multiple times if you require multiple aliases.
+You can use the [systemitem]``set-cname`` parameter multiple times if you require multiple aliases.
 
 The private key and the server certificate can be found in the directory `/root/ssl-build/susemanager/` as `server.key` and `server.crt`.
 The name of the last directory depends on the hostname used with `--set-hostname` option.
-
+
+
 
 [[ssl-certs-selfsigned-create-replace]]
 == Create a new CA and Server Certificates
@@ -68,8 +71,8 @@ rhn-ssl-tool --gen-server --dir="/root/ssl-build" --set-country="COUNTRY" \
 --set-hostname="susemanager.example.top" --set-cname="example.com"
 ----
 Ensure that the [systemitem]``set-cname`` parameter is the fully qualified domain name of your {productname} Server.
-You can use the the [systemitem]``set-cname`` parameter multiple times if you require multiple aliases.
+You can use the [systemitem]``set-cname`` parameter multiple times if you require multiple aliases.
 +
-You need to generate a server certificate also for each proxy, using their host names and cnames.
+You need to generate a server certificate also for each proxy, using their hostnames and cnames.
 
 

modules/administration/pages/ssl-certs.adoc

@@ -39,7 +39,7 @@ There are two main ways of achieving this.
 In older versions of {productname}, by default, all the intermediate CAs are installed on the client.
 However, you could also configure your services on the server to provide them to the client.
 In this case, during the SSL handshake, the server presents the server certificate as well as all the intermediate CAs.
-This mechanims is used now as the new default configuration.
+This mechanism is used now as the default configuration.
 
 //Whichever method you choose, you must ensure that the ``CA_CERT`` environment variable points to the root CA, and all intermediate CAs.
 //It should not contain the server certificate.
@@ -52,12 +52,12 @@ They usually charge an annual fee for this service.
 Using a third party CA makes certificates harder to spoof, and provides additional protection for your installation.
 If you have certificates signed by a third party CA, you can import them to your {productname} installation.
 
-This manual describe the use of SSL certificates in 2 steps
+This manual describe the use of SSL certificates in two steps:
 
 1. How to create a self-signed certificate with {productname} tools
 2. How to deploy a certificate on {productname} Server or Proxy
 
 In case the certificates are provided by a third party instance like an own or external PKI, step 1 can be skipped.
 
-* For more on how to create self-signed certificates, see xref:administration:ssl-certs-selfsigned.adoc[].
-* For more on how to imported certificates, see xref:administration:ssl-certs-imported.adoc[].
+* For more information about creating self-signed certificates, see xref:administration:ssl-certs-selfsigned.adoc[].
+* For more information about importing certificates, see xref:administration:ssl-certs-imported.adoc[].