Using and Configuring Red Hat Subscription Manager

Red Hat Subscription Management 1

to register systems, manage subscriptions, and view notifications for systems

Edition 2

Red Hat Subscription Management Documentation Team

April 4, 2018

Abstract

Red Hat Subscription Manager is a local service which tracks installed products and subscriptions on a local system to help manage subscription assignments. It communicates with the backend subscription service (the Customer Portal or an on-premise server such as Subscription Asset Manager) and works with content management tools such as yum.
This guide covers advanced configuration and usage for Subscription Manager, aside from the basic registration procedures in Quick Registration for RHEL.

Chapter 1.  Getting started with Red Hat Subscription Manager

With Red Hat products, you can manage your subscriptions with different applications depending on your organization’s needs. Red Hat Subscription Manager is an on-premise application that sends information back to the Red Hat Customer Portal about your subscription usage.
Red Hat Subscription Management Options

Figure 1.1. Red Hat Subscription Management Options

After Subscription Manager is installed on a local system, it can track product installation, attached subscriptions, and subscriptions that are still available to be consumed. It also tracks subscription expirations and automatically attaches new subscriptions based on the system hardware and the product being attached. Most systems require simple registration. The default configuration registers the system with the main account to the Customer Portal.
Red Hat Subscription and Registration Process

Figure 1.2. Red Hat Subscription and Registration Process

A properly registered and attached product is eligible for support and errata updates. To be properly registered, the system needs to both be attached to your account and then attached to a subscription. Attaching your system to a subscription consumes one or more entitlements from a valid subscription depending on the type of system that it is.
This guide covers how to understand and edit the configuration of Red Hat Subscription Manager. It is intended for more advanced administrators. For regular system registration, see the Quick Registration for Red Hat Enterprise Linux guide in the subscription management documentation set.
If you have not purchased a subscription for your organization, you can find all available products at the Red Hat Store.

Chapter 2. Registration, attaching, and removing subscriptions in Subscription Manager

Before you can receive support for a Red Hat product, the system needs to be registered and attached to the subscription. User systems can be registered to Red Hat Subscription Management during the first boot of the machine, as well as after the machine has been configured. You can also unregister the system if it no longer needs to be managed using that product.

2.1. Registering and attaching a system in the Subscription Manager user interface

  1. Open the Subscription Manager user interface:
    [root@server ~]# subscription-manager-gui
  2. Select the product you need to register, and click the Register button.
  3. By default, subscription Manager registers your system against the Red Hat Customer Portal. If you use a different registration proxy, configure it here. When you are ready to proceed, click the Next button.
  4. Enter your credentials for the Red Hat Customer Portal, and enter a name to differentiate the system from others attached to your account. Click Register.
  5. Click Attach to attach the system to the account. By default, Subscription Manager automatically attaches the system to a subscription that matches the system architecture.

Note

When auto-attaching a system, the subscription service looks at whether the system is physical or virtual, as well as how many sockets the system has:
  • A physical system usually consumes two entitlements, whereas a virtual system consumes one.
  • One entitlement is consumed per two sockets on a system.

2.2. Activating a subscription with an activation key in the Subscription Manager user interface

An on-premise application can pre-configure subscriptions to use for a system, and that pre-configured set of subscriptions is identified by an activation key. That key can then be used to attach those subscriptions on a local system.
  1. Install the configuration RPM or manually configure Subscription Manager to point to the subscription application. For example:
    [root@server ~]# rpm -ivh http://sam.example.com/pub/candlepin-cert-consumer-latest.noarch.rpm
  2. Launch Subscription Manager with the --register option to open the registration screens immediately:
    [root@server ~]# subscription-manager-gui --register
  3. Select I will use an Activation Key, and click Next.
  4. Enter the name of the organization to which the system will belong, the activation key value (an alphanumeric string), and the system name to use for the entry in the on-premise application.
  5. Click Register.

2.3. Removing a subscription from a system in the Subscription Manager user interface

In some scenarios, you may need to remove a subscription from a system; you may be upgrading the system which requires a new subscription or trying to free an entitlement for another system.
  1. Open the Subscription Manager user interface:
    [root@server ~]# subscription-manager-gui
  2. Select the My Subscriptions tab, and select the subscription you want to remove.
  3. Click Remove.
  4. Click Yes to confirm the removal.
