Migrating from RHN Classic

Red Hat Subscription Management 1

to migrate from older Red Hat Network Classic (hosted) to updated subscription management

Red Hat Subscription Management Documentation Team

January 11, 2016


Beginning with Red Hat Enterprise Linux 6.1/5.7, a new way of representing subscriptions was introduced. The Red Hat subscription management structure provides more detailed, accurate, and clear representations of the relationships between subscriptions, systems, their parent organizations, and overall usage patterns. This guide addresses migration paths from legacy Red Hat Enterprise Linux systems to the updated subscription framework.
Maintaining subscription assignments with systems is a critical part of management as infrastructures change and are updated. Maintaining those subscriptions is essentially migrating the subscriptions.
There are currently two migration paths, depending on the system and what is changing:
  • Systems can be upgraded from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7. Both Red Hat Enterprise Linux 6 and 7 systems use the same type of subscription management services, but the available content repositories and product subscriptions are different between the platforms. This means that subscriptions must be managed appropriately as part of upgrading the underlying system.
  • Red Hat Enterprise Linux 5 and Red Hat Enterprise Linux 6 systems can migrate from channel-based subscription services to Red Hat Subscription Management. This is truly migrating subscriptions, since the subscriptions are moved from one type of service to another.
Upgrading the System

Since Red Hat Enterprise Linux 6 can use Red Hat Subscription Management and Red Hat Enterprise Linux 7 systems must use Red Hat Subscription Management, there is no need to migrate the subscription services: it is the same service. However, the system migration and installed product migrations may not happen at the same time, which means that the subscriptions required to cover the system at Red Hat Enterprise Linux 6 may be different than the ones required after it is upgraded. This requires administering the subscriptions for the system, by updating the registration, configuring repositories, and re-attaching the subscriptions.

Migrating Subscription Services

Red Hat Subscription Management structure provides detailed, accurate, and clear representations of the relationships between subscriptions, systems, their parent organizations, and overall usage patterns. This is done by identifying the different elements involved in subscription management — the system, the installed products, and the assigned subscriptions — with unique certificates.

This is a fundamentally different approach than the legacy channel approach, which only defined user access to a pool of subscriptions. Systems which are registered to RHN Classic can be migrated to the new Red Hat Subscription Management in a way that preserves all of the original subscription assignments.

1. Managing Subscriptions When Upgrading to RHEL 7

Red Hat Enterprise Linux 7.0 introduces a new tool that can upgrade a Red Hat Enterprise Linux 6.x operating system to Red Hat Enterprise Linux 7, redhat-upgrade-tool.
The procedures and requirements for upgrading from Red Hat Enterprise Linux 6 to 7 are outside the scope of this document. This document only provides the steps related to managing system subscriptions as part of the upgrade process. For full information on upgrading your system, including requirements and warnings, see https://access.redhat.com/site/solutions/637583.


The redhat-upgrade-tool upgrades the underlying operating system, but any software or applications installed may not necessarily be upgraded by the script. Many products do not yet have Red Hat Enterprise Linux 7 content repositories available.
While the system can be upgraded, many of the applications on that system may not be able to be upgraded to Red Hat Enterprise Linux 7 if no hosted content repositories are available.
In most cases, upgrading a Red Hat Enterprise Linux 6 environment will be much like installing a fresh Red Hat Enterprise Linux 7 system, in that the system will be registered as a new identity to the subscription service and new subscriptions will be attached to the system after registration. However, currently attached system subscriptions must be handled properly to ensure that they are available to new and upgraded systems or to other systems in the infrastructure.
To manage sybscriptions during an upgrade to Red Hat Enterprise Linux 7:
  1. Update the Red Hat Enterprise Linux 6 to install the required upgrade tools, and reboot the system.
  2. Run the preupgrade check.
  3. Unregister your system from the previous subscription service. This is done using the unregister command.
    [root@server  ~]# subscription-manager unregister
  4. Remove the Red Hat Enterprise Linux 6 product certificate to allow the system to be upgraded. If the product certificate is not removed, then later attempting to register the system creates a conflict, because it is incorrectly interpreted as a Red Hat Enterprise Linux 6 system.
    [root@server  ~]# rm -rf /etc/pki/product/69.pem
  5. Use the upgrade script to upgrade the system to Red Hat Enterprise Linux 7. In this example, the version is set to Red Hat Enterprise Linux 7.0 and the installation directory points to a public FTP repository.
    [root@server  ~]# redhat-upgrade-tool-cli --network 7.0 --instrepo ftp://ftp.redhat.com/pub/redhat/rhel/7.0/x86_64/os


    This only upgrades the base operating system. Any additional products or applications need to be upgraded separately.
  6. Register your system again with the subscription service. This is done using the register command.
    [root@server  ~]# subscription-manager register --username admin@example.com
    The system has been registered with id: 7d133d55-876f-4f47-83eb-0ee931cb0a97
  7. Locate any available Red Hat Enterprise Linux 7 repositories for any required layered products, and configure yum to use those repositories.
  8. Optional. Attach any required subscriptions. For example:
    [root@server1 ~]# subscription-manager list --available
        Available Subscriptions
    ProductName:            RHEL for Physical Servers
    ProductId:              MKT-rhel-server
    PoolId:                 ff8080812bc382e3012bc3845ca000cb
    Quantity:               10
    Expires:                2016-09-21
    [root@server1 ~]# subscription-manager attach --pool=ff8080812bc382e3012bc3845ca000cb

