Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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
Copy link

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
    Copy to Clipboard Toggle word wrap

  2. Install the katello-ca-consumer-latest.noarch.rpm package: 

    # yum localinstall katello-ca-consumer-latest.noarch.rpm
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

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'
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

    The command displays output similar to the following: 

    Successfully attached a subscription for: Red Hat Satellite Infrastructure Subscription
    Copy to Clipboard Toggle word wrap

  4. Optional: Verify that the Satellite Infrastructure subscription is attached: 

    # subscription-manager list --consumed
    Copy to Clipboard Toggle word wrap

2.3. Configuring Repositories
Copy link

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 "*"
    Copy to Clipboard Toggle word wrap

  2. Enable the following repositories: 

    # subscription-manager repos --enable=rhel-7-server-rpms \
--enable=rhel-7-server-satellite-capsule-6.7-rpms \
--enable=rhel-7-server-satellite-maintenance-6-rpms \
--enable=rhel-7-server-satellite-tools-6.7-rpms \
--enable=rhel-server-rhscl-7-rpms \
--enable=rhel-7-server-ansible-2.8-rpms
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  4. Optional: Verify that the required repositories are enabled: 

    # yum repolist enabled
    Copy to Clipboard Toggle word wrap

2.4. Installing Capsule Server Packages
Copy link

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
    Copy to Clipboard Toggle word wrap

  2. Install the satellite-capsule package: 

    # yum install satellite-capsule
    Copy to Clipboard Toggle word wrap

2.5. Synchronizing the System Clock With chronyd
Copy link

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
    Copy to Clipboard Toggle word wrap

  2. Start and enable the chronyd service: 

    # systemctl start chronyd
# systemctl enable chronyd
    Copy to Clipboard Toggle word wrap

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.

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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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"
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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.

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:

  1. Section 2.6.2.1, “Creating a Custom SSL Certificate for Capsule Server”
  2. Section 2.6.2.2, “Deploying a Custom SSL Certificate to Capsule Server”
  3. Section 2.6.2.3, “Deploying a Custom SSL Certificate to Hosts”

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

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
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

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

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
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat