Certificates

Checking for Validity

During installation any certificates for Katello are checked for validity. The same can be performed manually with katello-certs-check. Doing so can be useful when looking into SSL related issues or configuring custom certificates.

katello-certs-check -c ~/path/to/server.crt\
                    -k ~/path/to/server.key\
                    -b ~/path/to/cacert.crt

If you would like to configure Katello with a set of invalid certs, the validation check can be skipped by passing --certs-skip-check to the installer.

Custom Server Certificates

New Katello Installations

foreman-installer --scenario katello\
                  --certs-server-cert ~/path/to/server.crt\
                  --certs-server-key ~/path/to/server.key\
                  --certs-server-ca-cert ~/path/to/cacert.crt

--certs-server-ca-cert is the CA used for issuing the server certs. This CA gets distributed to content hosts and Smart Proxies.

For Smart Proxies the following options are passed to foreman-proxy-certs-generate:

foreman-proxy-certs-generate --foreman-proxy-fqdn "$FOREMAN_PROXY"\
                             --certs-tar ~/$FOREMAN_PROXY-certs.tar\
                             --server-cert ~/path/to/server.crt\
                             --server-key ~/path/to/server.key\
                             --server-ca-cert ~/cacert.crt

The rest of the procedure is identical to the default CA setup.

Existing Katello Installations

The first run of foreman-installer --scenario katello uses the default CA for both server and client certificates. To enforce the custom certificates to be deployed, one needs to set --certs-update-server to update the server certificate. --certs-update-server-ca should be given when updating the server CA in order for katello-ca-consumer-latest.noarch.rpm to be regenerated.

foreman-installer --scenario katello\
                  --certs-server-cert ~/path/to/server.crt\
                  --certs-server-key ~/path/to/server.key\
                  --certs-server-ca-cert ~/path/to/cacert.crt\
                  --certs-update-server --certs-update-server-ca

After the server CA changes the new version of the katello-ca-consumer RPM needs to be installed on content hosts:

rpm -Uvh http://katello.example.com/pub/katello-ca-consumer-latest.noarch.rpm

Any custom CA on the server needs to be used on the server certificates of any Smart Proxies as well. The certificates for Smart Proxies are generated by foreman-proxy-certs-generate.

foreman-proxy-certs-generate --foreman-proxy-fqdn "$FOREMAN_PROXY_CONTENT"\
                             --certs-tar ~/$FOREMAN_PROXY_CONTENT-certs.tar\
                             --server-cert ~/path/to/server.crt\
                             --server-key ~/path/to/server.key\
                             --server-ca-cert ~/cacert.crt\
                             --certs-update-server

After generation the utility will provide the necessary details on how to copy the new certificates to and run the installer on the Smart Proxy.

Updating Certificates

On the Katello server

To regenerate the server certificates when using the default CA or enforce deploying new certificates for the custom server CA the installer may be run in this way:

foreman-installer --scenario katello --certs-update-server

To regenerate all the certificates used in the Katello server use the --certs-update-all flag. This will generate and deploy the certificates as well as restart corresponding services.

On a Smart Proxy

For updating the certificates on a Smart Proxy pass the same options (--certs-update-server or --certs-update-all) to foreman-proxy-certs-generate. A tarball is generated containing the new certs and output will be shown indicating how to transfer it to the Smart Proxy and run the installer.