After you have removed the subscription from Subscription Manager, verify the subscription entitlement is now free in Red Hat Customer Portal, as well

Chapter 3. Registration, attaching, and removing subscriptions in the Subscription Manager command line

Before you can receive support for a Red Hat product, the system needs to be registered and attached to the subscription. User systems can be registered to Red Hat Subscription Management during the first boot of the machine, as well as after the machine has been configured. You can also unregister the system if it no longer needs to be managed using that product.

3.1. Registering and attaching a system using the command line

To register a user system, use the register command using your Red Hat Customer Portal credentials. When the system is successfully authenticated, it registers the newly-assigned system inventory ID and the user account name which registered it.
Use the register command:
[root@server1 ~]# subscription-manager register --username admin-example --password secret

      The system has been registered with id: 7d133d55-876f-4f47-83eb-0ee931cb0a97

Note

When auto-attaching a system, the subscription service looks at whether the system is physical or virtual, as well as how many sockets the system has:
  • A physical system usually consumes two entitlements, whereas a virtual system consumes one.
  • One entitlement is consumed per two sockets on a system.
To register a system with auto-attach enabled, use the register command:
      [root@server1 ~]# subscription-manager register --username admin-example --password secret --auto-attach

3.2. Activating a subscription with an activation key in the command line

An on-premise application can pre-configure subscriptions to use for a system, and that pre-configured set of subscriptions is identified by an activation key. That key can then be used to attach those subscriptions on a local system.
  1. Install the configuration RPM or manually configure Subscription Manager to point to the subscription application. For example:
    [root@server ~]# rpm -ivh http://sam.example.com/pub/candlepin-cert-consumer-latest.noarch.rpm
  2. Run the register command with the --activationkey parameter to attach the configured subscriptions:
    # subscription-manager register --username=jsmith --password=secret --org="IT Dept" --activationkey=abcd1234

3.3. Removing a subscription from a system using the command line

In some scenarios, you may need to remove a subscription from a system; you may be upgrading the system which requires a new subscription or trying to free an entitlement for another system.
To remove a system, use the command:
[root@server1 ~]# subscription-manager remove --poolnumber

Note

You can also remove all subscriptions from the system using
subscription-manager remove --all
.

Chapter 4. Using certificates with Subscription Manager

Red Hat uses certificates to verify the identity of the system and authenticate that it is compliant with the subscriptions as outlined in your contract. Any time there is a change in the subscription at the organization level, Red Hat revokes the certificate and issues a new one. The organization administrator must then download the new certificate to the system.
A certificate uses the .pem file type and contains both keys and certificates. There are five types of certificates:
  • Identity certificate: identifies the system to the subscription service.
  • Subscription certificate: Defines the products a user can install on their system based on the subscriptions that have been attached to that system.
  • Product certificate: Contains the information about a product after it has been installed
  • CA certificate: 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.
  • 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.

4.1. Importing subscription certificates

In certain situations, new product subscriptions can be added by installing the subscription certificate directly rather than polling the subscription service. For example, systems which are offline must have subscriptions manually added because they cannot connect to the subscription service directly. Alternatively, an administrator may want to attach a subscription for a product which is not yet installed.
Before you begin, you need to retrieve the offline system’s certificate from the Customer Portal:
  • From the Customer Portal, open the Systems page.
  • Click the offline system. If necessary, attach the subscriptions to the system.
  • Click the My Subscriptions tab.
  • Click the Download All Certificates button. This exports all of the subscription certificates, for each product, to a single .zip file. Save the file to a portable media device, like a flash drive. Alternatively, click the Download link on the row for the subscription to download an individual certificate.
Once you have the certificate(s) downloaded, copy them to the offline system. If all certificates were downloaded in an archive file, then there are multiple archives in the downloaded certificates.zip file. Unzip the directories until you see the .PEM files for the subscription certificates are available.
Import the certificates:
  • Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  • Open the System menu, and select the Import Certificate item.
  • Click the file folder icon at the right of the field to navigate to the .pem file of the product certificate.
  • Click the Import Certificate button.
All of the uploaded subscriptions are attached to the system.
Alternatively, you can import the certificates using the command line:
# subscription-manager import --certificate=/tmp/export/entitlement_certificates/596576341785244687.pem
          --certificate=/tmp/export/entitlement_certificates/3195996649750311162.pem

          Successfully imported certificate 596576341785244687.pem
          Successfully imported certificate 3195996649750311162.pem

