Chapter 3. Transitioning from Satellite 5 to 6

This chapter describes how to perform migrating of clients from the old Satellite 5 to Satellite 6 using the bootstrap script, and how to retire the old Satellite instance after the transition process is finished.

The bootstrap script used for transition handles content registration, Product certificates, and Puppet configuration. The bootstrap script has the advantage of subscribing a Red Hat Enterprise Linux system to a Satellite 6, regardless of where it is registered (RHN, Satellite 5, SAM, RHSM), or if it is registered at all.

The bootstrap script enables you to:

  • Migrate a client from Satellite 5 to Satellite 6.
  • Migrate a client from one Satellite 6 instance to another.
  • Register a new Red Hat Enterprise Linux system to Satellite 6.

3.1. Prerequisites

  • If you have Satellite 5.8 running on a s390 system, you must build a fresh Satellite 6 on an x86_64 architecture system. Satellite 6 cannot run on s390 systems.
  • Ensure you start with a fully-functional, up-to-date Satellite 6.
  • The Satellite 6 instance must be synchronized with the required Red Hat content before you start the transition process.
  • You have configured activation keys for the hosts. For more information on configuring activation keys, see Managing Activation Keys in the Content Management Guide.
  • Optionally, configure host collections to match your environment. For more information on creating a host collection, see Configuring Host Collections in Managing Hosts.

3.2. The Transitioning Workflow

The workflow includes the following steps:

  1. Installing the Bootstrap Script on a Client.
  2. Migrating a Red Hat Enterprise Linux System:

    1. Running the bootstrap script on a client system.
    2. Approving the Puppet certificate in the web UI as an administrator.
    3. Ensuring the completing of the transition process on a client system.

3.3. Performing the Transition

Satellite 6 uses the bootstrap script to migrate existing clients from the old Satellite 5 instance.

The bootstrap script handles content registration, Product certificates, and Puppet configuration.

3.3.1. Installing the Bootstrap Script

The bootstrap script package, katello-client-bootstrap, is installed by default on the base system of Satellite Server and the script itself is installed in the /var/www/html/pub/ directory to make it available to clients. It can be accessed using a URL in the following form:

The script includes documentation in a readme file. To view the file on the Satellite CLI:

$ less /usr/share/doc/katello-client-bootstrap-version/

Installing the Bootstrap Script on a Client

As the script is only required once, and only for the root user, you can place it in /root and remove after use. As root, install the bootstrap script on client systems as follows:

  1. Ensure you are in the root directory:

    # cd
  2. Download the script:

    # curl -O

    This will install the script to the current directory.

  3. Make the script executable:

    # chmod +x
  4. To confirm that the script can now be run, view the usage statement as follows:

    # ./ -h
  5. Optionally, when the transition process is complete, remove the script:

    # cd
    # rm

3.3.2. Migrating a Red Hat Enterprise Linux 6 System

Migrating a Red Hat Enterprise Linux 6 System

  1. Enter the bootstrap command as follows with values suitable for your environment.

    For the --server option, specify the FQDN name of Satellite Server or Capsule Server. For --location, --organization, and --hostgroup options, use quoted names, not labels, as arguments to the options.

    # --login=admin \
    --server \
    --location="Example Location" \
    --organization="Example Organization" \
    --hostgroup="Example Host Group" \

    The script will prompt you for the password corresponding to the Satellite user name you entered with the --login option.

  2. The script will run and send notices of progress to stdout. Watch for output prompting you to approve the Puppet certificate. For example:

    [NOTIFICATION], [2016-04-26 10:16:00], [Visit the UI and approve this certificate via Infrastructure->Capsules]
    [NOTIFICATION], [2016-04-26 10:16:00], [if auto-signing is disabled]
    [RUNNING], [2016-04-26 10:16:00], [/usr/bin/puppet agent --test --noop --tags no_such_tag --waitforcert 10]
  3. The client will wait until an administrator approves the Puppet certificate. Sign the Puppet certificate as follows:

    1. In the web UI, navigate to Infrastructure > Capsules.
    2. Select Certificates to the right of the name of the Capsule corresponding to the FQDN given with the --server option.
    3. In the Actions column select Sign to approve the client’s Puppet certificate.
    4. Return to the client to see the remainder of the bootstrap process completing.
  4. In the web UI, navigate to Hosts > All hosts and ensure that the client is connected to the correct host group.