2. Migrating Systems from RHN Classic

As part of migration, the RHN Classic channels configured on a system are mapped to Customer Portal Subscription Management product certificates for every installed product. Subscription Manager can use those certificates to attach or autoattach the appropriate subscriptions to the system once it is registered.
Migration tools are available to transition system registration from RHN Classic to Customer Portal Subscription Management or to Subscription Asset Manager and then re-apply its previous subscriptions.
For both Red Hat Enterprise Linux 5 and 6, migrating a system's registration and subscriptions from RHN Classic Hosted to Customer Portal Subscription Management (hosted) uses the rhn-migrate-classic-to-rhsm migration script.

2.1. Differences Between Customer Portal Subscription Management and RHN Classic

There are some conceptual differences between Customer Portal Subscription Management and RHN Classic, and this translates into differences both in functionality and in how information is displayed.

2.1.1. Purpose of Migration

"Subscription Concepts and Workflows" outlines the importance of clear, detailed, and consistent subscription tracking. It is an increasingly critical part of IT maintenance. The older channel-based subscription management process in RHN Classic was great at providing access, but it was very difficult to get an accurate accounting of how subscriptions were applied, how many subscriptions were being used, where subscriptions were being used, and what any individual system was using.
As the need for more granular subscription management has emerged, Customer Portal Subscription Management, Subscription Asset Manager, and similar subscription services from Red Hat are designed to focus exclusively on subscription management. Other systems management tasks, such as content delivery and configuration management, are then handled by other applications designed for those system management tasks.
For that reason, Customer Portal Subscription Management or Subscription Asset Manager are used in conjunction with a robust systems management tool such as Satellite 6, JBoss Operations Network, Puppet, and other applications.
Red Hat Enterprise Linux systems should be migrated to Customer Portal Subscription Management or Subscription Asset Manager in order to provide the enhanced subscription tracking, asset inventory management, and compliance reporting that a robust subscription management service offers. Customer Portal Subscription Management offers better and more detailed subscription information which is invaluable to IT administrators.

2.1.2. The Focus of Customer Portal Subscription Management

The core of Customer Portal Subscription Management is defining a relationship between subscriptions and the systems which are using them. To achieve this, subscriptions are organized based on the available and installed products for a system.
As the terms imply, subscriptions in Customer Portal Subscription Management define available products. These are the products a system is covered to install and update and receive support for. Locally, Red Hat Subscription Manager tracks what products are actually installed and provides information on how the installed, real products match against the potential or attached subscriptions.
Customer Portal Subscription Management has a very narrow focus. It only concerns subscriptions and products. Therefore, it only manages subscriptions and content delivery. Higher level system management is performed by system management products like Satellite 6 or JBoss Operations Network,

2.1.3. The Focus of RHN Classic

RHN Classic is more focused on general system management than on subscription management alone. (In this way, it is a hosted version of Satellite.)
RHN Classic provides a number of tools to manage systems, including configuration file editing and kickstarting new systems. Part of that management is registering the system and assigning subscriptions, but with an important difference from Customer Portal Subscription Management. RHN Classic tries to provide access to subscribed content, so the intent is not to track usage but to make sure that access is available.
The simplest way to accomplish this is to organize all products into pools or channels, and then use subscriptions to provide access to those channels. This results in a much simpler global view of subscriptions, but it loses the relationship between local systems, subscriptions, and installed products.

2.1.4. Differences in Functionality

Both Customer Portal Subscription Management and Subscription Asset Manager are exclusively focused on subscription management. They are not, and are not intended to be, systems management tools. This is different than RHN Classic, which included subscription management as part of its overall purpose of systems management.
Because of the different emphases in Customer Portal Subscription Management and RHN Classic, there are differences in what functionality they support.

Table 1. Comparison of Customer Portal Subscription Management and RHN Classic Functions

Customer Portal Subscription Management RHN Classic
Registering a system
Assigning subscriptions
Content delivery
Managing configuration files Must be done locally.
Taking system snapshots Must be done locally.
Kickstarting systems Satellite 6 or other management tools.
Running scripts Satellite 6 or other tools.

2.1.5. Differences in Registration and Subscription Processes

One side effect of the different emphases in Customer Portal Subscription Management and RHN Classic is how they handle the subscription and registration processes.
In RHN Classic, which emphasizes access, systems are automatically subscribed to compatible channels as part of its registration process. Registration itself is the act of granting access.
Customer Portal Subscription Management is dedicated to defining relationships between purchased subscriptions and real product usage. While it is possible to attach compatible subscriptions automatically to a system (and this is the default configuration for firstboot), it is also possible to attach subscriptions manually. This gives administrators the option of exerting greater control over what subscriptions are attached and when — and even the option to force subscriptions when they are not otherwise compatible with a system.

