Red Hat Satellite 6.

Upgrading and Updating Red Hat Satellite

Upgrading and updating Red Hat Satellite Server and Capsule Server

Last Updated: 2019-01-16

Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite
Upgrading and updating Red Hat Satellite Server and Capsule Server

Red Hat Satellite Documentation Team

[email protected]
Legal Notice
Copyright © 2019 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity
logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other
countries.

Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.

Java ® is a registered trademark of Oracle and/or its affiliates.

XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.

MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.

Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to
or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other countries
and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract
This guide describes upgrading and updating Red Hat Satellite Server, Capsule Server, and hosts.
 Table of Contents

Table of Contents
.CHAPTER
. . . . . . . . .1.. .UPGRADE
. . . . . . . . . OVERVIEW
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . .
1.1. PREREQUISITES 3
1.2. UPGRADE PATHS 4
1.3. FOLLOWING THE PROGRESS OF THE UPGRADE 6

.CHAPTER
. . . . . . . . .2.. .UPGRADING
. . . . . . . . . . . RED
. . . . .HAT
. . . .SATELLITE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . .
2.1. PREPARING A SELF-REGISTERED CONNECTED SATELLITE 7
2.2. PREPARING A SELF-REGISTERED DISCONNECTED SATELLITE 8
2.2.1. Unregistering Satellite Server 9
2.2.2. Downloading the Binary DVD Images 9
2.2.3. Configuring Satellite Server with Offline Repositories 10
2.2.4. Downloading Packages Manually 11
2.3. MIGRATING FROM RED HAT ENTERPRISE LINUX 6 TO RED HAT ENTERPRISE LINUX 7 12
2.3.1. Exclusions 12
2.3.2. Before You Begin 12
2.3.3. Satellite Server Migration Overview 12
2.3.4. Migrating a Satellite Server 13
2.3.5. Migrating a Capsule Server 16
2.4. UPGRADING SATELLITE SERVER 17
2.4.1. Upgrading a Connected Satellite Server 18
2.4.2. Upgrading a Disconnected Satellite Server 20
2.5. UPGRADING CAPSULE SERVERS 24
2.6. POST-UPGRADE TASKS 27
2.6.1. Upgrading Discovery 27
2.6.1.1. Upgrading Discovery on Satellite Server 27
2.6.1.2. Upgrading Discovery on Capsule Servers 28
2.6.2. Upgrading Satellite Clients 28
2.6.3. Upgrading virt-who 30
2.6.4. Removing the Previous Version of the Satellite Tools Repository 30
2.6.5. Updating the PXE loader options 30
2.6.6. Updating Templates 31
2.6.6.1. Provisioning Templates 31
2.6.7. Upgrading the External DHCP Service 32

. . . . . . . . . .3.. .UPGRADING
CHAPTER . . . . . . . . . . . PUPPET
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
...........
3.1. UPGRADE PATH 33
3.2. TESTING PUPPET MODULES 33
3.3. PERFORMING THE UPGRADE 34

.CHAPTER
. . . . . . . . .4.. .UPDATING
. . . . . . . . . .SATELLITE
. . . . . . . . . .SERVER,
. . . . . . . . CAPSULE
. . . . . . . . . .SERVER,
. . . . . . . .AND
. . . . CONTENT
. . . . . . . . . .HOSTS
. . . . . . . . . . . . . . . . . . . .37
...........
4.1. UPDATING SATELLITE SERVER 37
4.2. UPDATING CAPSULE SERVER 38
4.3. UPDATING CONTENT HOSTS 39

1
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

2
 CHAPTER 1. UPGRADE OVERVIEW

CHAPTER 1. UPGRADE OVERVIEW


WARNING

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

This chapter details the prerequisites and available upgrade paths to Red Hat Satellite 6.3. Review this
information before upgrading your current Red Hat Satellite 6 installation.

In this guide, the terms update, upgrade, and migrate have the following meanings:

