Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Migrating Red Hat Update Infrastructure

Red Hat Update Infrastructure 4

Migrating to Red Hat Update Infrastructure 4 and upgrading to the latest version of Red Hat Update Infrastructure

Red Hat Customer Content Services

Abstract

This document lists the requirements and provides detailed instructions to help cloud providers migrate to Red Hat Update Infrastructure 4 (RHUI 4). It also provides detailed instructions to upgrade to the latest version of Red Hat Update Infrastructure.

Making open source more inclusive
Copy link

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

After you have installed Red Hat Update Infrastructure (RHUI) 4, it is possible to migrate your existing repositories from RHUI 3 to RHUI 4.

Migration enables RHUI 3 repositories on your RHUI 4 machine. However, it does not migrate the RPM contents or the RPM data. You must re-synchronize these repositories automatically or manually after the migration is complete.

Before you begin the migration process, note the following recommendations and limitations:

  • You cannot upgrade directly from RHUI 3 to RHUI 4. You must install RHUI 4 alongside your current RHUI 3 installation. You can then synchronize the RHUI 3 repositories on RHUI 4 using the same CA certificate from RHUI 3. This also ensures that old clients are able to access content from RHUI 4. Finally, you can change the RHUI 3 load balancer to point to the RHUI 4 CDS nodes.
  • You cannot use LEAPP to upgrade from RHUI 3 to RHUI 4. You must set up RHUI 4 alongside RHUI 3 and then migrate the RHUI data.
  • With RHUI 4, you can use any version of a load balancer, before and after migration. For example, you can use a RHEL 7 version of an HAProxy node from RHUI 3 with a RHUI 4 instance instead of a RHEL 8 version from RHUI 4.

  • To route to two different instances of RHUI, for example a RHUI 3 instance and a RHUI 4 instance, from one address or load balancer, you must set up a RHUI 4 instance so that it can take over all the content from the old RHUI 3 instance.

    However, a configuration where you run both RHUI3 and RHUI4 instances using a single address or a load balancer is not recommended. You can encounter a number of problems ranging from SSL certificate conflicts to repository path changes in between requests.

Migration uses the rhui-manager utility, available in your Red Hat Update Infrastructure (RHUI) 4 installation, to transfer your repositories from RHUI 3 to RHUI 4. You must install RHUI 4 before migrating your repositories.

The rhui-manager utility uses the sub-command migration and the following mandatory arguments:

  1. --hostname - The hostname of the remote RHUI 3 RHUA node
  2. --password - The rhui-manager password of the remote RHUI 3 RHUA node
Note

You must add the public part of an SSH key pair for the current user on the RHUI 4 machine to the .ssh/authorized_keys file on the RHUI 3 machine.

Although a default path is provided, it is likely that the path to your keyfile may not match the provided default. You may have to add the following argument to your migration command:

  • --keyfile_path - The path to the SSH private key on the RHUI 4 machine. The default path is /root/.ssh/id_rsa_rhua.

1.2. Migrating repositories from RHUI 3 to RHUI 4
Copy link

The following procedure explains how to migrate your RHUI 3 repositories to RHUI 4.

Prerequisites

  • Ensure that RHUI 4 is installed on your destination machine. For more information, see Installing Red Hat Update Infrastructure.
  • Ensure that you have the necessary credentials to access your RHUI 3 machine.

  • Ensure that a RHUI entitlement certificate is available on your RHUI 4 machine. In case it is not, run the following command to add the certificate: 

    # rhui-subscription-sync
    Copy to Clipboard Toggle word wrap

  • Optional: Ensure that you have cached the repository information to speed up the migration. You can do so using the following command: 

    # rhui-manager repo unused
    Copy to Clipboard Toggle word wrap