2.1.6. Exclusivity

A system should be registered with either Customer Portal Subscription Management (the default) or with RHN Classic — it cannot be registered with both. The two subscription services are mutually exclusive, with separate sets of client tools and separate system inventories.
When a system is registered with either system, it is given an identifier for that subscription inventory. Both Customer Portal Subscription Management and RHN Classic check for a pre-existing identifier before completing the registration process.
If a system is already registered with one system, then attempting to register with the other results in an error.

2.1.7. Migration Paths

The migration process involves moving the system's full registration information — including its subscriptions — from RHN Classic to Customer Portal Subscription Management. The system is identified by a unique number. This can either be a systemid value (Red Hat Enterprise Linux 5 or 6) or an installation number (Red Hat Enterprise Linux 5).
The migration script takes the identifier and then uses it to extract and migrate the system entry. rhn-migrate-classic-to-rhsm performs the migration based on the system ID, in the /etc/sysconfig/rhn/systemid file.

2.2. Installing the Migration Tools

If you have a virt-limit=unlimited subscription (e.g., a data center), you need to set up virt-who before migrating to RHSM from RHN. If you don’t set up virt-who prior to the migration, repositories and/or subscriptions may fall off of any system that is using a virt-who required subscription.
An automatic virt-who configuration tool is available on Customer Portal for systems running RHEL 6 and RHEL 7.
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 Customer Portal Subscription Management product certificates.
  1. The migration tools and data are usually in the main channels for Red Hat Enterprise Linux 5 or 6, but they may be located in optional or supplementary channels. Do a simple yum search to make sure that the packages are available. For example:
    [root@server ~]# yum search subscription-manager-migration -v
    Not loading "rhnplugin" plugin, as it is disabled
    Loading "product-id" plugin
    Loading "refresh-packagekit" plugin
    Loading "security" plugin
    Loading "subscription-manager" plugin
    Updating certificate-based repositories.
    ================= N/S Matched: subscription-manager-migration ==================
    subscription-manager-migration.x86_64 : Migration scripts for moving to
                                          : certificate based subscriptions
    Repo        : rhel-6-server-rpms
    subscription-manager-migration-data.noarch : RHN Classic to RHSM migration data
    Repo        : rhel-6-server-rpms
    If necessary, enable the supplementary repositories which contain the migration RPMs.
    [root@server ~]# subscription-manager repos --enable rhel-6-server-optional-rpms
  2. Install the migration tool packages.
    [root@server ~]# yum install subscription-manager-migration subscription-manager-migration-data

2.3. Migrating from RHN Classic to Customer Portal Subscription Management


If you have a virt-limit=unlimited subscription (e.g., a Virtual Data Center entitlement), you need to set up virt-who before migrating to RHSM from RHN. If you don’t set up virt-who prior to the migration, repositories and/or subscriptions may fall off of any system that is using a virt-who required subscription.
A system which was registered against the hosted subscription service, RHN Classic, can be migrated to Customer Portal Subscription Management using the rhn-migrate-classic-to-rhsm script.
The general action is that it unregisters the system from RHN Classic, registers it with Customer Portal Subscription Management, and opens Subscription Manager (either GUI or CLI) to attach subscriptions.
The rhn-migrate-classic-to-rhsm script has this syntax:
rhn-migrate-classic-to-rhsm [--force|--gui|--help|--no-auto|--servicelevel=SERVICE_LEVEL]
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
migration.migration_date: 2012-09-14T14:55:29.280519
This makes it easy to track the migration process for systems within the infrastructure.
Comparison for migration:

Please refer to the following table for comparisons between RHN Classic and Red Hat Customer Portal Subscription Management capabilities. Note, this table may contain statements regarding future services not yet approved for implementation and does not indicate a commitment for delivery.

Additional information on migration options and deployment strategies for RHN Classic Hosted customers can be found at: "Transition of Red Hat Network Classic Hosted to Red Hat Subscription Management" and "RHN Classic Hosted/stand-alone Proxy Customer Options for Red Hat Enterprise Linux 7 (RHEL 7)"


RHN Classic

Red Hat Portal (Red Hat Subscription Management)

Red Hat Product Support

Red Hat Enterprise Linux versions supported

All current products and versions in Red Hat Enterprise Linux 4 All current products and versions in Red Hat Enterprise Linux 5 and Red Hat Enterprise Linux 6 All current products and versions in Red Hat including Enterprise Linux 7 are supported via Red Hat Satellite 5.7 But not via RHN Classic Hosted or stand-alone Proxy)

Red Hat Enterprise Linux 5 (5.7 and newer) Red Hat Enterprise Linux 6 (6.1 and newer) Red Hat Enterprise Linux 7 Intended for future versions of Red Hat Enterprise Linux

Red Hat Enterprise Virtualization versions supported

All current products and versions including RHEV 2.1, 2.2, 3.0

RHEV 3.0 and newer

Red Hat Enterprise Linux Migration to RHSM support?


