Upgrading and Updating Red Hat Satellite

1. Optional: Clone your existing Satellite Servers. For more information, see Chapter 2, Cloning Satellite Server.
2. Upgrade Satellite Server to 6.12. For more information, see Section 3.1, “Upgrading Satellite Server”.
3. Upgrade all Capsule Servers to 6.12. For more information, see Section 3.3, “Upgrading Capsule Servers”.
4. Continue with Section 3.5, “Performing Post-Upgrade Tasks”.

1. If you want to have several smaller outage windows instead of one larger window.
2. If Capsules in your organization are managed by several teams and are located in different locations.
3. If you use a load-balanced configuration, you can upgrade one load-balanced Capsule and keep other load-balanced Capsules at one version lower. This allows you to upgrade all Capsules one after another without any outage.

1. Back up the source server.
2. Clone the source server to the target server.
3. Power off the source server.
4. Update the network configuration on the target server to match the target server’s IP address with its new host name.
5. Restart goferd in Content hosts and Capsules to refresh the connection.
6. Test the new target server.

1. Perform a backup with PostgreSQL databases active excluding the Pulp data:

   # satellite-maintain backup offline --skip-pulp-content \
   --assumeyes /var/backup

2. Stop and disable Satellite services:

   # satellite-maintain service stop
   # satellite-maintain service disable

3. Copy the Pulp data to the target server:

   # rsync --archive --partial --progress --compress \
   /var/lib/pulp/ target_server.example.com:/var/lib/pulp/

Procedure

1. In the Satellite web UI, navigate to Content > Red Hat Repositories.
2. Toggle the Recommended Repositories switch to the On position.

3. From the list of results, expand the following repositories and click the Enable icon to enable the repositories:

   • To upgrade Satellite clients, enable the Red Hat Satellite Client 6 repositories for all Red Hat Enterprise Linux versions that clients use.

   • If you have Capsule Servers, to upgrade them, enable the following repositories too:

     Red Hat Satellite Capsule 6.12 (for RHEL 8 x86_64) (RPMs)

     Red Hat Satellite Maintenance 6.12 (for RHEL 8 x86_64) (RPMs)

     Red Hat Enterprise Linux 8 (for x86_64 – BaseOS) (RPMs)

     Red Hat Enterprise Linux 8 (for x86_64 – AppStream) (RPMs)

   Note

   If the 6.12 repositories are not available, refresh the Red Hat Subscription Manifest. In the Satellite web UI, navigate to Content > Subscriptions, click Manage Manifest, then click Refresh.

4. In the Satellite web UI, navigate to Content > Sync Status.
5. Click the arrow next to the product to view the available repositories.
6. Select the repositories for 6.12. Note that Red Hat Satellite Client 6 does not have a 6.12 version. Choose Red Hat Satellite Client 6 instead.

7. Click Synchronize Now.

   Important

   If an error occurs when you try to synchronize a repository, refresh the manifest. If the problem persists, raise a support request. Do not delete the manifest from the Customer Portal or in the Satellite web UI; this removes all the entitlements of your content hosts.

8. If you use Content Views to control updates to the base operating system of Capsule Server, update those Content Views with new repositories, publish, and promote their updated versions. For more information, see Managing Content Views in Managing Content.

Upgrading Capsule Servers

1. Create a backup.

   • On a virtual machine, take a snapshot.

   • On a physical machine, create a backup.

     For information on backups, see Backing Up Satellite Server and Capsule Server in Administering Red Hat Satellite.

2. Clean yum cache:

   # yum clean metadata

3. Synchronize the satellite-capsule-6.12-for-rhel-8-x86_64-rpms repository in the Satellite Server.
4. Publish and promote a new version of the content view with which the Capsule is registered.

5. The rubygem-foreman_maintain is installed from the Satellite Maintenance repository or upgraded from the Satellite Maintenance repository if currently installed.

   In the current upgrade process, you must enable the Satellite 6.12 (or Capsule) repository to restrict any updates outside the Satellite Maintenance repository. Please read the Known Issues in the Release Notes as a workaround before proceeding further.

   Ensure Capsule has access to satellite-maintenance-6.12-for-rhel-8-x86_64-rpms and execute:

   # subscription-manager repos --enable \
   satellite-capsule-6.12-for-rhel-8-x86_64-rpms
   
   # satellite-maintain self-upgrade

   If the Capsule 6.11 system was upgraded from Red Hat Enterprise Linux 7 to Red Hat Enterprise Linux 8 using Leapp, manually enable the Capsule module:

   # dnf module enable satellite-capsule:el8

6. On Capsule Server, verify that the foreman_url setting points to the Satellite FQDN:

   # grep foreman_url /etc/foreman-proxy/settings.yml

7. Check the available versions to confirm the version you want is listed:

   # satellite-maintain upgrade list-versions

8. Because of the lengthy upgrade time, use a utility such as tmux to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously.

   If you lose connection to the command shell where the upgrade command is running you can see the logged messages in the /var/log/foreman-installer/capsule.log file to check if the process completed successfully.

