Chapter 2. Upgrading Red Hat Satellite

Warning

If you have Satellite 6 installed in a high availability configuration, contact Red Hat Support before upgrading to Satellite 6.3.

Use the following procedures to upgrade your existing Red Hat Satellite to Red Hat Satellite 6.3:

Before upgrading, see Section 1.1, “Prerequisites”.

2.1. Preparing a Self-Registered Connected Satellite

Red Hat Satellite 6.3 does not support self-registered Satellites. You must register self-registered Satellite Servers to the Red Hat Content Delivery Network.

To register a self-registered Satellite to the Red Hat Content Delivery Network, complete the following steps.

  1. Verify that the Satellite Server is managed by Foreman:

    1. In the Satellite web UI, navigate to Hosts > All Hosts.
    2. On the host that you want to register, 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 register to the Red Hat Content Delivery Network, enter the following commands to remove the subscriptions and unregister the host:

    # subscription-manager remove --all
    # subscription-manager unregister
  3. Remove the katello-ca-consumer package or any other version of the package:

    # yum remove 'katello-ca-consumer*'
  4. The katello agent is used only for clients of Satellite and must be removed. To remove the katello-agent and gofer packages, stop and disable the goferd service, then enter the remove command:

    # systemctl stop goferd
    # systemctl disable goferd
    # yum remove katello-agent python-gofer-proton gofer
  5. Point the base system to Red Hat for registration by restoring the backup configuration with the following commands:

    # cd /etc/rhsm
    # mv rhsm.conf rhsm.satellite.back
    # mv rhsm.conf.kat-backup rhsm.conf
  6. Register your Satellite Server to the Red Hat Customer Portal:

    Note

    If your Red Hat Satellite 6 subscription is in the Satellite Manifest, you must remove the subscription. This makes the Red Hat Satellite 6 subscription available to attach to the target server. For more information, see the Managing Subscriptions section of the Content Management Guide.

    # subscription-manager register
  7. Attach a Satellite subscription to the system:

    # subscription-manager list --available --matches '*Red Hat Satellite*'
    # subscription-manager attach --pool=pool_id
  8. To prevent problems with third-party or incorrect Red Hat repositories, disable all repositories:

    # subscription-manager repos --disable "*"
  9. To enable the supported repositories for Red Hat Satellite 6.2, enter the following command:

    • For Red Hat Enterprise Linux 6:

      # subscription-manager repos --enable=rhel-6-server-rpms \
      --enable=rhel-server-rhscl-6-rpms \
      --enable=rhel-6-server-satellite-6.2-rpms
    • For Red Hat Enterprise Linux 7:

      # subscription-manager repos --enable=rhel-7-server-rpms \
      --enable=rhel-server-rhscl-7-rpms \
      --enable=rhel-7-server-satellite-6.2-rpms
  10. Clean any metadata from any non-Red Hat Content Delivery Network yum repositories:

    # yum clean all

For Red Hat Enterprise Linux 6 users, proceed to the Section 2.3, “Migrating from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7”.

For Red Hat Enterprise Linux 7 users, proceed to Section 2.4, “Upgrading Satellite Server”.

2.2. Preparing a Self-Registered Disconnected Satellite

If your self-registered Satellite is in a disconnected environment, it is possible to upgrade it by using an ISO image. This method is not recommended for any other situation as ISO images might not contain the latest updates, bug fixes, and functionality.

If the base system has not been updated from the Red Hat CDN, package dependency errors are possible. To resolve dependency errors, you must manually download and install the required version of packages, see Section 2.2.4, “Downloading Packages Manually” for instructions.

To reduce dependency errors when upgrading or installing, use the latest version of Red Hat Enterprise Linux that was available at the time the version of Red Hat Satellite you want to install was released. You can check the release date of the version of Red Hat Satellite you want to install in the Red Hat Knowledgebase article Red Hat Satellite Release Dates and then check for the minor version of Red Hat Enterprise Linux that was current at that time in the Red Hat Knowledgebase article Red Hat Enterprise Linux Release Dates.

2.2.1. Unregistering Satellite Server

  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

2.2.2. Downloading the Binary DVD Images

  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

2.2.3. Configuring Satellite Server with Offline Repositories

  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

2.2.4. Downloading Packages Manually