YES, for Red Hat Enterprise Linux 5 (5.8 and newer) - via migration tooling as described in Red Hat Subscription Management

YES, for Red Hat Enterprise Linux 6 (6.3 and newer) - via migration tooling as described in Red Hat Subscription Management and How to migrate a Red Hat Enterprise Linux System from RHN Classic to RHSM

Red Hat Satellite 5

YES, all versions of 5.x

PARTIAL, Satellite 5 certificates can be issued from Customer Portal. Satellite 5.6 or 5.7 can be integrated with SAM 1.3+ to provide subscription status reporting

Red Hat Satellite 6



Support for all product SKUs

YES, but future product products may not be enabled for RHN Classic

Subscription Management Support

Default Client for installation method

Red Hat Enterprise Linux 5 (5.7 and older) Red Hat Enterprise Linux 6 (6.1 and older) All Red Hat Enterprise Linux 4

Red Hat Enterprise Linux 6 (6.3 and later) Red Hat Enterprise Linux 5 (5.9 and later) future versions of Red Hat Enterprise Linux

Content Basis for Client

RHN Classic rhn-channel command and What is the command "rhn-channel" and how to use it?

Red Hat Subscription Manager subscription-manager command to register and add subscriptions

Command line utilities for Client

yum update (Red Hat Enterprise Linux 5 and later), up2date (Red Hat Enterprise Linux 4)

yum update

System registration

rhn_register, rhnreg_ks

Activation keys

YES, with Smart Management subscriptions

List subscriptions available to apply to installed system on Client


subscription-manager list --available

Force list all subscriptions on Client


Smart autosubscribe a subscription


subscription-manager register --autosubscribe How do I subscribe to a channel in Red Hat Subscription Management?

Graphical user interface utilities for Client

System → Administration → RHN Registration

System → Administration → Red Hat Subscription Manager

Package update utility

/usr/bin/yum System → Administration → Add/Remove Software

/usr/bin/yum System → Administration → Add/Remove Software

Yum plugin support

yum-rhn-plugin (provides rhnplugin.conf)

subscription-manager (provides subscription-manager.conf and product-id.conf)

Web-based administration tool for customers

Support for updating content through Content Delivery Network



Email errata notifications



Support for IP-Based Firewall Rules

Support for sosreport diagnostics logging



Optional and Supplementary Channels available?

Support for subscription status

PARTIAL, Red Hat Satellite 5.6 or 5.7 can be integrated with Red Hat SAM 1.3+ for subscription status


Support for subscription consumption reports

PARTIAL, Red Hat Satellite 5.6 or 5.7 can be integrated with Red Hat SAM 1.3 for subscription status

YES, via Red Hat Subscription Asset Manager FUTURE, via Red Hat Satellite 6

System Management Support

Support for Smart Management Red Hat Enterprise Linux Add-On


YES, with Red Hat Satellite 6

Support for machine provisioning and monitoring

YES, with Smart Management subscriptions

YES, via Red Hat Satellite 6 provisioning feature

Content Management Support

Content Download GUI



Support for remote updating

YES, with Smart Management subscriptions


Support for offline updating

FUTURE, via Red Hat Subscription Asset Manager YES, via Red Hat Satellite 6

Support for proxied updating

YES, via Red Hat Satellite Proxy 5

YES, via Red Hat Subscription Asset Manager (SAM) and Red Hat Satellite 6 Capsule Server

2.3.1. Basic RHN Classic to Customer Portal Subscription Management Migration

Simply running the rhn-migrate-classic-to-rhsm tool migrates the system profile, registers the system with Customer Portal Subscription Management Subscription Management, and autoattaches the system to the best-matched subscriptions. Optionally, administrators can also set a service level preference for the system, which is used to help evaluate what subscriptions to select.
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 --servicelevel=premium
RHN Username: jsmith@example.com
The script prompts for the username and password to use to connect to Red Hat Network. It uses these credentials to authenticate to both Red Hat Network Classic and Red Hat Network Subscription Management, 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:
Each discovered channel is then mapped to a corresponding product certificate (Section 2.4, “Looking at Channel and Certificate Mappings”). Not every product has a product certificate, so not every channel may have a map. Only the products with a channel have a corresponding certificate map.
The matching certificates are installed in the /etc/pki/product directory.
List of channels for which certs are being copied

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 Customer Portal Subscription Management.
Attempting to register system to RHN ...
The system has been registered with id: abcd1234
System server.example.com successfully registered to RHN.
The script then autoattaches matching subscriptions to the system and lists all selected subscriptions.
Attempting to auto-subscribe to appropriate subscriptions ...
Installed Product Current Status:
ProductName:            Red Hat Enterprise Linux Desktop
Status:                 Subscribed

Successfully subscribed.

2.3.2. Migrating to an On-Premise Service

The rhn-migrate-classic-to-rhsm tool migrates the system to Customer Portal Subscription Management (hosted) services by default, using the default configuration for Subscription Manager. For infrastructures which have an on-premise subscription management service such as Subscription Asset Manager, this configuration can be changed so that the migration process registers the systems with the on-premise subscription services and attaches matching subscriptions.
This is done by using the --serverurl option, which specifies the URL of the on-premise service. In this case, the authorization credentials must also be given for the on-premise subscription management service account (which is independent of the RHN account).
[root@server ~]# rhn-migrate-classic-to-rhsm --serverurl=sam.example.com

