Chapter 2. Installing Capsule Server

Procedure

1. To store all the source certificate files, create a directory that is accessible only to the root user.

   # mkdir /root/capsule_cert

   Copy to Clipboard Toggle word wrap

2. Create a private key with which to sign the Certificate Signing Request (CSR).

   Note that the private key must be unencrypted. If you use a password-protected private key, remove the private key password.

   If you already have a private key for this Capsule Server, skip this step.

   # openssl genrsa -out /root/capsule_cert/capsule_cert_key.pem 4096

   Copy to Clipboard Toggle word wrap

3. Create the /root/capsule_cert/openssl.cnf configuration file for the Certificate Signing Request (CSR) and include the following content:

   [ req ]
   req_extensions = v3_req
   distinguished_name = req_distinguished_name
   x509_extensions = usr_cert
   prompt = no
   
   [ req_distinguished_name ] 

   1

   
   C  = Country Name (2 letter code)
   ST = State or Province Name (full name)
   L  = Locality Name (eg, city)
   O  = Organization Name (eg, company)
   OU = The division of your organization handling the certificate
   CN = capsule.example.com 

   2

   
   
   [ v3_req ]
   basicConstraints = CA:FALSE
   keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
   extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
   subjectAltName = @alt_names
   
   [ usr_cert ]
   basicConstraints=CA:FALSE
   nsCertType = client, server, email
   keyUsage = nonRepudiation, digitalSignature, keyEncipherment
   extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
   nsComment = "OpenSSL Generated Certificate"
   subjectKeyIdentifier=hash
   authorityKeyIdentifier=keyid,issuer
   
   [ alt_names ]
   DNS.1 = capsule.example.com 

   3

   Copy to Clipboard Toggle word wrap

   1

   In the [ req_distinguished_name ] section, enter information about your organization.

   2

   Set the certificate’s Common Name CN to match the fully qualified domain name (FQDN) of your Capsule Server or a wildcard value *. To confirm a FQDN, on that Capsule Server, enter the hostname -f command. This is required to ensure that the katello-certs-check command validates the certificate correctly. If you set a wildcard value, you must add the -t capsule option when you use the katello-certs-check command.

   3

   Set the Subject Alternative Name (SAN) DNS.1 to match the fully qualified domain name (FQDN) of your server.

4. Generate the Certificate Signing Request (CSR):

   # openssl req -new \
   -key /root/capsule_cert/capsule_cert_key.pem \ 

   1

   
   -config /root/capsule_cert/openssl.cnf \ 

   2

   
   -out /root/capsule_cert/capsule_cert_csr.pem 

   3

   Copy to Clipboard Toggle word wrap

   1

   Path to the private key.

   2

   Path to the configuration file.

   3

   Path to the CSR to generate.

5. Send the certificate signing request to the Certificate Authority. The same Certificate Authority must sign certificates for Satellite Server and Capsule Server.

   When you submit the request, specify the lifespan of the certificate. The method for sending the certificate request varies, so consult the Certificate Authority for the preferred method. In response to the request, you can expect to receive a Certificate Authority bundle and a signed certificate, in separate files.

Procedure

1. On Satellite Server, validate the custom SSL certificate input files:

   # katello-certs-check \
   -t capsule -c /root/capsule_cert/capsule_cert.pem \      

   1

   
   -k /root/capsule_cert/capsule_cert_key.pem \  

   2

   
   -b /root/capsule_cert/ca_cert_bundle.pem      

   3

   Copy to Clipboard Toggle word wrap

   1

   Path to Capsule Server certificate file that is signed by a Certificate Authority.

   2

   Path to the private key that was used to sign Capsule Server certificate.

   3

   Path to the Certificate Authority bundle.

   If you set a wildcard value * for the certificate’s Common Name CN = in the /root/capsule_cert/openssl.cnf configuration file, you must add the -t capsule option to the katello-certs-check command.

   If the command is successful, it returns two capsule-certs-generate commands, one of which you must use to generate the certificate archive file for your Capsule Server.

   To use the certificates inside a new-capsule.example.com, run this command:

   capsule-certs-generate --foreman-proxy-fqdn "$CAPSULE" \
       --certs-tar  "~/$CAPSULE-certs.tar" \
       --server-cert "/root/capsule_cert/capsule_cert.pem" \
       --server-key "/root/capsule_cert/capsule_cert_key.pem" \
       --server-ca-cert "/root/capsule_cert/ca_cert_bundle.pem" \

   Copy to Clipboard Toggle word wrap

   To use the certificates inside an existing-capsule.example.com, run this command instead:

     capsule-certs-generate --foreman-proxy-fqdn "$CAPSULE" \
       --certs-tar "~/$CAPSULE-certs.tar" \
       --server-cert "/root/capsule_cert/capsule_cert.pem" \
       --server-key "/root/capsule_cert/capsule_cert_key.pem" \
       --server-ca-cert "/root/capsule_cert/ca_cert_bundle.pem" \
       --certs-update-server

   Copy to Clipboard Toggle word wrap

2. Depending on your requirements, enter the capsule-certs-generate command on the Satellite Server that generates a certificate for a new or existing Capsule. The output of the katello-certs-check command may not be accurate in some cases. Therefore, you must follow the steps mentioned above instead of the command outputs.

   In this command, change $CAPSULE to the FQDN of your Capsule Server.

3. Retain a copy of the satellite-installer command that the capsule-certs-generate command returns for deploying the certificate to your Capsule Server.

   Example output of capsule-certs-generate

   output omitted
   satellite-installer --scenario capsule \
   --certs-tar-file "/root/capsule.example.com-certs.tar" \
   --foreman-proxy-register-in-foreman "true" \
   --foreman-proxy-foreman-base-url "https://satellite.example.com" \
   --foreman-proxy-trusted-hosts "satellite.example.com" \
   --foreman-proxy-trusted-hosts "capsule.example.com" \
   --foreman-proxy-oauth-consumer-key "s97QxvUAgFNAQZNGg4F9zLq2biDsxM7f" \
   --foreman-proxy-oauth-consumer-secret "6bpzAdMpRAfYaVZtaepYetomgBVQ6ehY" \
   --puppet-server-foreman-url "https://satellite.example.com"

   Copy to Clipboard Toggle word wrap

4. On Satellite Server, copy the certificate archive file to your Capsule Server:

   # scp /root/capsule_cert/capsule.example.com-certs.tar \
   root@capsule.example.com:/root/capsule.example.com-certs.tar

   Copy to Clipboard Toggle word wrap

5. On Capsule Server, to deploy the certificate, enter the satellite-installer command that the capsule-certs-generate command returns.

   When network connections or ports to Satellite are not yet open, you can set the --foreman-proxy-register-in-foreman option to false to prevent Capsule from attempting to connect to Satellite and reporting errors. Run the installer again with this option set to true when the network and firewalls are correctly configured.

   Important

   Do not delete the certificate archive file after you deploy the certificate. It is required, for example, when upgrading Capsule Server.