If you must download a package manually, complete the following procedure:

  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.

2.3. Migrating from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7

Red Hat Satellite 6.3 is supported only on Red Hat Enterprise Linux 7. If you have Red Hat Satellite 6 running on Red Hat Enterprise Linux 6, you must first migrate to Red Hat Enterprise Linux 7. The migration process uses the Satellite clone tool, introduced with Red Hat Satellite 6.3. This tool creates a clone of an existing Satellite Server from a Satellite backup.

The Satellite clone tool does not support migrating a Capsule Server to Red Hat Enterprise Linux 7. Instead you must backup the existing Capsule Server, restore it on Red Hat Enterprise Linux 7, then reconfigure the Capsule Server.

2.3.1. Exclusions

The Satellite migration process includes only the Red Hat Satellite environment. Any customizations made outside the Satellite environment, for example manually configured cron jobs, are outside the scope of this guide.

2.3.2. Before You Begin

Terminology

Throughout this procedure, ensure that you understand the following terminology:

  • Source server - existing Satellite Server or Capsule Server
  • Target server - new server, to which Satellite Server or Capsule Server is being migrated

Requirements

In migrating a Satellite Server or Capsule Server, the following requirements apply:

  • Install only a minimal Red Hat Enterprise Linux 7 instance. Do not install any Red Hat Enterprise Linux 7 software groups, or third-party applications. Complete the prerequisites in the Preparing your environment for installation section of the Installation Guide.
  • The target server must have capacity to store the backup files, which the source server transfers to the target server, and the backup files when they are restored. If you have more than 500 GB of Pulp data, Red Hat recommends copying the Pulp data directly from the source server to the target server. Copying the Pulp data is generally faster than creating a compressed archive file of this data, then decompressing it on the target server. For more information about both these methods see Section 2.3.4, “Migrating a Satellite Server”.

2.3.3. Satellite Server Migration Overview

The high-level steps of migrating Satellite Server or a Capsule Server are as follows:

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

Isolate the target server from internal networks to avoid unwanted communication with Capsule Servers and hosts. Reconnect the target server after the source server is decommissioned.

A connection to the Red Hat Content Delivery Network (CDN) is required for subscription activation and Satellite installation, unless installing from ISO files.

2.3.4. Migrating a Satellite Server

The following procedure describes migrating an existing Satellite Server installation to the target 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.

2.3.5. Migrating a Capsule Server

The following procedure describes migrating an existing Capsule Server installation to the target 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.

Capsule Servers using Custom Certificates

If your Capsule Server is configured with custom certificates, you must configure the migrated Capsule Server with custom certificates again. Follow the procedure Configuring Capsule Server with a Custom Server Certificate in the Installation Guide.

2.4. Upgrading Satellite Server

This section describes how to upgrade Satellite Server.

Red Hat Satellite 6.3 introduces foreman-maintain. This tool provides various features to update, upgrade, and help keep Satellite running.

Before You Begin

  • You must be on the minor version 6.2.11 or later of Red Hat Satellite Server 6.2 if installed on Red Hat Enterprise Linux 7. If Satellite Servers and Capsule Servers are on Red Hat Enterprise Linux 6, the minimum version is 6.2.13 and they must then be migrated to Red Hat Enterprise Linux 7. You do not need to upgrade to a Red Hat Satellite version higher than these stated minimums to upgrade to Satellite 6.3. Direct upgrades from earlier minor versions are not supported. For more information, see Upgrading Satellite Server and Capsule Server in the Red Hat Satellite 6.2 Installation Guide.
  • Review and update your firewall configuration prior to upgrading your Satellite Server. For more information, see the Ports and Firewalls Requirements section of the Red Hat Satellite Installation Guide.
  • Ensure that you do not delete the manifest from the Customer Portal or in the Satellite Web UI because this removes all the entitlements of your content hosts.
  • Back up and remove all Foreman hooks before upgrading. Restore any hooks only after Satellite is known to be working after the upgrade is complete.
  • If you have edited any of the default templates, backup them up either by cloning or exporting them. Cloning is the recommended method because that prevents them being overwritten in future updates or upgrades. To confirm if a template has been edited, you can view its History before you upgrade or view the changes in the audit log after an upgrade. In the web UI, Navigate to Monitor > Audits and search for the template to see a record of changes made. If you use the export method, restore your changes by comparing the exported template and the default template, manually applying your changes.
