Chapter 2. Upgrading Red Hat Satellite

1. Verify whether Satellite Server’s base system is managed by Foreman:

   1. In the Satellite web UI, navigate to Hosts > All Hosts.
   2. On the host that you want to migrate, click Edit.
   3. In the upper right of the screen, if you can view the Unmanage host button, click Unmanage host.

2. On the base system that you want to migrate, enter the following commands to remove the subscriptions and unregister the host:

   # subscription-manager remove --all
   # subscription-manager unregister

1. Go to Red Hat Customer Portal and log in.
2. Click DOWNLOADS.
3. Select Red Hat Enterprise Linux.

4. Ensure that you have the correct product and version for your environment.

   • Product Variant is set to Red Hat Enterprise Linux Server.
   • Version is set to the minor version of the product you plan to use as the base system.
   • Architecture is set to the 64 bit version.
5. On the Product Software tab, download the Binary DVD image for the version you want to use.
6. Click DOWNLOADS and select Red Hat Satellite.

7. Ensure that you have the correct product and version for your environment.

   • Product Variant is set to Red Hat Satellite.
   • Version is set to the minor version of the product you want use.
   • Architecture is set to the 64 bit version.
8. On the Product Software tab, download the Binary DVD image for the version you want to use.

9. Copy the ISO files to the Satellite base system or other accessible storage device.

   # scp localfile username@hostname:remotefile

1. Create a mount point.

   # mkdir /media/rhel7-server

2. Mount the ISO image for Red Hat Enterprise Linux to the mount point.

   # mount -o loop rhel7-Server-DVD.iso /media/rhel7-server

3. Copy the ISO file’s repository data file.

   # cp /media/rhel7-server/media.repo /etc/yum.repos.d/rhel7-server.repo

4. Edit the repository data file and add the baseurl directive.

   baseurl=file:///media/rhel7-server/

   The following example shows the repository data file using Red Hat Enterprise Linux 7.2:

   # vi /etc/yum.repos.d/rhel7-server.repo
   [InstallMedia]
   name=Red Hat Enterprise Linux 7.2
   mediaid=1446216863.790260
   metadata_expire=-1
   gpgcheck=0
   cost=500
   baseurl=file:///media/rhel7-server/

5. Verify that the repository is configured.

   # yum repolist
   Loaded plugins: product-id, search-disabled-repos, subscription-manager
   This system is not registered to Red Hat Subscription Management. You can use subscription-manager to register.
   repo id          repo name                       status
   InstallMedia     Red Hat Enterprise Linux 7.2    4,620

6. Create a mount point:

   # mkdir /media/sat6

7. Mount the ISO image for Red Hat Satellite Server to the mount point.

   # mount -o loop sat6-DVD.iso /media/sat6

8. Change to the directory where the Satellite ISO is mounted.

   # cd /media/sat6/

9. Stop Katello services.

   # katello-service stop

10. Run the installer script in the mounted directory.

    # ./install_packages

    If the script fails because of missing or outdated packages, you must download and install these separately. See Section 2.2.4, “Downloading Packages Manually” for instructions.

    If the script fails because of installed packages being newer than those required, enter yum distribution-synchronization to downgrade the installed packages to the versions that come from the Red Hat Enterprise Linux ISO, then run the installation script again. This occurs if you have repositories configured whose source is not the Red Hat Enterprise Linux ISO. Use of such repositories is an unsupported configuration.

11. Disable the ISO based repositories to avoid conflicts with repositories provided by Satellite Server.

    1. Install yum-config-manager:

       # yum install yum-utils

    2. Disable the ISO based repositories:

       # yum-config-manager --disable InstallMedia --disable satellite-local --disable scl-local --disable satellite-puppet4

    3. Confirm yum repositories are disabled:

       # yum repolist

1. Go to Red Hat Customer Portal and log in.
2. Click DOWNLOADS.
3. Select RPM Package Search and search for the required package.
4. Locate the package suitable for your architecture and download it to the system where Satellite is installed.
5. Optional: Remove ?auth= and the following authentication hash from after the RPM package name.
6. Use yum localinstall to install the required packages simultaneously.

1. Back up the source Satellite Server or Capsule Server.
2. Stop all Satellite services.
3. Copy Satellite data to the target server.
4. Shut down the source Satellite Server or Capsule Server.
5. Migrate the source Satellite Server or Capsule Server.
6. Finalize the target Satellite Server or Capsule Server configuration.
7. Decommission the source Satellite Server or Capsule Server.

1. On the source server, identify the current Red Hat Satellite subscription.

   # subscription-manager list --consumed \
   --matches 'Red Hat Satellite'|grep "Pool ID:"|awk '{print $3}'

   Note the Red Hat Satellite subscription pool ID because you need this in a later step.

2. On the source server, remove the Red Hat Satellite subscription.

   # subscription-manager remove --serial=$(subscription-manager list \
   --consumed \
   --matches 'Red Hat Satellite'|grep "Serial:"|awk '{print $2}')

