Chapter 3. Upgrading Red Hat Satellite

Upgrade Satellite Server

1. Create a backup.

   • On a virtual machine, take a snapshot.

   • On a physical machine, create a backup.

     For more information about backups, see Backing Up Satellite Server and Capsule Server in the Administering Red Hat Satellite 6.7 guide.

2. Optional: If you made manual edits to DNS or DHCP configuration in the /etc/zones.conf or /etc/dhcp/dhcpd.conf files, back up the configuration files because the installer only supports one domain or subnet, and therefore restoring changes from these backups might be required.

3. Optional: If you made manual edits to DNS or DHCP configuration files and do not want to overwrite the changes, enter the following command:

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

4. Optional: If you use PostgreSQL as an external database, on the PostgreSQL server, install the rh-postgresql12-postgresql-evr package, which is available from the rhel-7-server-satellite-6.8-rpms repository:

   # yum install rh-postgresql12-postgresql-evr

5. In the Satellite web UI, navigate to Hosts > Discovered hosts. On the Discovered Hosts page, power off and then delete the discovered hosts. From the Select an Organization menu, select each organization in turn and repeat the process to power off and delete the discovered hosts. Make a note to reboot these hosts when the upgrade is complete.

6. Ensure that the Satellite Maintenance repository is enabled:

   # subscription-manager repos --enable \
   rhel-7-server-satellite-maintenance-6-rpms

7. Ensure that the rubygem-foreman_maintain package that provides satellite-maintain is installed and up to date:

   # yum install rubygem-foreman_maintain

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

   # satellite-maintain upgrade list-versions

9. Use the health check option to determine if the system is ready for upgrade. When prompted, enter the hammer admin user credentials to configure satellite-maintain with hammer credentials. These changes are applied to the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

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

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

10. Because of the lengthy upgrade time, use a utility such as screen to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously. For more information about using the screen command, see How do I use the screen command? article in the Red Hat Knowledge Base.

    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.

11. Perform the upgrade:

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

12. Check when the kernel packages were last updated:

    # rpm -qa --last | grep kernel

13. Optional: If a kernel update occurred since the last reboot, stop the satellite-maintain services and reboot the system:

    # satellite-maintain service stop
    # reboot

14. If using a BASH shell, after a successful or failed upgrade, enter:

    # hash -d satellite-maintain service 2> /dev/null

15. 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 that you make.

16. If you make changes in the previous step, restart the satellite-maintain services.

    # satellite-maintain service restart

17. If you have the OpenSCAP plug-in installed, but do not have the default OpenSCAP content available, enter the following command:

    # foreman-rake foreman_openscap:bulk_upload:default

Upgrade Disconnected Satellite Server

1. Create a backup.

   • On a virtual machine, take a snapshot.
   • On a physical machine, create a backup.

2. A pre-upgrade script is available to detect conflicts and list hosts which have duplicate entries in Satellite Server that can be unregistered and deleted after upgrade. In addition, it will detect hosts which are not assigned to an organization. If a host is listed under Hosts > All hosts without an organization association and if a content host with same name has an organization already associated with it then the content host will automatically be unregistered. This can be avoided by associating such hosts to an organization before upgrading.

   Run the pre-upgrade check script to get a list of hosts that can be deleted after upgrading. If any unassociated hosts are found, associating them to an organization before upgrading is recommended.

   # foreman-rake katello:upgrade_check

   If the upgrade check reports a failure due to running tasks, then it is recommended that you wait for the tasks to complete. It is possible to cancel some tasks, but you should follow the guidance in the Red Hat Knowledgebase solution How to manage paused tasks on Red Hat Satellite 6 to understand which tasks are safe to cancel and which are not safe to cancel.

3. Optional: If you made manual edits to DNS or DHCP configuration in the /etc/zones.conf or /etc/dhcp/dhcpd.conf files, back up the configuration files because the installer only supports one domain or subnet, and therefore restoring changes from these backups might be required.

4. Optional: If you made manual edits to DNS or DHCP configuration files and do not want to overwrite the changes, enter the following command:

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

5. Optional: If you use PostgreSQL as an external database, on the PostgreSQL server, install the rh-postgresql12-postgresql-evr package, which is available from the rhel-7-server-satellite-6.8-rpms repository:

   # yum install rh-postgresql12-postgresql-evr

6. In the Satellite web UI, navigate to Hosts > Discovered hosts. If there are discovered hosts available, turn them off and then delete all entries under the Discovered hosts page. Select all other organizations in turn using the organization setting menu and repeat this action as required. Reboot these hosts after the upgrade has completed.
7. Make sure all external Capsule Servers are assigned to an organization, otherwise they might get unregistered due to host-unification changes.

8. Remove old repositories:

   # rm /etc/yum.repos.d/*

9. Stop the satellite-maintain services.

   # satellite-maintain service stop

10. Obtain the latest ISO files by following the Downloading the Binary DVD Images procedure in the Installing Satellite Server from a Disconnected Network guide.
11. Create directories to serve as a mount point, mount the ISO images, and configure the rhel7-server repository by following the Configuring the Base System with Offline Repositories procedure in the Installing Satellite Server from a Disconnected Network guide. Do not install or update any packages at this stage.