2.3.3. Manually Selecting Subscriptions

Alternatively, the rhn-migrate-classic-to-rhsm can open the Subscription Manager UI to allow administrators to select the subscriptions manually.
The --gui option tells the rhn-migrate-classic-to-rhsm to register the system only and then to open the UI, rather than attaching subscriptions to the system.
The overall process is identical to the one in Section 2.3.1, “Basic RHN Classic to Customer Portal Subscription Management Migration” until the penultimate step. Rather than attaching subscriptions, it returns the URL and then opens the Subscription Manager GUI to the All Available Subscriptions tab.
[root@server ~]# rhn-migrate-classic-to-rhsm --gui 
RHN Username: jsmith@example.com

Retrieving existing RHN classic subscription information ...

... 8< ...

Launching the GUI tool to manually subscribe the system ...
Subscription Selection Tab

Figure 1. Subscription Selection Tab

2.4. Looking at Channel and Certificate Mappings

The subscription-manager-migration-data package contains a mapping file that maps RHN Classic channels to Customer Portal Subscription Management 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 Red Hat 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 installed in 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 a 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 Customer Portal Subscription Management or where products are not fully subscribed.

2.5. About Certificates Used for Products and Subscriptions

Part of managing subscriptions requires verifying the identity of everything involved, such as the system, the subscription service, and the available products. The subscription service uses certificates to handle the identity and authentication aspects of the subscription service. These certificates also contain the actual data about available subscriptions and installed products.
The first time a subscription attached to a system, the system downloads a certificate from the subscription service. The subscription certificate contains all of the information about products that are available through that subscription. The subscription certificate is revoked and reissued any time there is a change in the subscriptions for an organization. Once a product is actually installed on a machine, then another certificate is issued to manage the subscriptions for the product on the system.
Each certificate issued and used by the Subscription Manager services is a .pem formatted file. This file format stores both keys and certificates in a base-64 blob. For example:
The rct tool with Subscription Manager can be used to extract and view information from these certificates, in a pretty-print format. (So can general PKI management tools like openssl and pk12util.)
This section describes the different certificates used by the subscription service and the subscription information contained in those certificates. A much more detailed description of X.509 certificates and a public key infrastructure (PKI) is given in the Red Hat Certificate System documentation in Chapter 1. Introduction to Public-Key Cryptography in the Red Hat Certificate System Planning, Installation, and Deployment Guide.

2.5.1. Summary of Certificates Used by Subscription Services

Table 2. Types of Certificates Used for Content and Subscriptions

Certificate Type Description Default Location
Identity Certificate Used to identify the system to the subscription service. This contains a unique ID which is assigned to the system when it is registered to the system. The identity certificate itself is generated by the subscription service when the system is registered and then sent to the system. /etc/pki/consumer
Subscription Certificate Contains a list of products that are available to a system to install, based on the subscriptions that have been attached to the system. The subscription certificate defines the software products, the content delivery location, and validity dates. The presence of a subscription certificate means that the system has used one of the quantities from the subscription. /etc/pki/entitlement
Product Certificate Contains the information about a product after it has been installed. /etc/pki/product/product_serial#.pem
CA Certificate A certificate for the certificate authority which issued the SSL server certificate used by the subscription service. This must be installed on a system for the system to use SSL to connect to the subscription service. /etc/rhsm/ca/candlepin-ca.pem
Satellite Certificate An XML-formatted certificate which contains a product list. This is used by on-premise Satellite 5.x systems, not the newer subscription service.

2.5.2. The Structure of Identity Certificates

An identity certificate is a standard SSL client certificate. This certificate is issued by the subscription service when the system registers to it. The system subsequently uses this certificate to authenticate to the subscription service whenever it contacts the service after registration.
The certificate contains three important pieces of information:
  • The system UUID, in the subject CN of the certificate
  • The subscription service which the system is registered to, in the issuer field of the certificate
  • The user account which registered the system, as the DirName value in the Subject Alt Name
The validity period of this certificate is associated with the time when the system was registered, not to any subscription contract periods or user account settings.

Example 1. Identity Certificate

        Version: 3 (0x2)
        Serial Number: 1430 (0x596)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=subscription.server.example.com, C=US, L=Raleigh  
            Not Before: Oct  6 16:32:05 2010 GMT
            Not After : Oct  6 23:59:59 2011 GMT
        Subject: CN=4881bd2f-868b-438c-af96-8b1d283daffc  
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            Netscape Cert Type:
                SSL Client, S/MIME
            X509v3 Key Usage:
                Digital Signature, Key Encipherment, Data Encipherment
            X509v3 Authority Key Identifier:

            X509v3 Subject Key Identifier:
            X509v3 Extended Key Usage:
                TLS Web Client Authentication
            X509v3 Subject Alternative Name:  
    Signature Algorithm: sha1WithRSAEncryption

