Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Upgrading Red Hat Satellite

Upgrading Satellite includes upgrading your Satellite Server, synchronizing the required repositories, and upgrading Capsule Servers.

3.1. Upgrading your Satellite Server
Copy link

Upgrading a connected Satellite Server includes backing up the server, updating the system and Satellite configuration, and performing the upgrade.

Warning

Note that the satellite-installer is executed during an upgrade or update. Any files managed by satellite-installer are overwritten. Check if you have any manual changes that would be overwritten by satellite-installer. You can use the --noop option with the satellite-installer to test for changes. For more information, see the Red Hat Knowledgebase solution How to use the noop option to check for changes in Satellite config files during an upgrade.

If you use the Red Hat Lightspeed advisor service in Satellite, the following process upgrades to Red Hat Lightspeed in Satellite. The satellite-maintain tool pulls the container images of Red Hat Lightspeed in Satellite automatically.

Prerequisites

  • If you made manual edits to your DNS or DHCP configuration in the /etc/zones.conf or /etc/dhcp/dhcpd.conf files, ensure DNS and DHCP configuration management is disabled: 

    # satellite-installer \
--foreman-proxy-dhcp-managed false \
--foreman-proxy-dns-managed false

    This prevents the upgrade process from overwriting your DNS and DHCP configuration.

  • If you use Red Hat Lightspeed advisor service in Satellite in your environment, ensure you are logged in to registry.redhat.io so that the latest container images can be downloaded: 

    # podman login --authfile /etc/foreman/registry-auth.json registry.redhat.io

Procedure

  1. Create a backup of your Satellite Server. The backup can be a virtual machine (VM) snapshot or a regular full backup. For more information, see Backing up Satellite Server and Capsule Server in Administering Red Hat Satellite.

  2. Ensure that the Satellite Maintenance repository is enabled: 

    # subscription-manager repos --enable \
satellite-maintenance-6.18-for-rhel-9-x86_64-rpms

  3. Upgrade the satellite-maintain utility to its latest version: 

    # satellite-maintain self-upgrade

  4. Determine whether your system is ready for Satellite upgrade: 

    # satellite-maintain upgrade check

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

    Note

    The satellite-maintain upgrade check might prompt you for the Hammer admin user credentials. These changes are applied to the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

  5. Run the Satellite Server upgrade command. Because of the lengthy upgrade time, consider using a utility such as tmux. For more information, see Section 2.3, “Following the progress of the upgrade”. 

    # satellite-maintain upgrade run

  6. If the satellite-maintain command told you to reboot, then reboot the system: 

    # reboot

  7. Perform the following post-upgrade tasks to ensure your environment is adjusted to any changes applied during the upgrade.

    1. Verify whether the default templates changed during the upgrade. Update any custom templates that you created by cloning a default template to reflect these changes.

      Note

      Use custom provisioning snippets to execute custom code before or after the provisioning process instead of cloning default templates. You can avoid recreating cloned templates if you use custom provisioning snippets. For more information about configuring custom provisioning snippets, see Running custom code during host provisioning by using Satellite web UI in Provisioning hosts.

    2. If your Satellite shows any discovered hosts, reboot them:

      1. In the Satellite web UI, navigate to Hosts > Discovered hosts.
      2. Select Any Organization to display all discovered hosts.
      3. Reboot all discovered hosts.

3.2. Synchronizing the new repositories
Copy link

You must enable and synchronize the new 6.18 repositories before you can upgrade Capsule Servers and Satellite clients.

Procedure

  1. In the Satellite web UI, navigate to Content > Red Hat Repositories.

  2. Enable the following repositories:

    • Repositories required to upgrade Capsule Servers:

      • Red Hat Satellite Capsule 6.18 (for RHEL 9 x86_64) (RPMs)
      • Red Hat Satellite Maintenance 6.18 (for RHEL 9 x86_64) (RPMs)
      • Red Hat Enterprise Linux 9 (for x86_64 – BaseOS) (RPMs)
      • Red Hat Enterprise Linux 9 (for x86_64 – AppStream) (RPMs)

    • Repositories required to upgrade Satellite clients:

      • Red Hat Satellite Client 6 for each Red Hat Enterprise Linux version your clients are using
  3. In the Satellite web UI, navigate to Content > Sync Status.

  4. Synchronize the following repositories:

    • All repositories for version 6.18
    • Red Hat Satellite Client 6 repositories for each Red Hat Enterprise Linux version your clients are using

Troubleshooting

  • Refresh the Red Hat subscription manifest to resolve issues with synchronizing repositories. In the Satellite web UI, navigate to Content > Subscriptions > Manage Manifest > Refresh.

    Warning

    Do not delete the manifest from the Customer Portal or in the Satellite web UI. Deleting your manifest removes all the entitlements of your hosts.

Additional resources

3.3. Upgrading Capsule Servers
Copy link

After upgrading your Satellite Server and synchronizing the required repositories, you can upgrade your Capsule Servers.

Note

You can use the Capsule Upgrade Playbook job template to upgrade Capsule Servers remotely. For more information about running remote jobs based on templates, see Configuring and setting up remote jobs in Managing hosts.

Prerequisites

Procedure

  1. Create a backup of your Capsule Server. The backup can be a virtual machine (VM) snapshot or a regular full backup. For more information, see Backing up Satellite Server and Capsule Server in Administering Red Hat Satellite.

  2. Ensure that the Satellite Maintenance repository is enabled: 

    # subscription-manager repos \
 --enable satellite-maintenance-6.18-for-rhel-9-x86_64-rpms

  3. Upgrade the satellite-maintain utility on the Capsule Server to its latest version: 

    # satellite-maintain self-upgrade

  4. Determine whether Capsule Server is ready for the upgrade: 

    # satellite-maintain upgrade check

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

  5. Run the Satellite upgrade command. Because of the lengthy upgrade time, consider using a utility such as tmux. For more information, see Section 2.3, “Following the progress of the upgrade”. 

    # satellite-maintain upgrade run

  6. If the satellite-maintain command told you to reboot, then reboot the system: 

    # reboot

If your Satellite uses an external database, you can upgrade the database from RHEL 8 to RHEL 9. You can upgrade the operating system while upgrading Satellite from 6.17 to 6.18.

Prerequisites

Procedure

  1. Create a backup of your existing external database.
  2. Restore the backup on the new Red Hat Enterprise Linux 9 server.

  3. Verify that Satellite can reach the new database: 

    # PGPASSWORD='My_Foreman_Database_Password' psql -h postgres.example.com -p 5432 -U foreman -d foreman -c "SELECT 1 as ping"

  4. If your Satellite Server can reach the new database server by using the old name, you do not need to make any further changes. 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

If you use Red Hat Lightspeed in Satellite, you must refresh Red Hat Lightspeed in Satellite registration of your hosts to keep using services of Red Hat Lightspeed in Satellite after upgrading Satellite Server.

Prerequisites

  • You have root access on your hosts.

Procedure

  • On your hosts, refresh insights-client registration: 

    # insights-client --register --force

    You can use remote execution to run this command on your hosts.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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

Legal Notice

Theme

© 2026 Red HatBack to top