Upgrading — The process of advancing your Satellite Server and Capsule Server installations
from a y-stream release to the next, for example Satellite 6.2 to Satellite 6.3.

Updating — The process of advancing your Satellite Server and Capsule Server installations
from a z-stream release to the next, for example Satellite 6.2.10 to Satellite 6.2.11.

Migrating — The process of moving an existing Satellite installation to another Red Hat

Enterprise Linux server.

For interactive upgrade instructions, you can also use the Red Hat Satellite Upgrade Helper on the
Red Hat Customer Portal. This application provides you with an exact guide to match your current
version number. You can find instructions that are specific to your upgrade path, as well as steps to
prevent known issues. For more information, see Satellite Upgrade Helper on the customer portal.

IMPORTANT

The Red Hat Satellite Server and Capsule Server y-stream versions must match. For
example, a 6.2 Satellite Server is not compatible with a 6.3 Capsule Server and a 6.3
Satellite Server is not compatible with a 6.2 Capsule Server. Mismatching Satellite Server
and Capsule Server versions will result in the Capsule Server failing silently. However, a
Capsule Server using one z-stream version older than the Satellite Server is supported.
For example, a Satellite 6.2.11 Satellite Server is compatible with a 6.2.10 Capsule
Server.

1.1. PREREQUISITES
Upgrading to Satellite 6.3 affects your entire Satellite infrastructure. Before proceeding, complete the
following:

Read the Red Hat Satellite 6.3 Release Notes.

Review this guide so that you are aware of the upgrade process and its impact.

Plan your upgrade path. For more information, see Section 1.2, “Upgrade Paths”.

Plan for the required Satellite downtime. The upgrade process requires that Satellite services be
shut down for the duration.

3
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

Plan for the storage requirements. The storage requirements for Red Hat Satellite 6.3 have
changed from the previous version. For more information, see Storage Requirements and
Recommendations in the Installation Guide.

Back up your Satellite Server and all Capsule Servers. For more information, see Backup and
Disaster Recovery in the Red Hat Satellite 6.2 Server Administration Guide.


WARNING

If you customize configuration files, manually or use a tool such as Hiera, these
customizations are overwritten when the installation script runs during upgrading or
updating. You can use the --noop option with the satellite-installer script to test for
changes. For more information, see the Red Hat Knowledgebase solution How to
use the noop option to check for changes in Satellite config files during an upgrade.

1.2. UPGRADE PATHS

The upgrade path to Red Hat Satellite 6.3 is determined by your environment. Satellite 6.3 is supported
only on Red Hat Enterprise Linux 7. Satellite Servers and Capsule Servers on Red Hat Enterprise Linux 6
must be updated to Satellite 6.2.13 or later, migrated to Red Hat Enterprise Linux 7, then upgraded to
Satellite 6.3. Satellite Servers and Capsule Servers on Red Hat Enterprise Linux 7 must be updated to
Satellite 6.2.11 or later, then upgraded to Satellite 6.3.

4
 CHAPTER 1. UPGRADE OVERVIEW

Figure 1.1. Overview of Satellite 6.3 Upgrade Paths

Supported upgrade paths:

Satellite 6.2.11 or later → Satellite 6.3

Satellite 6.1.9 or later → Satellite 6.2.11 or later → Satellite 6.3

Satellite 6.0.x → Satellite 6.1.9 or later → Satellite 6.2.11 or later → Satellite 6.3


WARNING

Upgrading from the Beta to GA version is not supported.

5
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

The high level steps in upgrading to Satellite 6.3 are as follows. If your installation already meets some
of the following requirements, omit that step. For example, if Satellite 6.2.11 is already installed, you can
omit the update step.

1. Upgrade Satellite Server and all Capsule Servers from Satellite 6.0.x to Satellite 6.1.9. For more
information, see Upgrading Red Hat Satellite Server and Capsule Server in the Red Hat Satellite
6.1 Installation Guide.