3. On the source server, perform a backup and copy the Pulp data to the target server. Estimate the size of the Pulp data on your Satellite server to decide whether to include the Pulp data in the backup or not:

   # du -sh /var/lib/pulp/

   If you have less than 500 GB of Pulp data

   1. Perform an online backup with MongoDB and PostgreSQL databases active including the Pulp data:

      # katello-service stop
      # katello-service start --only mongod,postgresql
      # katello-backup --online-backup /backup --assumeyes

      In this example the backup files are output to the directory /backup.

   2. Stop and disable all Satellite services:

      # katello-service stop
      # for i in $(katello-service list| awk '{print $1}'); do chkconfig $i off;done

   3. Copy the Pulp data to the target server:

      # scp /backup/pulp_data.tar root@target_server.example.com:/backup/

   4. On Satellite 6.3.1 and earlier, copy the Qpid data to the target server:

      # rsync --archive --partial --progress --compress \
      /var/lib/qpidd target_server.example.com:/var/lib/qpidd

   If you have more than 500 GB of Pulp data

   1. Perform an online backup with MongoDB and PostgreSQL databases active excluding the Pulp data:

      # katello-service stop
      # katello-service start --only mongod,postgresql
      # katello-backup --online-backup --skip-pulp-content /backup --assumeyes

      In this example the backup files are output to the directory /backup.

   2. Stop and disable all Satellite services:

      # katello-service stop
      # for i in $(katello-service list| awk '{print $1}'); do chkconfig $i off;done

   3. Copy the Pulp data to the target server:

      # rsync --archive --partial --progress --compress \
      /var/lib/pulp target_server.example.com:/var/lib/pulp

   4. On Satellite 6.3.1 and earlier, copy the Qpid data to the target server:

      # rsync --archive --partial --progress --compress \
      /var/lib/qpidd target_server.example.com:/var/lib/qpidd

4. If the Remote Execution feature is enabled on the source server, copy the contents of the directory /usr/share/foreman-proxy/.ssh to the same directory on the target server. The private SSH key stored in this directory is required to enable Satellite Server remote access to hosts. For more details see Running Jobs on Hosts in the Red Hat Satellite Managing Hosts guide.
5. On the target server, either mount the shared storage or copy all the files from the /backup directory of the source Satellite Server.
6. Shut down the Red Hat Enterprise Linux server hosting the source server.

7. Register the target server to the Customer Portal, attach the necessary subscriptions, and enable the Satellite repositories. For more information, see Installing Satellite Server from a Connected Network in the Red Hat Satellite 6.2 Installation Guide.

   1. Register the target server to the Customer Portal:

      # subscription-manager register your_customer_portal_credentials

   2. Attach the subscription to the target server:

      # subscription-manager attach --pool=pool_ID

      The Red Hat Satellite subscription pool ID is identified earlier in this procedure.

   3. Ensure only the required repositories are enabled.

      # subscription-manager repos --disable=*
      # subscription-manager repos \
      --enable=rhel-7-server-rpms \
      --enable=rhel-server-rhscl-7-rpms \
      --enable=rhel-7-server-satellite-maintenance-6-rpms \
      --enable=rhel-7-server-satellite-6.2-rpms

8. On the target server, install the satellite-clone package.

   # yum install satellite-clone

