Chapter 2. Installing Capsule Server

Before you install Capsule Server, you must ensure that your environment meets the requirements for installation. For more information, see Section 1.1, “System Requirements”.

2.1. Registering to Satellite Server

Use this procedure to register the base operating system on which you want to install Capsule Server to Satellite Server.

Prerequisites

Before registering it to Satellite Server, ensure that the base operating system on which you want to install Capsule meets the following conditions:

Subscription Manifest Prerequisites

  • On Satellite Server, a manifest must be installed and it must contain the appropriate repositories for the organization you want Capsule to belong to.
  • The manifest must contain repositories for the base operating system on which you want to install Capsule, as well as any clients that you want to connect to Capsule.
  • The repositories must be synchronized.

For more information on manifests and repositories, see Managing Subscriptions in the Red Hat Satellite Content Management Guide.

Proxy and Network Prerequisites

  • The Satellite Server base operating system must be able to resolve the host name of the Capsule base operating system and vice versa.
  • The base operating system on which you want to install Capsule Server must not be configured to use a proxy to connect to the Red Hat CDN.
  • You must configure the host and network-based firewalls accordingly. For more information, see Section 1.5, “Ports and Firewalls Requirements”.
  • You must have a Satellite Server user name and password. For more information, see Configuring External Authentication in Administering Red Hat Satellite.

Procedure

To register your system to Satellite Server, complete the following steps:

  1. Download the katello-ca-consumer-latest.noarch.rpm package on the base operating system on which you want to install Capsule. The consumer RPM configures the host to download content from the content source that is specified in Satellite.

    # curl --insecure --output katello-ca-consumer-latest.noarch.rpm https://satellite.example.com/pub/katello-ca-consumer-latest.noarch.rpm
  2. Install the katello-ca-consumer-latest.noarch.rpm package:

    # yum localinstall katello-ca-consumer-latest.noarch.rpm
  3. Register the Capsule base operating system with the environments that you want Capsule to belong to. Use an activation key to simplify specifying the environments. For more information about activation keys, see Managing Activation Keys in the Content Management Guide.

    # subscription-manager register --org=organization_name --activationkey=example_activation_key

2.2. Attaching the Satellite Infrastructure Subscription

After you have registered Capsule Server, you must identify your subscription Pool ID and attach an available subscription. The Red Hat Satellite Infrastructure subscription provides access to the Red Hat Satellite, Red Hat Enterprise Linux, and Red Hat Software Collections (RHSCL) content. This is the only subscription required.

Red Hat Satellite Infrastructure is included with all subscriptions that include Smart Management. For more information, see the Red Hat Knowledgebase solution Satellite Infrastructure Subscriptions MCT3718 MCT3719.

Subscriptions are classified as available if they are not already attached to a system. If you are unable to find an available Satellite subscription, see the Red Hat Knowledgebase solution How do I figure out which subscriptions have been consumed by clients registered under Red Hat Subscription Manager? to run a script to see if your subscription is being consumed by another system.

Procedure

  1. Identify the Pool ID of the Satellite Infrastructure subscription:

    # subscription-manager list --all --available --matches 'Red Hat Satellite Infrastructure Subscription'

    The command displays output similar to the following:

    Subscription Name:   Red Hat Satellite Infrastructure Subscription
    Provides:            Red Hat Satellite
                          Red Hat Software Collections (for RHEL Server)
                          Red Hat CodeReady Linux Builder for x86_64
                          Red Hat Ansible Engine
                          Red Hat Enterprise Linux Load Balancer (for RHEL Server)
                          Red Hat
                          Red Hat Software Collections (for RHEL Server)
                          Red Hat Enterprise Linux Server
                          Red Hat Satellite Capsule
                          Red Hat Enterprise Linux for x86_64
                          Red Hat Enterprise Linux High Availability for x86_64
                          Red Hat Satellite
                          Red Hat Satellite 5 Managed DB
                          Red Hat Satellite 6
                          Red Hat Discovery
    SKU:                 MCT3719
    Contract:            11878983
    Pool ID:             8a85f99968b92c3701694ee998cf03b8
    Provides Management: No
    Available:           1
    Suggested:           1
    Service Level:       Premium
    Service Type:        L1-L3
    Subscription Type:   Standard
    Ends:                03/04/2020
    System Type:         Physical
  2. Make a note of the subscription Pool ID. Your subscription Pool ID is different from the example provided.
  3. Attach the Satellite Infrastructure subscription to the base operating system that your Capsule Server is running on:

    # subscription-manager attach --pool=pool_id

    The command displays output similar to the following:

    Successfully attached a subscription for: Red Hat Satellite Infrastructure Subscription
  4. Optional: Verify that the Satellite Infrastructure subscription is attached:

    # subscription-manager list --consumed

2.3. Configuring Repositories

Use this procedure to enable the repositories that are required to install Capsule Server.

Procedure

