Migrating Systems from RHN Classic to Certificate-based CentOS Network

As described in and , there are differences in how RHN Classic and Certificate-based CentOS Network define and manage subscriptions.

As part of migration, the RHN Classic channels are mapped to Certificate-based CentOS Network X.509 product certificates for every installed product. Subscription Manager can use those certificates to subscribe or autosubscribe the system to the appropriate subscriptions once it is registered.

Migration tools are available to transition system registration from RHN Classic to Certificate-based CentOS Network and then re-apply its previous subscriptions. Product certificates in general are described in .

There are two migration paths supported:

There is no migration path from a Satellite system to Certificate-based CentOS Network.

Installing the Migration Tools

The migration tools are contained in the subscription-manager-migration package. An additional package, subscription-manager-migration-data, is required to map the RHN Classic channels to Certificate-based CentOS Network product certificates.

  1. The migration tools and data are in supplementary channels. If necessary, enable the supplementary repositories, as described in .

Migrating from RHN Classic to Certificate-based CentOS Network

A system which was registered against the hosted subscription service, RHN Classic, can be migrated to Certificate-based CentOS Network using the rhn-migrate-classic-to-rhsm script.

The general action is that it unregisters the system from RHN Classic, registers it with Certificate-based CentOS Network, and opens Subscription Manager (either GUI or CLI) to assign subscriptions.

The rhn-migrate-classic-to-rhsm script has this syntax: 

rhn-migrate-classic-to-rhsm [--force|--cli-only|--help|--no-auto]

After running migration, the system facts list 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

This makes it easy to track the migration process for systems within the infrastructure.

Example 14.7. Basic RHN Classic to Certificate-based CentOS Network Migration

Simply running the rhn-migrate-classic-to-rhsm tool migrates the system profile and then opens the Subscription Manager GUI so that administrators can assign subscriptions to the system.

While administrators only have to run the command, the script itself runs through a series of steps to migrate the account. 

[root@server ~]# rhn-migrate-classic-to-rhsm
RHN Username: jsmith@example.com
Password:

The script prompts for the username and password to use to connect to CentOS Network. It uses these credentials to authenticate to both CentOS Network Classic and Certificatebased CentOS Network, to verify the account settings.

Once the account is verified, the script creates a channel list for the system. 

Retrieving existing RHN classic subscription information ...
+----------------------------------+
System is currently subscribed to:
+----------------------------------+
rhel-i386-client-5

Each discovered channel is then mapped to a corresponding product certificate (). Not every product has a product certificate, so not every channel may have a map. Only the channels with a certificate channel to a corresponding certificate map.

The matching certificates are copied into the /etc/pki/product directory. 

List of channels for which certs are being copied
rhel-i386-client-5
Product Certificates copied successfully to /etc/pki/product !!

Then, the script unregisters the system from RHN Classic. 

Preparing to unregister system from RHN classic ...
System successfully unregistered from RHN Classic.

Then, it registers the system with Certificate-based CentOS Network. 

Attempting to register system to Certificate-based RHN ...
The system has been registered with id: abcd1234
System server.example.com successfully registered to Certificate-based RHN.
Launching the GUI tool to manually subscribe the system ...

The last step opens the Subscription Manager GUI to the All Available Subscriptions tab so that the administrator can manually assign the subscriptions to the system.


Alternatively, the rhn-migrate-classic-to-rhsm can automatically subscribe the system to matching subscriptions.

Example 14.8. All CLI-Based Migration

The --cli-only option tells the rhn-migrate-classic-to-rhsm to register the system with the autosubscribe option, so all of the migration process occurs in the command line.

The overall process is identical to the one in until the final step. 

[root@server ~]# rhn-migrate-classic-to-rhsm --cli-only
RHN Username: jsmith@example.com
Password:
....
Attempting to auto-subscribe to appropriate subscriptions ...
Installed Product Current Status:
ProductName:            Red Hat Enterprise Linux Desktop
Status:                 Subscribed
Please visit https://access.redhat.com/management/consumers/abcd1234 to view the details, and to make changes if necessary.

Unregistering from RHN Classic Only

