Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Upgrading connected Red Hat Satellite to 6.18

Red Hat Satellite 6.18

Upgrade Satellite Server and Capsule

Red Hat Satellite Documentation Team

Abstract

This guide describes how to upgrade a connected Red Hat Satellite Server and Capsule Server.

Providing feedback on Red Hat documentation
Copy link

We appreciate your feedback on our documentation. Let us know how we can improve it.

Use the Create Issue form in Red Hat Jira to provide your feedback. The Jira issue is created in the Red Hat Satellite Jira project, where you can track its progress.

Procedure

  1. Log in to Atlassian Jira.
  2. Click the following link: Create Issue.
  3. Complete the Summary, Description, and Reporter fields. In the Description field, include the documentation URL, chapter or section number, and a detailed description of the issue. Do not modify any other fields in the form.
  4. Click Create.

Chapter 1. Red Hat Satellite Upgrade Helper app
Copy link

You can use the Red Hat Satellite Upgrade Helper app to obtain customized upgrade instructions.

For interactive instructions for performing the upgrade, you can use the Red Hat Satellite Upgrade Helper on the Red Hat Customer Portal. This application provides upgrade instructions customized for your current version number of Satellite. As a result, you receive instructions that are specific to your upgrade path, as well as steps to prevent known issues. For more information, see Satellite Upgrade Helper on the Red Hat Customer Portal.

Additional resources

Chapter 2. Preparing for Satellite upgrade
Copy link

Review the following available upgrade paths and planning considerations before upgrading your current Red Hat Satellite installation to Red Hat Satellite 6.18.

2.1. Upgrade path overview
Copy link

You can upgrade from Red Hat Satellite 6.17 to Red Hat Satellite 6.18.

The upgrade process includes the following high-level steps:

  1. Ensuring that your Satellite Servers and Capsule Servers are running on Satellite 6.17.

  2. Upgrading your Satellite Server:

    1. Upgrading your Satellite Server to 6.18.
    2. Synchronizing the new 6.18 repositories.
  3. Upgrading your Capsule Servers to 6.18.

You can upgrade your Capsules separately over multiple maintenance windows because versions 6.17 and 6.16 remain compatible with your upgraded Satellite Server 6.18. Upgrading Capsules separately can be useful in the following situations:

  • If you want to have several smaller outage windows instead of one larger window.
  • If Capsules in your organization are managed by several teams and are located in different locations.
  • 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.

Capsules at version 6.17 and 6.16 retain all of their previous functionality. New functionality added in the 6.18 release is available only after you upgrade your Capsules to 6.18.

2.2. Planning Satellite upgrade
Copy link

Upgrading to Satellite 6.18 affects your entire Satellite infrastructure. Plan carefully before proceeding.

  • Read the Red Hat Satellite 6.18 Release notes.
  • Consider whether any of your integrations need updating. Some Satellite API endpoints, Hammer CLI commands, and modules from the Satellite Ansible Collection can differ between versions of Satellite. For information about changes in these tools, see the Red Hat Satellite 6.18 Release notes.
  • Optional: You can test the upgrade on a clone of your Satellite Server. After you successfully test the upgrade on the clone, you can repeat the upgrade on your primary Satellite Server and discard the clone. Alternately, you can promote the clone to your primary Satellite Server and discard the previous primary Satellite Server. For more information, see Cloning Satellite Server in Administering Red Hat Satellite.
  • You can upgrade to Satellite 6.18 from any Satellite 6.17 patch version.

  • Satellite services are shut down during the upgrade. Ensure to plan for the required downtime. The upgrade process duration varies depending on your hardware configuration, network speed, and the amount of data that is stored on the server:

    • On average installations, upgrading Satellite Server takes up to 30 minutes and upgrading a single Capsule Server takes up to 10 minutes.
    • On very large installations, upgrading Satellite Server can take up to 1 – 2 hours and upgrading a single Capsule Server can take up to 15 – 30 minutes.

2.3. Following the progress of the upgrade
Copy link

Using a utility such as tmux helps follow the progress of the upgrade without the need to maintain a continuous shell session.

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 logs in /var/log/foreman-installer/satellite.log to check if the process completed successfully.

For more information about using tmux, see the tmux(1) man page on your system.

Chapter 3. Upgrading Red Hat Satellite
Copy link

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

  • The base system of the Capsule is registered to the newly upgraded Satellite Server.
  • Ensure that you synchronize the required repositories on Satellite Server. For more information, see Section 3.2, “Synchronizing the new repositories”.
  • If the Capsule Server is registered to a content view, add the Capsule 6.18 repositories to the content view. Publish and promote a new version of the content view. For more information, see Managing content views in Managing content.

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

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.

Appendix A. Troubleshooting permission issues
Copy link

Satellite upgrades perform pre-upgrade checks. If the pre-upgrade check discovers permission issues, you must identify and remedy the issues before proceeding with the upgrade.

A permission issue might look similar to the following one: 

2024-01-29T20:50:09 [W|app|] Could not create role 'Ansible Roles Manager': ERF73-0602 [Foreman::PermissionMissingException]: some permissions were not found:

If you see an error like this on your Satellite Server, identify and remedy the permission issues.

Procedure

  1. On your Satellite Server, identify permission issues: 

    # satellite-maintain health check --label duplicate_permissions

  2. Fix permission issues: 

    # foreman-rake db:seed

Verification

  • Rerun the check to ensure no permission issues remain: 

    # satellite-maintain health check --label duplicate_permissions

Legal Notice
Copy link

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.
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

© 2026 Red HatBack to top