sat5to6(8)

NAME
sat5to6 - Migrates a system profile from Red Hat Satellite v.5 to Red Hat Satellite v.6 as part of the Satellite Transition process.

SYNOPSIS
sat5to6 [--destination-user=DESTINATION_USER] | [--destination-password=DESTINATION_PASSWORD] | [--destination-url=URL] | [--legacy-user=LEGACY_USER] | [--legacy-password=LEGACY_PASSWORD] | [--no-auto] | [--no-proxy] | [--registration-state=STATE] | [--servicelevel=SERVICE_LEVEL] | [--remove-rhn-packages] | [--help]

DESCRIPTION
sat5to6 migrates a system profile which is registered to a Red Hat Satellite v.5 instance to a Red Hat Satellite v.6 instance. The tool assumes that the command hammer import content-host has run successfully on the Satellite v.6 installation, that a content-host for the client where sat5to6 is to be executed has been created, and that the resulting RPM has been built and installed on the Satellite v.5 host to which the client is subscribed.

This script queries the Satellite v.5 instance to which it is registered for information about the channels to which it is subscribed, and the content-host UUID to which it should re-attach in Satellite v.6. It relies on data found in the subscription-manager-migration-data package to correctly lay down product-certificates prior to re-registering to Satellite v.6. The subscription-manager-migration-data package must be installed before the sat5to6 script can be run successfully.

BACKGROUND
Access to support and updates for products is determined through subscriptions. Subscriptions are attached to a system, which means that the system has the right to install and update a product with full support. Subscriptions for an entire account are tracked through a subscription management service.

With the channel-based framework, the subscription management service was an on-premise Satellite v.5. With the new certificate-based subscriptions, the subscription management service is an on-premise Satellite v.6. The differences between the two types of subscription management services are described in this Knowledgebase article: <https://access.redhat.com/knowledge/articles/63269>

The sat5to6 tool is provided to automate as much as possible the act of 're-pointing' a system from recieving updates from Satellite v.5, to receiving them and being managed by a Satellite v.6 installation. The full migration details are described in the Red Hat Satellite v.6 Transition Guide: <https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.0/html/Transition_Guide/Transitioning_Systems.html>

sat5to6 allows a system to remain registered to both its Satellite v.5 and its Satellite v.6 parent until such time as testing shows the Satelite v.6 configuration is as desired. At this point, the administrator can purge the Satellite v.5 profile.

OPTIONS

-h, --help
    Print the specific help information for the command.

-n, --no-auto
    Do not attempt to automatically attach subscriptions to the associated content-host in the Satellite v.6 instance.

-s SERVICE_LEVEL, --servicelevel=SERVICE_LEVEL
    Set a preferred service level for the system, such as premium or standard. This service level preference is then used as one of the criteria for autoattaching subscriptions to the system.

--remove-rhn-packages
    After unregistering from Satellite v.5, remove legacy packages: osad, rhn-check, rhn-client-tools, rhncfg, rhncfg-actions, rhncfg-client, rhncfg-management, rhn-setup, rhnpush, rhnsd, spacewalk-abrt, spacewalk-oscap, yum-rhn-plugin. Once unregistered from Satellite v.5, they are no longer needed. Once packages are removed, subsequent attempts to migrate will be blocked with a message indicating "Perhaps this script was already executed with --remove-rhn-packages?". --remove-rhn-packages can only be used with --registration-state=purge, since it does not make sense to keep a system registered without the tooling.

--no-proxy
    Disable/ignore any previous RHN proxy settings when migrating to the new subscription management service.

--registration-state={keep|unentitle|purge}
    Defines the state the tool should leave the legacy profile in. Options are keep (make no changes on the legacy system), unentitle (leave the legacy profile but remove any entitlements or subscriptions it is consuming), and purge (delete the legacy profile). The default is unentitle.

--legacy-user=LEGACY_USER
    Specify the user name on the Satellite v.5 system of a user who has administrator-access to this system's profile.

--legacy-password=LEGACY_PASSWORD
    Specify the legacy-user's password.

--destination-url=DESTINATION_URL
    Specify the URL of the destination Satellite v.6 installation

--destination-user=DESTINATION_USER
    Specify the user-name of an administrative user on Satellite v.6.

--destination-password=DESTINATION_PASSWORD
    Specify the destination-user's password.

USAGE
The migration process moves the system from the inventory of the Satellite v.5 instance to the inventory of the Satellite v.6 instance, and then applies subscriptions to the system. The script runs through these steps:

    1. Authenticate to both Satellite v.5 and Satellite v.6 to verify the account settings.

    2. Get a channel list for the system.

    3. Match each channel to a corresponding certificate map.

    4. Copy over the product certificates for the old channels.

    5. Unregister (unless --registration-state=keep specified) from Satellite v.5

    6. Stop and disable legacy services: osad, rhnsd.

    7. Register to Satellite v.6, connecting to the content-host UUID created as part of the transition process. Unless --no-auto is specified, autoattach the best-matched subscriptions.