For more information about using the bootstrap script, see Registering Hosts to Red Hat Satellite Using The Bootstrap Script in Managing Hosts.

3.4. Retiring the old Satellite 5 Server

This section shows how to retire the old Satellite 5 Server after you have performed the complete migration from Red Hat Satellite 5 Server to a new Satellite 6 Server and you do not need the old Satellite 5 Server anymore. If you have migrated your Satellite 5 to the new RHSM system, proceed to Section 3.4.1, “Migrating Subscriptions to the New Satellite 6”.

If you have not migrated your Satellite 5 to the new RHSM system, create new manifests as described in Managing Subscriptions in the Content Management Guide and add them to the new Satellite 6. Optionally, run the following Python script to delete the profile of the old Satellite from RHN:

#!/usr/bin/env python

import getpass
import os
import sys
import libxml2
import xmlrpclib
from optparse import OptionParser

parser = OptionParser()
parser.add_option("-l", "--login", dest="login", help="Login user for RHN Satellite/Hosted", metavar="LOGIN")
parser.add_option("-p", "--password", dest="password", help="Password for specified user. Will prompt if omitted", metavar="PASSWORD")
parser.add_option("-s", "--server", dest="serverfqdn", help="FQDN of satellite server - omit https:// (default: %s)" % DEFAULT_SERVERFQDN, metavar="SERVERFQDN", default=DEFAULT_SERVERFQDN)
(options, args) = parser.parse_args()

if not options.login:
    print "Must specify login option.  See usage:"
    print "\nExample usage: ./ -l admin -p password"
    login = options.login
    password = options.password
    serverfqdn = options.serverfqdn

if not password: password = getpass.getpass("%s's password:" % login)

SATELLITE_URL = "https://%s/rpc/api" % serverfqdn
SYSTEMID_FILE = "/etc/sysconfig/rhn/systemid"

# Check For root
# Have to be root to open the SYSTEMID_FILE which is chmod'd 0600
if os.getuid() != 0:
    print "This script requires root-level access to run."

# Log into Satellite and get an authentication token
client = xmlrpclib.Server(SATELLITE_URL, verbose=0)

# Parse /etc/sysconfig/rhn/systemid to ge the system ID
# Use the systemid and delete the systems RHN profile
parsed_file = libxml2.parseDoc(file(SYSTEMID_FILE).read())
systemid = parsed_file.xpathEval('string(//member[* ="system_id"]/value/string)').split('-')[1]
print systemid
    print "The system with SystemID " + systemid + " was successfully deleted"
except xmlrpclib.Fault, e:
    print "XMLRPC fault \n\t%s" % e

# Logout of Satellite

3.4.1. Migrating Subscriptions to the New Satellite 6

This section describes how to migrate subscriptions from the old Satellite 5 Server to the new Satellite 6 Server.

  1. Configure new subscriptions:

    1. Log in to the Customer Portal and go to SUBSCRIPTIONS.
    2. Navigate to Inventory and click Satellite Organizations.
    3. Select the check box to the left of the name of the old Satellite 5 Server and click Delete Selected. In the alert box that appears, click Delete to delete the unit.
    4. Click on the name of the new Satellite 6 Server and select the check box to the left of the name of the transition subscription. Click Remove selected. In the alert box click Remove to remove the subscription.
    5. Click Attach a subscription, select the real Satellite subscription, and click Attach selected.
    6. Run the following command on the new Satellite 6 Server to refresh subscription manager.

      # subscription-manager refresh
  2. Enable repositories on the new Satellite 6 Server

    1. On the old Satellite 5 Server use the following command to view what channels you had enabled.

      # spacewalk-channel -l
    2. On the new Satellite 6 Server use the following command to list enabled repositories for an organization:

      # hammer product list --organization "organization_name"
    3. Configure the new Satellite 6 Server to ensure all necessary repositories are enabled.

      For Web UI users

      Navigate to Content → Red Hat Repositories and select repositories to be enabled.

      For CLI Users

      Enable repositories using either the name or ID number. Optionally, include the release version and base architecture.

      # hammer repository-set enable \
      --product "product_name" \
      --name "repository_name" \
      --organization "org_name" \
      --releasever "" \
      --basearch "x86_64"