2. If Satellite 6.1 is installed, upgrade Satellite Server and all Capsule Servers from Satellite 6.1.9
or later to Satellite 6.2.11 or later. For more information, see Upgrading Red Hat Satellite Server
and Capsule Server in the Red Hat Satellite 6.2 Installation Guide.

3. If Satellite 6.2.x is installed, but not Satellite 6.2.11 or later, update Satellite Server and all
Capsule Servers to Satellite 6.2.11 release. Satellite Servers and Capsule Servers on Red Hat
Enterprise Linux 6 must be updated to Satellite 6.2.13. For more information, see Updating
Satellite Server, Capsule Server, and Content Hosts in the Red Hat Satellite 6.2 Installation
Guide.

4. Migrate Satellite Server and all Capsule Servers to Red Hat Enterprise Linux 7. For more
information, see Section 2.3, “Migrating from Red Hat Enterprise Linux 6 to Red Hat Enterprise
Linux 7”.

5. Upgrade Satellite Server and all Capsule Servers to Satellite 6.3. For more information, see
Section 2.4, “Upgrading Satellite Server”.

6. Upgrade the Satellite tools on all Satellite clients. For more information, see Section 2.6.2,
“Upgrading Satellite Clients”.

Self-Registered Satellites
Red Hat Satellite no longer supports self-registered Satellites. You must register self-registered Satellite
Servers to the Red Hat Content Delivery Network. For more information about self-registered Satellites,
see Section 2.1, “Preparing a Self-Registered Connected Satellite”.

1.3. FOLLOWING THE PROGRESS OF THE UPGRADE

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. You can also see the screen manual
page for more information.

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.

6
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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 this chapter to upgrade your existing Red Hat Satellite environment to Red Hat Satellite 6.3.

The chapter includes prerequisites such as Section 2.3, “Migrating from Red Hat Enterprise Linux 6 to
Red Hat Enterprise Linux 7”, scenarios for Section 2.4, “Upgrading Satellite Server”, a scenario for
Section 2.5, “Upgrading Capsule Servers”, and Section 2.6, “Post-Upgrade Tasks”.

Before upgrading, see the 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:

a. In the Satellite web UI, navigate to Hosts > All Hosts.

b. On the host that you want to register, click Edit.

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

7
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

8
 CHAPTER 2. UPGRADING RED HAT 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:

a. In the Satellite web UI, navigate to Hosts > All Hosts.

b. On the host that you want to migrate, click Edit.

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

9
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

10
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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.

a. Install yum-config-manager:

# yum install yum-utils

b. Disable the ISO based repositories:

# yum-config-manager --disable InstallMedia --disable satellite-

local --disable scl-local --disable satellite-puppet4

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

11
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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.

12
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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

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

13
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

b. Stop and disable all Satellite services:

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

c. Copy the Pulp data to the target server:

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

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

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

b. Stop and disable all Satellite services:

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

c. Copy the Pulp data to the target server:

# rsync --archive --partial --progress --compress \

/var/lib/pulp target_server.example.com:/var/lib/pulp

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

14
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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.

a. Register the target server to the Customer Portal:

# subscription-manager register your_customer_portal_credentials

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

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

a. Change the backup_dir value to the path containing the backup files.

b. Change the rhel_migration value to true.

c. 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:

15
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

a. Log in to the Satellite web UI.

b. Ensure that the correct organization is selected.

c. Navigate to Content > Red Hat Subscriptions, then click Manage Manifest.

d. Click Refresh Manifest.

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

a. Complete the prerequisite steps for the virt-who daemon. For more information, see
Prerequisites in the Virtual Instances Guide.

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

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

16
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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,

17
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

To upgrade a Satellite Server connected to the Red Hat Content Delivery Network, proceed to
Section 2.4.1, “Upgrading a Connected Satellite Server”.

To upgrade a Satellite Server not connected to the Red Hat Content Delivery Network, proceed
to Section 2.4.2, “Upgrading a Disconnected Satellite Server”.

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