There may be an instance where a system should be unregistered from RHN Classic but is not yet ready to be registered to Certificate-based CentOS Network. The rhn-migrate-classic-to-rhsm tool can be used simply to unregister a system from RHN Classic. This still copies over the product certificates for the classic channels to configure the system in the style of certificate-based subscriptions, but it does not register the machine with subscription service.

To unregister the system only, use the --no-auto option. 

[root@server ~]# rhn-migrate-classic-to-rhsm --no-auto
RHN Username: jsmith@example.com
Password:
Retrieving existing RHN classic subscription information ...
+----------------------------------+
System is currently subscribed to:
+----------------------------------+
rhel-i386-client-5
List of channels for which certs are being copied
rhel-i386-client-5
Product Certificates copied successfully to /etc/pki/product !!
Preparing to unregister system from RHN classic ...
System successfully unregistered from RHN Classic.

Because there are product certificates, Subscription Manager will show a red, invalid status for the system and issue notifications until the system is registered and subscriptions applied.

Migrating a Disconnected System

Some systems may never be connected to an external network or may be prevented from accessing CentOS Network or a Satellite system. These systems still require valid subscriptions and product certificates, though.

The rhn-migrate-classic-to-rhsm uses the information in /etc/sysconfig/rhn/systemid to get the previous registration information and map channels to certificates. If a system is disconnected, it may not have a systemid file.

Most systems, even ones never registered with RHN Classic, do have an installation number. When CentOS software is purchased through a vendor, the purchased software is identified in an installation number or subscription number (described in ) in the /etc/sysconfig/rhn/install-num file.

The installation number is in essence a code which contains all of the information about the products and versions purchased for the system. For example, this installation number shows that it is valid for RHEL Client and RHEL Workstation channels. 

[root@server ~]# python /usr/lib/python2.4/site-packages/instnum.py da3122afdb7edd23
Product: RHEL Client
Type: Installer Only
Options: Eval FullProd Workstation
Allowed CPU Sockets: Unlimited
Allowed Virtual Instances: Unlimited
Package Repositories: Client Workstation
key: 14299426 "da3122"
checksum: 175 "af"
options: 4416 "Eval FullProd Workstation"
socklimit: -1 "Unlimited"
virtlimit: -1 "Unlimited"
type: 2 "Installer Only"
product: 1 "client"
{"Workstation": "Workstation", "Base": "Client"}

For a system which is not connected to either RHN Classic or a Satellite system, the installation number can be used to transition the product information from the older channel-based subscription model to the X.509 certificate model, managed by Subscription Manager.

The install-num-migrate-to-rhsm script identifies the channels that a disconnected system is subscribed to and then copies in the appropriate product certificates. Simply run the command: 

[root@server ~]# install-num-migrate-to-rhsm

The script copies in the product certificates for the channels into the /etc/pki/product directory.

Once the system is migrated, it can be registered remotely and have entitlement certificates installed as described in .

Even though the system is not registered, the system facts display what script was used for migration. 

[root@server ~]# subscription-manager facts --list | grep migr
migration.migrated_from: install_number

Because the system was not previously registered with RHN Classic, the migration facts do not include a system ID number.

Looking at Channel and Certificate Mappings

The subscription-manager-migration-data package contains a mapping file that maps RHN Classic channels to Certificate-based CentOS Network product certificates. This file (/usr/share/rhsm/product/RHEL-5/channel-cert-mapping.txt) uses simple keys to map the values: 

channel_name: product_name-hash-product_cert.pem

For example, this maps the Community Enterprise Linux Client channel to the corresponding product certificate: 

rhel-i386-client-workstation-5: Client-Workstation-i386-b0d4c042-6e31-45a9-bd94-ff0b82e43b1a-71.pem

During migration, that mapping is translated into product_cert.pem and the product certificate is copied into the /etc/pki/product directory. For the rhel-i386-client-workstation-5, this migrates to the 71.pem product certificate (the last two digits of the mapping).

However, many channels are available for legacy systems only or have not yet released an X.509 product certificate. In that case, the channel has no mapping. 

jbappplatform-4.3.0-fp-i386-server-5-rpm: none

This can create a situation where not all channels are migrated over to Certificate-based CentOS Network or where products are not fully subscribed.