Procedure

  1. On your RHUI 4 machine, use the rhui-manager utility to begin the migration: 

    # rhui-manager migrate --hostname my-rhui3-rhua.example.com --password <your_password> --keyfile_path ~/.ssh/id_rsa_rhua
    Copy to Clipboard Toggle word wrap

  2. If the migration fails with an error similar to the following, a conflict has occurred between the repositories that you are trying to migrate and those that already exist on your RHUI 4 machine. 

    ERROR: Configured repos detected. Use --force to ignore. Exiting
    Copy to Clipboard Toggle word wrap

    To fix this, use the --force argument to run the migration.

    Note

    Using the --force argument deletes and recreates any repositories whose IDs match the RHUI 3 repository IDs. 

    # rhui-manager migrate --hostname my-rhui3-rhua.example.com --password <your_password> --keyfile_path ~/.ssh/id_rsa_rhua --force
    Copy to Clipboard Toggle word wrap

  3. Optional: If custom repositories were migrated, you need to manually upload the RPM content to them.

    For detailed instructions on how to do so, see the upload_rpms_document.txt file located in the /root/.rhui/migration/ directory.

Verification

  • Run the following command and verify whether the RHUI 3 repositories are now available on your RHUI 4 machine: 

    # rhui-manager repo list
    Copy to Clipboard Toggle word wrap

1.3. Migrating client RPMs from RHUI 3 to RHUI 4
Copy link

After you upgrade to RHUI 4, you might want to keep using your RHUI 3 client RPMs. You can do so by migrating the RHUI 3 certificate authority (CA) to your RHUI 4 system and and configuring RHUI 4 to use the CA.

Prerequisites

  • Ensure that you have the necessary credentials to access your RHUI 3 machine.

Procedure

  1. Copy the CA certificate and CA key from RHUI 3 to RHUI 4.

    • The certificate, rhui-default-ca.crt, is located in the /etc/pki/rhui/certs/ directory.
    • The key, rhui-default-ca.key, is located in the /etc/pki/rhui/private/ directory.

  2. On the RHUA node, rerun rhui-installer and specify the CA copied from the RHUI 3 installation. 

    # rhui-installer --rerun --remote-fs-server <address> --rhua-hostname <RHUA hostname> --cds-lb-hostname <HAProxy hostname> --user-supplied-rhui-ca-crt rhui-default-ca.crt --user-supplied-rhui-ca-key rhui-default-ca.key
    Copy to Clipboard Toggle word wrap
    • --remote-fs-server: The remote mountpoint for the shared file system.
    • --rhua-hostname: The hostname of the RHUA node. You must specify the name as a Fully Qualified Domain Name (FQDN).
    • --cds-lb-hostname: The name of the load balancer that clients use to access the CDS. You must specify the name as a Fully Qualified Domain Name (FQDN).
    • --user-supplied-rhui-ca-crt rhui-default-ca.crt: The CA certificate copied from the RHUI 3 installation.

    • --user-supplied—​rhui-ca-key rhui-default-ca.key: The CA key copied from the RHUI 3 installation.

      Note

      You can use the RHUI 3 HAProxy if it is configured to use the new RHUI 4 CDS nodes. Or, you can use a new RHUI 4 HAProxy by updating the DNS so that the RHUI 3 HAProxy hostname points to the new HAProxy.

Red Hat Update Infrastructure (RHUI) is periodically upgraded to introduce bug fixes, enhancements, and fix common vulnerabilities and exposures.

Important

Red Hat recommends keeping your installation up to date by applying the latest RHUI updates when they are released.

2.1. Updating Red Hat Update Infrastructure
Copy link

To update your instance of Red Hat Update Infrastructure (RHUI) to the latest version, you must take the following steps.

Prerequisites

  • Root access to the RHUA node.
  • All of your RHUI nodes are subscribed and are using the correct repositories as desribed in Installing Red Hat Update Infrastructure.
  • Repository synchronization tasks are scheduled to run after the update is complete. Tasks that run while the update is in progress might be aborted. For more information see Known Issues.
Important

The rhui-installer supports upgrading the version of PostgreSQL. Before doing that it is important to back up your PostgreSQL database.