4.2. Updating subscription certificates

A subscription certificate represents a subscription that has been attached to a given system. It includes all of the products which are included in the subscription for service and support, the subscription start and end dates, and the number of subscriptions included for each product. A subscription certificate does not list products that are currently installed on the system; rather, it lists all products that are available to the system.
The subscription certificate is an X.509 certificate and is stored in a base 64-encoded blob in a .pem file.
When a subscription expires or is changed, then the subscription certificate must be updated to account for the changes. The Red Hat Subscription Manager polls the subscription service periodically to check for updated subscription certificates; this can also be updated immediately or pulled down from the Customer Portal. The subscription certificates are updated by revoking the previous subscription certificate and generating a new one to replace it.
  1. Download the certificate(s) you need to update as described in Section 4.1, “Importing subscription certificates”.
  2. Use the refresh command:
    [root@server1 ~]# subscription-manager refresh

4.3. Regenerating identity certificates

To regenerate the system's identity certificate (meaning it is revoked and replaced), use the identity command.
Although credentials are not normally required with the identity command, using the --force option will require the username and password and will cause the Subscription Manager to prompt for the credentials if they are not passed in the command. This can be helpful if the identity certificate needs to be regenerated using a different Red Hat account than the original registration.
      [root@server1 ~]# subscription-manager identity --regenerate --force
      Username: js    mith@example.com
      Password:
      Identity certificate has been regenerated.

4.4. Viewing certificate information using the rct tool

The rct tool performs two tasks:
  • Displays the size and statistics of the certificate information (stat-cert).
  • 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.
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

4.5. 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 using the cat-cert command:
# rct cat-cert /path/to/PEM_FILE [--no-product] [--no-content]

Note

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.

Chapter 5. Configuring options in Red Hat Subscription Manager

5.1. Enabling supplementary and optional repositories

As product subscriptions are attached to systems, the system gains access to content repositories that are identified in the system’s certificate. Content repositories are based on the product and on the content delivery network (CDN) that are defined in the rhsm.conf file.
A subscription may include access to optional content repositories in addition to the default repositories that are automatically enabled on the system. These optional repositories must be enabled before the packages in them can be installed even if the system has the appropriate subscriptions for the products in those repositories.
List all available repos for the system, including disabled repos:
[root@server1 ~]# subscription-manager repos --list
The optional and supplementary channels are named
rhel-6-server-optional-rpms
and
rhel-6-server-supplementary
respectively.
The repositories can be enabled using the
--enable
command:
[root@server ~]# subscription-manager repos --enable rhel-6-server-optional-rpms
Likewise, unwanted repositories can be disabled using the
repos --disable
command.

5.2. Disabling the Subscription Manager repository

Maintaining a redhat.repo file may not be desirable in some environments. It can create static in content management operations if that repository is not the one actually used for subscriptions. This is relevant for disconnected systems or systems using an on-premise content mirror.
This default repository can be disabled by editing the Subscription Manager configuration and setting the manage_repos value to zero (0):
[root@server1 ~]# subscription-manager config --rhsm.manage_repos=0

5.3. Using an HTTP proxy

Some network environments may only allow external Internet access or access to content servers by going through an HTTP proxy.
Subscription Manager can be configured to use an HTTP proxy for all of its connections to the subscription service. (This is also an advanced configuration option at firstboot.) To configure the proxy:
[root@server1 ~]# subscription-manager config
      --server.proxy_hostname=proxy.example.com
      --server.proxy_port=8080
      --server.proxy_user=admin
      --server.proxy_password=secret

Note

Leaving the proxy_hostname argument blank means that no HTTP proxy is used. proxy_port for the proxy server port.

5.4. Checking logs in Subscription Manager

There are two log files maintained for Red Hat Subscription Manager in the /var/log/rhsm directory:
  • rhsm.log shows every invocation and result of running Subscription Manager in either the user interface or the command line
  • rhsmcertd.log shows every time a new certificate is generated, which happens on a schedule defined by the cert
Frequency parameter in the rhsm.conf file. The rhsm.log file contains the sequence of every Python call for every operation invoked through the Subscription Manager tools. Each entry has this format:
YYYY-MM-DD HH:MM:SS,process_id [MESSAGE_TYPE] call python_script response
The response in the log entry can be very complex, spanning multiple lines, or relatively simply, with just a status code.
Because each log entry in rhsm.log relates to the Python script or function that was called, there can be multiple log entries for a single operation.

