-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Satellite
Chapter 4. Transitioning from Satellite 5 to 6
This chapter describes the prerequisites for performing a successful transition from Red Hat Satellite 5 to Satellite 6, and the basic transition workflow. It also describes how to install and use the required transition tools, and covers the most common transition use cases.
4.1. Prerequisites and Assumptions
The following list describes the prerequisites and assumptions you need to address to ensure a successful transition from Red Hat Satellite 5.6 or 5.7 to Satellite 6.
- Ensure you start with a fully-functional, up-to-date Satellite 5.6 or 5.7 Server.
- Satellite 6 must be correctly installed and configured on a second machine. This installation must include a manifest that provides access to the same content as the Satellite 5.6 or 5.7 instance, and for the same number of clients.
- The Satellite 6 instance must be synchronized with the desired Red Hat content before you start the transition process. The transition tools are purposely designed not to copy Red Hat content from Satellite 5 to Satellite 6.
- The migration tools are designed to work in environments where network security prevents direct connection between the Satellite 5 and Satellite 6 instances. Consequently, the tools were designed to work in isolation, in two stages. The first stage is to export data from Satellite 5, and the second stage is to import data into Satellite 6. After the first stage is complete, you can use network tools (for example, SCP) or physical media to transfer the exported data to the Satellite 6 Server’s base system.
-
The export tools run on the Satellite 5 system. This allows direct access to the Satellite 5 database, repositories, and existing tools such as
spacewalk-report
. It is also necessary because some customer sites have networking restrictions that limit access to the Satellite 5 instance. - The import tools run on the Satellite 6 system, for similar reasons.
Given the differences in data models and functionality between Satellite 5 and Satellite 6, importing Satellite 5 data cannot achieve a perfectly-configured Satellite 6 instance. The goal is to reduce the amount of configuration as much as possible. The main purpose of the transition tools is to create an initial setup of a new Satellite 6 installation. It is possible to import data from your Satellite 5 Server at any time, and the transition tools will attempt to handle any data conflicts that occur. However, Red Hat recommends that you perform the transition before you perform any tasks except required configuration on your Satellite 6 Server.
4.2. The Transitioning Workflow
The transitioning workflow consists of two main phases, each consisting of several steps. These are described in the following sections.
Preparing for Transition
The preparation phase consists of the following steps:
- Install Satellite 6.
- Navigate to the Red Hat Customer Portal and create a manifest for each organization that you are going to import.
-
Download those manifests to the Satellite 6 base system. Rename each manifest according to the organization for which it is intended. Replace each and every punctuation mark or space with an underscore. For example, an organization called
MyOrg, Inc.
can use the MYORG__INC_.zip manifest. Use the
hammer import organization
command to import your organizations and their manifests. For example:# hammer import organization --csv-file /tmp/exports/users.csv \ --upload-manifests-from /root/manifest-dir
Performing the Transition
After you have completed the steps described in Section 4.2, “The Transitioning Workflow”, the Satellite 6 instance is ready to accept transition data. This phase consists of the following steps:
- Export the entities (metadata and content) from an installed Satellite 5 system, using tools installed on the Satellite 5 Server machine.
- Transfer the exported entities to the Satellite 6 instance, using SCP, a USB device, or other suitable means.
- Import the Satellite 5 entities, using tools installed on the Satellite 6 Server machine.
- Tune the Satellite 6 configuration to suit your deployment.
The existing spacewalk-report
tool extracts most of the information from the Satellite 5 instance. Several new reports have been added, as well as two new tools that are used as part of the export process:
-
spacewalk-channel-export
: This tool exports channel data and metadata beyond that available at the report level. -
spacewalk-export
: This tool is a wrapper that combines the various export processes into a single tool, and packages the resulting export data into a single data set that can be transferred to the Satellite 6 system.
The existing hammer
tool has been extended with a new plug-in. This plug-in is compatible with the Satellite 5 export data format, and accesses the Satellite 6 instance using its public API. The import tools track which Satellite 5 entities have been mapped to which Satellite 6 entities. This means you can run the import tools multiple times without duplicating entities.
4.3. Preparing for the Transition
The transition tools and process assume the following conditions are true:
- A fully-functional Satellite 5.6 or 5.7 instance exists.
- Satellite 6 has been correctly installed on a new machine.
- Direct connectivity between the Satellite 5 and Satellite 6 instances cannot be guaranteed.
- The Satellite 6 instance contains a manifest that enables access to the same content that the Satellite 5 instance accesses, for the same number of client machines.
- The Satellite 6 instance has already synchronized the desired Red Hat content. The transition tools make every attempt not to copy Red Hat content from Satellite 5 to Satellite 6.
-
The export tools execute on the Satellite 5 system. This is necessary to allow direct access to the Satellite 5 database, repositories, and existing tools such as
spacewalk-report
. - The import tools execute on the Satellite 6 system, for similar reasons.
- The result of importing Satellite 5 data is not a perfectly-configured Satellite 6 instance. The goal is to alleviate as much setup as reasonably possible, given the differences in data models and functionality between Satellite 5 and 6.
For hosts to be able to check in with Satellite 6, the daemon supplied by the subscription-manager package,
rhsmcertd
, must be running. Subscription-manager is installed and enabled by default on Red Hat Enterprise Linux 7, but for Red Hat Enterprise Linux 5 and 6 you must ensure that it is.On the hosts, check the status of
rhsmcertd
.# service rhsmcertd status
If necessary, start
rhsmcertd
.# service rhsmcertd start
To enable subscription-manager to start at system start.
# chkconfig rhsmcertd on
4.3.1. Preparing the Satellite 5 Server for Transition
Preparing your Satellite 5 Server for transition requires that you subscribe to some specific channels and download extra packages to ensure that your transition runs smoothly. This is described in the following sections.
Installing the Latest Reporting Packages
On Satellite 5, install the latest spacewalk-reports
and spacewalk-utils
packages from the Satellite 5.6 or 5.7 channel.
# yum install spacewalk-reports spacewalk-utils
The latest spacewalk-report
package provides additional reports which are used by the transition tools:
- activation-keys
- channels
- config-files-latest
- kickstart-scripts
- repositories
- system-profiles
You can use the spacewalk-report
command to confirm the addition of these new reports.
The spacewalk-utils
package provides two additional command-line tools, which are used by the transition tools: /usr/bin/spacewalk-export
and /usr/bin/spacewalk-export-channels
.
The spacewalk-reports
package is fully supported by Red Hat and provides additional reports designed for use by the spacewalk-export
tools. You can also use these reports for general, day-to-day reporting.
Installing Extra Transition Packages
Ensure your Satellite 5 Server is subscribed to the RHN Tools channel. This channel provides the latest updates to the subscription-manager
and python-rhsm
packages, which are required to install the subscription-manager-migration
command.
Install the subscription-manager
and python-rhsm
packages:
# yum install subscription-manager python-rhsm
4.3.2. Preparing the Satellite 6 Server for Transition
To prepare the Satellite 6 Server for transition, ensure the rubygem-hammer_cli_import
package is installed. If necessary, enter yum install rubygem-hammer_cli_import
to install it from the Satellite 6 repositories.
On Satellite 6, enter the following command to verify that the transition tools were successfully installed:
# hammer import --help Usage: hammer import [OPTIONS] SUBCOMMAND [ARG] ...
4.4. Exporting Entities from Satellite 5
Before you can transition your Satellite 5 data to Satellite 6, you need to export the required entities into a specially-formatted file suitable for use by the Satellite 6 import tools.
The expected workflow on the Satellite 5 Server is to use the spacewalk-export
command as a wrapper. This wrapper command calls the following commands to export Satellite 5 entities:
- spacewalk-report channels
- Export all custom and cloned channels and repositories for all organizations.
- spacewalk-report activation-keys
- Export activation keys.
- spacewalk-report kickstart-scripts
- Exports kickstart scripts for all organizations.
- spacewalk-report users
- Export organizations and users.
- spacewalk-report system-groups
- Export all system groups for all organizations.
- spacewalk-report config-files-latest
- Export information on configuration channels and the latest configuration file versions.
- spacewalk-report repositories
- Export repositories.
- spacewalk-report system-profiles
- Export information about the systems managed by Satellite 5.
Running the exports directly on the Satellite 5 Server allows complete access to the spacewalk-report
functionality, including limiting the data exported, using the --where
and --like
options. However, if the goal is to export as much as possible, or at most limit by organization, the spacewalk-export
tool can manage the process for you.
The spacewalk-export
command also uses the spacewalk-export-channels
command to collect information and content for non-Red Hat channels.
4.4.1. Exporting Data from Satellite 5
On Satellite 5, enter the following command to list the entities that you can export:
# spacewalk-export --list-entities INFO: Currently-supported entities include: INFO: channels : Custom/cloned channels and repositories for all organizations INFO: activation-keys : Activation keys INFO: kickstart-scripts : Kickstart scripts for all organizations INFO: users : Users and Organizations INFO: system-groups : System-groups for all organizations INFO: config-files-latest : Latest revision of all configuration files INFO: repositories : Defined repositories INFO: system-profiles : System profiles for all organizations
You can use the --entities
option to limit the export by entity.
# spacewalk-export --entities users,repositories
You can also use the --entities
option with the channels
parameter to export all channel data available on the Satellite 5 instance. Using this format calls both spacewalk-report channels
and spacewalk-export-channels
commands, and consequently exports both Red Hat and non-Red Hat channels.
You can use the --org
option to limit the export by organization. Use the spacewalk-report users
command to retrieve a list of organization IDs.
# spacewalk-export --org=organization-id
If you omit the --org
option, the spacewalk-export
command will export all channels, including any not assigned to an organization. If you have only one organization then it is recommended to omit the option.
By default, the spacewalk-export
command stores all exports in the ~/spacewalk-export-dir/exports file, and packages all export data into the ~/spacewalk-export-dir/spacewalk_export.tar.gz file. You can use the following options on the command line to specify different values:
# spacewalk-export --export-dir=your-export-directory # spacewalk-export --export-package=your-export-package-name
The following is an example of a typical export session:
Example 4.1. Example of a Typical Export Session
# spacewalk-export INFO: Processing channels... Processing organization: GLOBAL SUPPORT SERVI RED HAT, INC. * channel: clone-rhel-x86_64-server-5 with: 15778 packages * channel: clone-rhel-x86_64-server-6 with: 12157 packages * channel: clone-rhel-x86_64-server-optional-6 with: 6931 packages . . * channel: epel-puppet-rhel6-server-x86_64 with: 8 packages * channel: puppet-rhel5-server-x86_64 with: 409 packages * channel: puppet-rhel6-server-x86_64 with: 373 packages INFO: Processing system-groups... INFO: Processing activation-keys... INFO: Processing repositories... INFO: Processing users... INFO: Export-file created at /root/spacewalk-export-dir/spacewalk_export.tar.gz
4.4.2. Transferring Exports to Satellite 6
After you have successfully exported all the required entities from your Satellite 5 Server, transfer the /root/spacewalk-export-dir/spacewalk_export.tar.gz file to the Satellite 6 Server. If the two servers are connected over the network, you can use scp
or a similar tool to transfer the file. Alternatively, use removable media such as a USB device or DVD.
Red Hat strongly recommends that you place the spacewalk_export.tar.gz file in the /tmp/ directory on your Satellite 6 system. This ensures that the extracted files have suitable permissions for the import process.
Extracting the Exported Archive
Extract the spacewalk_exports.tar.gz archive into the /tmp/ directory on your Satellite 6 Server. This creates a /tmp/exports/ directory that contains all the exported data, ready to import and recreate within the Satellite 6 Server. As part of the import process, use the --directory
option with the hammer import
commands to specify this directory as the source directory.
Ensure you have sufficient disk space to extract the archive within the /tmp/ directory.
The transition process uses local disk mirrors to import data from the archive into Satellite 6. If the /tmp/ directory cannot be used, ensure that you use an alternative that provides sufficient space and read access for the apache user and group.
On Satellite 6, ensure that the apache user and group has read access to the /tmp/exports/ directory. If necessary, adjust the group and permissions:
# chgrp -R apache /tmp/exports/ # chmod -R 0750 /tmp/exports/
If SELinux is enabled, ensure the tmp_t
SELinux file context is applied to the /tmp/exports/ directory. If necessary, apply the label manually:
# chcon -R system_u:object_r:tmp_t:s0 /tmp/exports/
If the SELinux context is not set correctly, Satellite cannot synchronize the content.
4.5. Importing to Satellite 6
Importing Satellite 5 data to a fresh Satellite 6 installation can be a lengthy process, requiring multiple steps, and the order in which you import the different entities is important. Some entities depend on the existence of others, and if you attempt to import entities in the wrong order, the import could fail. You also need to know exactly which exported CSV file is appropriate for which entity.
Options for Importing Entities
You can perform either a manual or an unattended import. Satellite 6 provides the hammer import all
command to facilitate each of these approaches. This command is a wrapper for the various subcommands that import the different groups of entities. It calls each of the required subcommands in the correct order to complete the import of entities from Satellite 5 to a fresh Satellite 6 installation. You can perform any required setup or manipulation of your Satellite 5 data, create the required manifests, and then import everything in one step.
The hammer import all
command ensures that entities with dependencies are created in the correct order. You can use the hammer import all --list-entities
command to display all entities that the import process is aware of. This command also lists the entities in order of dependency. This is useful if you want to limit which entities to import (using the --entities
parameter), and also if you choose to perform a manual import, and need to know the correct order in which to run the individual import commands (using the --dry-run
parameter).
4.5.1. Prerequisites
The prerequisites for performing either a manual or an unattended import are the same:
-
Valid output of
satellite-export all
from your Satellite 5 Server copied to the Satellite 6 Server and extracted into a suitable directory. The default location is /tmp/exports, but you can override this with the--directory
parameter. New manifests for any organizations that you need to create in Satellite 6. There is no default manifest directory; specify the directory with the
--manifest-directory
parameter.NoteIf you do not use
--manifest-directory
, you need to import the manifests before you run thehammer import all
command.
4.5.2. The Import Workflow
After the data exported from Satellite 5 is made available to the Satellite 6 system, it is ready to import. The import workflow is as follows:
- Import organizations. This includes importing a manifest if one exists.
- Import users.
- Import system groups as host collections.
- Enable and synchronize Red Hat repositories. This is referred to as repository discovery.
- Import repositories.
- Import custom channels and cloned channels as content views.
- Import activation keys.
- Import kickstart snippets as template snippets.
- Import configuration files to Puppet modules.
- Import system profiles as content hosts.
4.5.3. Performing an Unattended Import
This section describes how to use the hammer import all
command to perform an unattended import of entities, previously extracted from Satellite 5 (for example, using the spacewalk-export
command) as described in Section 4.4.2, “Transferring Exports to Satellite 6”.
On Satellite 6, use a command as follows to import the data previously extracted to the /tmp/exports directory:
# hammer import all --directory=/tmp/exports
If any errors occur during the import, inspect the ~/import.log file for details. You can also use the --logfile filename
parameter when you enter the import
command to specify a different log file location.
4.5.3.1. Fine-tuning the Import Process
The hammer import all
command passes information to each of the import subcommands. Unless otherwise specified, this command uses default values to perform the import. You can use the following parameters to help fine-tune the import:
-
--into-org-id
is passed toimport organization --into-org-id
. -
--manifest-directory
is passed toimport organization --upload-manifests-from
. -
--merge-users
is passed toimport user --merge-users
. -
--macro_mapping
is passed toimport config-file --macro-mapping
. -
--debug
,--delete
,--directory
,--logfile
,--quiet
, and--verbose
work as for all otherhammer import
commands. -
--synchronize
is passed to the--synchronize
parameter for the following subcommands:repository-enable
,repository
, andcontent-view
. -
--no-async
is passed to the--no-async
parameter for the following subcommands:repository-enable
,repository
, andcontent-view
. -
--wait
is passed to the--wait
parameter for the following subcommands:repository-enable
,repository
, andcontent-view
.
Red Hat recommends that you always use the --synchronize
, --wait
, and --no-async
parameters.
If --synchronize
is not specified, the import
command does not synchronize content from Red Hat (repository-enable
) or non-Red Hat (repository
) sources. Content Views and Content Host creation depend on having content available, and will fail if synchronization is incomplete.
If --wait
is not specified, the import all
command does not wait until repositories have finished synchronizing. This will result in errors when the tool attempts to create content views and content hosts, because those entities rely on content being available.
If --no-async
is not specified, the import all
command makes all of its requests to Satellite 6 in parallel. This can overload the Satellite 6 Server and cause a variety of errors, such as connection timeouts and database-connection refusals.
The --synchronize
, --wait
, and --no-async
parameters do not take arguments; if they are not specified on the command line, they default to false.
If an import-entity-command is not exposed by import all
, the default for that parameter of that entity is used. For example, for import user
, the role mapping at /etc/hammer/cli.modules.d/import/role_map.yml is always used.
4.5.4. Performing a Manual Import
This section describes how to perform a manual import of entities from Satellite 5 to a new installation of Satellite 6.
The order in which you import entities is important. Entities are owned by organizations in Satellite 5; consequently, you need to import organizations before users, for example. You can use the hammer import all --dry-run
command to list the available entities and the order in which they should be imported.
4.6. Importing Organizations
To transition organizations, use the users.csv file and recreate the Satellite 5 organizations listed within it. You can use the hammer import
command on the command line or use the hammer interactive shell.
Run the following command to import organizations into Satellite 6:
# hammer import organization --csv-file /tmp/exports/users.csv
The following is an example of an interactive session. This example also demonstrates the --upload-manifests-from
and --verbose
options:
Example 4.2. Example of Interactive Import Session
# hammer shell
hammer> import organization --csv-file /tmp/exports/users.csv \
--upload-manifests-from /root/manifests --verbose
Importing from /tmp/exports/users.csv
Creating new organization: RED HAT SATELLITE ENGINEERING
Uploading manifest /root/manifests/RED_HAT_SATELLITE_ENGINEERING.zip to org-id 5
Waiting for the task [a231d19c-aee7-42b8-9566-07651ac029f4] ......
Organization [1->5] already imported.
Organization [1->5] already imported.
Organization [1->5] already imported.
Organization [1->5] already imported.
Creating new organization: SOE-ORG
Uploading manifest /root/manifests/SOE-ORG.zip to org-id 6
Waiting for the task [5da6dd16-0bf6-4ad0-924f-a9d5e1802565] ......
Organization [7->6] already imported.
Summary
Found 5 organizations.
Created 2 organizations.
Uploaded 2 manifests.
Use the hammer organization list
command to list the organizations within Satellite 6.
# hammer organization list ---|-------------------------------|-------------------------------|------------ ID | NAME | LABEL | DESCRIPTION ---|-------------------------------|-------------------------------|------------ 5 | RED HAT SATELLITE ENGINEERING | RED_HAT_SATELLITE_ENGINEERING | 6 | Test Organization | Test_Organization | 3 | Satellite Documentation | Satellite_Documentation | ---|-------------------------------|-------------------------------|------------
The import process creates organizations based on the organizations listed in the user.csv file. The Satellite 5 organization IDs are mapped to new Satellite 6 organization IDs. This is illustrated by the "[1→5]" and similar entries in Example 4.2, “Example of Interactive Import Session”. Alternatively, you can use the hammer import organization --into-org-id org_id
command to reduce all of the Satellite 5 organizations into a single, flat organization within Satellite 6. You can use the hammer organization list
command to determine the correct organization ID.
All import data is stored in CSV files in the ~/.transition_data/ directory. This information is critical for any subsequent data imports. Do not modify the data in this directory.
A history of hammer commands is stored in the /root/.foreman/history file, and any errors from hammer commands are stored in the /root/.foreman/log/hammer.log file.
The hammer import
command logs all output to the ~/import.log file. You can use the --logfile
option to any hammer import
subcommand to specify a different name and location for the log file.
Generating and Activating a Manifest
You need to activate a manifest for the organizations for which you want to populate content and other data. You can generate a manifest from within the Red Hat Customer Portal, and then activate that manifest for the imported organization.
The following procedure assumes you have already created a suitable manifest in the Red Hat Customer Portal.
To Activate the Manifest for Satellite 6:
- Log in to the Satellite 6 web UI as an administrative user.
- Select the required organization from the main menu at the upper left.
- Click Content > Red Hat Subscriptions
- On the Actions tab, under Upload New Manifest, click Browse, navigate to and select the manifest file that you downloaded.
- In the Satellite 6 web UI, click Upload to upload the manifest to the Satellite 6 Server.
Repeat this procedure for each required organization.
4.6.1. Importing Users
The import process recreates the Satellite 5 users in each Satellite 5 organization from the users.csv file. User passwords cannot be copied from Satellite 5 to Satellite 6; instead, the process generates a new random password for each user that it imports. This information is saved in a CSV file, which as the administrator you can parse and send notifications to each user listed with their new password. You can use the hammer import
command on the command line or use the hammer interactive shell.
The import process tracks which entities have already been processed. You can, for example, enter the hammer import user
command multiple times, using different input files (CSV files). The import
command recognizes user IDs it has already imported, and skips them on subsequent processes.
Run the following command to import users into Satellite 6:
# hammer import user --csv-file /tmp/exports/users.csv \ --new-passwords passwords.csv
The following is an example of an interactive session:
Example 4.3. Example of Interactive Import Session
hammer> import user --csv-file /tmp/exports/users.csv --new-passwords /root/new-user-passwords.csv Summary Created 7 users.
To show the users were created, log in to the web UI and navigate to Administer > Users. Alternatively, use the command line as shown below. You can list all users or search by name or other properties.
# hammer user list ---|-------------------|-------------|------------------- ID | LOGIN | NAME | EMAIL ---|-------------------|-------------|------------------- 4 | sat5_admin | Admin Nimda | root@localhost 3 | admin | Admin User | root@milky.way 6 | normal | Morm Al | root@localhost 10 | testorg | Red Hat | root@localhost 7 | sysgroup | Red Hat | root@localhost 8 | suseadmin | SUSE Admin | root@localhost ---|-------------------|-------------|------------------- # hammer user list --search sat5_admin ---|------------|-------------|--------------- ID | LOGIN | NAME | EMAIL ---|------------|-------------|--------------- 4 | sat5_admin | Admin Nimda | root@localhost ---|------------|-------------|---------------
The following is an example password file for the imported users:
# head new-user-passwords.csv mail,login,password sat5admin@example.com,sat5_admin,sat5_admin_svenkmxf auser1@example.com,auser1,auser1_pwfnagdk auser2@example.com,auser2,auser2_rsgywazf
By default, Satellite 6 creates an admin user as the initial administrator. It is common for Satellite 5 customers to also create a generic administrative user; consequently, if the import process detects a Satellite 5 admin user, it renames that user to sat5_admin.
4.6.2. Transitioning System Groups to Host Collections
Red Hat Satellite 5 uses system groups to maintain collections of multiple systems. Satellite 6 uses host collections to perform the same task. The Satellite transition tools provide options to transition your Satellite 5 system groups to Satellite 6 host collections.
The following example demonstrates a typical use case. Run this command on your Satellite 6 system, and substitute the CSV file with your own:
# hammer import host-collection --csv-file /tmp/exports/system-groups.csv
Summary
Created 4 host_collections.
You can use the hammer host-collection list --organization-id ORG-ID
to verify that the system groups have been recreated as host collections. Ensure you use the correct organization ID.
You can also log in to the web UI as an administrator to verify that the host collections were created. Ensure you are in the correct organization, and then navigate to Hosts > Host Collections.
4.6.3. Enabling Yum Repositories
Red Hat Satellite 5 and Satellite 6 use different methods to group RPM files and to present them. In Satellite 5, all RPM files are placed into channels which you clone, and you then manage the content from within those cloned channels. The satellite-sync
command synchronizes Red Hat channels from RHN into Satellite 5. In Satellite 6, everything is a yum repository and you filter the content from that repository that is exposed to the systems being managed by Satellite 6.
Several options exist for recreating Satellite 5 repositories and importing the content:
-
Use the
hammer import repository --synchronize
command to initiate repository synchronization in the background. -
Use the
hammer import repository --synchronize --wait
command to initiate repository synchronization in the background, but wait for each synchronization to complete before proceeding to the next repository. -
Use the
hammer import repository
command with neither option and then synchronize the content manually using the web UI orhammer
commands.
Recommended Practices for Synchronizing Content
The default behavior of the hammer import repository
command is to not automatically synchronize content. Many of the following import operations require that synchronization be complete before they can run successfully. Synchronization is a time-consuming task, because it involves retrieving content from external sources into your Satellite 6 Server.
Red Hat recommends that you schedule a background synchronization of all content before proceeding. Only repositories available to imported organizations are enabled. The hammer import
command does not alter organizations that are not part of the overall transition process.
Run the following command to find, enable, and synchronize all Red Hat content enabled by the uploaded manifest files and matched by channels synchronized on the Satellite 5 Server. This command tells the import process to wait until the synchronization is complete, and only synchronizes one repository at a time.
# hammer import repository-enable --synchronize --wait --no-async
After the repository-enable
command is complete, enter the following command to process local and custom repositories in a similar fashion.
# hammer import repository --synchronize --wait --no-async
The following is an example session of importing repositories but without performing any content synchronization.
Example 4.4. Example Session of Importing Repositories
The following is an example session of successfully importing repositories into Satellite 6.
# hammer import all --entities repository Import repository with arguments --csv-file /tmp/exports/repositories.csv [Foreman] Username: admin [Foreman] Password for admin: Summary Created 10 repositories. Created 5 products.
Enabling External Yum Repositories
You need to recreate all non-Red Hat yum repositories that Satellite 5 was configured to use as new external yum repositories from which Satellite 6 can import content.
The following example demonstrates using the --synchronize
option to import and synchronize repositories.
A successful import and synchronization produces very little output unless you use the -v
(verbose) option. The synchronization process can take a long time (several hours depending on the number of repositories, bandwidth, and other factors), during which no output is displayed.
Example 4.5. Importing and Synchronizing non-Red Hat Repositories
# hammer import repository --synchronize --wait \
--no-async --csv-file /tmp/exports/repositories.csv
Summary
No action taken.
Viewing Imported Products and Repositories
Navigate to Content > Products in the Satellite 6 web UI to view the resulting Products and repositories for your organization. Alternatively, use the following hammer
commands:
# hammer organization list ---|-------------------------------|-------------------------------|------------ ID | NAME | LABEL | DESCRIPTION ---|-------------------------------|-------------------------------|------------ 5 | RED HAT SATELLITE ENGINEERING | RED_HAT_SATELLITE_ENGINEERING | 6 | Test Organization | Test_Organization | 3 | Satellite Documentation | Satellite_Documentation | ---|-------------------------------|-------------------------------|------------ # hammer product list --organization-id 5 ----|--------------|-------------|-------------------------------|--------------|------------------ ID | NAME | DESCRIPTION | ORGANIZATION | REPOSITORIES | SYNC STATE ----|--------------|-------------|-------------------------------|--------------|------------------ 131 | GOOGLE.COM | | RED HAT SATELLITE ENGINEERING | 1 | Syncing Complete. 133 | NOVELL.COM | | RED HAT SATELLITE ENGINEERING | 3 | Syncing Complete. 134 | OPENSUSE.ORG | | RED HAT SATELLITE ENGINEERING | 2 | Syncing Complete. 135 | PNL.GOV | | RED HAT SATELLITE ENGINEERING | 1 | Syncing Complete. 132 | REDHAT.COM | | RED HAT SATELLITE ENGINEERING | 3 | Syncing Complete. ----|--------------|-------------|-------------------------------|--------------|------------------
The default behavior of the hammer import repository
command is to not automatically synchronize content, but rather only to enable the repositories listed in the repositories.csv file. Red Hat recommends that you use the --synchronize
option to schedule a background synchronization of all content before proceeding.
Enabling Red Hat Repositories
The Red Hat repositories are synchronized from the Red Hat Content Delivery Network (CDN). Because of these differences, it can be difficult to determine if you have imported all relevant Red Hat content into your Satellite 6 Server. Red Hat recommends that you import into Satellite 6 all CDN content that equates to previously synchronized Satellite 5 channels. This ensures that your Red Hat Enterprise Linux systems have access to the same content as they did in Satellite 5.
The hammer import
command on Satellite 6 provides an option to review your Satellite 5 channels and enable the corresponding repositories in Satellite 6. This section guides you through the process of discovering and enabling the appropriate Red Hat repositories. This command provides the same --wait
and --synchronize
options for initiating the import of Red Hat content automatically. This needs to be completed before moving to the next step.
The following example demonstrates the --synchronize
option to enable and synchronize Red Hat repositories.
Example 4.6. Enabling and Synchronizing Red Hat Repositories
# hammer import repository-enable --csv-file /tmp/exports/channels.csv \ --synchronize Only repositories available to IMPORTED organizations will be enabled! Organization ACME_Corporation... Organization GLOBAL_SUPPORT_SERVI_RED_HAT__INC_... Enabling /content/dist/rhel/server/5/5Server/x86_64/os/Packages for channel rhel-x86_64-server-5 Sync started! Enabling /content/dist/rhel/server/5/5Server/x86_64/supplementary/os/Packages for channel rhel-x86_64-server-supplementary-5 Sync started! Enabling /content/dist/rhel/server/6/6Server/x86_64/rhn-tools/os/Packages for channel rhn-tools-rhel-x86_64-server-6 Sync started! Enabling /content/dist/rhel/server/6/6Server/x86_64/optional/os/Packages for channel rhel-x86_64-server-optional-6 Sync started! Enabling /content/dist/rhel/server/6/6Server/x86_64/os/Packages for channel rhel-x86_64-server-6 Sync started! Enabling /content/dist/rhel/server/5/5Server/x86_64/rhn-tools/os/Packages for channel rhn-tools-rhel-x86_64-server-5 Sync started!
4.6.4. Transitioning Custom and Cloned Channels to Content Views
Red Hat Satellite 5 uses the concept of cloned channels to restrict the number of Red Hat-supplied channels and RPM files. Custom content is added to custom channels, which are typically children of cloned channels. In Satellite 6, for both Red Hat and non-Red Hat content, you use a single repository and then provide filtered views of that repository to the systems managed by Satellite 6. These filtered views are called content views.
This section describes how to recreate your Satellite 5 custom and cloned channels as content views. This process provides a near-equivalent set of content to systems in Satellite 6 as was available in Satellite 5.
Run the following command to import the Satellite 5 channels as content views in the Satellite 6 Server. Use the --dir
option to specify the appropriate export directory.
# hammer import content-view --csv-file /tmp/exports/CHANNELS/export.csv \ --dir /tmp/exports/CHANNELS
Run the following command to synchronize the imported channels:
# hammer import content-view --csv-file /tmp/exports/CHANNELS/export.csv \ --synchronize
You can combine the two commands and synchronize the channels at the same time.
# hammer import content-view --csv-file /tmp/exports/CHANNELS/export.csv \ --dir /tmp/exports/CHANNELS --synchronize
The following is an example session of importing channels to content views.
Example 4.7. Importing Channels to Content Views
# hammer import content-view --csv-file /tmp/exports/CHANNELS/export.csv \ --dir /tmp/exports/CHANNELS Creating new product: Local-repositories Creating new local_repository: Local repository for clone-rhel-x86_64-server-5 No such content_view: 101 Repository Local_repository_for_clone-rhel-x86_64-server-5 is not (fully) synchronized. Retry once synchronization has completed. Product [1Local-repositories->118] already imported. Creating new local_repository: Local repository for clone-rhel-x86_64-server-6 No such content_view: 102 Product [1Local-repositories->118] already imported. Creating new local_repository: Local repository for custom-clone-master-puppet-rhel6-server-x86_64 Repository Local_repository_for_custom-clone-master-puppet-rhel6-server-x86_64 is not (fully) synchronized. Retry once synchronization has completed. Product [1Local-repositories->118] already imported. Creating new local_repository: Local repository for epel-puppet-rhel6-server-x86_64 Repository Local_repository_for_epel-puppet-rhel6-server-x86_64 is not (fully) synchronized. Retry once synchronization has completed.
Example 4.8. Synchronizing Imported Channels
# hammer import content-view --csv-file /tmp/exports/CHANNELS/export.csv \ --synchronize Product [1Local-repositories->118] already imported. Local_repository [1117->12] already imported. Sync started! No such content_view: 101 Repository Local_repository_for_clone-rhel-x86_64-server-5 is not (fully) synchronized. Retry once synchronization has completed. Product [1Local-repositories->118] already imported. Local_repository [1113->13] already imported. Sync started! No such content_view: 102 Repository Local_repository_for_clone-rhel-x86_64-server-6 is not (fully) synchronized. Retry once synchronization has completed. Product [1Local-repositories->118] already imported. Local_repository [1115->14] already imported. Sync started! Repository Local_repository_for_custom-clone-master-puppet-rhel6-server-x86_64 is not (fully) synchronized. Retry once synchronization has completed. Product [1Local-repositories->118] already imported. Local_repository [1125->21] already imported. Sync started!
Example 4.9. Combining Import and Synchronization of Channels
# hammer import content-view --csv-file /tmp/exports/CHANNELS/export.csv \ --dir /tmp/exports/CHANNELS --synchronize Product [1Local-repositories->98] already imported. Local_repository [1117->12] already imported. No such content_view: 101 Creating new content_view: Clone of Red Hat Enterprise Linux (v. 5 for 64-bit x86_64) Product [1Local-repositories->98] already imported. Local_repository [1113->13] already imported. No such content_view: 102 Creating new content_view: Clone of Red Hat Enterprise Linux Server (v. 6 for 64-bit x86_64) Product [1Local-repositories->98] already imported. Local_repository [1115->14] already imported. No such content_view: 103 Creating new content_view: Clone of RHEL Server Optional (v. 6 64-bit x86_64)
You can use the web UI to monitor the status of the import. Log in as an administrator, select the appropriate organization from the context menu at the upper left, and then click Content > Sync Status.
You might need to enter the command with the synchronize
option more than once after the previous steps have completed, before you see the content view being generated.
4.6.5. Importing Activation Keys
Activation keys in both Satellite 5 and 6 serve almost identical purposes. The command-line tools use activation keys to register and subscribe systems to Red Hat Satellite. Activation keys in Satellite 5 have different properties, such as system groups, channel entitlements, and system entitlements (provisioning, monitoring), compared to Satellite 6, which uses content views and host collections.
The earlier stages of the transition process focused on recreating the Satellite 5 data types within Satellite 6. This section describes how to import the activation keys from Satellite 5 and to associate them with the imported data types.
The following example illustrates a typical use case for importing activation keys.
Example 4.10. Importing Activation Keys into Satellite 6
# hammer import activation-key --csv-file /tmp/exports/activation-keys.csv
Activation key usage_limit: unlimited
Creating new activation_key: 1-rhel5-puppet
Associating activation key [1] with host collections [2]
Creating new ak_content_view: ak_1
Publishing content view: 15
Associating activation key [1] with content view [15]
Updating activation_key with id: 1
Creating new ak_content_view: ak_2
.
.
.
Summary
Skipped 2 activation_keys.
Created 3 activation_keys.
You can use the hammer activation-key list --organization-id ORG-ID
command to verify that the activation keys have been recreated. Ensure you use the correct organization ID.
You can also log in to the web UI as an administrator to verify that the activation keys were created. Ensure you are in the correct organization, and then navigate to Content > Activation Keys.
The following example illustrates the use of the command-line tools to verify the import of activation keys.
Example 4.11. Verifying the Import of Activation Keys
# hammer activation-key list --organization-id 3 ---|------------------------------------|----------------|-----------------------|------------- ID | NAME | CONSUMED | LIFECYCLE ENVIRONMENT | CONTENT VIEW ---|------------------------------------|----------------|-----------------------|------------- 1 | 1-rhel6-puppet | 0 of Unlimited | |ak_1 3 | 1-rhel5-puppet | 0 of Unlimited | |ak_3 ---|------------------------------------|----------------|-----------------------|-------------
4.6.6. Transitioning Kickstart Profiles
The Satellite transition tools do not migrate entire kickstart profiles. Due to some significant differences between the Satellite 5 and Satellite 6 infrastructures, there is no suitable migration path between the two versions.
The transition tools can migrate kickstart scripts, and these can be used in Satellite 6 Provisioning Templates, which are an approximation of kickstart profiles.
Exporting Kickstart Scripts
The transition tools extract and export kickstart scripts from kickstart profiles as part of the overall export process on the Satellite 5 Server. These scripts are stored in the kickstart-scripts.csv file in the export archive, which is copied to the Satellite 6 Server.
Importing Template Snippets
When you extract the export archive onto the Satellite 6 Server, the hammer import
command uses the kickstart-scripts.csv file to create template snippets. These snippets are in the form of %pre and %post scripts that you can use with any new kickstart profiles in Satellite 6.
4.6.7. Transitioning Configuration Channels to Puppet Modules
Red Hat Satellite 5 uses configuration channels to support configuration file management. Configuration channels are collections of configuration entries, which in turn specify files and values that Satellite 5 applies to systems that are registered to it. Configuration channels support the upload of flat files for delivery to associated systems.
Satellite 6 uses Puppet to provide improved configuration management; consequently, part of the transition process requires that configuration channels be converted into a single Puppet module.
The export process on Satellite 5 includes the latest revision of all configuration files. The import process uses this information to perform the following tasks:
- Generate Puppet modules for each Satellite 5 configuration channel.
- Map any Satellite 5 macros in the configuration files to whatever Puppet facts are found.
- Build the modules.
- Create a Satellite 6 repository for each configuration channel, and a Product to hold those repositories.
- Upload the built Puppet modules into Satellite 6.
The following table describes the current mapping between Satellite 5 substitution macros and Puppet facts.
Table 4.1. Mapping of Satellite 5 Macros to Satellite 6 Puppet Facts
Satellite 5 Macro | Puppet Fact |
---|---|
rhn.system.sid | None |
rhn.system.profile_name | None |
rhn.system.description | None |
rhn.system.hostname | FQDN or host name |
rhn.system.ip_address | ipaddress |
rhn.system.custom_info(key_name) | None |
rhn.system.net_interface.ip_address(eth_device) | ipaddress_{NETWORK INTERFACE} |
rhn.system.net_interface.netmask(eth_device) | netmask_{NETWORK INTERFACE} |
rhn.system.net_interface.broadcast(eth_device) | None |
rhn.system.net_interface.hardware_address(eth_device) | macaddress_{NETWORK INTERFACE} |
rhn.system.net_interface.driver_module(eth_device) | None |
Transitioning Configuration Channels to Puppet Modules
The following example illustrates a simple use case for transitioning configuration channels to Puppet modules.
Example 4.12. Transitioning Configuration Channels and Files to Puppet Modules
# hammer import config-file --csv-file /tmp/exports/config-files-latest.csv
Writing converted files
Building and uploading puppet modules
Successfully uploaded file 'redhatsatelliteengineering-test_channel-1.0.0.tar.gz'.
Summary
Uploaded 1 puppet module.
Wrote 1 puppet module.
Wrote 4 puppet_files.
Created 1 puppet repository.
Created 1 product.
4.6.8. Transitioning System Profiles to Content Hosts
Red Hat Satellite 5 uses System Profiles to store information about the systems (machines) that are registered to it. This includes the operating system version and a list of all packages that are installed on each system. This applies to both bare-metal and virtual machines.
In Satellite 6, this information is stored in Content Hosts. Instead of "system", Satellite 6 uses the term "host" to refer to any machine that is registered to it. Part of the transition process maps Satellite 5 System Profiles to Satellite 6 Content Hosts. A Satellite 6 host is created when an actual system re-registers to Satellite 6 with the consumer ID of the Content Host.
Transitioning system profiles is the last step in the transition process prior to actually transitioning your Satellite 5 systems to Satellite 6. You can transition system profiles as part of the hammer import all
command, or by specifically importing them, using the hammer import all --entities content-host
command.
Building the System Profile Transition RPM File
Before you can transition your Satellite 5 systems to Satellite 6, you need to build the required RPM file. The hammer import all
command displays instructions on how to do this, tailored to your specific environment, after you have successfully transitioned system profiles to content hosts.
After you have successfully transitioned your system profiles to content hosts, you should see output similar to the following:
Example 4.13. Example Instructions for Building a System Profile Transition RPM File
To build the system-profile-transition rpm, enter:
# cd /root/rpm-working-dir/SPECS && rpmbuild -ba \ --define "_topdir /root/rpm-working-dir" \ system-profile-transition-myhost.example.com-1410140956-0.0.1.spec
Then find your system-profile-transition-myhost.example.com-1410140956 package in /root/rpm-working-dir/RPMS/noarch/ directory.
4.6.9. Transitioning Systems
This section covers background information, prerequisites, and assumptions that must be addressed prior to transitioning your client systems. It also covers the actual process for transitioning your Satellite 5 client systems to Satellite 6 client hosts. This process is primarily aimed at customers who have numerous systems currently registered to a Satellite 5 Server.
The system transition process aims to achieve the following goals:
- Ensure that each Satellite 5 client is registered to a new Satellite 6 instance, with as much of the existing Satellite 5 setup maintained as possible.
- Help customers stay in compliance with their Red Hat Enterprise Linux usage. The process removes the Satellite 5 entitlements used by a given system when that system is registered to Satellite 6.
Prerequisites
Before you begin the system transition process, ensure that you have each of the following:
- An up-to-date Satellite 5.6 or 5.7 Server. In this example, this system is called "SAT5x".
- An up-to-date Red Hat Enterprise Linux client system registered to SAT5x.
- An up-to-date Satellite 6 Server. In this example, this system is called "SAT6".
- Manifests created for each Organization on SAT5x and downloaded to the Satellite 6 base system. Manifests renamed according to the organization for which it is intended. Punctuation marks and spaces replaced with an underscore. For example, an organization called MyOrg, Inc. can use the MYORG__INC_.zip manifest.
Assumptions
The system migration process makes several assumptions as part of the task of moving your Satellite 5 systems to Satellite 6:
-
The
hammer import content-host
command has completed successfully. - An RPM file containing a mapping between Satellite 5 SIDs and matching Satellite 6 content-host UUIDs has been created.
- The above-mentioned RPM file has been installed on the Satellite 5 Server’s base system.
-
The
sat5to6
package and dependencies have been installed on each client system. This package provides thesat5to6
command, which performs the following tasks on the system where it is used: - Queries its Satellite 5 parent for a consumer ID.
- Loads the appropriate PEM files onto the client machine, based on the Satellite 5 channels to which the machine is subscribed.
- Registers the host on which it is used to a specified Satellite 6 Server, attaching it to the content host UUID specified by its Satellite 5 parent.
- Manages the "retired" Satellite 5 profile in one of three ways, as specified by the user:
-
keep
: Do nothing. Retain the Satellite 5 profile in its original state. -
unentitle
: Retain the Satellite 5 profile but remove all subscriptions and entitlements (default). -
purge
: Delete the Satellite 5 profile completely.
Performing the Transition Using the sat5to6 Script
This section describes the process for transitioning your Satellite 5 client systems to Satellite 6 client hosts, and updating the subscription configuration accordingly based on the profiles.
This section makes the following assumptions:
-
You have successfully used the
spacewalk-export
command on your Satellite 5 Server to export all required entities. - You have copied the resulting spacewalk_export.tar.gz file to the /tmp/ directory on your Satellite 6 Server, and extracted it into the same directory.
-
You have successfully used the
hammer import all
command on the Satellite 6 Server, and followed the resulting instructions to build the required RPM file. You have the necessary system transition packages installed on the Satellite 5 Server. To ensure these packages are installed, enter the following command:
# yum install /tmp/system-profile-transition-*.rpm
Transitioning Your Satellite 5 Systems to Satellite 6
This process assumes that your client is already subscribed to the appropriate RHN Tools channel. This channel provides access to the sat5to6
RPM file and its dependencies. For each client that is registered to your Satellite 5 Server, enter the following commands:
Install the
sat5to6
package and its dependencies:# yum install sat5to6
Install the Public Certificate for Satellite’s Certificate Authority. This also configures
subscription-manager
with the correct URL so that the system can properly register via the Satellite 6.x instance. In this example, $FQDN represents the fully qualified domain name of the Satellite or Satellite Capsule.ImportantEnsure you use HTTP and not HTTPS for this installation; the Satellite 6 CA certificate is not yet installed and so HTTPS will fail.
# yum install http://$FQDN/pub/katello-ca-consumer-latest.noarch.rpm
Update the
yum
andopenssl
packages.# yum update yum openssl
Use the
sat5to6
command to register your client to your Satellite 6 instance, and attach it to the content host created for it by the import process.# sat5to6 --registration-state unentitle \ --legacy-user=admin --legacy-password=password \ --destination-user=admin --destination-password=changeme
Enable the Satellite Tools repository which contains the
katello-agent
andpuppet
packages.# subscription-manager repos --enable=rhel-*-server-satellite-tools-6.2-rpms
Install the
katello-agent
andpuppet
packages:# yum install katello-agent puppet
Configure the goferd and puppet services to start on boot.
# chkconfig goferd on # chkconfig puppet on
Configure Puppet with the host name of the Satellite or Satellite Capsule that will manage its configuration. In this example, $FQDN represents the fully qualified domain name of the Satellite or Satellite Capsule.
# echo "server=$FQDN" >> /etc/puppet/puppet.conf
Restart the goferd and puppet services.
# service goferd restart # service puppet restart
As part of the new Satellite 6 installation, the katello-ca-consumer-latest
package sets up the CA certificates and default values in the /etc/rhsm/rhsm.conf file. This enables SSL and also means you do not need to specify the --destination-url
parameter as part of the sat5to6
command.
Example 4.14. Example Session of a System Transition
The following is an example session of a successful transition of Satellite 5 systems to Satellite 6 hosts. The actual output will vary according to the organization names, system names, and other details of your own environment.
# sat5to6 --registration-state=unentitle --legacy-user=admin \ --legacy-password=password --destination-user=admin \ --destination-password=changeme Org: MY ENGINEERING ORG Environment: Library Retrieving existing legacy subscription information... +-----------------------------------------------------+ System is currently subscribed to these legacy channels: +-----------------------------------------------------+ rhel-x86_64-server-6 +-----------------------------------------------------+ Installing product certificates for these legacy channels: +-----------------------------------------------------+ rhel-x86_64-server-6 Product certificates installed successfully to /etc/pki/product. Attempting to register system to destination server... WARNING This system has already been registered with Red Hat using RHN Classic. Your system is being registered again using Red Hat Subscription Management. Red Hat recommends that customers only register once. To learn how to unregister from either service please consult this Knowledge Base Article: https://access.redhat.com/kb/docs/DOC-45563 The system has been registered with ID: ac063466-0abc-1bb3-abc0-33abf6c1dd3a Installed Product Current Status: Product Name: Red Hat Enterprise Linux Server Status: Subscribed System 'dhcp1234.example.com' successfully registered.