How to back up your PostgreSQL database is described in Chapter 12. Backing up and restoring Red Hat Update Infrastructure of the Configuring and Managing Red Hat Update Infrastructure documentation.

Important

Do not attempt to keep the RHUA node up to date by simply applying all available package updates. Doing so may break the RHUA. Updating the RHUA must be performed exclusively by following the procedure below.

If you only want to apply OS updates and exclude any RHUI package updates, exclude the RHUI repository in your update transaction. For example, on the command line, run the following command: 

# dnf --disablerepo=rhui-4-for-rhel-8-x86_64-rpms update
Copy to Clipboard Toggle word wrap

You may need to reboot the system or restart RHUI services after this transaction.

Note

To keep the CDS nodes up to date, it is not sufficient to apply available package updates on them. Because various configurations are modified in many RHUI versions, it is necessary to reapply the configurations by following the procedure below.

Procedure

  1. On the RHUA node, update RHUI Installer. 

    # dnf update rhui-installer
    Copy to Clipboard Toggle word wrap

  2. Run RHUI Installer:

    • If you are updating from RHUI 4.10 and you have already started using the on_demand synchronization policy, copy the relevant part of the configuration to the custom configuration file as described in Preserving Custom Configuration After RHUI Upgrade.

    • Run the rhui-installer command as follows:

      • If you are updating from RHUI 4.1.0 or older, you must specify your custom RHUI CA along with the rerun option: 

        # rhui-installer --rerun --user-supplied-rhui-ca-crt <custom_RHUI_CA.crt> --user-supplied-rhui-ca-key <custom_RHUI_CA_key>
        Copy to Clipboard Toggle word wrap

      • If you are updating from RHUI 4.1.1 or newer, run RHUI Installer with just the rerun option: 

        # rhui-installer --rerun
        Copy to Clipboard Toggle word wrap

      • If you are updating the version of PostgreSQL from 12 to 15 you must specify this using the --postgresql-version option along with the rerun option: 

        # rhui-installer --postgresql-version 15 --rerun
        Copy to Clipboard Toggle word wrap

  3. Optional: In some environments, rhui-installer fails to rerun and displays the following error instead: 

    There have been identified artifacts with forbidden checksum md5. Run pulpcore-manager handle-artifact-checksums first to unset forbidden checksums.
    Copy to Clipboard Toggle word wrap

    To fix this error:

    1. Run the following command on the RHUA node: 

      # env PULP_SETTINGS=/etc/pulp/settings.py pulpcore-manager handle-artifact-checksums
      Copy to Clipboard Toggle word wrap
    2. Run rhui-installer with the rerun option.

  4. Check if the rhui-installer installed updated packages.

    By default the rhui-installer will install any available RHEL package updates. RHUA must be rebooted if any package has been updated that requires rebooting. The command to check this is: 

    # needs-restarting -r
    Copy to Clipboard Toggle word wrap
    Note

    This command is part of the yum-utils package, which must be installed on the RHUA for the command to be available.

  5. To apply updated templates and playbooks, reinstall all of the CDS nodes.

    This will also install any available RHEL package updates. To avoid that, run the below command with the --no_update flag. 

    # rhui-manager --noninteractive cds reinstall --all
    Copy to Clipboard Toggle word wrap

  6. Check if updated packages were installed on the CDS nodes.

    If package updates were installed the CDS nodes may need to be rebooted. To check if your CDS nodes do need to be rebooted, log on to them and run this command: 

    # needs-restarting -r
    Copy to Clipboard Toggle word wrap
    Note

    This command is part of the yum-utils package, which must be installed on the CDS for the command to be available.

  7. Log in to RHUI Manager. 

    # rhui-manager
    Copy to Clipboard Toggle word wrap

Verification

  • On the RHUA node, run the following command and verify whether the latest version of RHUI is installed. 

    # rpm -q rhui-tools
    Copy to Clipboard Toggle word wrap

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, 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, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
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