12. Configure the Satellite 6.8 repository from the ISO file.

    1. Copy the ISO file’s repository data file for the Red Hat Satellite packages:

       # cp /media/sat6/media.repo /etc/yum.repos.d/sat6.repo

    2. Edit the /etc/yum.repos.d/sat6.repo file:

       # vi /etc/yum.repos.d/sat6.repo

       1. Change the default InstallMedia repository name to Satellite-6.8:

          [Satellite-6.8]

       2. Add the baseurl directive:

          baseurl=file:///media/sat6/

13. Configure the Red Hat Software Collections repository from the ISO file.

    1. Copy the ISO file’s repository data file for Red Hat Software Collections packages:

       # cp /media/sat6/RHSCL/media.repo /etc/yum.repos.d/RHSCL.repo

    2. Edit the /etc/yum.repos.d/RHSCL.repo file:

       # vi /etc/yum.repos.d/RHSCL.repo

       1. Change the default InstallMedia repository name to RHSCL:

          [RHSCL]

       2. Add the baseurl directive:

          baseurl=file:///media/sat6/RHSCL/

14. Configure the Red Hat Satellite Maintenance repository from the ISO file.

    1. Copy the ISO file’s repository data file for Red Hat Satellite Maintenance packages:

       # cp /media/sat6/sat-maintenance/media.repo /etc/yum.repos.d/sat-maintenance.repo

    2. Edit the /etc/yum.repos.d/sat-maintenance.repo file:

       # vi /etc/yum.repos.d/sat-maintenance.repo

       1. Change the default InstallMedia repository name to Satellite-Maintenance:

          [Satellite-Maintenance]

       2. Add the baseurl directive:

          baseurl=file:///media/sat6/sat-maintenance/

15. Optional: If you have applied custom Apache server configurations, note that the custom configurations are reverted to the installation defaults when you perform the upgrade.

    To preview the changes that are applied during the upgrade, enter the satellite-installer command with the --noop (no operation) option. These changes are applied when you enter the satellite-maintain upgrade command in a following step.

    1. Add the following line to the /etc/httpd/conf/httpd.conf configuration file.

       Include /etc/httpd/conf.modules.d/*.conf

    2. Restart the httpd service.

       # systemctl restart httpd

    3. Start the postgresql and rh-mongodb34-mongod database services.

       # systemctl start postgresql
       # systemctl start rh-mongodb34-mongod

    4. Enter the satellite-installer command with the --noop option:

       # satellite-installer --scenario satellite --upgrade --verbose --noop

       Review the /var/log/foreman-installer/satellite.log to preview the changes that are applied during the upgrade. Locate the +++ and --- symbols that indicate the changes to the configurations files. Although entering the satellite-installer command with the --noop option does not apply any changes to your Satellite, some Puppet resources in the module expect changes to be applied and might display failure messages.

    5. Stop the satellite-maintain services:

       # satellite-maintain service stop

16. Because of the lengthy upgrade time, use a utility such as screen to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously. For more information about using the screen command, see How do I use the screen command? article in the Red Hat Knowledge Base.

    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.

17. Ensure that the rubygem-foreman_maintain package that provides satellite-maintain is installed and up to date:

    # yum install rubygem-foreman_maintain

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

    # satellite-maintain upgrade list-versions

19. Use the health check option to determine if the system is ready for upgrade. When prompted, enter the hammer admin user credentials to configure satellite-maintain with hammer credentials. These changes are applied to the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

    # satellite-maintain upgrade check --target-version 6.8 \
    --whitelist="repositories-validate,repositories-setup"

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

20. Perform the upgrade:

    # satellite-maintain upgrade run --target-version 6.8 \
    --whitelist="repositories-validate,repositories-setup"

    Warning

    If you run the command from a directory containing a config subdirectory, you will encounter the following error:

    ERROR: Scenario (config/satellite.yaml) was not found, can not continue.

    In such a case, change directory, for example to the root user’s home directory, and run the command again.

    If the script fails due to missing or outdated packages, you must download and install these separately. For more information, see the Resolving Package Dependency Errors section in the Installing Satellite Server from a Disconnected Network guide.

21. If using a BASH shell, after a successful or failed upgrade, enter:

    # hash -d satellite-maintain service 2> /dev/null

22. Check when the kernel packages were last updated:

    # rpm -qa --last | grep kernel

23. Optional: If a kernel update occurred since the last reboot, stop the satellite-maintain services and reboot the system:

    # satellite-maintain service stop
    # reboot

24. 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 that you made.

25. If you make changes in the previous step, restart the satellite-maintain services.

    # satellite-maintain service restart

26. If you have the OpenSCAP plug-in installed, but do not have the default OpenSCAP content available, enter the following command.

    # foreman-rake foreman_openscap:bulk_upload:default

27. In the Satellite web UI, go to Configure > Discovery Rules and associate selected organizations and locations with discovery rules.