Chapter 2. Installing Capsule Server
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 Preparing your Environment for Installation . 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. Red Hat 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 Red Hat 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. Ensure HTTPS connection using client certificate authentication is possible between Capsule Server and Satellite Server. HTTP proxies between Capsule Server and Satellite Server are not supported. You must configure the host and network-based firewalls accordingly. For more information, see Ports and Firewalls Requirements . You can register hosts with Satellite using the host registration feature, the Satellite API, or Hammer CLI. Procedure In the Satellite web UI, navigate to Hosts > Register Host . Click Generate to create the registration command. Click on the files icon to copy the command to your clipboard. Log in to the host you want register and run the previously generated command. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled. CLI procedure Generate the host registration command using the Hammer CLI: If your hosts do not trust the SSL certificate of Satellite Server, you can disable SSL validation by adding the --insecure flag to the registration command. Log in to the host you want register and run the previously generated command. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled. API procedure Generate the host registration command using the Satellite API: If your hosts do not trust the SSL certificate of Satellite Server, you can disable SSL validation by adding the --insecure flag to the registration command. Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in the Content Management guide. To enter a password as command line argument, use username:password syntax. Keep in mind this can save the password in the shell history. For more information about registration see Registering a Host to Red Hat Satellite in Managing Hosts . Log in to the host you want register and run the previously generated command. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled. 2.2. Attaching the Satellite Infrastructure Subscription Note Skip this step if you have SCA enabled on Satellite. There is no requirement of attaching the Red Hat Satellite Infrastructure Subscription to the Capsule Server using subscription-manager. For more information about SCA, see Simple Content Access . 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 and Red Hat Enterprise Linux content. For Red Hat Enterprise Linux 7, it also provides access to Red Hat Software Collections (RHSCL). This is the only subscription required. Red Hat Satellite Infrastructure is included with all subscriptions that include Satellite, formerly known as Smart Management. For more information, see Satellite Infrastructure Subscriptions MCT3718 MCT3719 in the Red Hat Knowledgebase . 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 another system is consuming your subscription. Procedure Identify the Pool ID of the Satellite Infrastructure subscription: The command displays output similar to the following: Make a note of the subscription Pool ID. Your subscription Pool ID is different from the example provided. Attach the Satellite Infrastructure subscription to the base operating system that your Capsule Server is running on. If SCA is enabled on Satellite Server, you can skip this step: The command displays output similar to the following: Optional: Verify that the Satellite Infrastructure subscription is attached: 2.3. Configuring Repositories Use this procedure to enable the repositories that are required to install Capsule Server. Select the option that corresponds with operating system and version you want to install on: Red Hat Enterprise Linux 8 Red Hat Enterprise Linux 7 2.3.1. Red Hat Enterprise Linux 8 Disable all repositories: Enable the following repositories: Enable the module: Note Enablement of the module satellite:el8 warns about a conflict with postgresql:10 and ruby:2.5 as these modules are set to the default module versions on Red Hat Enterprise Linux 8. The module satellite:el8 has a dependency for the modules postgresql:12 and ruby:2.7 that will be enabled with the satellite:el8 module. These warnings do not cause installation process failure, hence can be ignored safely. For more information about modules and lifecycle streams on Red Hat Enterprise Linux 8, see Red Hat Enterprise Linux Application Streams Life Cycle . 2.3.2. Red Hat Enterprise Linux 7 Disable all repositories: Enable the following repositories: 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 . Clear any metadata: Optional: Verify that the required repositories are enabled: 2.4. Installing Capsule Server Packages Before installing Capsule Server packages, you must update all packages that are installed on the base operating system. Red Hat Enterprise Linux 7 Red Hat Enterprise Linux 8 Procedure To install Capsule Server, complete the following steps: 2.4.1. Red Hat Enterprise Linux 7 Update all packages: Install the Satellite Server packages: 2.4.2. Red Hat Enterprise Linux 8 Update all packages: Install the Satellite Server packages: 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 Using the Chrony suite to configure NTP in Red Hat Enterprise Linux 8 Configuring basic system settings , and Configuring NTP Using the chrony Suite in the Red Hat Enterprise Linux 7 System Administrator's Guide . Procedure Install the chrony package: Start and enable the chronyd service: 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. If you use a default SSL certificate, you must also configure each external Capsule Server with a distinct default SSL certificate. For more information, see Section 2.6.1, "Configuring Capsule Server with a Default SSL Certificate" . If you use a custom SSL certificate, you must also configure each external Capsule Server with a distinct custom SSL certificate. For more information, see Section 2.6.2, "Configuring Capsule Server with a Custom SSL 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 Satellite Server default Certificate Authority (CA). Prerequisites Capsule Server is registered to Satellite Server. For more information, see Registering to Satellite Server . Capsule Server packages are installed. For more information, see Installing Capsule Server Packages . Procedure 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 : On Satellite Server, generate the /root/capsule_cert/ capsule.example.com -certs.tar certificate archive for your Capsule Server: 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 On Satellite Server, copy the certificate archive file to your Capsule Server: 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: Section 2.6.2.1, "Creating a Custom SSL Certificate for Capsule Server" Section 2.6.2.2, "Deploying a Custom SSL Certificate to Capsule Server" Section 2.6.2.3, "Deploying a Custom SSL Certificate to Hosts" 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. Procedure To store all the source certificate files, create a directory that is accessible only to the root user: 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. Create the /root/capsule_cert/openssl.cnf configuration file for the CSR and include the following content: Generate CSR: 1 Path to the private key. 2 Path to the configuration file. 3 Path to the CSR to generate. Send the certificate signing request to the certificate authority (CA). The same CA 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 CA for the preferred method. In response to the request, you can expect to receive a CA 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 Satellite Server is configured with a custom certificate. For more information, see Configuring Satellite Server with a Custom SSL Certificate in Installing Satellite Server in a Connected Network Environment . Capsule Server is registered to Satellite Server. For more information, see Registering to Satellite Server . Capsule Server packages are installed. For more information, see Installing Capsule Server Packages . Procedure On Satellite Server, validate the custom SSL certificate input files: 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. Example output of katello-certs-check 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 USDCAPSULE to the FQDN of your Capsule Server. 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 On Satellite Server, copy the certificate archive file to your Capsule Server: 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: 2.7. Assigning the Correct Organization and Location to Capsule Server in the Satellite web UI After installing Capsule Server packages, if there is more than one organization or location, you must assign the correct organization and location to Capsule to make Capsule visible in the Satellite web UI. Note Assigning a Capsule to the same location as your Satellite Server with an embedded Capsule prevents Red Hat Insights from uploading the Insights inventory. To enable the inventory upload, synchronize SSH keys for both Capsules. Procedure Log into the Satellite web UI. From the Organization list in the upper-left of the screen, select Any Organization . From the Location list in the upper-left of the screen, select Any Location . In the Satellite web UI, navigate to Hosts > All Hosts and select Capsule Server. From the Select Actions list, select Assign Organization . From the Organization list, select the organization where you want to assign this Capsule. Click Fix Organization on Mismatch . Click Submit . Select Capsule Server. From the Select Actions list, select Assign Location . From the Location list, select the location where you want to assign this Capsule. Click Fix Location on Mismatch . Click Submit . In the Satellite web UI, navigate to Administer > Organizations and click the organization to which you have assigned Capsule. Click Capsules tab and ensure that Capsule Server is listed under the Selected items list, then click Submit . In the Satellite web UI, navigate to Administer > Locations and click the location to which you have assigned Capsule. Click Capsules tab and ensure that Capsule Server is listed under the Selected items list, then click Submit . Verification Optionally, you can verify if Capsule Server is correctly listed in the Satellite web UI. Select the organization from the Organization list. Select the location from the Location list. In the Satellite web UI, navigate to Hosts > All Hosts . In the Satellite web UI, navigate to Infrastructure > Capsules .
hammer host-registration generate-command --activation-keys " My_Activation_Key " hammer host-registration generate-command --activation-keys " My_Activation_Key " --insecure true curl -X POST https://satellite.example.com/api/registration_commands --user " My_User_Name " -H 'Content-Type: application/json' -d '{ "registration_command": { "activation_keys": [" My_Activation_Key_1 , My_Activation_Key_2 "] }}' curl -X POST https://satellite.example.com/api/registration_commands --user " My_User_Name " -H 'Content-Type: application/json' -d '{ "registration_command": { "activation_keys": [" My_Activation_Key_1 , My_Activation_Key_2 "], "insecure": true }}' subscription-manager list --all --available --matches 'Red Hat Satellite Infrastructure Subscription' 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 subscription-manager attach --pool= pool_id Successfully attached a subscription for: Red Hat Satellite Infrastructure Subscription subscription-manager list --consumed subscription-manager repos --disable "*" subscription-manager repos --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms --enable=satellite-capsule-6.11-for-rhel-8-x86_64-rpms --enable=satellite-maintenance-6.11-for-rhel-8-x86_64-rpms dnf module enable satellite-capsule:el8 subscription-manager repos --disable "*" subscription-manager repos --enable=rhel-7-server-rpms --enable=rhel-7-server-satellite-capsule-6.11-rpms --enable=rhel-7-server-satellite-maintenance-6.11-rpms --enable=rhel-server-rhscl-7-rpms --enable=rhel-7-server-ansible-2.9-rpms yum clean all yum repolist enabled yum update yum install satellite-capsule yum update dnf install satellite-capsule yum install chrony systemctl start chronyd systemctl enable chronyd mkdir /root/ capsule_cert capsule-certs-generate --foreman-proxy-fqdn capsule.example.com --certs-tar /root/capsule_cert/ capsule.example.com -certs.tar output omitted satellite-installer --scenario capsule --certs-tar-file "/root/capsule_cert/ 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 " scp /root/capsule_cert/ capsule.example.com -certs.tar root@ capsule.example.com :/root/ capsule.example.com -certs.tar mkdir /root/capsule_cert openssl genrsa -out /root/capsule_cert/capsule_cert_key.pem 4096 [ req ] req_extensions = v3_req distinguished_name = req_distinguished_name x509_extensions = usr_cert prompt = no [ req_distinguished_name ] CN = capsule.example.com [ 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 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 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 Validation succeeded. To use them inside a NEW USDCAPSULE, run this command: capsule-certs-generate --foreman-proxy-fqdn "USDCAPSULE" --certs-tar "~/USDCAPSULE-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 USDCAPSULE, run this command INSTEAD: capsule-certs-generate --foreman-proxy-fqdn "USDCAPSULE" --certs-tar "~/USDCAPSULE-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 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 " scp /root/capsule_cert/ capsule.example.com -certs.tar root@ capsule.example.com :/root/ capsule.example.com -certs.tar yum localinstall http:// capsule.example.com /pub/katello-ca-consumer-latest.noarch.rpm