5.5. Retrieving the system UUID

The system UUID is a unique identifier used in the inventory subscription service. This UUID can be used to re-register the system if there is some kind of corruption or for internal tracking.
From the command-line, use the identity command to return the current UUID. The UUID is the Current identity is value.
[root@server1 ~]# subscription-manager identity Current identity is: 63701087-f625-4519-8ab2-633bb50cb261 name: server1.example.com org name: 6340056 org id: 8a85f981302cbaf201302d89931e059a

Chapter 6. Working with yum repos

Red Hat Subscription Manager works with yum. Subscription Manager has its own yum plug-ins: product-id for subscription-related information for products and subscription-manager which is used for the content repositories.

6.1. Viewing available repositories

Subscription management application can define a number of different content repositories, based on environments, physical locations, and other factors. Even when using the Red Hat content delivery network, multiple repositories are available depending on the product.
The repos command lists all of the repositories that are available to the configuration environments and organization for a system, and then shows whether those repositories are enabled for the system.

6.2. Enabling supplementary and optional repositories

As product subscriptions are attached to systems, the associated content repositories (identified in the subscription certificate) are made available to the system. The content repositories are based on the product and on the content delivery network, defined in the baseurl parameter of the rhsm.conf file.
A subscription may include access to optional content repositories along with the default repositories. These optional repositories must be enabled before the packages in them can be installed (even if the system has the appropriate subscriptions for the products in those repositories):
  1. List all available repos for the system, including disabled repos.
    [root@server1 ~]# subscription-manager repos --list
  2. The repositories can be enabled using the --enable option with the repos command:
    [root@server ~]# subscription-manager repos --enable rhel-6-server-optional-rpms
The optional and supplementary channels are named rhel-6-server-optional-rpmsand rhel-6-server-supplementary, respectively. Likewise, unwanted repositories can be disabled using the repos --disable command.

6.3. Disabling the subscription manager repository

When a system is registered using Subscription Manager, the rhsmcertd process creates a special yum repository — redhat.repo. As the system adds subscriptions, the product channels are added to the redhat.repo file.
Maintaining a redhat.repo file may not be desirable in some environments. It can create static in content management operations if that repository is not the one actually used for subscriptions, such as for a disconnected system or a system using an on-premise content mirror. This default redhat.repo repository can be disabled by editing the Subscription Manager configuration and setting the manage_repos value to zero (0).
[root@server1 ~]# subscription-manager config --rhsm.manage_repos=0

6.4. Setting firewall access for content delivery

For systems registered with Customer Portal Subscription Management or a local Subscription Asset Manager instance, all content is delivered from Red Hat-hosted repositories. The URL (set by default in the rhsm.conf file in the baseurl parameter) is cdn.redhat.com.
However, there is no single server for cdn.redhat.com; there are multiple potential servers which all resolve to that address. The download server is selected based on what is geographically closest to the requesting machine. This results in much faster download times and better availability for content — however, in some firewall configuration, the required IP addresses could be blocked.
If yum downloads are failing, the it may be necessary to open the firewall to allow access to the IP address of the available content delivery servers. A list of IP addresses is available at Public CIDR Lists for Red Hat, both in a list and in a downloadable JSON file.

Appendix A. Revision History

Revision History
Revision 2.0-1May 17, 2018Anni Bond
Added diagram to first chapter
Revision 2.0-0April 4, 2018Anni Bond
BZ#1535071 - [CSAT] subscription problem1547202 - [CSAT] Redhat subscription components
BZ#1547202 - [CSAT] Redhat subscription components
BZ#1409456 - The Customer Portal hasn't looked or behaved like those screenshots for at least one revision
BZ#1547032 - Update Edit Using and Configuring Subscription Manager to remove references to RHN
Revision 1.4-18June 5, 2017Andrew Dahms
BZ#1431524 - Updated a description of the --all option when checking available entitlements.
Revision 1.4-17July 9, 2015Ella Deon Ballard
Updating reference to CIDR list.
Revision 1.4-16March 5, 2015Jo Somers
Removing reference to Xen with virt-who.
Revision 1.3-14April 13, 2014Ella Deon Ballard
Updating instance-based and virtual setup sections.
Revision 1.3-12September 18, 2013Deon Ballard
New content and reorganization for the SAM 1.3 release.