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 and Restoring Satellite Server and Capsule Server in the Administering Red Hat Satellite 6.4 guide.

2. Back up the DNS and DHCP configuration files /etc/zones.conf and /etc/dhcp/dhcpd.conf as the installer only supports one domain or subnet, and therefore restoring changes from these backups might be required.

3. If you have 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. 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.

5. Refresh your subscription:

   # subscription-manager refresh

6. Enable the Satellite Maintenance and Red Hat Enterprise Linux Ansible repositories:

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

7. Enter the following command to install foreman-maintain or to update it to the latest version:

   # yum install rubygem-foreman_maintain

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

   # foreman-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 foreman-maintain with hammer credentials. These changes are applied to the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

   # foreman-maintain upgrade check --target-version 6.5

   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:

    # foreman-maintain upgrade run --target-version 6.5

12. Check when the kernel packages were last updated:

    # rpm -qa --last | grep kernel

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

    # reboot

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

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

15. 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 foreman-maintain services.

    # foreman-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. Back up the DNS and DHCP configuration files /etc/zones.conf and /etc/dhcp/dhcpd.conf as the installer only supports one domain or subnet, and therefore restoring changes from these backups might be required.

4. If you have made manual edits to DNS or DHCP configuration files and do not want to overwrite the changes, run the installer script as follows:

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

5. 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.
6. Make sure all external Capsule Servers are assigned to an organization, otherwise they might get unregistered due to host-unification changes.

7. Remove old repositories:

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

8. Stop the foreman-maintain services.

   # foreman-maintain service stop

9. Obtain the latest ISO files by following the Downloading the Binary DVD Images procedure in the Installing Satellite Server from a Disconnected Network guide.
10. 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.

11. Configure the Satellite 6.5 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.5:

          [Satellite-6.5]

       2. Add the baseurl directive:

          baseurl=file:///media/sat6/

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

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

14. If you have custom Apache server configurations, they will be reverted to the installation defaults in the next step. If you want to see what will be changed when you perform the upgrade, you can enter the upgrade command with the --noop (no operation) option and review the changes that will be applied when you enter the upgrade command in the following step. If you choose not to do this test, skip to the next step now. Alternatively, proceed as follows:

    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. Run the installer script with the --noop option:

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

       Review the /var/log/foreman-installer/satellite.log to see what changes would be applied if the --noop option was omitted. Look for the +++ and --- symbols indicating changes to configurations files. Because the above "no operation" option does not actually create the files, and some Puppet resources in the module expect them to be there, some failure messages are to be expected.

    5. Stop the foreman-maintain services:

       # foreman-maintain service stop

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

16. Enter the following command to install foreman-maintain or to update it to the latest version:

    # yum install rubygem-foreman_maintain

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

    # foreman-maintain upgrade list-versions

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

    # foreman-maintain upgrade check --target-version 6.5 \
    --whitelist="repositories-validate,repositories-setup"

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

19. Perform the upgrade:

    # foreman-maintain upgrade run --target-version 6.5 \
    --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 Downloading Packages Manually section in the Installing Satellite Server from a Disconnected Network guide.

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

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

21. Check when the kernel packages were last updated:

    # rpm -qa --last | grep kernel

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

    # reboot

23. Check and restore any changes required to the DNS and DHCP configuration files using the backups that you make.

24. If you make changes in the previous step, restart the foreman-maintain services.

    # foreman-maintain service restart

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

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