2.5.3. The Structure of Subscription Certificates

A subscription is analogous to an assigned software license. Subscription certificates contain a list of available products for a system — software that the system has been granted rights to download and update. When a system is attached to a subscription pool, the system pulls down the subscription certificate from the subscription service, which contains all of the information about available products.
A subscription certificate contains a list of every potential product from every potential content source. The structure of the subscription certificate, then, allows multiple namespaces for products, content servers, roles, orders, and systems. A subscription certificate also contains complete information about the attached pool, even for products which may not be compatible with the specific system. In a subscription certificate, the architecture and version definitions contain all of the allowed architectures and versions.


The local Subscription Manager polls the subscription service routinely (every four hours by default) to check for changes in the subscriptions. When a subscription is changed in some way, then the original subscription certificate is revoked and is replaced with a new subscription certificate.
The subscription certificate is a *.pem file stored in the subscription certificates directory, /etc/pki/entitlement. The name of the *.pem file is a numeric identifier that is generated by the subscription service. This ID is an inventory number that is used to associate a subscription quantity with the system in the software inventory.
The heading of the certificate contains the name of the subscription service which issued it, the validity period of the certificate (which is tied to the installation date of the product), and then the serial number of the installation of the product.
        Version: 3 (0x2)
        Serial Number:
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=candlepin.example.com, C=US, L=City
            Not Before: Oct  8 17:55:28 2010 GMT
            Not After : Oct  2 23:59:59 2011 GMT
        Subject: CN=8a878c912b875189012b8cfbc3f2264a
... [snip] ...
The key definition of the product is given in custom certificate extensions that are appended to the certificate. Each namespace defines certain information about a product, including its name, content servers which can deliver it, the format of delivery, and a GPG key to identify the release. Every individual entry is identified by a numeric object identifier (OID) with the same basic format:
The 2 indicates that it is a product entry. product_# is a unique ID which identifies the specific product or variant. config_# relates to the installation information for that product, like its content server or the quantity available.


Every subscriptions-related extension begins with the OID base The subsequent numbers identify different subscription areas:
  • .2. is the product-specific information
  • .1. is the subscription information
  • .4. contains the contract information, like its ID number and start and end dates
  • .5. contains the system information, like the system ID which installed a product
A product definition contains a series of entries which configure all of the information required to identify and install the product. Each type of information has its own ID, the config_# in the OID, that is used consistently for all products. An example product is listed in Example 2, “Annotated Red Hat Enterprise Linux High Availability Product Extensions in a Subscription Certificate”.

Example 2. Annotated Red Hat Enterprise Linux High Availability Product Extensions in a Subscription Certificate

            content repository type  
                .HRed Hat Enterprise Linux High Availability (for RHEL Subscription) (RPMs)
            channel name  
                ..Red Hat
            download URL  
            key download URL  
            flex quantity  
            repo enabled setting  

2.5.4. The Structure of Product Certificates

The products that are installed on a system through the subscriptions attached to a system are identified by certificates. When an available product is installed, the subscription service generates a product certificate, which contains the information about the product contract and the specific installation.
Structurally, subscription certificates and product certificates are very similar, because they both provide much of the same information about products. The main difference is that a product certificate contains information about a single product that has been installed, so no other subscription information (like other available products or other product versions) is included in a product certificate the way that it is in a subscription certificate.
A product certificate contains a single product namespace (meaning, a single product definition) which shows only what is actually installed on the system. The architecture and version definitions in a product certificate reflect the architecture and version of the product that is actually installed.
The product certificate is a *.pem file stored in the subscription certificates directory, /etc/pki/product/product_serial#.pem. The name of the *.pem file is a numeric identifier that is generated by the subscription service. As with subscription tracking, the generated ID is an inventory number, used to track installed products and associate them with systems within the subscription service.

2.5.5. Viewing Certificate Information with the rct Tool

The rct tool performs two tasks:
  • It displays the size and statistics of the certificate information (stat-cert).
  • It displays information (headers) contained within the certificate, such as product or content set information (cat-cert).