To configure the required repositories, complete the following steps:

  1. Disable all repositories:

    # subscription-manager repos --disable "*"
  2. Enable the following repositories:

    # subscription-manager repos --enable=rhel-7-server-rpms \
    --enable=rhel-7-server-satellite-capsule-6.8-rpms \
    --enable=rhel-7-server-satellite-maintenance-6-rpms \
    --enable=rhel-7-server-satellite-tools-6.8-rpms \
    --enable=rhel-server-rhscl-7-rpms \
    --enable=rhel-7-server-ansible-2.9-rpms
    Note

    If you are installing Capsule Server as a virtual machine hosted on Red Hat Virtualization, you must also enable the Red Hat Common repository, and install Red Hat Virtualization guest agents and drivers. For more information, see Installing the Guest Agents and Drivers on Red Hat Enterprise Linux in the Virtual Machine Management Guide for more information.

  3. Clear any metadata:

    # yum clean all
  4. Optional: Verify that the required repositories are enabled:

    # yum repolist enabled

2.4. Installing Capsule Server Packages

Before installing the Capsule Server packages, you must update all packages that are installed on the base operating system.

Procedure

To install Capsule Server, complete the following steps:

  1. Update all packages:

    # yum update
  2. Install the satellite-capsule package:

    # yum install satellite-capsule

2.5. Synchronizing the System Clock With chronyd

To minimize the effects of time drift, you must synchronize the system clock on the base operating system on which you want to install Capsule Server with Network Time Protocol (NTP) servers. If the base operating system clock is configured incorrectly, certificate verification might fail.

For more information about the chrony suite, see Configuring NTP Using the chrony Suite in the Red Hat Enterprise Linux 7 System Administrator’s Guide.

Procedure

  1. Install the chrony package:

    # yum install chrony
  2. Start and enable the chronyd service:

    # systemctl start chronyd
    # systemctl enable chronyd

2.6. Configuring Capsule Server with SSL Certificates

Red Hat Satellite uses SSL certificates to enable encrypted communications between Satellite Server, external Capsule Servers, and all hosts. Depending on the requirements of your organization, you must configure your Capsule Server with a default or custom certificate.

2.6.1. Configuring Capsule Server with a Default SSL Certificate

Use this section to configure Capsule Server with an SSL certificate that is signed by the Satellite Server default Certificate Authority (CA).

Prerequisites

Before configuring Capsule Server with a default server certificate, ensure that your Capsule Server meets the following conditions:

Procedure

To configure Capsule Server with a default server certificate, complete the following steps:

  1. On Satellite Server, to store all the source certificate files for your Capsule Server, create a directory that is accessible only to the root user, for example /root/capsule_cert:

    # mkdir /root/capsule_cert
  2. On Satellite Server, generate the /root/capsule_cert/capsule_certs.tar certificate archive for your Capsule Server:

    # capsule-certs-generate \
    --foreman-proxy-fqdn capsule.example.com \
    --certs-tar /root/capsule_cert/capsule_certs.tar

    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_certs.tar"\
    --foreman-proxy-content-parent-fqdn           "satellite.example.com"\
    --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"

  3. 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
  4. 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.

2.6.2. Configuring Capsule Server with a Custom SSL Certificate

If you configure Satellite Server to use a custom SSL certificate, you must also configure each of your external Capsule Servers with a distinct custom SSL certificate.

To configure your Capsule Server with a custom certificate, complete the following procedures on each Capsule Server:

2.6.2.1. Creating a Custom SSL Certificate for Capsule Server

On Satellite Server, create a custom certificate for your Capsule Server. If you already have a custom SSL certificate for Capsule Server, skip this procedure.

When you configure Capsule Server with custom certificates, note the following considerations:

  • You must use the Privacy-Enhanced Mail (PEM) encoding for the SSL certificates.
  • You cannot use the same certificate for both Satellite Server and Capsule Server.
  • The same Certificate Authority must sign certificates for Satellite Server and Capsule Server.

Procedure

To create a custom SSL certificate, complete the following steps:

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

    # mkdir /root/capsule_cert
  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
  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
    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
    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.

2.6.2.2. Deploying a Custom SSL Certificate to Capsule Server

Use this procedure to configure your Capsule Server with a custom SSL certificate signed by a Certificate Authority. The satellite-installer command, which the capsule-certs-generate command returns, is unique to each Capsule Server. Do not use the same command on more than one Capsule Server.

Prerequisites

Before configuring Capsule Server with a custom server certificate, ensure that your Satellite and Capsules meet the following conditions:

Procedure

To configure your Capsule Server with a custom SSL certificate, complete the following steps:

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

    # katello-certs-check \
    -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
    1
    Path to the Capsule Server certificate file that is signed by a Certificate Authority.
    2
    Path to the private key that was used to sign the 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.

    Example output of katello-certs-check

    Validation succeeded.
    
    To use them inside a NEW $CAPSULE, 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" \
    
    To use them inside an EXISTING $CAPSULE, 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

  2. On Satellite Server, from the output of the katello-certs-check command, depending on your requirements, enter the capsule-certs-generate command that generates a certificate for a new or existing Capsule.

    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_certs.tar"\
    --foreman-proxy-content-parent-fqdn           "satellite.example.com"\
    --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"

  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
  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.

2.6.2.3. Deploying a Custom SSL Certificate to Hosts

After you configure Capsule Server to use a custom SSL certificate, you must also install the katello-ca-consumer package on every host that is registered to this Capsule Server.

Procedure

  • On each host, install the katello-ca-consumer package:

    # yum localinstall \
    http://capsule.example.com/pub/katello-ca-consumer-latest.noarch.rpm