Using Custom Certificates

This guide describes how to use and update certificates on orcharhino Server and orcharhino Proxies. If you want to use custom SSL/TLS certificates, you can add them during the installation process or replace the orcharhino default certificates at a later stage. For more information, see main installation steps in the orcharhino Server Installation Guide.

In general, you can change the SSL certificates of your orcharhino, for example, if you want to use your own CA or a 3rd party non self-signed CA. You can change the katello-server-ca, but you must not change the katello-default-ca.

Ensure to carry out the following procedure with absolute caution. Aborting the procedure will irreparably damage your orcharhino. Ensure to create a backup to which you can revert to.

After this procedure, you must reconnect all external orcharhino Proxies and all managed hosts.

Prerequisites

Successfully installed orcharhino with self-signed certificates

Installing orcharhino automatically creates self-signed certificates to ensure a secure connection from your local machine to your orcharhino.
Set the host name according to the name the certificates are issued to.

Migrating to Non Self-Signed Certificates

Follow this procedure if you want to migrate from a self-signed certificate to a non self-signed certificate. This allows you to use your own CA and certificates. With this procedure, you overwrite active SSL certificates on your orcharhino.

Prerequisite

The certificate my_crt.pem, the server key my_key.pem, and the CA my_ca.pem must be available in PEM format in /root/or_ssl/ on your orcharhino.

Procedure

Connect to your orcharhino using SSH:
```
# ssh root@orcharhino.example.com
```
Stop all orcharhino services:
```
# orcharhino-maintain service stop
```

Update the certificates on your orcharhino:

# orcharhino-installer \
--certs-server-ca-cert /root/or_ssl/my_ca.pem \
--certs-server-cert /root/or_ssl/my_crt.pem \
--certs-server-key /root/or_ssl/my_key.pem \
--certs-update-server \
--certs-update-server-ca \
--scenario katello

Start all orcharhino services to enable new certificates:
```
# orcharhino-maintain service start
```
If you use orcharhino Proxies: Transfer certificates to additional orcharhino Proxies. Create the certificates for orcharhino Proxies on your orcharhino:
```
# foreman-proxy-certs-generate \
--certs-tar "/root/$FOREMAN_PROXY-certs.tar" \
--foreman-proxy-fqdn "$FOREMAN_PROXY"
```
Replace $FOREMAN_PROXY with the FQDN of your orcharhino Proxy. Transfer the certs.tar archive to your orcharhino Proxy by following the instructions from the output of the previous command.

Reconnect managed hosts because the katello-server-ca has been updated. Delete the previously used certificates, install katello-ca-consumer-latest.noarch.rpm, and reregister your managed hosts:

# rpm -e katello-ca-consumer-orcharhino.example.com
# subscription-manager clean
# rpm -ivh https://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
# subscription-manager register --org="$ORG" --activationkey="$ACTIVATIONKEY"

Updating Custom Certificates on orcharhino Server

Follow this procedure to overwrite currently active custom SSL certificates on your orcharhino Server.

Procedure

Connect to your orcharhino Server using SSH:
```
# ssh root@orcharhino.example.com
```
Stop all orcharhino services:
```
# orcharhino-maintain service stop
```
If your CA certificate file has not changed, update the certificate as follows:
```
# orcharhino-installer \
--certs-server-cert /root/or_ssl/my_crt.pem \
--certs-server-key /root/or_ssl/my_key.pem \
--certs-update-server \
--scenario katello
```
This procedure only updates the certificates to access the management UI and for interprocess communication. It does not update katello-ca-consumer-latest.noarch.rpm or katello-rhsm-consumer. There are no changes on your managed hosts necessary.
If your non self-signed .ca file has changed, update the certificates as follows:
```
# orcharhino-installer \
--certs-server-ca-cert /root/or_ssl/my_ca.pem \
--certs-server-cert /root/or_ssl/my_crt.pem \
--certs-server-key /root/or_ssl/my_key.pem \
--certs-update-server \
--certs-update-server-ca \
--scenario katello
```
This procedure also updates katello-ca-consumer-latest.noarch.rpm and katello-rhsm-consumer. You need to deploy this package to all managed hosts and reregister them to orcharhino as described in reconnect clients.
Restart all orcharhino services:
```
# orcharhino-maintain service start
```
Optional: If you use orcharhino Proxies, follow the output of orcharhino-installer to update the certificates on orcharhino Proxies. For more information, see updating custom certificates on orcharhino Proxy.

Updating Custom Certificates on orcharhino Proxy

Procedure

Connect to your orcharhino Server using SSH:
```
# ssh root@orcharhino.example.com
```

Create a backup of ssl-builds:

# mkdir /root/ssl-build_backup/ && cp -r /root/ssl-build /root/ssl-build_backup

Remove the old certificates for the orcharhino Proxy:

Ensure you have a backup before deleting files in /root/ssl-build/. If you delete more than the folder for the orcharhino Proxy, you need to rebuild all certificates, including all self-signed ones which results in a change where you need to re-register all managed hosts.

# rm -fr /root/ssl-build/orcharhino-proxy.network2.example.com

Generate the certificates:

# foreman-proxy-certs-generate \
--certs-tar "/root/orcharhino-proxy.network2.example.com-certs.tar" \
--foreman-proxy-fqdn "orcharhino-proxy.network2.example.com" \
--server-ca-cert /root/certs/orcharhino-proxy.ca \
--server-cert /root/certs/orcharhino-proxy.cert \
--server-cert-req /root/certs/orcharhino-proxy.csr \
--server-key /root/certs/orcharhino-proxy.key

Copy the archive to your orcharhino Proxy:

# scp /root/orcharhino-proxy.network2.example.com-certs.tar root@orcharhino-proxy.network2.example.com:root/

On your orcharhino Proxy, rerun the orcharhino-installer:

# orcharhino-installer \
--certs-tar-file "/root/orcharhino-proxy.network2.example.com-certs.tar" \
--certs-update-server \
--certs-update-server-ca \
--scenario foreman-proxy-content