The precise details returned by either command depend on the type of certificate being checked. Viewing Certificate Sizes and Statistics
Large accounts and organizations can have a large number of products and subscriptions, in multiple orders. This results in a very large number of products and content sets available to the organization, and all of the information is defined in the entitlement certificate.
The main reason to view certificate statistics is that certificate sizes, for a number of reasons, impact content delivery service performance. Older versions of entitlement certificates (version 1.0) used different, less efficient DER encoding, so that large amounts of information results in very large certificates. (This could cause timeouts or crashes when dealing with content services. Newer entitlement certificate versions (version 3.0) use more efficient encoding on large content sets, which improves overall subscription service performance.
A large number of content sets is anything over 185 total sets. Both the total number of content sets and the size of the DER encoding in the certificate could affect performance.
This information is displayed using the stat-cert command and specifying the PEM file of the certificate to check.
# rct stat-cert /path/to/PEM_FILE

Table 3. Information Returned by stat-cert

Parameter Description Possible Values Certificate Types It Applies To
Type Identifies the type of certificate being checked.
  • Entitlement
  • Identity
  • Product
  • Entitlement
  • Identity
  • Product
Version The version of the certificate formatting which indicates the type of DER encoding used.
  • 3.0 (new)
  • 1.0 (old)
  • Entitlement
  • Identity
  • Product
DER size The size of the certificate contents (not the size of the certificate file itself). Size in bytes
  • Entitlement
  • Product
  • Identity
Subject Key ID size The size of the hashed public key for the key associated with the certificate (not the size of the key file itself). Size in bytes
  • Entitlement
  • Identity
Content sets The total number of all available content sets for the system, for all supported versions for products for the system. Number
  • Entitlement
For example, for an entitlement certificate:
[root@server ~]# rct stat-cert /etc/pki/entitlement/2027912482659389239.pem
Type: Entitlement Certificate
Version: 1.0
DER size: 47555b
Subject Key ID size: 553b
Content sets: 100
While the size of the certificate is less of an issue for identity and product certificates (which are quite small), the stat-cert command can still be used to view the size and statistics of the certificates.
For example, for a product certificate:
[root@server ~]# rct stat-cert /etc/pki/product/69.pem
Type: Product Certificate
Version: 1.0
DER size: 1558b
For an identity certificate:
[root@server ~]# rct stat-cert /etc/pki/consumer/cert.pem
Type: Identity Certificate
Version: 1.0
DER size: 1488b
Subject Key ID size: 20b Viewing Certificate Information
Each certificate contains a complete set of information that contains all of the details for whatever element is being identified — such as its serial number, associated products, order information, or content sets, depending on the type of certificate. That information can be displayed, in pretty-print form, using the cat-cert command.
# rct cat-cert /path/to/PEM_FILE [--no-product] [--no-content]


Entitlement certificates contain additional information about available products and configured content repositories. Since this information can be huge, the --no-product and --no-content options can be used to cut out the long lists of products and repositories and only return certificate and order information.
Those options are not used when getting information about identity or product certificates.
The most basic information is the information about the certificate itself, such as its directory path, its serial umber and subject name, and its validity period (start and end dates). The information about the certificate itself is in the Certificate section. The subject DN of the certificate is in the Subject section.
For example, for the identity certificate:
[root@server ~]# rct cat-cert /etc/pki/consumer/cert.pem

        Identity Certificate

        Path: /etc/pki/consumer/cert.pem
        Version: 1.0
        Serial: 824613308750035399
        Start Date: 2012-11-09 16:20:22+00:00
        End Date: 2013-11-09 16:20:22+00:00
        Alt Name: DirName:/CN=server.example.com

CN: e94bc90e-44a1-4f8c-b6fc-0a3e9d6fac2b
A product certificate contains additional information in a Product section, which defines the information for the specific installed product, such as its name, product version, and any yum tags used for that product. For example:
[root@server ~]# rct cat-cert /etc/pki/product/69.pem

       Product Certificate

       Path: /etc/pki/product/69.pem
       Version: 1.0
       Serial: 12750047592154746449
       Start Date: 2012-10-04 18:45:02+00:00
       End Date: 2032-09-29 18:45:02+00:00

       CN: Red Hat Product ID [b4f7ac9e-b7ed-45fa-9dcc-323beb20e916]

       ID: 69
       Name: Red Hat Enterprise Linux Server
       Version: 6.4
       Arch: x86_64
        Tags: rhel-6,rhel-6-server
The most information is contained in the entitlement certficate. Along with the Certificate and Subject sections, it also has a Product section that defines the product group that is covered by the subscription.
Then, it contains an Order section that details everything related to the purchase of the subscription (such as the contract number, service level, total quantity, quantities assigned to the system, and other details on the subscription).
A subscription for a product covers the version purchased and every previous version of the product. For example, when a subscription is purchased Red Hat Enterprise Linux 6, the subscription provides full access to all RHEL 6 repositories, plus acces to all RHEL 5 repositories and then other included product content repositories, like Subscription Asset Manager. Every available content repository is lised in a Content section that contains the repository name, associated tags, its URL, and a notice on whether the yum repository is enabled by default.
For example:
[root@server ~]# rct cat-cert /etc/pki/entitlement/2027912482659389239.pem
       Entitlement Certificate

       Path: /etc/pki/entitlement/2027912482659389239.pem
       Version: 1.0
       Serial: 2027912482659389239
       Start Date: 2011-12-31 05:00:00+00:00
       End Date: 2012-12-31 04:59:59+00:00

       CN: 8a99f9843adc8b8f013ae5f9de022b73

      ID: 69
      Name: Red Hat Enterprise Linux Server
      Arch: x86_64,ia64,x86

      Name: Red Hat Enterprise Linux Server, Premium (8 sockets) (Up to 4 guests)
      Number: 2673502
      SKU: RH0103708
      Contract: 10011052
      Account: 5206751
      Service Level: Premium
      Service Type: L1-L3
      Quantity: 100
      Quantity Used: 1
      Socket Limit: 8
      Virt Limit:
      Virt Only: False
      Stacking ID:
      Warning Period: 0
      Provides Management: 0

      Type: yum
      Name: Red Hat Enterprise Linux 6 Server (RPMs)
      Label: rhel-6-server-rpms
      Vendor: Red Hat
      URL: /content/dist/rhel/server/6/$releasever/$basearch/os
      GPG: file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
      Enabled: True
      Expires: 86400
      Required Tags: rhel-6-server
There can be dozens or even hundreds of products and content repositories contained within a single entitlement certificate. In that case, the cat-cert command results can be truncated by using the --no-product or --no-content options to remove the Product and Content sections (respectively).

2.5.6. The Structure of Satellite Certificates (Classic Style of Certificates)


Satellite certificates are used by Satellite 5.x deployments. They are not used on Red Hat Enterprise Linux or by any certificate-based subscription service.
Every system has to have a secure, authoritative way to identify what subscriptions are available. For Satellite 5.x systems, this identification is done through a digitally-signed XML document that lists the products and quantities that a customer has purchased.
As with subscription certificates, a Satellite certificate contains the information about the subscription that was purchased, including the total number of systems that can be registered against that subscription and its start and end dates.
There are two types of subscriptions:
  • System subscriptions are subscriptions for services that can be performed, such as monitoring, provisioning, and virtualization.
  • Channel subscriptions, or content subscriptions, provide access to the different software product download channels on Red Hat Network. These include Red Hat Enterprise Linux add-ons like Supplementary and FastTrack and layered products like Red Hat Directory Server.
Both types can be included in a single Satellite certificate.
A system subscription and the metadata for a subscription are both configured similarly in the certificate:
<rhn-cert-field name="configuration_area">value</rhn-cert-field>
The name argument identifies what entity is being configured. This can be the organization which ordered the subscription (name="owner"), the start and end dates for the subscription (name="issued" and name="expires"), or the subscription itself. A system subscription uses the name argument to set the service being covered; every content subscription is set as a name="channel-family" type, with the specific product identified in an additional family argument.
The first section of the Satellite certificate is the metadata. The metadata identifies the organization which purchased it and the start and end dates of the subscription. The field being set is in the name argument, while the value is between the tags. The last lines of the certificate also set metadata for the subscription, including the version of the Satellite and the signature that signs the XML document (and allows the XML file to be used as a certificate).
  <rhn-cert-field name="product">RHN-SATELLITE-001</rhn-cert-field>
  <rhn-cert-field name="owner">Example Corp</rhn-cert-field>
  <rhn-cert-field name="issued">2009-04-07 10:18:33</rhn-cert-field>
  <rhn-cert-field name="expires">2009-11-25 00:00:00</rhn-cert-field>

... [snip] ...

  <rhn-cert-field name="satellite-version">5.3</rhn-cert-field>
  <rhn-cert-field name="generation">2</rhn-cert-field>
Version: Crypt::OpenPGP 1.03

The name="slot" field lists how many total systems are allowed to use this Satellite certificate to receive content. It is a global quantity.
  <rhn-cert-field name="slots">119</rhn-cert-field>
The system subscriptions are set by identifying the service type in the name argument and then setting the quantity as the value within the tags.
  <rhn-cert-field name="provisioning-slots">117</rhn-cert-field>
  <rhn-cert-field name="monitoring-slots">20</rhn-cert-field>
  <rhn-cert-field name="virtualization_host">67</rhn-cert-field>
The content subscriptions can include any combination of products, including base Red Hat Enterprise Linux subscriptions, variations of Red Hat Enterprise Linux, Red Hat Enterprise Linux add-ons, and general software products. General Red Hat Enterprise Linux server subscriptions are listed in the rhel-server family, while a specific Virtualization Server subscription provides an additional rhel-server-vt family.
  <rhn-cert-field name="channel-families" quantity="95" family="rhel-server"/>
  <rhn-cert-field name="channel-families" quantity="67" family="rhel-server-vt"/>
Add-ons and products for Red Hat Enterprise Linux systems (but not necessarily operating system products) are also in a rhel-* family, because that refers to the platform the product is supported on. In this example, Red Hat Directory Server is in the rhel-rhdirserv family.
  <rhn-cert-field name="channel-families" quantity="3" family="rhel-rhdirserv"/>
Most subscriptions will also include a subscription tool set to manage and enable within clients features such as provisioning or configuration management when registered to RHN Classic or Satellite 5.x.
  <rhn-cert-field name="channel-families" quantity="212" family="rhn-tools"/>

3. Revision History

Revision History
Revision 1.5-0February 28, 2017Anni Bond
Added information about virt-who migration.
Revision 1.4-12January 11, 2016Red Hat Subscription Management Documentation Team
Added a table comparing the differences between RHN Classic and RHSM.
Revision 1.4-10September 10, 2014Deon Ballard
Removing install-num-migrate-to-rhsm for RHEL 5 migrations, since support was dropped in RHEL 5.11.
Revision 1.3-5September 18, 2013Deon Ballard
New content and reorganization for the SAM 1.3 release.

Legal Notice

Copyright © 2016 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
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.