18
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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. In the Satellite web UI, navigate to Content > Red Hat Subscriptions, and then click Manage
Manifest. In the Subscription Manifest pane, click the Actions tab, and then click Refresh
Manifest to download the latest copy of the Subscription Manifest.

5. Configure the repositories in the Satellite web UI:

a. In the Satellite web UI, navigate to Content > Red Hat Repositories and select the RPMs
tab.

b. From the PRODUCT list, find and expand Red Hat Enterprise Linux Server.

c. From the REPOSITORY SET list, find and expand Red Hat Satellite Tools 6.3 (for RHEL7
Server) (RPMs).

d. Select Red Hat Satellite Tools 6.3 for RHEL 7 Server RPMs x86_64.

6. Synchronize the newly enabled repositories:

a. In the Satellite web UI, navigate to Content > Sync Status.

b. Click the arrow next to the product to view available repositories.

c. Select the repositories for 6.3.

d. Click Synchronize Now.

If you get an error when trying to update a repository, ensure 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. Refresh the manifest and if the problem persists, raise a
support request.

7. Update any pre-existing Content Views that utilize 6.2 version repositories with the new version
for 6.3. Publish and promote updated versions of any Content Views that now have the new 6.3
version repositories.

8. Refresh your subscription:

# subscription-manager refresh

9. Enable the Satellite Maintenance repository:

19
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

# subscription-manager repos --enable rhel-7-server-satellite-

maintenance-6-rpms

10. Install foreman-maintain:

# yum install rubygem-foreman_maintain

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

# foreman-maintain upgrade list-versions

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

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

14. Perform the upgrade:

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

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

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

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

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

# katello-service restart

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

20
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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

21
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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:

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

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

b. Restart the httpd service.

# systemctl restart httpd

c. Start the postgresql and mongod database services.

# systemctl start postgresql

# systemctl start mongod

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

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

noop

22
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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.

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

23
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

24
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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

25
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

26
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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.6. 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.6.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.6.1.1. Upgrading Discovery on Satellite Server

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

a. Navigate to Hosts > Provisioning templates.

b. On the PXELinux global default line, click Clone.

c. Enter a new name for the template in the Name field, for example ACME PXE global
default.

d. In the template editor field, change the line ONTIMEOUT local to ONTIMEOUT discovery
and click Submit.

27
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

e. Navigate to Administer > Settings.

f. Locate Global default PXELinux template and click on its Value.

g. Select the name of the newly created template from the menu and click the tick button.

h. Navigate to Hosts > Provisioning templates.

i. 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.6.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:

a. Click the subnet name.

b. On the Capsules tab, ensure the Discovery Capsule is set to a Capsule you configured
above.

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

28
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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.

29
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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

4. Upgrade the following Katello, Pulp, and qpid packages.

# yum upgrade katello-agent katello-host-tools katello-host-tools-

fact-plugin pulp-rpm-handlers qpid-proton-c

5. Restart goferd.

# systemctl restart goferd

2.6.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.6.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.6.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.6.5. Updating the PXE loader options

30
 CHAPTER 2. UPGRADING RED HAT SATELLITE

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.6.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.6.6.1. Provisioning Templates

31
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

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.6.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:

Configuring Satellite Server with External DHCP in the Installation Guide.

Configuring Capsule Server with External DHCP in the Installation Guide.

32
 CHAPTER 3. UPGRADING PUPPET

CHAPTER 3. UPGRADING PUPPET

Red Hat Satellite 6.3 uses Puppet 3 by default, but you can also upgrade to Puppet 4. Satellite 6.4 will
support only Puppet 5. The migration path for Puppet 5 supports only Puppet 4 to Puppet 5 migrations.
Therefore if you are using a version of Puppet prior to version 4, you must upgrade to Puppet 4 prior to
upgrading to Satellite 6.4. Satellite 6.3 includes an upgrade path to Puppet 4, and Red Hat recommends
you do it now to prepare for your next upgrade. This chapter describes the process of upgrading to
Puppet 4.

