Get Started with Red Hat Subscription Management

Updated -

Both graphical and command-line tools are available to manage your Red Hat subscriptions and entitlements with the Red Hat Subscription Management (RHSM) service. This article provides a quick entry into how Subscription Management works. That's followed by an overview Subscription Management components, with tips on how to troubleshoot problems you may encounter as you try to register Red Hat software products.

Both graphical and command-line tools are available to manage your Red Hat subscriptions and entitlements with the Red Hat Subscription Management (RHSM) service. This article provides a quick entry into how Subscription Management works. That's followed by an overview Subscription Management components, with tips on how to troubleshoot problems you may encounter as you try to register Red Hat software products.

Using Subscription Management with Red Hat Enterprise Linux 7

Red Hat Enterprise Linux (RHEL) 7 is the first RHEL version to require that you use Subscription Management tools to entitle a RHEL system. Although you can use Subscription Management to entitle other versions of RHEL, Subscription Management is the preferred way to register and subscribe Red Hat Enteprise Linux systems.

Understanding Subscription Management

The primary goal of Subscription Management is to manage Red Hat product subscriptions. You manage subscriptions by working with subscriptions that provide software entitlements. You use those entitlements to get new and updated Red Hat software, as well as remain in compliance with Red Hat usage agreements. Here are the basic things you do with Subscription Management tools:

  • Register: By registering your system, you attach that system to your Red Hat account. This allows Subscription Management to uniquely inventory the system.
  • Subscribe: By subscribing the system, you enable the use of selected Red Hat products. You can either auto-subscribe (to consume any entitlement available with your account) or you can select a specific entitlement (in case you want one with a specific level of support, expiration date, and so on).
  • Enable repositories: Multiple repositories (formerly referred to as channels in RHN classic) are enabled by default when you subscribe. You can enable or disable other repositories associated with that product (such as update or source code repositories) as needed.
  • Review and track: You can review the entitlements you have available and those you have consumed by running commands from the client or accessing hosted (https://access.redhat.com/subscriptions/) or on-premise (SAM) services.

Here are some quick tips for understanding Subscription Management:

  • Subscription Management tools - Once you are using Subscription Management, there are several tools you can use to manage your Red Hat subscriptions. There are command-line and GUI tools from the client side, while on the server side you have the customer portal and SAM:

  • Subscription-Manager command line interface: From the shell, run the subscription-manager command (with various options). This command support different options for querying subscriptions (consumed and available), registering the local system, subscribing to specific entitlements, and otherwise maintaining your local subscriptions.

  • Subscription-Manager GUI: From the desktop, select System -> Administration -> Red Hat Subscription Manager to display the Subscription Manager GUI. This will show you information about subscriptions on the local system, as well as available subscriptions. Figure 1 shows an example of the Subscription Manager GUI, displaying locally installed Red Hat products:

Subscription-Manager Window

Figure 1: View subscription information from the Subscription-Manager Window

  • Customer Portal: On the server side of Subscription Management, the Red Hat customer portal Subscriptions page lets you view information about all the subscriptions and systems consuming subscriptions associated with your Red Hat user account. The following figure shows the Red Hat Customer Portal subscription page.

Subscription Managements on the Red Hat customer portal

Figure 2: View subscription information from the Customer Portal Subscription Management

  • Subscription Asset Manager (SAM): For customers that want to manage their subscriptions on premise, Subscription Asset Manager (SAM) is an on-premise subscription management application for managing subscriptions for multiple systems. With SAM, you can view what subscriptions are available and what are consumed from your Red Hat accounts without accessing the Red Hat Customer Portal directly.

Refer to the following articles to learn more about the value of Red Hat Subscription Management:

Overview of Red Hat Subscription Management
The Benefits of Red Hat Subscription Management
Benefits of a Red Hat subscription

Using Subscription Management commands

The following are examples of using subscription-manager and related commands to register a system, query subscription information, and otherwise manage subscriptions. To get more information about subscription-manager, type man subscription-manager or run subscription-manager with no options to see the syntax for the command:


# subscription-manager
Usage: subscription-manager MODULE-NAME [MODULE-OPTIONS] [--help]
Primary Modules:
  attach         Attach a specified subscription to the registered system
  list           List subscription and product information for this system
  refresh        Pull the latest subscription data from the server
  register       Register this system to the Customer Portal or another subscription management service
...

To get help for a particular module (for example, the register module), use the --help option as follows:


# subscription-manager register --help
Usage: subscription-manager register [OPTIONS]
Register this system to the Customer Portal or another subscription management service
Options:
  -h, --help            show this help message and exit
  --proxy=PROXY_URL     proxy URL in the form of proxy_hostname:proxy_port
  --proxyuser=PROXY_USER
                        user for HTTP proxy with basic authentication
  --proxypassword=PROXY_PASSWORD
                        password for HTTP proxy with basic authentication
  --username=USERNAME   username to use when authorizing against the server
  --password=PASSWORD   password to use when authorizing against the server
...

Registering and Subscribing

To register a system that is not yet registered, run the following command (replacing yourusername and yourpassword with your Red Hat username and password):

# subscription-manager register --username=yourusername --password=yourpassword
The system has been registered with id: 231c3a37-8e14-449c-a232-3de2d5c8fa8a

To list which subscriptions are available for your registered Red Hat account, type the following:

# subscription-manager list --available | less

To automatically choose and consume a subscription after the system is registered, type the following:

# subscription-manager attach --auto
The system has been registered with id: 231c3a37-8e14-449c-a232-3de2d5c8fa8a

Instead of automatically choosing a subscription, after you list available subscriptions, consume a particular subscription by entering its pool ID as follows:

# subscription-manager attach --pool=7b64f895519e98de4138735cea132a
Successfully attached a subscription for: Red Hat Enterprise Linux for Virtual Datacenters, Premium

To see what subscriptions have been consumed on your system, run the following:

# subscription-manager list --consumed

Enabling Repositories

Registering and subscribing your RHEL system ultimately gives you access to software repositories. After you subscribe to one or more entitlements (PoolIDs), the following file is either created or enhanced:

/etc/yum.repos.d/redhat.repo

The contents of the redhat.repo file reflect all the available repositories from subscribed entitlements. Here's an example of a repository entry from that file:

name = Red Hat Enterprise Linux 6 Server (RPMs)
baseurl = https://cdn.redhat.com/content/dist/rhel/server/6/$releasever/$basearch/os
enabled = 1
gpgcheck = 1
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
sslverify = 1
sslcacert = /etc/rhsm/ca/redhat-uep.pem
sslclientkey = /etc/pki/entitlement/6415396139649515674-key.pem
sslclientcert = /etc/pki/entitlement/6415396139649515674.pem
...

Refer to the yum.conf man page for descriptions of the options just shown. In particular, you can see the location where software packages for this repository are stored (baseurl). Those packages are only accessible if enabled = 1 is set. A quicker way to see which repositories are enabled is with yum repolist:


# yum repolist
...
repo id                                  repo name                                                                             status
rhel-6-server-eus-rpms                   Red Hat Enterprise Linux 6 Server - Extended Update Support (RPMs)                    11,120
rhel-6-server-rpms                       Red Hat Enterprise Linux 6 Server (RPMs)                                              11,121
rhel-6-server-supplementary-rpms         Red Hat Enterprise Linux 6 Server - Supplementary (RPMs)              

To enable a repository, you can simply change the enabled = 0" to enabled = 1 line under the repository you want in the redhat.repo file. Or, instead, you could use the yum-config-manager command as follows:

# yum-config-manager --enable rhel-6-server-sam-rpms

The example just shown enables the Subscription Asset Manager repository. To find the names of other available repositories, look for the names in square brackets [] in the redhat.repo file.

Unattaching and Unregistering

To unattach a specific subscription from your system, get the serial number for that subscription (see what is consumed) then remove it as follows:

# subscription-manager list --consumed
# subscription-manager remove --serial=584943852285074892

To unregister the system, type the following:

# subscription-manager unregister
System has been unregistered.

To clean out all subscription data, run the following:

# subscription-manager clean

Understanding Entitlements

You don't need to know much about certificates to use Subscription Management in most cases. However, if you want to troubleshoot subscription problems, it helps to know that certificates allow systems to be identified to the Subscription Management service and are the basis of authentication, authorization, and inventory capabilities of the service.

Subscription certificates are stored in the /etc/pki/ directory and its subdirectories. Here are examples of what to expect to find in several of those subdirectories that relate to entitlements:

/etc/pki/product
Contains certificates that describe the actual Red Hat products that are installed on the system. In that directory, you should see at least the 69.pem file, which identifies this as a RHEL system, and possibly certificates for other products that might be installed. Here are some examples of certificate files in this directory:

  • 69.pem: This certificate identifies the release version, architecture and name of the Red Hat Enterprise Linux system installed on the computer. The 69.pem file is created by the anaconda installer.

  • 70.pem: This certificate identifies the name, version number and architecture associated with RHEL Extended Update Support.

  • 150.pem: This certificate identifies the Red Hat Enterprise Virtualization name, version, and architecture, as well as information on the issuer of this entitlement (Red Hat).

  • 201.pem: This certificate identifies the name, version number and architecture for Red Hat Software Collections.

As soon as you install a package from a repository, assuming you didn't just install it from a local RPM, the .pem file representing the product that package comes from is added to the /etc/pki/product directory.

If the last package from a product is deleted from the system, yum will remove the related .pem file from the /etc/pki/product directory. The one exception is the 69.pem file, which can't be deleted with a yum command. The 69.pem file should always be on your RHEL system.

/etc/pki/consumer
When you register your system (subscription-manager register), the cert.pem and key.pem files are added to this directory. Those files are removed when you unregister (subscription-manager unregister).

/etc/pki/entitlement
Contains certificates for subscriptions that have been attached to the local system (for example, subscription-manager attach --pool=xxxxx). The .pem files placed in this directory contain the most detailed information about what you get with a particular subscription. Each entitlement .pem file includes the following kinds of information:

  • Certificate: Information such as the Pool ID for the subscription, the start and end date that it is valid, and the serial number associated with it.

  • Issuer: Describes information such as the organization that issued the certificate (Red Hat, Inc.) and that organization's email address.

  • Product: Multiple products can be listed in Product sections. Each product has an ID, a Name and valid architectures.

  • Order: Includes details about what is included with this particular subscription. The order is associated with a particular Name, Number, and SKU. It will also include the Service Level and Service Type, along with how many of the subscriptions are available and how many have been used.

Running subscription-manager unattach --all deletes everything in the /etc/pki/entitlements directory.

Investigating Subscription Certificates

Subscription certificates are stored in X.509 format. If you are debugging problems with those certificates, you can use the openssl command to view their contents. But finding the right options to use can be cumbersome. A better choice is the rct tool, which is made specifically for the job of displaying information about certificates.

The rct command can be used to view the contents of certificates (rct cat-cert *.pem) or details about certificates (rct stat-cert *.pem). For example, this command shows the list of repositories, products and order information associated with a specific certificate:

# rct cat-cert /etc/pki/entitlement/4163951369645195746.pem

Some of the questions you can answer with rct cat-cert include:

  • What products are entitled with the certificate (Red Hat Enterprise Linux, Red Hat Enterprise Virtualization, Jboss Enterprise Application Platform, and so on)?
  • When does the certificate expire?
  • What are the SKU, contract number, account number, service level, entitlement quantities, and other attributes of the order?
  • What yum repositories are available with this entitlement?

The following example shows statistics about a certificate:

# rct stat-cert /etc/pki/entitlement/4163951369645195746.pem

Some of the questions you can answer with rct stat-cert include:

  • How many content sets (yum repositories or ISO files) are included in the certificate? Large content sets (over 185 total sets) can cause performance problems.
  • What is the DER size (which gives the size of the certificate contents, not the full size of the certificate)? Again, if this is large, performance problems can result.

For more information on the rct command, refer to Viewing Certificate Information with the rct Tool, Using the rct tool to troubleshoot Red Hat Subscription Management issues, or the rct man page (type man rct).

Subscription Configuration

Problems can arise when subscription management configuration settings are wrong. Subscription management configuration settings are defined in the following file:

/etc/rhsm/rhsm.conf

Type this command to see current settings:

# subscription-manager config --list
[server]
   hostname = [subscription.rhn.redhat.com]
   insecure = [0]
   port = [443]
   prefix = [/subscription]
   proxy_hostname = []
   proxy_password = []
   proxy_port = []
   proxy_user = []
   ssl_verify_depth = [3]

[rhsm]
   baseurl = [https://cdn.redhat.com]
   ca_cert_dir = [/etc/rhsm/ca/]
   consumercertdir = [/etc/pki/consumer]
   entitlementcertdir = [/etc/pki/entitlement]
   manage_repos = [1]
   pluginconfdir = [/etc/rhsm/pluginconf.d]
   plugindir = [/usr/share/rhsm-plugins]
   productcertdir = [/etc/pki/product]
   repo_ca_cert = [/etc/rhsm/ca/redhat-uep.pem]
   report_package_profile = [1]

[rhsmcertd]
   autoattachinterval = [1440]
   certcheckinterval = [240]

Square brackets ([]) shown above indicate that the default value is being used. If you suspect your subscription management settings are misconfigured, edit the /etc/rhsm/rhsm.conf file to change any values set improperly. For example, if you changed the hostname by mistake, put in the right value for your satellite server or set it back to subscription.rhn.redhat.com.

Was this helpful?

We appreciate your feedback. Leave a comment if you would like to provide more detail.
It looks like we have some work to do. Leave a comment to let us know how we could improve.
Close

Welcome! Check out the Getting Started with Red Hat page for quick tours and guides for common tasks.