After migration, the system facts maintained by Subscription Manager display what script was used for migration and what the previous system ID was.
[root@server ~]# subscription-manager facts --list | grep migr
migration.classic_system_id: 09876
migration.migrated_from: rhn_hosted_classic
migration.migration_date: 2012-09-14T14:55:29.280519

  MIGRATION AND AUTOSUBSCRIBE
The sat5to6 tool, by default, autoattaches the best-matching subscriptions to the system. This allows migrations to be automated.

It is assumed that the system in question has been prepared for migration by installing the Certificate Authority and configuration-changes for the Satellite v.6 instance. This typically accomplished by installing the katello-ca-consumer-latest.noarch.rpm generated as part of the Satellite v.6 installation:
[root@system ~]# yum install http://satellite-6-fqdn/pub/katello-ca-consumer-latest.noarch.rpm
Loaded plugins: product-id, rhnplugin, security, subscription-manager
This system is not registered to Red Hat Subscription Management. You can use subscription-manager to register.
This system is receiving updates from RHN Classic or RHN Satellite.
Setting up Install Process
katello-ca-consumer-latest.noarch.rpm                                                                                                                                  | 7.6 kB     00:00
Examining /var/tmp/yum-root-qAyTn5/katello-ca-consumer-latest.noarch.rpm: katello-ca-consumer-satelite-6-fqdn-1.0-1.noarch
Marking /var/tmp/yum-root-qAyTn5/katello-ca-consumer-latest.noarch.rpm to be installed
Resolving Dependencies
--> Running transaction check
---> Package katello-ca-consumer-satellite-6-fqdn.noarch 0:1.0-1 will be installed
--> Finished Dependency Resolution
Dependencies Resolved
==============================================================================================
 Package                               Arch   Version Repository                         Size
==============================================================================================
Installing:
 katello-ca-consumer-satellite-6-fqdn  noarch 1.0-1   /katello-ca-consumer-latest.noarch 11 k
Transaction Summary
==============================================================================================
Install       1 Package(s)
Total size: 11 k
Installed size: 11 k
Is this ok [y/N]: y
Downloading Packages:
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : katello-ca-consumer-satellite-6-fqdn-1.0-1.noarch                                                                                                            1/1
  Verifying  : katello-ca-consumer-satellite-6-fqdn-1.0-1.noarch                                                                                                            1/1
Installed:
  katello-ca-consumer-satellite-6-fqdn.noarch 0:1.0-1
Complete!
[root@system ~]#

Once the system is configured to 'know about' the Satellite v.6 instance, sat5to6 can be used to migrate it:
[root@system ~]# sat5to6 --registration-state=unentitle
Legacy username: admin
Legacy password:
Destination username: admin
Destination password:
Retrieving existing legacy subscription information...
+-----------------------------------------------------+
System is currently subscribed to these legacy channels:
+-----------------------------------------------------+
rhel-x86_64-server-6
rhn-tools-rhel-x86_64-server-6
+-----------------------------------------------------+
No product certificates are mapped to these legacy channels:
+-----------------------------------------------------+
rhn-tools-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: ec71d453-a346-477c-9dfb-86e1be344414
Installed Product Current Status:
Product Name: Red Hat Enterprise Linux Server
Status:       Subscribed
System 'URI:CN=system-fqdn' successfully registered.
[root@system ~]#

sat5to6 prompts for usernames and passwords if not provided on the command-line.

Optionally, the --servicelevel argument sets an SLA preference to use with the system. The SLA associated with a subscription is then evaluated when determining what subscriptions to autoattach to the system, along with other factors like installed products, existing channel assignments, and architecture.

FILES

/etc/sysconfig/rhn/systemid
    The digital server ID for this machine, assigned upon registering with Satellite v.5. This file does not exist otherwise.

/etc/sysconfig/rhn/up2date
    The common configuration file used by RHN client programs.

/var/log/rhsm/rhsm.log
    The Subscription Manager log file. This contains any errors encountered while attempting to register the system to the Satellite v.6 instance, or with attaching subscriptions to the system.

subscription-manager-migration-data.rpm
    The package which contains the mappings for the migration script to migrate channels to the appropriate product certificates.

SEE ALSO
install-num-migrate-to-rhsm(8), subscription-manager(8), rhn-migrate-classic-to-rhsm(8).

AUTHORS

Alex Wood <awwod@redhat.com>

BUGS

This script is part of the Red Hat Subscription Manager tool. Report bugs to <http://bugzilla.redhat.com>, using the Red Hat Enterprise Linux product and the subscription-manager component.

COPYRIGHT

Copyright © 2014 Red Hat, Inc.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.