9. Use the health check option to determine if the system is ready for upgrade:

   # satellite-maintain upgrade check --target-version 6.12

   Review the results and address any highlighted error conditions before performing the upgrade.

10. Perform the upgrade:

    # satellite-maintain upgrade run --target-version 6.12

11. Check when the kernel packages were last updated:

    # rpm -qa --last | grep kernel

12. Optional: If a kernel update occurred since the last reboot, reboot the system:

    # reboot

13. Optional: If you made manual edits to DNS or DHCP configuration files, check and restore any changes required to the DNS and DHCP configuration files using the backups made earlier.
14. Optional: If you use custom repositories, ensure that you enable these custom repositories after the upgrade completes.

Upgrading Capsule Servers using remote execution

1. Create a backup or take a snapshot.

   For more information on backups, see Backing Up Satellite Server and Capsule Server in Administering Red Hat Satellite.

2. In the Satellite web UI , navigate to Monitor > Jobs.
3. Click Run Job.
4. From the Job category list, select Maintenance Operations.
5. From the Job template list, select Capsule Upgrade Playbook.
6. In the Search Query field, enter the host name of the Capsule.
7. Ensure that Apply to 1 host is displayed in the Resolves to field.
8. In the target_version field, enter the target version of the Capsule.
9. In the whitelist_options field, enter the options.
10. Select the schedule for the job execution in Schedule.
11. In the Type of query section, click Static Query.

Procedure

1. Create a backup.
2. Restore the backup on the new server.

3. If Satellite reaches the new database server via the old name, no further changes are required. Otherwise reconfigure Satellite to use the new name:

   # satellite-installer \
   --foreman-db-host newpostgres.example.com \
   --katello-candlepin-db-host newpostgres.example.com \
   --foreman-proxy-content-pulpcore-postgresql-host newpostgres.example.com

To Update Satellite Server:

1. Ensure the Satellite Maintenance repository is enabled:

   # subscription-manager repos --enable \
   satellite-maintenance-6.12-for-rhel-8-x86_64-rpms

2. Check the available versions to confirm the next minor version is listed:

   # satellite-maintain upgrade list-versions

3. Use the health check option to determine if the system is ready for upgrade. On first use of this command, satellite-maintain prompts you to enter the hammer admin user credentials and saves them in the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

   # satellite-maintain upgrade check --target-version 6.12.z

   Review the results and address any highlighted error conditions before performing the upgrade.

4. Because of the lengthy update time, use a utility such as tmux to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously.

   If you lose connection to the command shell where the upgrade command is running, you can see the logged messages in the /var/log/foreman-installer/satellite.log file to check if the process completed successfully.

5. Perform the upgrade:

   # satellite-maintain upgrade run --target-version 6.12.z

6. Check when the kernel packages were last updated:

   # rpm -qa --last | grep kernel

7. Optional: If a kernel update occurred since the last reboot, stop Satellite services and reboot the system:

   # satellite-maintain service stop
   # reboot

1. Ensure that you have synchronized the following repositories in your connected Satellite Server.

   rhel-8-for-x86_64-baseos-rpms
   rhel-8-for-x86_64-appstream-rpms
   satellite-6.12-for-rhel-8-x86_64-rpms
   satellite-maintenance-6.12-for-rhel-8-x86_64-rpms

2. Download the debug certificate of the organization and store it locally at, for example, /etc/pki/katello/certs/org-debug-cert.pem or a location of your choosing. For more information, see Creating an Organization Debug Certificate in Administering Red Hat Satellite.

3. Create a Yum configuration file under /etc/yum.repos.d, such as satellite-disconnected.repo, with the following contents:

   [rhel-8-for-x86_64-baseos-rpms]
   name=Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)
   baseurl=https://satellite.example.com/pulp/content/My_Organization/Library/content/dist/rhel8/8/x86_64/baseos/os
   enabled=1
   sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem
   sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem
   sslcacert = /etc/pki/katello/certs/katello-server-ca.crt
   sslverify = 1
   
   [rhel-8-for-x86_64-appstream-rpms]
   name=Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)
   baseurl=https://satellite.example.com/pulp/content/My_Organization/Library/content/dist/rhel8/8/x86_64/appstream/os
   enabled=1
   sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem
   sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem
   sslcacert = /etc/pki/katello/certs/katello-server-ca.crt
   sslverify = 1
   
   [satellite-6.12-for-rhel-8-x86_64-rpms]
   name=Red Hat Satellite 6.12 for RHEL 8 RPMs x86_64
   baseurl=https://satellite.example.com/pulp/content/My_Organization/Library/content/dist/layered/rhel8/x86_64/satellite/6.12/os
   enabled=1
   sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem
   sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem
   sslcacert = /etc/pki/katello/certs/katello-server-ca.crt
   
   [satellite-maintenance-6.12-for-rhel-8-x86_64-rpms]
   name=Red Hat Satellite Maintenance 6.12 for RHEL 8 RPMs x86_64
   baseurl=https://satellite.example.com/pulp/content/My_Organization/Library/content/dist/layered/rhel8/x86_64/sat-maintenance/6.12/os
   enabled=1
   sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem
   sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem
   sslcacert = /etc/pki/katello/certs/katello-server-ca.crt
   sslverify = 1