3.1. UPGRADE PATH

Before upgrading to Puppet 4, you must first review your Puppet modules, and make changes, to ensure
they are compatible with Puppet 4 before upgrading Puppet. For example, if the client has blank
configuration values after running the Puppet agent, updating Puppet modules is indicated.

Red Hat Satellite and Capsules do not have to be upgraded to Puppet 4 at the same time. You have the
flexibility to upgrade Capsules depending on your progress with testing and upgrading Puppet modules.
An alternative is to install new Capsules and move hosts to them after testing. You can use Satellite web
UI, the Hammer CLI, or the bootstrap script to move hosts from a Puppet 3 Capsule to a Puppet 4
Capsule.

Cloning an existing Capsule to use for final testing of upgraded Puppet modules is also recommended.
Cloning an existing Capsule can take a long time depending on the size of the repositories.

You must install the Puppet 4 agent on the hosts for full functionally, but hosts must not be upgraded to
Puppet 4 agent before their Capsule is upgraded to Puppet 4. For more information about installing
Puppet agent, see Installing the Puppet Agent.

Using Parameters to Determine Puppet Versions

You can configure Satellite to install the Puppet 4 agent instead of the Puppet 3 agent during host
provisioning. The Kickstart template file has the parameter enable-puppet4; if set to true, the
provisioning template installs the Puppet 4 agent and configures puppet.conf in the
/etc/puppetlabs/puppet/ directory. If the parameter is not defined, Puppet 3 agent is installed.

To enforce Puppet 4 for hosts, create a parameter at the host group level with name enable-puppet4
and set its value to true.

1. In the web UI, navigate to Configure > Host Groups and select the name of the host group you
want to configure.

2. Click the Parameters tab, and in the Host Group Parameters area, click Add Parameter.

3. In the Name field, enter enable-puppet4 and in the Value field, enter true.

4. Click Submit to save the changes.

3.2. TESTING PUPPET MODULES

Use the following guidelines to test your Puppet modules before you begin upgrading:

1. Test Puppet modules first on a workstation, separate from Satellite.

2. Check the command syntax using the puppet parser validate command.

33
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

3. Configure the Satellite Capsules running Puppet 3 to use the future parser and test again. To
enable this feature, run the Satellite installer with the option --puppet-server-parser
future.

The future parser in Puppet 3.8 enables functionality identical to the Puppet language used in Puppet
4.0. After enabling it, check the logs in /var/log/puppet/ for errors. If you find errors, correct them
and test again. See the Puppet 3.8 Reference Manual for information on the future parser.

3.3. PERFORMING THE UPGRADE

Use this section to upgrade a Satellite or Capsule to Puppet 4. For a new installation, see the Red Hat
Satellite Installation Guide.

Before You Begin

Ensure you complete the upgrade to Satellite 6.3.

Review your Puppet modules and upgrade where required to Puppet 4.

Ensure all hosts connected to the system that you want to upgrade have the latest Puppet 3
agent and not version 4. You must not upgrade hosts to Puppet 4 agent before their Capsule.
The Satellite tools repository supplies the Puppet package. See Section 2.6.2, “Upgrading
Satellite Clients” for more information.

Create a backup or a snapshot of your system. For more information, see Backing Up and
Restoring Satellite Server and Capsule Server in Administering Red Hat Satellite.

Upgrading Satellite or Capsule To Puppet 4

1. Enable the Puppet 4 repository:

a. On a Satellite:

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

b. On a Capsule:

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

2. Upgrade Puppet:

# satellite-installer --upgrade-puppet

Before You Begin

Ensure the Puppet 4 repositories for your hosts are enabled in Satellite Server.

Ensure your hosts associated Content Views have been updated to include the Puppet 4 agent.