Warning

If you implemented custom certificates, you must retain the content of both the /root/ssl-build directory and the directory in which you created any source files associated with your custom certificates.

Failure to retain these files during an upgrade causes the upgrade to fail. If these files have been deleted, they must be restored from a backup in order for the upgrade to proceed.

Configuring the BASH shell

The BASH shell stores the location of a binary in a hash table. During the upgrade, the location of the katello-service script is changed, but BASH does not register this change, and foreman-maintain fails if it calls the script after the change.

  • Optional: Before the upgrade, users of the BASH shell can set the checkhash option temporarily to ensure katello-service works after the installer completes. Enter a command as follows in your BASH shell:

    # shopt -s checkhash
  • After a successful or failed upgrade, in all currently running BASH shells, enter the following command:

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

Upgrade Scenarios

You cannot upgrade a self-registered Satellite. You must register the self-registered Satellite to the Red Hat Content Delivery Network (CDN) and then perform the upgrade. To register the self-registered Satellite to the CDN, see Section 2.1, “Preparing a Self-Registered Connected Satellite”.

2.4.1. Upgrading a Connected Satellite Server

Use this procedure for a Satellite Server connected to the Red Hat Content Delivery Network.

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

2.4.2. Upgrading a Disconnected Satellite Server

Use this procedure for a Satellite Server not connected to the Red Hat Content Delivery Network.

Before You Begin

  • You must be on the minor version 6.2.11 or later of Red Hat Satellite Server 6.2 if installed on Red Hat Enterprise Linux 7. If Satellite Servers and Capsule Servers are on Red Hat Enterprise Linux 6, the minimum version is 6.2.13 and they must then be migrated to Red Hat Enterprise Linux 7. You do not need to upgrade to a Red Hat Satellite version higher than these stated minimums to upgrade to Satellite 6.3. Direct upgrades from earlier minor versions are not supported. For more information, see Upgrading Satellite Server and Capsule Server in the Red Hat Satellite 6.2 Installation Guide.
  • Review and update your firewall configuration prior to upgrading your Satellite Server. For additional information, see Ports and Firewalls Requirements section of the Red Hat Satellite Installation Guide.
  • Ensure that you do not delete the manifest from the Customer Portal or in the Satellite Web UI because this removes all the entitlements of your content hosts.
  • Back up and remove all Foreman hooks before upgrading. Reinstate hooks only after Satellite is known to be working after the upgrade is complete.
Warning

If you implemented custom certificates, you must retain the content of both the /root/ssl-build directory and the directory in which you created any source files associated with your custom certificates.

Failure to retain these files during an upgrade causes the upgrade to fail. If these files have been deleted, they must be restored from a backup in order for the upgrade to proceed.

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.

2.5. Synchronizing the New Repositories

You must enable and synchronize the Red Hat Satellite Tools and Red Hat Satellite Capsule repositories for 6.3 before you can upgrade Capsule Servers and Satellite clients.

Synchronizing the New Repositories

  1. In the Satellite web UI, navigate to Content > Red Hat Repositories and select the RPMs tab.
  2. From the PRODUCT list, find and expand Red Hat Enterprise Linux Server.
  3. From the REPOSITORY SET list, find and expand Red Hat Satellite Tools 6.3 (for RHEL7 Server) (RPMs).
  4. Select the check box for Red Hat Satellite Tools 6.3 for RHEL 7 Server RPMs x86_64.
  5. From the PRODUCT list, find and expand Red Hat Satellite Capsule.
  6. From the REPOSITORY SET list, find and expand Red Hat Satellite Capsule 6.3 (for RHEL7 Server) (RPMs).
  7. Select the check box for Red Hat Satellite Capsule 6.3 for RHEL 7 Server RPMs x86_64.

    Note

    If the 6.3 repositories are not available, refresh the Subscription Manifest. Navigate to Content > Red Hat Subscriptions, click Import/Remove Manifest, then click Refresh Manifest.

  8. Navigate to Content > Sync Status.
  9. Click the arrow next to the product to view the available repositories.
  10. Select the repositories for 6.3.
  11. Click Synchronize Now.

    Important

    If an error occurs when you try to synchronize a repository, refresh the manifest. If the problem persists, raise a support request. Do not delete the manifest from the Customer Portal or in the Satellite web UI; this removes all the entitlements of your content hosts.

  12. Update any pre-existing Content Views that use version 6.2 repositories with the new version for 6.3. Publish and promote updated versions of any Content Views that now have the new 6.3 repositories. For more information, see Managing Content Views in the Content Management Guide.