4. In the configuration file, replace /etc/pki/katello/certs/org-debug-cert.pem in sslclientcert and sslclientkey with the location of the downloaded organization debug certificate.
5. Update satellite.example.com with correct FQDN for your deployment.

6. Replace My_Organization with the correct organization label in the baseurl. To obtain the organization label, enter the command:

   # hammer organization list

7. Enter the reposync command:

   # reposync --delete --download-metadata -p ~/Satellite-repos -n \
    --disableplugin=foreman-protector \
    --repoid rhel-8-for-x86_64-baseos-rpms \
    --repoid rhel-8-for-x86_64-appstream-rpms \
    --repoid satellite-6.12-for-rhel-8-x86_64-rpms \
    --repoid satellite-maintenance-6.12-for-rhel-8-x86_64-rpms

   This downloads the contents of the repositories from the connected Satellite Server and stores them in the directory ~/Satellite-repos.

8. Verify that the RPMs have been downloaded and the repository data directory is generated in each of the sub-directories of ~/Satellite-repos.

9. Archive the contents of the directory

   # cd ~
   # tar czf Satellite-repos.tgz Satellite-repos

10. Use the generated Satellite-repos.tgz file to upgrade in the disconnected Satellite Server.

1. Copy the generated Satellite-repos.tgz file to your disconnected Satellite Server

2. Extract the archive to anywhere accessible by the root user. In the following example /root is the extraction location.

   # cd /root
   # tar zxf Satellite-repos.tgz

3. Create a Yum configuration file under /etc/yum.repos.d, such as satellite-disconnected.repo, with the following contents:

   [rhel-8-for-x86_64-baseos-rpms]
   name=Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)
   baseurl=file:///root/Satellite-repos/rhel-8-for-x86_64-baseos-rpms
   enabled=1
   
   [rhel-8-for-x86_64-appstream-rpms]
   name=Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)
   baseurl=file:///root/Satellite-repos/rhel-8-for-x86_64-appstream-rpms
   enabled=1
   
   [satellite-6.12-for-rhel-8-x86_64-rpms]
   name=Red Hat Satellite 6 for RHEL 8 Server RPMs x86_64
   baseurl=file:///root/Satellite-repos/satellite-6.12-for-rhel-8-x86_64-rpms
   enabled=1
   
   [satellite-maintenance-6.12-for-rhel-8-x86_64-rpms]
   name=Red Hat Satellite Maintenance 6 for RHEL 8 Server RPMs x86_64
   baseurl=file:///root/Satellite-repos/satellite-maintenance-6.12-for-rhel-8-x86_64-rpms
   enabled=1

4. In the configuration file, replace the /root/Satellite-repos with the extracted location.

5. Check the available versions to confirm the next minor version is listed:

   # satellite-maintain upgrade list-versions

6. Use the health check option to determine if the system is ready for upgrade. On first use of this command, satellite-maintain prompts you to enter the hammer admin user credentials and saves them in the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

   # satellite-maintain upgrade check --whitelist="check-upstream-repository,repositories-validate" --target-version 6.12.z

7. Review the results and address any highlighted error conditions before performing the upgrade.

8. Because of the lengthy update time, use a utility such as tmux to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously.

   If you lose connection to the command shell where the upgrade command is running, you can see the logged messages in the /var/log/foreman-installer/satellite.log file to check if the process completed successfully.

9. Perform the upgrade:

   # satellite-maintain upgrade run --whitelist="check-upstream-repository,repositories-setup,repositories-validate" --target-version 6.12.z

10. Check when the kernel packages were last updated:

    # rpm -qa --last | grep kernel

11. Optional: If a kernel update occurred since the last reboot, stop Satellite services and reboot the system:

    # satellite-maintain service stop
    # reboot

Procedure

1. Ensure that the Satellite Maintenance repository is enabled:

   # subscription-manager repos --enable \
   satellite-maintenance-6.12-for-rhel-8-x86_64-rpms

2. Check the available versions to confirm the next minor version is listed:

   # satellite-maintain upgrade list-versions

3. Use the health check option to determine if the system is ready for upgrade:

   # satellite-maintain upgrade check --target-version 6.12.z

   Review the results and address any highlighted error conditions before performing the upgrade.

4. Because of the lengthy update time, use a utility such as tmux to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously.

   If you lose connection to the command shell where the upgrade command is running, you can see the logged messages in the /var/log/foreman-installer/capsule.log file to check if the process completed successfully.

5. Perform the upgrade:

   # satellite-maintain upgrade run --target-version 6.12.z

6. Check when the kernel packages were last updated:

   # rpm -qa --last | grep kernel

7. Optional: If a kernel update occurred since the last reboot, stop Satellite services and reboot the system:

   # satellite-maintain service stop
   # reboot