The Puppet repositories for upgrading a host are Red Hat release and platform dependent, and
sometimes also architecture dependent.

34
 CHAPTER 3. UPGRADING PUPPET

The Puppet 4 repositories take the following form for desktop, server, and workstation:

rhel-X-platform-satellite-tools-6.3-puppet4-rpms

Where X is the major release version, and platform is desktop, server, or workstation.

The Puppet 4 repositories take the following form for alternative architectures:

rhel-X-for-architecture-satellite-tools-6.3-puppet4-rpms

Where X is the major release version, and architecture is for example arm, power, hpc-node,
or system-z. Some repositories are for subscriptions with extended support. For example,
Extended Update Support (EUS) is indicated by eus after the architecture.

For more information about types of extended support, see the Red Hat Knowledgebase article
Red Hat Enterprise Linux - Top Support Policies.

1. On the content host, search for the Puppet 4 RPM repository:

# subscription-manager repos |grep puppet4

2. Enable the Puppet 4 repository suitable for the host, for example:

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

3. Update all packages:

# yum update

4. Until Red Hat bug Bug 1517624 has been resolved, perform these additional steps:

# cp -rp /var/lib/puppet/ssl /etc/puppetlabs/puppet/

# cp /etc/puppet/puppet.conf.rpmsave
/etc/puppetlabs/puppet/puppet.conf
# sed -i 's|/var/lib/puppet|/opt/puppetlabs/puppet/cache|'
/etc/puppetlabs/puppet/puppet.conf
# sed -i 's|/var/log/puppet|/var/log/puppetlabs/puppet|'
/etc/puppetlabs/puppet/puppet.conf
# sed -i 's|/var/run/puppet|/var/run/puppetlabs|'
/etc/puppetlabs/puppet/puppet.conf
# sed -i 's|$vardir/ssl|/etc/puppetlabs/puppet/ssl|'
/etc/puppetlabs/puppet/puppet.conf

Post Upgrade Tasks

When you upgrade to Puppet 4, Puppet Server cannot function if the noexec bit is set on the temporary
mount point that Java uses.

Complete the following steps to ensure that the puppetserver service can start correctly:

1. Open the /etc/sysconfig/puppetserver file for editing:

# vi /etc/sysconfig/puppetserver

35
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

2. In the /etc/sysconfig/puppetserver file, change JAVA_ARGS="-Xms2G -Xmx2G -

XX:MaxPermSize=256m" to the following:

JAVA_ARGS="-Xms2G -Xmx2G -XX:MaxPermSize=256m -

Djava.io.tmpdir=/var/tmp"

You can set the variable /var/tmp to the directory you prefer.

3. Open the /etc/foreman-installer/custom-hiera.yaml for editing:

# vi /etc/foreman-installer/custom-hiera.yaml

4. In the /etc/foreman-installer/custom-hiera.yaml file, add the following line to make

your changes persistent across satellite-installer executions:

puppet::server_jvm_extra_args: '-XX:MaxPermSize=256m -
Djava.io.tmpdir=/var/tmp'

You can set the variable /var/tmp to the directory you prefer.

5. Restart the puppetserver service:

# systemctl restart puppetserver

6. Verify that the puppetserver service is running:

# systemctl status puppetserver

36
 CHAPTER 4. UPDATING SATELLITE SERVER, CAPSULE SERVER, AND CONTENT HOSTS

CHAPTER 4. UPDATING SATELLITE SERVER, CAPSULE

SERVER, AND CONTENT HOSTS
Use this chapter to update your existing Red Hat Satellite environment to a new minor version of Red Hat
Satellite, for example, from 6.3.0 to 6.3.1. For more information, see Chapter 4, Updating Satellite
Server, Capsule Server, and Content Hosts.

This chapter includes update procedures for Satellite Server, Capsule Server, and Content Hosts.

Updating Between Minor Versions of Satellite