2.6. Upgrading Capsule Servers

This section describes how to upgrade Capsule Servers.

Before You Begin

  • You must upgrade Satellite Server before you can upgrade any Capsule Servers.
  • The Capsule Server must be on minor version 6.2.11 at a minimum. If the Capsule Server is on Red Hat Enterprise Linux 6, the minimum version is 6.2.13. Direct upgrades from earlier minor versions are not supported. For more information, see Upgrading Between Minor Versions of Satellite in the Red Hat Satellite 6.2 Installation Guide.
  • Ensure the Red Hat Satellite Capsule 6.3 repository is enabled in Satellite Server and synchronized.
  • If you use Content Views to control updates to a Capsule Server’s base operating system, or for the Capsule Server repository, you must publish updated versions of those Content Views.
  • Ensure the Capsule’s base system is registered to the newly upgraded Satellite Server.
  • Ensure the Capsule has the correct organization and location settings in the newly upgraded Satellite Server.
  • Review and update your firewall configuration prior to upgrading your Capsule Server. For additional information, see the Ports and Firewalls Requirements section of the Red Hat Satellite Installation Guide.
Warning

If you implemented custom certificates, you must retain the content of both the /root/ssl-build directory and the directory in which you created any source files associated with your custom certificates.

Failure to retain these files during an upgrade causes the upgrade to fail. If these files have been deleted, they must be restored from a backup in order for the upgrade to proceed.

