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

Red Hat Subscription ManagementDocumentation Team

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.

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.

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.

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

Open the Subscription Manager user interface:

[root@server ~]# subscription-manager-gui

Select the product you need to register, and click the Register button.

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.

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.

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.

Install the configuration RPM or manually configure Subscription Manager to point to the subscription application. For example:

Launch Subscription Manager with the --register option to open the registration screens immediately:

[root@server ~]# subscription-manager-gui --register

Select I will use an Activation Key, and click Next.

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.

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.

Open the Subscription Manager user interface:

[root@server ~]# subscription-manager-gui

Select the My Subscriptions tab, and select the subscription you want to remove.

Click Remove.

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:

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.

Install the configuration RPM or manually configure Subscription Manager to point to the subscription application. For example:

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:

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:

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.

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.

4.4. Viewing certificate information using the rct tool

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.

4.6. Troubleshooting errors when generating certificates

4.6.1. Resolving errors with yum installation

Verify that the UUID from the system matches that it matches the one listed on the Customer Portal:

You are using the correct date and time for your system. SSL requires these values be accurate.

Your local network has the routes and SSL proxy rules it needs to connect.

That firewall/proxy administrators to see if any HTTPS inspection is being performed.

If all of the settings are accurate, you may need to reinstall the root certificate:

Download python-rhsm from the Customer Portal.

Copy the RPM package file to the RHEL server.

Install the package using rpm.

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.

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:

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):

List all available repos for the system, including disabled repos.

[root@server1 ~]# subscription-manager repos --list

The repositories can be enabled using the --enable option with the repos command:

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.