Updating is the process of migrating Satellite Server, Capsule Server, and Content Hosts to a new minor
version. Updates typically patch security vulnerabilities and correct minor issues discovered after code is
released. Generally speaking, updates require little time and are non-disruptive to your operating
environment.

Before updating, check the Red Hat Satellite Release Notes for potential conflicts and backup your
Satellite Server and all Capsule Servers. For more information, see Backing Up and Restoring Satellite
Server and Capsule Server in Administering Red Hat Satellite.

Follow these procedures to update between minor versions, for example, from 6.3.0 to 6.3.1.

4.1. UPDATING SATELLITE SERVER

Prerequisites

Ensure that you have synchronized Satellite Server repositories for Satellite, Capsule, and
Satellite Tools.

Ensure each external Capsule and Content Host can be updated by promoting the updated
repositories to all relevant Content Views.

If you have made changes to configuration files, manually or using a tool such as Hiera, they will
be overwritten when the installation script is run during upgrading or updating. You can use the
--noop option with the satellite-installer script to test for changes. For more
information, see the Red Hat Knowledgebase solution How to use the noop option to check for
changes in Satellite config files during an upgrade.

Updating Satellite Server to the Next Minor Version

To Update Satellite Server:

1. Ensure the Satellite Maintenance repository is enabled:

# subscription-manager repos --enable \

rhel-7-server-satellite-maintenance-6-rpms

2. Ensure foreman-maintain is installed and up to date:

# yum install rubygem-foreman_maintain

3. Check the available versions to confirm the next minor version is listed:

# foreman-maintain upgrade list-versions

37
Red Hat Satellite 6.3 Upgrading and Updating Red Hat Satellite

4. Use the health check option to determine if the system is ready for upgrade. On first use of this
command, foreman-maintain prompts you to enter the hammer admin user credentials and
saves them in the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

# foreman-maintain upgrade check --target-version 6.3.z

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

5. Because of the lengthy update 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.

6. Perform the upgrade:

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

7. Check to see if any of the kernel packages were updated since you last rebooted the system:

# rpm -qa --last | grep kernel

8. If a kernel update occurred since you last rebooted the system, reboot the system:

# reboot

4.2. UPDATING CAPSULE SERVER

Updating Capsule Servers to the Next Minor Version

To Update a Capsule Server:

1. Check that only the correct repositories are enabled:

a. List the enabled repositories:

# subscription-manager repos --list-enabled

b. Ensure that you only have the following repositories enabled:

rhel-7-server-rpms
rhel-7-server-satellite-capsule-6.3-rpms
rhel-server-rhscl-7-rpms
rhel-7-server-satellite-tools-6.3-rpms

If required, see the Configuring Repositories section of the Red Hat Satellite Installation
Guide for more information on disabling and enabling repositories. The rhel-7-server-
satellite-tools-6.3-rpms repository provides Katello Agent. If required, see the
Installing the katello Agent section of the Red Hat Satellite Installation Guide for more
information. The Red Hat Software Collections repository is optional, it is required for the
Remote Execution feature.

38
 CHAPTER 4. UPDATING SATELLITE SERVER, CAPSULE SERVER, AND CONTENT HOSTS

2. Stop Katello services:

# katello-service stop

3. Update all packages:

# yum update

If a kernel update occurs, make a note to reboot after the upgrade is complete. Do not reboot at
this point.

4. Perform the update by running the installer script with the --upgrade option.

# satellite-installer --scenario capsule --upgrade

5. If a kernel update occurred during the yum update step, reboot the system:

# reboot

6. If you did not reboot the system in the previous step, restart goferd:

# systemctl restart goferd

4.3. UPDATING CONTENT HOSTS

Updating Content Hosts to the Next Minor Version

To Update a Content Host, enter the following commands:

1. Update all packages:

# yum update

2. If a kernel update occurs, reboot the system:

# reboot

3. If you did not reboot the system in the previous step, restart goferd:

# systemctl restart goferd

39