Upgrading Capsule Servers

  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. If you have made manual edits to DNS or DHCP configuration files and do not want the changes overwritten, enter the following command.

    # satellite-installer --foreman-proxy-dns-managed=false \
    --foreman-proxy-dhcp-managed=false
  4. Disable the repository for Red Hat Satellite 6.2.

    # subscription-manager repos \
    --disable rhel-7-server-satellite-capsule-6.2-rpms
  5. Enable the new repositories.

    The Red Hat Software Collections repository provides a later version of Ruby required by some Red Hat Satellite features, including the Remote Execution feature. The Satellite tools repository provides gofer and katello-agent which provide communication services for managing Errata.

    • Enter the following command:

      # subscription-manager repos \
      --enable rhel-7-server-satellite-capsule-6.3-rpms \
      --enable rhel-server-rhscl-7-rpms \
      --enable rhel-7-server-satellite-tools-6.3-rpms
  6. In the Satellite web UI, go to Hosts > Discovered hosts. If there are discovered hosts available, power off the hosts 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. Clear the repository cache.

    # yum clean all
  8. Stop Katello services.

    # katello-service stop
  9. Update all packages.

    # yum update
  10. On Satellite Server, generate an archive with new certificates and update the certificate bundle. Failure to generate new certificates causes the communication services between Satellite Server and Capsule Server to fail.

    • If you use default Satellite SSL certificates, enter the following command:

      # capsule-certs-generate \
      --foreman-proxy-fqdn mycapsule.example.com \
      --certs-tar mycapsule.example.com-certs.tar \
      --certs-update-all

      You must replace mycapsule.example.com with the fully qualified domain name of Capsule Server.

    • If you use custom SSL certificates, enter the following command:

      # capsule-certs-generate \
      --foreman-proxy-fqdn mycapsule.example.com \ 1
      --certs-tar /root/capsule_cert/capsule_certs.tar \ 2
      --server-cert /root/capsule_cert/capsule_cert.pem \ 3
      --server-cert-req /root/capsule_cert/capsule_cert_csr.pem \ 4
      --server-key /root/capsule_cert/capsule_cert_key.pem \ 5
      --server-ca-cert /root/sat_cert/ca_cert_bundle.pem \ 6
      --certs-update-all --certs-update-server
      1
      The fully qualified domain name of Capsule Server
      2
      Path to the tar file with the certificate archive that this command generates
      3
      Path to Capsule Server certificate file
      4
      Path to Capsule Server certificate signing request file
      5
      Path to Capsule Server private key file
      6
      Path to Certificate Authority bundle
  11. Copy the certificate archive file to Capsule Server.

    # scp mycapsule.example.com-certs.tar mycapsule.example.com:~/
    Warning

    Do not remove the certificate archive file after the upgrade, it is required for future updates.

  12. If you plan to use Capsule Server as a proxy for discovered hosts, install the Discovery plug-in.

    # yum install rubygem-smart_proxy_discovery.noarch
  13. On the Capsule Server, verify that the foreman_url setting is correct.

    # grep foreman_url /etc/foreman-proxy/settings.yml

    The fully qualified domain name of the Satellite Server should display.

  14. Perform the upgrade by running the installer script with the --upgrade option, and specify the path to the certificate archive previously created on the Satellite Server. Additionally, as the --certs-update-all option was used above when generating the certificate archive, the following three command options are also required to regenerate the NSS database and deploy the updated certificate bundle: --certs-regenerate true and --certs-deploy true and --certs-update-all.

    # satellite-installer --scenario capsule --upgrade \
    --foreman-proxy-content-certs-tar mycapsule.example.com-certs.tar \
    --certs-update-all --certs-regenerate true --certs-deploy true
    Warning

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

    ERROR: Scenario (config/capsule.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.

  15. Check and restore any changes required to the DNS and DHCP configuration files using the backups made earlier.
  16. Upgrade the foreman-discovery package on Satellite Server and turn on the hosts that were shut down prior to the upgrade.

2.7. Post-Upgrade Tasks

Some of the procedures in this section are optional. You can choose to perform only those procedures that are relevant to your installation.

2.7.1. Upgrading Discovery

This section describes updating the PXELinux template and the boot image passed to hosts that use PXE booting to register themselves with Satellite Server. This procedure is not required if you do not use PXE booting of hosts to enable Satellite to discover new hosts.

2.7.1.1. Upgrading Discovery on Satellite Server

  1. Update the Discovery template in the Satellite web UI:

    1. Navigate to Hosts > Provisioning templates.
    2. On the PXELinux global default line, click Clone.
    3. Enter a new name for the template in the Name field, for example ACME PXE global default.
    4. In the template editor field, change the line ONTIMEOUT local to ONTIMEOUT discovery and click Submit.
    5. Navigate to Administer > Settings.
    6. Locate Global default PXELinux template and click on its Value.
    7. Select the name of the newly created template from the menu and click the tick button.
    8. Navigate to Hosts > Provisioning templates.
    9. Click Build PXE Default, then click OK.
  2. In the Satellite web UI, go to Configure > Discovery Rules and associate selected organizations and locations with discovery rules.

2.7.1.2. Upgrading Discovery on Capsule Servers

  1. Verify that the Foreman Discovery package is current on the Satellite Server.

    # yum upgrade tfm-rubygem-foreman_discovery
  2. If an update occurred in the previous step, restart Katello services.

    # katello-service restart
  3. Upgrade the Discovery image on the Satellite Capsule that is either connected to the provisioning network with discovered hosts or provides TFTP services for discovered hosts.

    # yum upgrade foreman-discovery-image
  4. On the same instance, install the package which provides the Proxy service, and then restart foreman-proxy service.

    # yum install rubygem-smart_proxy_discovery
    # service foreman-proxy restart
  5. In the Satellite web UI, go to Infrastructure > Capsules and verify that the relevant Capsule lists Discovery in the features column. Select Refresh from the Actions drop-down menu if necessary.
  6. Go to Infrastructure > Subnets and for each subnet on which you want to use discovery:

    1. Click the subnet name.
    2. On the Capsules tab, ensure the Discovery Capsule is set to a Capsule you configured above.

2.7.2. Upgrading Satellite Clients

Currently, the Satellite 6.2 version of katello-agent and other client libraries in the Satellite Tools repository are not formally tested or supported against Satellite 6.3. Packages can still be installed on clients but errata cannot be installed without updating katello-agent.

Upgrade all clients to the new version of katello-agent as soon as possible so that your clients are fully compatible with Satellite Server. This requires changing the Satellite Tools repository from 6.2 to 6.3, which can be done manually or by installing the satellite-6.3-tools-upgrade package. This package only contains a post installation script to change the Satellite Tools repository version.

Before You Begin

  • You must have upgraded Satellite Server.
  • You must have enabled the new Satellite Tools repositories on the Satellite.
  • You must have synchronized the new repositories in the Satellite.
  • If you have not previously installed katello-agent on your clients, use the manual method.
Warning

If you implemented custom certificates, you must retain the content of both the /root/ssl-build directory and the directory in which you created any source files associated with your custom certificates.

Failure to retain these files during an upgrade causes the upgrade to fail. If these files have been deleted, they must be restored from a backup in order for the upgrade to proceed.

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

2.7.3. Upgrading virt-who

If virt-who is installed on the Satellite or a Capsule Server, it will be upgraded as part of their upgrades. No further action is required. If virt-who is installed elsewhere, it must be upgraded manually.

Before You Begin

If virt-who is installed on a host registered to the Satellite or a Capsule Server, first upgrade the host to the latest packages available in the Satellite Tools repository. For details see Section 2.7.2, “Upgrading Satellite Clients”.

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

2.7.4. Removing the Previous Version of the Satellite Tools Repository

After completing the upgrade to Satellite 6.3, the Red Hat Satellite Tools 6.2 repository can be removed from Content Views and then disabled.

Disable Version 6.2 of the Satellite Tools Repository:

  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.

If the check box is dimmed, then the repository is still contained in a Content View. The orphaned packages in the repository will be removed automatically by a scheduled task (cron job).

2.7.5. Updating the PXE loader options

Red Hat Satellite 6.3 adds support for the PXE booting of UEFI systems. When you upgrade to Satellite 6.3, your provisioned hosts have a new PXE loader option. On upgraded hosts, the PXE loader option might default to none and cause PXE-based provisioning to stop working. To ensure that your hosts continue to work, you must select either PXELinux BIOS or PXELinux UEFI from a new PXE loader option for your host.

To update your PXE booting system settings:

  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.

2.7.6. Updating Templates

Cloned or custom templates in 6.2 that contain Ruby’s to_proc syntax, for example (1..3).collect(&:to_s), do not work in Satellite 6.3 due to security improvements. You must write the same code as a full Ruby block: (1..3).collect {|num| num.to_s}.

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

Use the following two examples as a guide:

Ruby syntax in 6.2 cloned template:

<% host_param('ssh_authorized_keys').split(',').map(&:strip).each do |ssh_key| -%>

Updated Ruby syntax for Satellite 6.3:

<% host_param('ssh_authorized_keys').split(',').map{ |item| item.strip }.each do |ssh_key| -%>

Ruby syntax in 6.2 cloned template:

nameserver=#{[subnet.dns_primary, subnet.dns_secondary].select(&:present?).join(',')}

Updated Ruby syntax for Satellite 6.3:

nameserver=#{[subnet.dns_primary, subnet.dns_secondary].select{ |item| item.present? }.join(',')}

2.7.6.1. Provisioning Templates

Previously, the Ruby expression <%= foreman_url %> was used in provisioning templates as part of the command to notify Satellite that the build is done. In 6.3, the templates use <%= foreman_url('built') %>, which explicitly calls the built template.

If you cloned or created custom provisioning templates in 6.2, search your templates for the lines:

curl -s -o /dev/null --insecure <%= foreman_url %>
wget -q -O /dev/null --no-check-certificate <%= foreman_url %>

Replace the expression:

<%= foreman_url %>

with:

<%= foreman_url('built') %>

2.7.7. Upgrading the External DHCP Service

If using an external DHCP server, you need to configure satellite-installer to use the remote_isc DHCP provider as opposed to the isc DHCP provider that is used in Satellite 6.2. Use the following sections to configure the external DHCP service on Satellite 6.3:

2.7.8. Validating the Mirror on Sync Setting for Red Hat Repositories

After the upgrade, ensure that you set the Mirror-on-Sync setting to Yes for the Red Hat repositories, excluding the repositories for which you intentionally set Mirror-on-Sync to No. For more information, see the Searching Red Hat repositories with the Mirror on Sync setting set to No article in the Red Hat Knowledge Base.