9. On the target server, customize the satellite-clone configuration file.

   Edit the configuration file /etc/satellite-clone/satellite-clone-vars.yml. To change an item from the default, remove the comment character (#), and edit its value.

   1. Change the backup_dir value to the path containing the backup files.
   2. Change the rhel_migration value to true.
   3. Change other values to suit your requirements.

10. On the target server, run the satellite-clone tool.

    # satellite-clone

11. On the target server, reconfigure DHCP, DNS, TFTP and remote execution services. The cloning process disables these services on the target Satellite Server to avoid conflict with the source Satellite Server.

    Reconfigure and enable DHCP, DNS, TFTP in the Satellite web UI. For more information, see Configuring DNS, DHCP, and TFTP on Satellite Server in the Installation Guide.

    Enable remote execution:

    # satellite-installer --scenario satellite \
    --enable-foreman-plugin-remote-execution \
    --enable-foreman-proxy-plugin-remote-execution-ssh

12. Log in to the Satellite web UI as user admin and password changeme. Change the admin user’s password.

13. Refresh the Satellite’s manifest.

    1. Log in to the Satellite web UI.
    2. Ensure that the correct organization is selected.
    3. Navigate to Content > Red Hat Subscriptions, then click Manage Manifest.
    4. Click Refresh Manifest.
    5. Navigate to Content > Red Hat Subscriptions and verify the available subscriptions are correct.

14. Edit Capsules' association with life cycles.

    The cloning process breaks the association between Capsule Servers and their lifecycle environments to avoid interference with existing infrastructure. On the target Satellite Server, follow the instructions in file /usr/share/satellite-clone/logs/reassociate_capsules.txt to reverse these changes.

15. Update your network configuration, for example, DNS, to match the target server’s IP address with its new host name.

16. If the source server uses the virt-who daemon, install and configure it on the target server.

    1. Complete the prerequisite steps for the virt-who daemon. For more information, see Prerequisites in the Virtual Instances Guide.
    2. Copy all the virt-who configuration files in directory /etc/virt-who.d/ from the source server to the same directory on the target server.
    3. Configure and start the virt-who daemon. For more information, see Configuring and Starting virt-who Service in the Virtual Instances Guide.

17. Restart goferd on all registered content hosts and Capsules.

    # systemctl restart goferd

18. Decommission the source server.

1. Install Red Hat Enterprise Linux 7 server. This is the new Capsule Server.
2. Install the new Capsule Server, but do not proceed to run the satellite-installer. For more information, see Installing Capsule Server in the Installation Guide, but stop after completing the Installing Capsule Server section.
3. Back up the source Capsule Server. For more information, see Back up and Disaster Recovery in the Red Hat Satellite 6.2 Server Administration Guide.

4. Stop all Satellite services on the source Capsule Server.

   # katello-service stop

5. Copy all backup files from the source server to the target server.
6. Restore the Capsule Server on the target server.
7. Shut down the source Capsule Server.
8. Update your network configuration, for example, DNS, to match the target server’s IP address with its new host name.
9. Decommission the source Capsule Server.

Upgrade Satellite Server

1. Create a backup.

   • On a virtual machine, take a snapshot.

   • On a physical machine, create a backup.

     For information on backups, see Backup and Disaster Recovery in the Red Hat Satellite 6.2 Server Administration 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. 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.

4. Refresh your subscription:

   # subscription-manager refresh

5. Enable the Satellite Maintenance repository:

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

6. Install foreman-maintain:

   # yum install rubygem-foreman_maintain

7. Check the available versions to confirm 6.3 is listed:

   # foreman-maintain upgrade list-versions

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

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

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

10. Perform the upgrade:

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

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

    # hash -d katello-service 2> /dev/null

12. Check and restore any changes required to the DNS and DHCP configuration files using the backups made earlier.

13. If you made changes in the previous step, restart Katello services:

    # katello-service restart

14. 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 the changes overwritten, run the following command.

   # 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. Stop Katello services.

   # katello-service stop

8. Obtain the latest ISO file, mount it, and install the packages following the procedures in the Downloading and Installing from a Disconnected Network section of the Red Hat Satellite Installation Guide.

9. 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 mongod database services.

      # systemctl start postgresql
      # systemctl start mongod

   4. Run the installer script with the --noop option as follows.

      # 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 Katello services.

      # katello-service stop

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

11. Perform the upgrade by running the installer script with the --upgrade option.

    # satellite-installer --scenario satellite --upgrade

    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.

12. Check and restore any changes required to the DNS and DHCP configuration files using the backups made earlier.

13. If you made changes in the previous step, restart Katello services.

    # katello-service restart

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

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

Upgrade Satellite Clients Using the satellite-6.3-tools-upgrade Package

1. In the Satellite web UI, navigate to Hosts > Content Hosts and select the Content Hosts to be upgraded.
2. From the Select Action list, select Manage Packages.
3. In the search field, enter the package name satellite-6.3-tools-upgrade.
4. From the Install list, select your preferred installation method. Wait for the message that the action has been successfully scheduled before proceeding to the next step.
5. In the search field, enter the package name katello-agent.
6. From the Update list, select your preferred update method. Wait for the message that the action has been successfully scheduled before proceeding to the next step.
7. Click Done.

Upgrade Satellite Clients Manually

1. Log into the client system.

2. Disable the repositories for the previous version of Satellite.

   # subscription-manager repos \
   --disable rhel-7-server-satellite-tools-6.2-rpms

3. Enable the Satellite tools repository for this version of Satellite.

   # subscription-manager repos \
   --enable=rhel-7-server-satellite-tools-6.3-rpms

4. Upgrade the Katello agent:

   # yum upgrade katello-agent

5. Restart goferd.

   # systemctl restart goferd

Upgrade virt-who Manually

1. Upgrade virt-who.

   # yum upgrade virt-who

2. Restart the virt-who service so the new version is activated.

   # systemctl restart virt-who.service

1. In the Satellite web UI, go to Content > Red Hat Repositories.
2. Under the RPM tab, find and expand the Product Red Hat Enterprise Linux Server.
3. Find and expand the Repository Set Red Hat Satellite Tools 6.2 (for Red Hat Enterprise Linux 7 Server) (RPMs).
4. Unselect Red Hat Satellite Tools 6.2 for Red Hat Enterprise Linux 7 Server RPMs x86_64.

1. In the Satellite web UI, navigate to Hosts > All hosts.
2. On the host that you want to update, click Edit.
3. In the upper-right of the Edit page, select Manage host.
4. Select the Operating System tab.
5. From the PXE loader list, select the method of PXE booting that you want.
6. Click Submit to save.

1. Search for affected lines containing &:.
2. Replace strings in the form your_code(&:your_code) with your_code{|i| i.your_code}.