Using and Configuring Red Hat Subscription Manager

Red Hat Subscription Management 1

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

Red Hat Subscription Management Documentation Team

October 1, 2013

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.

1. About Red Hat Subscription Manager

Effective asset management requires a mechanism to handle the software inventory — both the type of products and which systems that the software is installed on.
Red Hat Subscription Manager is installed on a local system and it tracks what products are installed, what subscriptions are available for the system, and what subscriptions are actually used by the system. It also tracks subscription expirations and automatically attaches new subscriptions based on the products and hardware.
Most systems require simple registration. The default configuration registers the system with the main account for the company, hosted on the Red Hat Customer Portal.
However, it is possible to configure advanced settings in Red Hat Subscription Manager to connect to proxy services, alternate subscription services, or even to change the information (such as architecture and hardware settings) for the system to tweak how subscriptions are attached.
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 Registeration for Red Hat Enterprise Linux guide in the subscription management documentation set.

2. Local System Tools (Red Hat Subscription Manager)

Both registration and subscriptions are managed on the local system through UI and CLI tools called Red Hat Subscription Manager. The Subscription Manager tracks and displays what subscriptions are available to the local system and what subscriptions have been consumed by the local system. The Subscription Manager works as a conduit back to the subscription service to synchronize changes like available product quantities or subscription expiration and renewals.

Note

The Red Hat Subscription Manager tools are always run as root because of the nature of the changes to the system. However, Red Hat Subscription Manager connects to the subscription service as a user account for the subscription service.
The Subscription Manager handles both registration and subscriptions for a system. The Subscription Manager is part of the firstboot process for configuring content and updates, but the system can be registered at any time through the Red Hat Subscription Manager UI or CLI. New subscriptions, new products, and updates can be viewed and applied to a system through the Red Hat Subscription Manager tools.
Red Hat Subscription Manager has two tools in its set, a UI-based client to manage the local machine and a CLI client for advanced users (which can be used to work with other applications or in scripting management tasks, like kickstarting machines.
These tools allow administrators to perform three major tasks directly related to managing subscriptions: registering machines, assigning (attaching) subscriptions to systems, and updating the certificates required for authentication. Some minor operations, like updating system facts, are available to help display and track what subscriptions are available.

2.1. Launching the Red Hat Subscription Manager UI

Red Hat Subscription Manager is listed as one of the administrative tools in the System > Administration menu in the top management bar.
Red Hat Subscription Manager Menu Option

Figure 1. Red Hat Subscription Manager Menu Option

Alternatively, the Red Hat Subscription Manager UI can be opened from the command line with a single command:
[root@server1 ~]# subscription-manager-gui
The Red Hat Subscription Manager UI has a single window with tabbed sections that offer quick views into the current state of the system, showing installed products, subscriptions for the system, and available subscriptions the system has access to. These tabs also allow administrators to manage subscriptions by subscribing and unsubscribing the system.
The Red Hat Subscription Manager has three tabs which manage products and subscriptions:
  • The My Subscriptions tab shows all of the current subscriptions that the system is subscribed to.
  • The All Available Subscriptions tab shows all of the subscriptions that are available to the system. The default displays only subscriptions that are compatible with the hardware, but these can be filtered to show any subscriptions which match the hardware, any subscriptions which match installed products, only subscriptions which do not overlap with a currently-attached subscription, or any subscription which matches a given string.
  • The My Installed Products tab shows the currently installed products on the system, along with their subscription status. This does not allow administrators to install software, only to view installed software.
Red Hat Subscription Manager Main Screen

Figure 2. Red Hat Subscription Manager Main Screen

2.2. Running the subscription-manager Command-Line Tool

Any of the operations that can be performed through the Red Hat Subscription Manager UI can also be performed by running the subscription-manager tool. This tool has the following format:
[root@server1 ~]# subscription-manager command [options]
Each command has its own set of options that are used with it. The subscription-manager help and manpage have more information.

Table 1. Frequently-Used subscription-manager Commands

Command Description
Operational Commands
register Registers or identifies a new system to the subscription service.
unregister Unregisters a machine, which strips its subscriptions and removes the machine from the subscription service.
attach Assigns a specific subscription to the machine.
remove Removes a specific subscription or all subscriptions from the machine.
redeem Autosubscribes a machine to a pre-specified subscription that was purchased from a vendor, based on its hardware and BIOS information.
import Manually installs a subscription certificate, rather than contacting the subscription service with a request and then receiving the certificate.
list Lists all of the subscriptions that are compatible with a machine, either subscriptions that are actually consumed by the machine or unused subscriptions that are available to the machine.
Configuration Commands
config Modifies a specified configuration parameter in the Red Hat Subscription Manager configuration file, /etc/rhsm/rhsm.conf. The parameters are passed in the form configuration_area.parameter="value".
service-level Sets the service-level preference for the system to use when selecting subscriptions in autoattach operations.
release Sets the operating system release version preference for the system to use when selecting subscriptions in autoattach operations.
refresh Pulls the latest subscription data from the server. Normally, the system polls the subscription server at a set interval (4 hours by default) to check for any changes in the available subscriptions. The refresh command checks with the subscription server immediately, outside the normal interval.
clean Removes all of the subscription and identity data from the local system, without affecting the consumer information in the subscription service. Any of the subscriptions consumed by the system are still consumed and are not available for other systems to use. The clean command is useful in cases where the local subscription information is corrupted or lost somehow, and the system will be reregistered using the register --consumerid=EXISTING_ID command.
Informative Commands
version Returns the version of the local Red Hat Subscription Manager client, the name of the subscription service the system is registered with, and the version of the subscription service.
identity Handles the identity certificate and registration ID for a system. This command can be used to return the current UUID or generate a new identity certificate.
facts Lists the system information, like the release version, number of CPUs, and other architecture information.
orgs, repos, environments Lists all of the configured organizations, environments, and content repositories that are available to the given user account or system. These commands are used to view information in a multi-org infrastructure. They are not used to configure the local machine or multi-org infrastructure.

3. Registering, Unregistering, and Reregistering a System

Software delivery, support, and other services for Red Hat products are managed through a subscription service. A subscription service, such as the Customer Portal or Subscription Asset Manager, tracks systems and the subscriptions attached to those systems.
A system is recognized to the subscription service by being registered with the service. A subscription is associated or attached to a system.
Systems can be registered with a subscription service during the firstboot process or as part of the kickstart setup (both described in the Installation Guide). Systems can also be registered after they have been configured or removed from the subscription service inventory (unregistered) if they will no longer be managed within that subscription system.

3.1. Registering from the GUI

  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. If the system is not already registered, then there will be a Register button at the top of the window in the top right corner of the My Installed Products tab.
  3. To identify which subscription server to use for registration, enter the hostname of the service. The default service is Customer Portal Subscription Management, with the hostname subscription.rhn.redhat.com. If a different subscription service, such as Subscription Asset Manager, was configured in step 1, then the hostname of the on-premise server is in the field.
    There are seveal different subscription services which use and recognize certificate-based subscriptions, and a system can be registered with any of them in firstboot:
    • Customer Portal Subscription Management, hosted services from Red Hat (the default)
    • Subscription Asset Manager, an on-premise subscription server which proxies content delivery back to the Customer Portal's services
    • Satellite 6, an on-premise service which handles both subscription services and content delivery
  4. Enter the user credentials for the given subscription service to log in.
    The user credentials to use depend on the subscription service. When registering with the Customer Portal, use the Red Hat Network credentials for the administrator or company account.
    However, for Subscription Asset Manager, the user account to use is created within the on-premise service and probably is not the same as the Customer Portal user account.
  5. Optionally, select the Manually assign subscriptions after registration checkbox.
    By default, the registration process automatically attaches the best-matched subscription to the system. This can be turned off so that the subscriptions can be selected manually, as in Section 4, “Attaching and Removing Subscriptions”.
  6. When registration begins, Subscription Manager scans for organizations and environments (sub-domains within the organization) to which to register the system.
    IT environments that use Customer Portal Subscription Management have only a single organization, so no further configuration is necessary. IT infrastructures that use an on-premise subscription service like Subscription Asset Manager might have multiple organizations configured, and those organizations may have multiple environments configured within them.
    If multiple organizations are detected, Subscription Manager prompts to select the one to join.
  7. With the default setting, subscriptions are automatically selected and attached to the system. Review and confirm the subscriptions to attach to the system.
    1. If prompted, select the service level to use for the discovered subscriptions.
    2. Subscription Manager lists the selected subscription. This subscription selection must be confirmed by clicking the Attach button for the wizard to complete.

3.2. Registering from the Command Line

The simplest way to register a machine is to pass the register command with the user account information required to authenticate to Customer Portal Subscription Management. When the system is successfully authenticated, it echoes back the newly-assigned system inventory ID and the user account name which registered it.
The register options are listed in Table 2, “register Options”.

Note

The default Red Hat Subscription Manager configuration registers with Customer Portal Subscription Management. To use an on-premise subscription management application, first configure the Subscription Manager client as in Section 3.3, “Registering with a Subscription Management Application”, and then run the register command.

Example 1. Registering a System to the Customer Portal

[root@server1 ~]# subscription-manager register --username admin-example --password secret

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

Example 2. Automatically Attaching While Registering

The register command has an option, --auto-attach, which allows the system to be registered to the subscription service and immediately attaches the subscription which best matches the system's architecture, in a single step.
[root@server1 ~]# subscription-manager register --username admin-example --password secret --auto-attach
This is the same behavior as when registering with the default settings in the Subscription Manager UI.

Table 2. register Options

Options Description Required
--username=name Gives the content server user account name. Required
--password=password Gives the password for the user account. Required
--serverurl=hostname Gives the hostname of the subscription service to use. The default is for Customer Portal Subscription Management, subscription.rhn.redhat.com. If this option is not used, the system is registered with Customer Portal Subscription Management. Required for Subscription Asset Manager
--baseurl=URL Gives the hostname of the content delivery server to use to receive updates. Both Customer Portal Subscription Management and Subscription Asset Manager use Red Hat's hosted content delivery services, with the URL https://cdn.redhat.com. Since Satellite 6 hosts its own content, the URL must be used for systems registered with Satellite 6. Required for Satellite 6
--org=name Gives the organization to which to join the system. Required, except for hosted environments
--environment=name Registers the system to an environment within an organization. Optional
--name=machine_name Sets the name of the system to register. This defaults to be the same as the hostname. Optional
--auto-attach Automatically attaches the best-matched compatible subscription. This is good for automated setup operations, since the system can be configured in a single step. Optional
--activationkey=key Attaches existing subscriptions as part of the registration process. The subscriptions are pre-assigned by a vendor or by a systems administrator using Subscription Asset Manager. Optional
--servicelevel=None|Standard|Premium Sets the service level to use for subscriptions on that machine. This is only used with the --auto-attach option. Optional
--release=NUMBER Sets the operating system minor release to use for subscriptions for the system. Products and updates are limited to that specific minor release version. This is used only used with the --auto-attach option. Optional
--force Registers the system even if it is already registered. Normally, any register operations will fail if the machine is already registered. Optional
--type=TYPE Sets what type of consumer is being registered. The default is system, which is applicable to both physical systems and virtual guests. Other types include hypervisor for virtual hosts, person, domain, rhui, and candlepin for some subscription management applications. Optional

3.3. Registering with a Subscription Management Application

By default, systems are registered with Customer Portal Subscription Management. The Red Hat Subscription Manager configuration must be updated to identify the alternate subscription service, and then the system can be registered as normal. This configuration can be updated manually or it can be automatically configured through a special RPM which is available with Subscription Asset Manager.
The simplest way to register a system with a subscription management application:
  1. Subscription Asset Manager has an RPM which contains the required certificate and automatically updates the server configuration. Installing the RPM of the Subscription Asset Manager configuration from the Subscription Asset Manager server is the simplest way to create the proper configuration.
    For example:
    [root@server ~]# rpm -ivh http://sam.example.com/pub/candlepin-cert-consumer-latest.noarch.rpm

3.4. Registering with an Activation Key

An on-premise Subscription Asset Manager 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.

3.4.1. Using Activation Keys from the GUI

Activation keys for Subscription Asset Manager are configured before the system is ever created or added to the inventory, and the activation keys are passed as part of registering the system.
  1. Install the configuration RPM or manually configure Red Hat Subscription Manager to point to the subscription application, as in Section 3.3, “Registering with a Subscription Management 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. Check the I will use an Activation Key checkbox and click the Next button.
  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 Subscription Asset Manager.
  5. Click the Register button.
After the registration completes, all of the pre-configured subscriptions are attached to the system.

3.4.2. Using Activation Keys from the Command Line

Activation keys for Subscription Asset Manager are configured before the system is ever created or added to the inventory, and the activation keys are passed as part of registering the system.
  1. Install the configuration RPM or manually configure Red Hat Subscription Manager to point to the subscription application, as in Section 3.3, “Registering with a Subscription Management Application”. For example:
    [root@server ~]# rpm -ivh http://sam.example.com/pub/candlepin-cert-consumer-latest.noarch.rpm
  2. Then, 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
    If there are multiple organizations — or even if there is only a single organization but it is possible for there to be multiple ones — it is still necessary to specify the organization for the system. That information is not defined in the activation key.

3.5. Registering an Offline System

Some systems may not have Internet connectivity, but administrators still want to attach and track the subscriptions for that system. This can be done by manually registering the system, rather than depending on Subscription Manager to perform the registration. This has two major steps, first to create an entry on the subscriptions service and then to configure the system.
  1. Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscriptions area.
  2. In the Utilization area, click the Register a system link to create the new inventory entry.
  3. Fill in the architecture and hardware information for the system, along with other required information.
    • The name for the entry, which is normally the hostname.
    • The system type, physical or virtual.
    • The architecture, which is used to determine compatible subscriptions.
    • The number of sockets, either the number of physical sockets or, for virtual machines, the number of CPUs. Some subscriptions apply to a certain number of sockets, and multiple subscriptions may be required to cover larger systems.
  4. Once the system is created, attach the appropriate subscriptions to that system.
    1. Open the Available Subscriptions tab.
    2. Click the checkboxes by all of the subscriptions to attach, and then click the Add Selected button.
  5. Once the subscriptions are added, open the My Subscriptions tab.
  6. 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 some kind of portable media, like a flash drive.
  7. Copy the subscription certificates from the media device over to the system.
  8. If all subscription certificates were downloaded in an archive file, then there are multiple archives in the downloaded certificates.zip file. Unzip the directories until the PEM files for the subscription certificates are available.
  9. Import the subscription certificates. This can be done using the Import Certificates item in the System menu or using the import command. For example:
    # 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
  10. Optionally, disable the automatic Red Hat repository.
    When a system is registered, Subscription Manager automatically creates a redhat.repo file to access hosted repositories. For disconnected systems, it may be preferable to disable this repository. This is described in Section 6.3, “Disabling the Subscription Manager Repository”.

Important

The logic that processes whether a product on a system has a valid subscription attached is performed on the subscription server, not the local client. This means that even if all products have the proper subscriptions attached an offline system will always show an unknown subscription status.
To connect the system to a subscription server and update the subscription status (meaning, moving the system from an offline system to an online system), download the identity certificate from the system entry in Customer Portal Subscription Management, and extract the cert.pem and key.pem files into the /etc/pki/consumer directory.

3.6. Setting up Virtual Hosts for Registration

Red Hat Enterprise Linux has an optional service available`which can automatically detect guests on a virtual host system and register them as virtual systems. This allows subscriptions which are specific to virtual systems to be available to the guest and for subscriptions which are inherited from the host to be applied to the guest.

3.6.1. Supported Hypervisors

The virt-who process can detect and associate guests on several hypervisors:
  • Red Hat Enterprise Virtualization Manager (KVM)
  • HyperV
  • VMware ESX

3.6.2. About Host/Guest Associations

Subscription relationships have a lot of potential flexibility. Some subscriptions can be applied to a physical machine or to a certain number of virtual machines, while others can be applied to a physical host and then inherited by guests.
For subscriptions to be managed effectively — particularly with inheritable subscriptions or interactions between subscriptions — there has to be an internal awareness in the subscription service of the relationships between hosts and guests. This is a host/guest mapping, which is literally a list of all of the guest identifiers for a given hypervisor.
Hypervisors are registered as a special type of consumer in Subscription Asset Manager or Customer Portal Subscription Management. Hypervisors themselves are managed as regular physical systems, but the hypervisor type indicates that that particular system will have guests mapped to it, and that subscriptions may be inheritable or applied differently to those guests.
With a host/guest mapping to associate every guest with a specific host, a subscription service can properly attach a single subscription to a virtual host and then apply an included and inheritable subscription to its guest (for example), rather than consuming two separate subscriptions for each instance.
This association is done by extracting a universally unique identifier for each guest and associating it with its hypervisor. These UUIDs are part of the system facts for each virtual system.
The hypervisor is registered first, and then a related process on the system scans for any guests and submits the discovered UUIDs to the subscription service. This is done by the virt-who process on the hypervisor.
There are three factors that must be true for the subscription service to recognize the host/guest association and properly attach subscriptions:
  • The appropriate virtual detection process must be run periodically to detect new guest instances.
  • The hypervisor and the guest systems must be registered to the same subscription service.
  • The hypervisor must have a subscription attached to it that includes virtual subscriptions or inheritable subscriptions.

3.6.3. Setting up a KVM Hypervisor

  1. Then register the hypervisor and attach any required subscriptions.
    [root@rhel-server ~]# subscription-manager register --type=hypervisor --username=admin --password=secret --org="ACME_Corp" --auto-attach
  2. Install the virt-who packages.
    [root@server ~]# yum install virt-who
  3. Start the virt-who service.
    [root@server ~]# service virt-who start
  4. Create and register virtual machines as normal.

3.6.4. Setting up a VMware Hypervisor

Note

The virt-who packages that create the host/guest mapping are available for Red Hat Enterprise Linux. In a VMware environment, there must be a Red Hat Enterprise Linux system available to run the virt-who process which connects to the VMware hypervisor.
  1. Register the Red Hat Enterprise Linux host which connects to the VMware vCenter server.
    [root@server ~]# subscription-manager register --username=admin@example.com --password=secret --org=1234-56789 --auto-attach
    If the subscription service is a Subscription Asset Manager instance, the organization ID is available in the Subscription Asset Manager UI or in the Portal entry for the organization. If another system is already registered to that organization, then the ID is available using the subscription-manager orgs command.
    By default, the hypervisor name is esx hypervisor UUID. This name can be changed in the Subscription Asset Manager UI by editing the system entry.
  2. Install the virt-who packages on the Red Hat Enterprise Linux system.
    [root@server ~]# yum install virt-who
  3. Open the virt-who configuration file (/etc/sysconfig/virt-who) and set up the required information for the subscription services.
    1. Enable ESX mode, and set the environment to Library:
      VIRTWHO_ESX=1
      VIRTWHO_ESX_ENV=Library
    2. Specify the owner of the subscriptions. This must be the ID of an organization. For example:
      VIRTWHO_ESX_OWNER=6340056
      The organization ID should be available in the Portal entry for the organization if there are multiple organizations. If it was registered with the Portal (which has a single organization) or if another system is already registered to that organization, then the ID is available using the subscription-manager orgs command.
    3. Set the hostname or IP address of the vCenter server:
      VIRTWHO_ESX_SERVER=vcenter.example.com
    4. Specify the username and password to use when connecting to the vCenter server:
      VIRTWHO_ESX_USERNAME=admin
      VIRTWHO_ESX_PASSWORD=secret
    5. Save the changes to the configuration file.
  4. Start the virt-who service; this begins gathering all of the host/guest data.
    [root@vmware-server ~]# service virt-who start
    The data are added to the /var/lib/virt-who/hypervisor-systemid-UUID file.
  5. Use chkconfig to configure the virt-who service so that it starts automatically when the system starts.
    [root@vmware-server ~]# chkconfig virt-who on

3.6.5. Registering Guest Instances

Register a virtual system the same as a physical system, using the same subscription service and organization as the host.
[root@virt-server ~]# subscription-manager register --username=admin --password=secret --org="ACME_Corp" --auto-attach

Note

The virt-who process must be running on the virtual host or on a hypervisor in the environment (for VMware) to ensure that virt-who process maps the guest to a physical host, so the system is properly registered as a virtual system. Otherwise, the virtual instance will be treated as a physical instance.

3.6.6. Creating a Data Center

There is a specific subscription available for data centers which registers a physical system as a hypervisor and then allows an unlimited number of virtual guests to be installed and registered on that system. That physical system can be a Red Hat Enterprise Linux system running RHEV, or it can be a non-Linux system, running VMware or HyperV. The configuration does not matter; as with running any virtualized environment, there simply must be one Red Hat Enterprise Linux system to run the virt-who process to create the host/guest mapping.
For each physical host in the environment:
  1. Attach the data center subsription to the hypervisor entry. The name of the subscription is Red Hat Enterprise Linux for Virtual Datacenters ... System:Physical.
  2. Register all guests for that host/hypervisor, as described in Section 3.6.5, “Registering Guest Instances”.

Note

If a virtual instance is migrated from one hypervisor to another, the Red Hat Enterprise Linux subscription is preserved, but any subscriptions for additional products, such as JBoss Enterprise Application Platform, must be released and then re-attached.

3.7. Unregistering

The only thing required to unregister a machine is to run the unregister command. This removes the system's entry from the subscription service, removes any subscriptions, and, locally, deletes its identity and subscription certificates.
From the command line, this requires only the unregister command.

Example 3. Unregistering a System

[root@server1 ~]# subscription-manager unregister
To unregister from the Subscription Manager GUI:
  1. Open the Subscription Manager UI.
    [root@server ~]# subscription-manager-gui
  2. Open the System menu, and select the Unregister item.
  3. Confirm that the system should be unregistered.

3.8. Restoring a Registration

There are times when the local registration and subscription information could be lost or corrupted. There could be a hardware failure or system crash. Or other IT considerations may require that a system be moved to a different machine. Whatever the reason, the local subscription configuration is lost.
A system can be registered against an existing system entry in the Red Hat subscription service, which essentially restores or reregisters that system. The reregister operation uses the original system ID with the registration request, so that all of the previous subscriptions associated with the system entry are restored along with the registration.
Reregistering a system uses the register command. This command passes the original UUID for a system to issue a request to the subscription service to receive a new certificate using the same UUID. This essentially renews its previous registration.

Example 4. Registering a System with an Existing Identity Certificate

The register command uses the original ID to identify itself to the subscription service and restore its previous subscriptions.
[root@server1 ~]# subscription-manager register --username admin-example --password secret --consumerid=7d133d55-876f-4f47-83eb-0ee931cb0a97

Table 3. register Options to Reregister the System

Options Description
--consumerid Gives the system UUID used by an existing system. The system's entry must exist in the Red Hat subscription service for the reregister operation to succeed.
--username=name Gives the content server user account name.
--password=password Gives the password for the user account.

4. Attaching and Removing Subscriptions

Assigning a subscription to a system gives the system the ability to install and update any Red Hat product in that subscription. A subscription is a list of all of the products, in all variations, that were purchased at one time, and it defines both the products and the number of times that subscription can be used. When one of those licenses is associated with a system, that subscription is attached to the system.

4.1. About Subscriptions

When a product is purchased from Red Hat, the resulting subscription contains all the details around that purchase, not just the product name:
  • All included products
  • Support levels for the products
  • The length of time that the subscription is valid
  • A contract number for the sale
  • The number of times that the subscription can be used
  • The content repositories for the products
Subscription Details

Figure 3. Subscription Details

All of that information is used to maintain the subscriptions across the infrastructure.

4.1.1. Pools and Available Subscriptions

When a product is purchased, its subscription defines a quantity, the number of times that the subscription can be used. That set of subscriptions is the pool. A product has a general ID that is universal. A pool has a specific ID that is only true for that specific subscription. A pool ID essentially relates a product to the subscription through which it was purchased.
[root@server1 ~]# subscription-manager list --available

+-------------------------------------------+
    Available Subscriptions
+-------------------------------------------+
ProductName:            RHEL for Physical Servers
ProductId:              MKT-rhel-server
PoolId: ff8080812bc382e3012bc3845ca000cb
Quantity:               10
Expires:                2013-09-20

4.1.2. About Relationships Between Subscriptions and Systems

4.1.2.1. Interactions with Subscriptions, Products, and Systems
Products on a system have relationships, dependencies, and conflicts between each other. Likewise, subscriptions have relationships that parallel the relationships of the software it represents. Some subscriptions allow virtual guests, some require other subscriptions, some conflict with other subscriptions.
Subscription define the relationships between installed products and each other and the systems on which those products are installed. Likewise, subscriptions can also define relationships between systems and how they interact within an environment. This is particularly apparent with virtual environments, where subscriptions can define different relationships for physical hosts and virtual guests, but there are other ways that systems can interact, such as data centers and cloud infrastructures. Subscriptions are a part of those meta relationships.
Using subscriptions to define these relationships introduces a lot of flexibility in how products and systems interact:
  • Associate a single quantity of a product with a single system (which is the most common relationship).
  • Restrict one product so that it cannot be installed on the same system as a specific, different product.
  • Keep a system on a consistent service level. Each subscription includes a definition for what service level (e.g., standard or premium) the product has. Subscription clients first try to assign subscriptions of the same service level (and this can be enforced) so that the system has consistent support levels.
  • Allow virtual guests to inherit some subscriptions from their host.
  • Allow some hosts to have unlimited guests for a data center deployment.
  • Allow a single “subscription” to be broken across multiple systems. This works in something like Red Hat Cloud Infrastructure, where a single purchase actually covers four products — Red Hat Enterprise Linux, Red Hat OpenStack, Red Hat Virtualization, and Satellite 6 — and those products each have their own subscription which can be used on different systems to create the stack.
  • Stack or combine subscriptions of the same type to cover a system.
4.1.2.2. Counting Subscriptions
Part of the subscription service inventory is keeping track of subscriptions – not just what subscriptions are purchased but how many of those subscriptions are available.
When a subscription is first purchased, it defines the quantity of times that the subscription can be used. The subscription count is based on a certain element of the underlying system, most commonly its socket count (but it can be something else, such as the number of cores, depending on the specific subscription). The element of a system or software which is directly covered by a subscription is called an instance.
For example, for the subscription for Red Hat Enterprise Linux for 2 sockets, the product is Red Hat Enterprise Linux and the attribute is a physical socket pair. The socket pair is the instance.
A single subscription quantity is usually tied to a single socket pair (or other attribute). A system with eight sockets, then, requires more subscription quantities to cover its socket count than a four socket system. (This is called stacking.)
This simplistic arrangement, however, does not apply to all subscriptions.
Starting in October 2013, Red Hat began introducing other types of subscription relationships, such as:
  • Multiple products with a single subscription (Red Hat Cloud Infrastructure)
  • Inheritable subscriptions
  • Data center subscriptions, which allow unlimited virtual guests (and only the host requires a specific subscription)
Additionally, the 2013 subscription changes altered how virtual guests are handled in subscriptions. There used to be subscriptions for physical systems and then different subscriptions for virtual guests. In the current subscription model, the same subscription is used for both physical and virtual systems – but the quantity used is different, depending on whether it is a physical system or a virtual one.
As stated previously, a single subscription quantity is used per socket pair on a physical system. A virtual guest counts as a single socket, not a socket pair – so it is essentially half of a subscription quantity. When virtual guests are added to the inventory, the total number of available subscriptions is multiplied by two (the instance multiplier). This allows the subscription count to stay in whole numbers, even with virtual guests taking only a “half” quantity.
However, with some subscriptions counts multiplied by two; data center virtual guests not consuming any individual subscriptions; some subscriptions (Cloud Infrastructure) relating to multiple products installed on different systems; and older, pre-2013-style subscriptions all in the same environment — the actual counts listed in the subscription utilization pages or subscription management tools may not appear to reflect the quantities purchased in the contract. The fundamental counts are the same; most of the differences reflect changes to keep the count whole or new, more flexible subscription types.

4.1.3. Validity and Expiration

When a subscription is purchased, it is valid for a specified amount of time. This is its validity period.
As a subscription reaches the end of its validity period (or if it is canceled), the rhsmcertd process tracks it. The subscription process then creates a system notification, using a message as it nears expiration and a warning after it expires.
When a system uses multiple subscriptions to cover a single product, then the product is considered covered until the earliest expiration of one of its subscriptions.
Validity periods are crucial for system maintenance, compliance tracking, and purchasing.
Enabling autoattaching on a system allows it to upadte its subscriptions automatically, so the system is always in a valid state as long as any subscription is available. This is covered more in Section 5.2, “Managing Subscription Expiration and Notifications”.

4.2. Manually Attaching and Removing Subscriptions through the GUI

4.2.1. Attaching a Subscription

  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. Open the All Available Subscriptions tab.
  3. Optionally, set the date range and click the Filters button to set the filters to use to search for available subscriptions.
    Subscriptions can be filtered by their active date and by their name. The checkboxes provide more fine-grained filtering:
    • match my system shows only subscriptions which match the system architecture.
    • match my installed products shows subscriptions which work with currently installed products on the system.
    • have no overlap with existing subscriptions excludes subscriptions with duplicate products. If a subscription is already attached to the system for a specific product or if multiple subscriptions supply the same product, then the subscription service filters those subscriptions and shows only the best fit.
    • contain the text searches for strings, such as the product name, within the subscription or pool.
    After setting the date and filters, click the Update button to apply them.
  4. Select one of the available subscriptions.
  5. Click the Attach button.

4.2.2. Removing Subscriptions

  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. Open the My Subscriptions tab.
    All of the active subscriptions to which the system is currently attached are listed. (The products available through the subscription may or may not be installed.)
  3. Select the subscription to remove.
  4. Click the Remove button in the bottom right of the window.

4.3. Manually Attaching and Removing Subscriptions through the Command Line

4.3.1. Attaching Subscriptions

Attaching subscriptions to a system requires specifying the individual product or subscription to attach, using the --pool option.
[root@server1 ~]# subscription-manager attach --pool=XYZ01234567
The options for the attach command are listed in Table 4, “attach Options”.
The ID of the subscription pool for the purchased product must be specified. The pool ID is listed with the product subscription information, which is available from running the list command:
[root@server1 ~]# subscription-manager list --available

+-------------------------------------------+
    Available Subscriptions
+-------------------------------------------+
ProductName:            RHEL for Physical Servers
ProductId:              MKT-rhel-server
PoolId:                 ff8080812bc382e3012bc3845ca000cb
Quantity:               10
Expires:                2011-09-20
Alternatively,the best-fitting subscriptions, as identified by the subscription service, can be attached to the system by using the --auto option (which is analogous to the --auto-attach option with the register command).
[root@server1 ~]# subscription-manager attach --auto

Table 4. attach Options

Options Description Required
--pool=pool-id Gives the ID for the subscription to attach to the system. Required, unless --auto is used
--auto Automatically attaches the system to the best-match subscription or subscriptions. Optional
--quantity=number Attaches multiple counts of a subscription to the system. This is used to cover subscriptions that define a count limit, like using two 2-socket server subscriptions to cover a 4-socket machine. Optional
--servicelevel=None|Standard|Premium Sets the service level to use for subscriptions on that machine. This is only used with the --auto option. Optional

4.3.2. Removing Subscriptions from the Command Line

A system can be attached to multiple subscriptions and products. Similarly, a single subscription or all subscriptions can be removed from the system.
Running the remove command with the --all option removes every product subscription and subscription pool that is currently attached to the system.
[root@server1 ~]# subscription-manager remove --all
It is also possible to remove a single product subscription. Each product has an identifying certificate installed with it. The product subscription to remove is identified in the remove command by referencing the ID number of that certificate.
  1. Get the serial number for the product certificate, if you are removing a single product subscription. The serial number can be obtained from the subscription#.pem file (for example, 392729555585697907.pem) or by using the list command. For example:
    [root@server1 ~]# subscription-manager list --consumed
    
    +-------------------------------------------+
        Consumed Product Subscriptions
    +-------------------------------------------+
    
    
    ProductName:         High availability (cluster suite)
    ContractNumber:      0
    SerialNumber:        11287514358600162
    Active:              True
    Begins:              2010-09-18
    Expires:             2011-11-18
  2. Run the subscription-manager tool with the --serial option to specify the certificate. To remove multiple subscriptions, use the --serial option multiple times.
    [root@server1 ~]# subscription-manager remove --serial=11287514358600162

4.4. Stacking Subscriptions

Subscriptions define an element or attribute that it covers for that product. For a layered product such as Red Hat Directory Server, this may be a single instance of the application or server. The attribute could also be based on the physical characteristics of the system, such as a socket pair. Whatever the counted element is, is an instance.
Whatever the element is, there must be a subscription for every occurance of the element. For example, Red Hat Enterprise Linux subscriptions commonly cover a socket pair. If there are four sockets on a system, then the system requires two subscriptions — one for each socket pair.
Most subscriptions can be combined or stacked to cover each instance. There are some rules on what subscriptions can be combined:
  • Subscriptions can be combined by using multiple quantities from the same subscription set.
  • Subscriptions from different contracts can be combined together as long as they are compatible (e.g., for the same architecture and the same type of instance).
  • Only the same product subscription can be combined. RHEL Server for 2-Sockets can be stacked with another RHEL Server for 2-Sockets subscription, but not with RHEL Server for Virtualization, even if they both cover the socket count.
  • Only the subscriptions with the same service level can be stacked. For example, if the first subscription attached to a system has a premium service level, then it can only be stacked with other subscriptions with a premium service level.
To combine subscriptions in the Subscription Manager UI, simply set the Quantity field to the required quantity to cover the count.
Stacking Quantities

Figure 4. Stacking Quantities

Example 5. Stacking in the Command Line

To combine subscriptions from the command line, use the --quantity option. The quantity taken applies to the product in the --pool option:
[root@server1 ~]# subscription-manager attach --pool=XYZ01234567 --quantity=2
One important thing in stacking is understanding how things are counted. There are two rules with counting subscriptions:
  • A socket pair requires a single subscription. (A single socket is still treated as a socket pair; likewise, an odd-number of sockets is treated as pairs.)
  • A virtual guest requires half a subscription.
The displayed quantities for subscriptions may be different than what is purchased because of the fact that a virtual guest is half of a subscription.
To make the subscription pool always come out in a whole number, the pool of available subscriptions is multiplied by two. If there are 15 Red Hat Enterprise Linux subscriptions purchased, than the displayed pool of available subscriptions is 30. This allows individual virtual machines to take a single subscription. This also means that it appears a physical system appears to use two subscriptions per socket pair.
Both the number of subscriptions total and the number of subscriptions consumed by both physical and virtual systems is fundamentally the same.

4.5. 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.
  1. Retrieve the certificate information for the system from the Customer Portal.
    1. Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Certificate-based Management area.
    2. In the summary of systems, click the name of the offline system.
    3. If necessary, attach the subscriptions to the system.
    4. Open the My Subscriptions tab.
    5. 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 some kind of portable media device, like a flash drive.
      To download individual subscription certificates, click the Download link on the row for the subscription.
  2. Copy the certificates over to the system machine.
  3. If all certificates were downloaded in an archive file, then there are multiple archives in the downloaded certificates.zip file. Unzip the directories until the PEM files for the subscription certificates are available.
  4. Import the certificates.
    This can be done from the command line using the import command:
    # 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
    This can also be performed through the Subscription Manager GUI:
    1. Launch Subscription Manager. For example:
      [root@server ~]# subscription-manager-gui
    2. Open the System menu, and select the Import Certificate item.
    3. Click the file folder icon at the right of the field to navigate to the .pem file of the product certificate.
    4. Click the Import Certificate button.
All of the uploaded subscriptions are attached to the system.

4.6. Autoattaching and Updating Subscriptions

Autoattaching is when subscriptions are selected and then attached to the system automatically by the subscription management application. The subscription management service selects the best-matched subscriptions based on a set of criteria like currently-installed products, architecture, and preferences like service level.
Autoattaching a system can be done as part of registration, it can be done after a certain amount of system configuration (to apply new subscriptions for additional products), or it can be enabled to occur periodically as part of managing subscription renewals.

4.6.1. Autoattaching at Registration

The register command has an option, --auto-attach, which allows the system to be registered to the subscription service and immediately attaches the subscriptions which best match the system's architecture, in a single step.
[root@server1 ~]# subscription-manager register --username admin-example --password secret --auto-attach

4.6.2. Autoattaching after Registration

The --auto option with the attach (which is analogous to the --auto-attach option with the register command) attaches the best-fitting subscriptions to the system based on it's currently installed products and other criteria.
[root@server1 ~]# subscription-manager attach --auto
Running this after registration may be useful if the system has add-on products like Cluster Suite or layered products like Red Hat Directory Server installed. Since these products are not installed by default, autoattaching at registration time may not apply the appropriate subscriptions to the machine. Autoattaching after they are installed can make it easier to attach the proper subscriptions, and it is a little easier since it is not necessary to find and select a pool ID.

4.6.3. Automatically Updating Subscriptions

The subscription daemon, rhsmcertd, monitors the subscriptions that are attached to a system and tracks when they near their expiration dates or if they are removed.
When a system has installed products without valid subscriptions, Red Hat Subscription Manager automatically attaches the best-matched subscriptions to cover the installed products on the system. This is the same process, conceptually, as autoattaching the system when registering a system, but this is all done without the administrator having to run a script. This process keeps the subscriptions updated even in a dynamic environment.
There are a couple of common scenarios where autoattaching is useful:
  • As new products are installed.
  • When subscriptions expire.
    Within 24 hours of when the subscription expires, the Subscription Manager automatically re-attaches subscriptions to the system.
  • When subscriptions are renewed.
  • When a subscription management application replaces its manifest.
    If a new manifest is uploaded (instead of refreshing the original manifest), the old manifest is delete. Any subscriptions attached to a system from the old manifest are automatically removed — which means that the system could have products that no longer have a subscription for them. Enabling autoattaching on a system means that the system can automatically request and apply subscriptions from the new manifest.
System autoattaching prevents a system from having products without a subscription as long as any active, compatible subscription is available for it.
Auto-attaching is enabled by default on systems to ensure that they maintain their subscription status. Auto-attaching can be disabled and re-enabled through the given subscription service (such as the Customer Portal or Subscription Asset Manager) and the local autoattaching check for rhsmcertd can be changed.

4.6.4. Setting Preferences for Systems

Autoattaching and updating subscriptions selects what subscriptions to attach to a system based on a variety of criteria, including current installed products, hardware, and architecture. It is possible to set two additional preferences for Subscription Manager to use:
  • Service levels for subscriptions
  • The operating system minor version (X.Y) to use
This is especially useful for healing, which runs daily to ensure that all installed products and current subscriptions remain active.
4.6.4.1. Setting Preferences in the UI
Both a service level preference and an operating system release version preference are set in the System Preferences dialog box in Subscription Manager.
  1. Open the Subscription Manager.
  2. Open the System menu.
  3. Select the System Preferences menu item.
  4. Select the desired service level agreement preference from the drop-down menu. Only service levels available to the Red Hat account, based on all of its active subscriptions, are listed.
  5. Select the operating system release preference in the Release version drop-down menu. The only versions listed are Red Hat Enterprise Linux versions for which the account has an active subscription.
  6. The preferences are saved and applied to future subscription operations when they are set. To close the dialog, click Close.
4.6.4.2. About Service-Level Preferences
Part of a subscription is recognizing the service level for a product on a given system. Setting a preferred service level for a system in Red Hat Subscription Manager means that Subscription Manager uses that preference as part of the criteria for automatically attaching subscriptions to the system the system, either when initially applying subscriptions or when healing subscriptions.
Red Hat service levels are defined in the contract; a summary of production support levels is available at https://access.redhat.com/support/offerings/production/sla.html.
The support, or service, information for each subscription is part of the subscription details. Two attributes are displayed, per subscription: its service level and its service type. The level defines how quickly support is guaranteed to respond to a case. The type defines the methods of communication; for production level support, this is always web and phone.
Service Level Information for a Subscription

Figure 5. Service Level Information for a Subscription

An account can have multiple levels of support available, even for the same product. The support level for a given system can be configured so that the appropriate level of support is available. A production system usually has a premium support level since it is a business critical system, while a development system may have standard support or be self-supported.

Note

By default, the highest available level of support is selected for the subscription and system.
4.6.4.3. Setting Service Levels Through the Command Line
Autoattaching a system sets the best match to the system based on its hardware and architecture, operating system, and installed products. There is an option, when autoattaching a system, to include service level in the process for selecting subscriptions. For example, a production system may prefer to have premium subscriptions over standard.
Setting a service level during registration or subscription does two things:
  • It selects subscriptions on a best match with the desired service level (and other criteria).
  • It sets the system preference to the specified service level.

Note

When a preference is set during registration, during subscription, or in the UI, this preference is applied both to current subscriptions and to renewals and healed subscriptions.
A general service level preference can be set using the service-level --set command.

Example 6. Setting a Service Level Preference

First, list the available service levels for the system, using the --list option with the service-level command.
[root@server ~]# subscription-manager service-level --list
+-------------------------------------------+
          Available Service Levels
+-------------------------------------------+
Standard
None
Premium
Self-Support
Then, set the desired level for the system.
[root@server ~]# subscription-manager service-level --set=self-support
Service level set to: self-support
The current setting for the local system is shown with the --show option:
[root#server ~]# subscription-manager service-level --show
Current service level: self-support
A service level preference can be defined when a subscription operation is being run (such as registering a system or attaching subscriptions after registration). This can be used to override a system preference. Both the register and attach commands have the --servicelevel option to set a preference for that action.

Example 7. Autoattaching Subscriptions with a Premium Service Level

[root#server ~]# subscription-manager attach --auto --servicelevel Premium
Service level set to: Premium
Installed Product Current Status:
ProductName:            RHEL 6 for Workstations
Status:                 Subscribed

Note

The --servicelevel option requires the --auto-attach option (for register) or --auto option (for attach). It cannot be used when attaching a specified pool or when importing a subscription.
4.6.4.4. Viewing Service Level Settings in the Command Line
A system can have multiple service levels available to it. An available level may not be the one that is actually in effect for the system or for a product on the system; it depends on the subscriptions themselves.
Service level information is viewed using the service-level command. This is an information command; it returns the current information about service levels for the system or the account, but it does not make any changes to the assigned service level.
To view available service levels for the system, use the --list option. Simply knowing what levels are available is helpful for setting preferences, autoattaching, or even purchasing subscriptions.
[root@server ~]# subscription-manager service-level --list
+-------------------------------------------+
          Available Service Levels
+-------------------------------------------+
Standard
None
Premium
Preferences for default service levels can be specified for an account and for a local system, and those two settings do not have to be the same.
The current setting for the local system is shown with the --show option:
[root#server ~]# subscription-manager service-level --show
Current service level: Premium
4.6.4.5. Setting a Preferred Operating System Release Version in the Command Line
Many IT environments have to be certified to meet a certain level of security or other criteria. In that case, major upgrades must be carefully planned and controlled — so administrators cannot simply run yum update and move from version to version.
Setting a release version preference limits the system access to content repositories associated with that operating system version instead of automatically using the newest or latest version repositories.
For example, if the preferred operating system version is 6.3, then 6.3 content repositories will be preferred for all installed products and attached subscriptions for the system, even as other repositories become available.
Only packages, updates, and errata for that specific version will be used for the system.

Example 8. Setting an Operating System Release During Registration

A preference for a release version can be set when the system is registered by using --release option with the register. This applies the release preference to any subscriptions selected and auto-attached to the system at registration time.
Setting a preference requires the --auto-attach option, because it is one of the criteria used to select subscriptions to auto-attach.
[root#server ~]# subscription-manager register --auto-attach --release=6.4 --username=admin@example.com...

Note

Unlike setting a service level preference, a release preference can only be used during registration or set as a preference. It cannot be specified with the attach command.

Example 9. Setting an Operating System Release Preference

The release command can display the available operating system releases, based on the available, purchased (not only attached) subscriptions for the account.
[root#server ~]# subscription-manager release --list
+-------------------------------------------+
          Available Releases
+-------------------------------------------+
6.2
6.3
The --set then sets the preference to one of the available release versions:
[root#server ~]# subscription-manager release --set=6.3
Release version set to: 6.3
4.6.4.6. Removing a Preference
To remove a preference through the command line, use the --unset with the appropriate command. For example, to unset a release version preference:
[root#server ~]# subscription-manager release --unset
Release version set to:
To remove or unset a preference in the UI:
  1. Open the Subscription Manager.
  2. Open the System menu.
  3. Select the System Preferences menu item.
  4. Set the service level or release version value to the blank line in the corresponding drop-down menu.
  5. Click Close.

4.7. Redeeming Vendor Subscriptions

Systems can be set up with pre-existing subscriptions already available to that system. For some systems which were purchased through third-party vendors, a subscription to Red Hat products is included with the purchase of the machine.
Red Hat Subscription Manager pulls information about the system hardware and the BIOS into the system facts to recognize the hardware vendor. If the vendor and BIOS information matches a certain configuration, then the subscription can be redeemed, which will allow subscriptions to be automatically attached to the system.

4.7.1. Redeeming Subscriptions through the GUI

Note

If the machine does not have any subscriptions to be redeemed, then the Redeem menu item is not there.
  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. If necessary, register the system, as described in Section 3.1, “Registering from the GUI”.
  3. Open the System menu in the top left of the window, and click the Redeem item.
  4. In the dialog window, enter the email address to send the notification to when the redemption is complete. Because the redemption process can take several minutes to contact the vendor and receive information about the pre-configured subscriptions, the notification message is sent through email rather than through the Subscription Manager dialog window.
  5. Click the Redeem button.
It can take up to ten minutes for the confirmation email to arrive.

4.7.2. Redeeming Subscriptions through the Command Line

Note

The machine must be registered first so that the subscription service can properly identify the system and its subscriptions.
The machine subscriptions are redeemed by running the redeem command, with an email address to send the redemption email to when the process is complete.
# subscription-manager redeem --email=jsmith@example.com

5. Viewing Subscription Usage Information and Notifications

5.1. Viewing Available and Used Subscriptions

To manage subscriptions, administrators need to know both what subscriptions are currently attached to a system and what subscriptions are available to the system.

5.1.1. Viewing Subscriptions in the GUI

Three tabs summarize each of the subscriptions and products for the specific machine: installed products (with subscriptions), attached subscriptions, and available subscriptions.
These summaries are always displayed in the Red Hat Subscription Manager UI.
Attached Subscriptions

The My Subscriptions tab shows all of the current subscriptions attached to the system.

My Subscriptions Tab

Figure 6. My Subscriptions Tab

Available Subscriptions

The All Available Subscriptions tab shows all of the subscriptions that are available to the system. The default displays only subscriptions that are compatible with the hardware, but these can be filtered to show subscriptions corresponding to other installed programs, only subscriptions that have not been installed, and subscriptions based on date.

All Available Subscriptions Tab

Figure 7. All Available Subscriptions Tab

The filters dynamically search for available subscriptions.
Filter and Date Area

Figure 8. Filter and Date Area

By default, the displayed subscriptions are filtered so that they are compatible with the system's recognized hardware, operating system version, and installed products. These filters can be changed to filter by other criteria:
  • match my system shows only subscriptions which match the system architecture.
  • match my installed products shows subscriptions which work with currently installed products on the system.
  • have no overlap with existing subscriptions excludes subscriptions with duplicate products. If a subscription is already attached to the system for a specific product or if multiple subscriptions supply the same product, then the subscription service filters those subscriptions and shows only the best fit.
  • contain the text searches for strings, such as the product name, within the subscription or pool.
Filters

Figure 9. Filters

My Installed Products

The My Installed Products tab shows the currently installed products on the system, along with their subscription status. This does not allow administrators to install software, only to view installed software.

My Installed Products Tab

Figure 10. My Installed Products Tab

5.1.2. Listing Subscriptions with the Command Line

As with the three tabs in the UI, there are several different ways to use the list command to display different areas of the subscriptions and products on the system.

Table 5. subscription-manager list Options

Option Description
--installed (or nothing) Lists all of the installed products on the system. If no option is given with list, it is the same as using the --installed argument.
--consumed Lists all of the subscriptions attached to the system.
--available [--all] Using --available alone lists all of the compatible, active subscriptions for the system. Using --available --all lists all options, even ones not compatible with the system.
--ondate=YYYY-MM-DD Shows subscriptions which are active and available on the specified date. This is only used with the --available option. If this is not used, then the command uses the current date.
--installed Lists all of the products that are installed on the system (and whether they have a subscription) and it lists all of the product subscriptions which are attached to the system (and whether those products are installed).
The list command shows all of the subscriptions that are currently attached to the system by using the --consumed option.
[root@server1 ~]# subscription-manager list --consumed

+-------------------------------------------+
    Consumed Product Subscriptions
+-------------------------------------------+


ProductName:        	Red Hat Enterprise Linux Server
ContractNumber:     	1458961
SerialNumber:       	171286550006020205
Active:             	True
Begins:             	2009-01-01
Expires:            	2011-12-31
The list command shows all of the subscriptions that are compatible with and available to the system using the --available option. To include every subscription the account has — both the ones that are compatible with the system and for other platforms — use the --all option with the --available. The --ondate option shows only subscriptions which are active on that date, based on their activation and expiry dates.
[root@server1 ~]# subscription-manager list --available --all

+-------------------------------------------+
    Available Subscriptions
+-------------------------------------------+


ProductName:            RHEL for Physical Servers
ProductId:              MKT-rhel-server
PoolId:                 ff8080812bc382e3012bc3845ca000cb
Quantity:               10
Expires:                2011-09-20


ProductName:            RHEL Workstation
ProductId:              MKT-rhel-workstation-mkt
PoolId:                 5e09a31f95885cc4
Quantity:               10
Expires:                2011-09-20

[snip]
The --installed option correlates the products that are actually installed on the system (and their subscription status) and the products which could be installed on the system based on the attached subscriptions (and whether those products are installed).
[root@server1 ~]# subscription-manager list --installed

+-------------------------------------------+
    Installed Product Status
+-------------------------------------------+
ProductName:         Red Hat Enterprise Linux 
Status:              Not Subscribed
Expires:
Subscription:
ContractNumber:
AccountNumber:


ProductName:         Load Balancer
Status:              Subscribed
Expires:             2012-02-20
Subscription:        54129829316535230
ContractNumber:      39
AccountNumber:       12331131231

5.1.3. Viewing Subscriptions Used in Both RHN Classic and Red Hat Subscription Management

Administrators need to have a sense of all of the subscriptions attached for their account, altogether, regardless of whether the system is managed in RHN Classic or Customer Portal Subscription Management. The Customer Portal provides a way of looking at the total attached subscriptions.
In the Subscriptions Overview page, the Subscription Utilization area at the top gives the current count for every active subscription for the entire account, and a total count of every used subscription, regardless of whether it is used in RHN Classic or Customer Portal Subscription Management. These numbers are updated whenever the subscription count changes in the subscription server.
Total Counts of Subscriptions for All Subscription Services

Figure 11. Total Counts of Subscriptions for All Subscription Services

Note

RHN Classic is intended to be used with legacy systems (Red Hat Enterprise Linux 6.0 or Red Hat Enterprise Linux 5.6 and earlier releases). It is strongly recommended that Red Hat Enterprise Linux 6.1/5.7 and later systems use Customer Portal Subscription Management, Subscription Asset Manager, or other certificate-based subscription management service.

5.2. Managing Subscription Expiration and Notifications

5.2.1. About Subscription Validity Ranges

Subscriptions are active for a certain period of time, called the validity period. When a subscription is purchased, the start and end dates for the contract are set.
On a system, there can be multiple subscriptions attached. Each product requires its own subscription. Additionally, some products may require multiple quantities of subscriptions for the product to be fully covered. For example, a 16 socket machine may require four 4-socket operating system subscriptions to cover the socket count.
The My Installed Software tab shows the subscription status for the entire system. It also shows a date; that is the first date that a product subscription goes from valid to invalid (meaning it expires).
Valid Until...

Figure 12. Valid Until...

For example, if you have a Load Balancer subscription that expires on April 17 and all other product subscriptions are valid until October 1, the Certificate Status summary show that the certificates are valid until April 17, the closest expiration date.
Subscriptions can string together in a queue. For example, you have a 4-socket system that uses two 2-socket subscriptions to cover the socket count. However, the system actually has three subscriptions attached to it:
  • 2-socket subscription A expires April 1, 2012.
  • 2-socket subscription B expires July 31, 2013.
  • 2-socket subscription C starts March 1, 2012 and expires April 1, 2014.
The system is valid through July 31, 2013, because Subscription C is already queued up to replace Subscription A when it expires.

5.2.2. About System Notifications

The Red Hat Subscription Manager provides a series of log and UI messages that indicate any changes to the valid certificates of any installed products for a system. In the Subscription Manager GUI, the status of the system subscriptions is color-coded, where green means all subscriptions are attached for all installed products, yellow means that some products may not have all of the required subscriptions attached but updates are still in effect, and red means that updates are disabled.
Color-Coded Status Views

Figure 13. Color-Coded Status Views

The command-line tools also indicate that status of the machine. The green, yellow, and red codes translate to text status messages of subscribed, partially subscribed, and expired/not subscribed, respectively.
[root@server ~]# subscription-manager list
+-------------------------------------------+
    Installed Product Status
+-------------------------------------------+

ProductName:            Red Hat Enterprise Linux Server
Status: Not Subscribed
Expires:                                         
SerialNumber:                                    
ContractNumber:                                  
AccountNumber:
Whenever there is a warning about subscription changes, a small icon appears in the top menu bar, similar to a fuel gauge.
Subscription Notification Icon

Figure 14. Subscription Notification Icon

As any installed product nears the expiration date of the subscription, the Subscription Manager daemon will issue a warning. A similar message is given when the system has products without a valid certificate, meaning either there is not subscription attached that covers that product or the product is installed past the expiration of the subscription. Clicking the Manage My Subscriptions... button in the subscription notification window opens the Red Hat Subscription Manager GUI to view and update subscriptions.
Subscription Warning Message

Figure 15. Subscription Warning Message

5.2.3. Responding to Subscription Status Changes

When the Subscription Manager UI opens, whether it was opened through a notification or just opened normally, there is an icon in the upper left corner that shows whether products lack a valid certificate. The easiest way to attach subscriptions which match invalidated products is to click the Auto-attach button.
Auto-attach Button

Figure 16. Auto-attach Button

5.3. Viewing Package Profiles for the Local System

A package profile is the list of installed packages on a system (regardless of its subscription status). Once a system is registered, then the rhsmcertd polls the system to determine what products are installed and forwards that information to the subscription service. The package list is an integral part of managing updates, system notifications, and errata notifications.

5.3.1. The Purpose and Use of Package Lists

Red Hat Subscription Manager maintains a local list of installed packages to track the subscription status of the system. The package profile contains some general information about each package in the list:
  • Package name
  • Package version
  • Epoch
  • Publisher
All of that information about currently installed packages is collected in a regular job by the rhsmcertd process and sent to the registering subscription service, along with the user login information.
The package list itself is handled slightly differently depending on how the sysem is registered.
  • For systems registered with Customer Portal Subscription Management through the local Subscription Manager, the package list is sent periodically to the Customer Portal Subscription Management hosted subscription services to check for updates.
    The package list is viewable in the Installed Products tab or by using the list --installed command.
  • For systems where their inventory entry was created in the Customer Portal (rather than using Subscription Manager), the package list is generated by the rhsmcertd process, sent to the subscription service along with the user login, and then stored.
    The package list is displayed on the system entry and used to generate errata notifications (although it is possible to opt out of the notifications themselves).

5.3.2. Viewing the Package Profile for a System

The package list is always visible locally in the My Installed Software tab of the UI or by using the list --installed command with the command-line tools.
The Subscription Manager daemon, rhsmcertd, checks the system periodically — once when it is first registered and then when it runs a refresh operation every four hours — to get the most current list of installed products. When the system is registered and then whenever there is a change to the package list, Subscription Manager sends an updated package profile to the subscription service.
The package profile is stored in a cache file in /var/lib/rhsm/packages/.
Having an updated package profile for a system helps the subscription service identify compatible subscriptions.

5.3.3. Stopping Package List Data Collection

A system can be registered in three main ways:
  • To Customer Portal Subscription Management through Red Hat Subscription Manager on the local system
  • To Customer Portal Subscription Management through the portal itself (as in Section 3.5, “Registering an Offline System”)
  • To an on-premise service such as Subscription Asset Manager
In all three cases, the registration process automatically begins creating and maintaining a package list for the given subscription service. Since package lists are a core aspect of subscription maintenance, this data collection cannot be suspended. If it is necessary to prevent data collection on the system, then remove the system from the subscription management service.
  • Unregister the system, as in Section 3.7, “Unregistering”.
  • Unregister the system and delete the entry from the portal.
    Since package lists for systems registered in the portal are also stored in the portal subscription database, the entire system entry must be deleted for the information to be removed.
  • Unregister the system from the on-premise subscription service, as in Section 3.7, “Unregistering”.

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.
[root@server1 ~]# subscription-manager repos --list
+----------------------------------------------------------+
     Entitled Repositories in /etc/yum.repos.d/redhat.repo
+----------------------------------------------------------+

RepoName:                    never-enabled-content
RepoId:                      never-enabled-content
RepoUrl:                     https://content.example.com/repos/optional
Enabled:                     0


RepoName:                    always-enabled-content
RepoId:                      always-enabled-content
RepoUrl:                     https://content.example.com/repos/dev
Enabled:                     1


RepoName:                    content
RepoId:                      content-label
RepoUrl:                     https://content.example.com/repos/prod
Enabled:                     1

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
    The optional and supplementary channels are named rhel-6-server-optional-rpms and rhel-6-server-supplementary, respectively.
  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
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 Section 6.2, “Enabling Supplementary and Optional Repositories” describes, 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.

7. Configuring Red Hat Subscription Manager

By default, Red Hat Subscription Manager (both GUI and CLI) talk to the subscription service and the Customer Portal for their subscription services and content delivery, respectively. Red Hat Subscription Manager can be configured to use different content servers or subscription services. Other aspects of the Red Hat Subscription Manager — like the locations to look for system and product certificates or the system information used by Red Hat Subscription Manager to identify compatible subscriptions — can also be customized to fit the network environment.

7.1. Red Hat Subscription Manager Configuration Files

The primary configuration file for Red Hat Subscription Manager, both the GUI and CLI tools, is the rhsm.conf configuration file. There are other support files that either influence the Red Hat Subscription Manager service or can help administrators better use the Subscription Manager.

7.1.1. All Files Used by Red Hat Subscription Manager

All of the files related to the configuration of Red Hat Subscription Manager are used by both the GUI and CLI; there is no separate configuration.

Table 6. Red Hat Subscription Manager Files and Directories

File or Directory Description
/etc/rhsm The primary Red Hat Subscription Manager configuration directory.
/etc/rhsm/rhsm.conf The Red Hat Subscription Manager configuration file. This is used by both the GUI and the CLI.
/etc/rhsm/facts Any user-defined JSON files that override or add system facts to determine subscription compatibility. Any facts files must end in .facts.
/var/lib/rhsm/cache/installed_products.json A master list of installed products, which is sent by Subscription Manager to a hosted content service, such as Subscription Asset Manager.
/var/lib/rhsm/facts/facts.json The default system facts filed, gathered by the Subscription Manager.
/var/lib/rhsm/packages/ The package profile cache (a list of installed products) which is gathered and periodically updated by the Subscription Manager.
/var/log/rhsm The Red Hat Subscription Manager log directory.
/var/log/rhsm/rhsm.log The log for the Red Hat Subscription Manager tools.
/var/log/rhsm/rhsmcertd.log The log for the Red Hat Subscription Manager daemon, rhsmcertd.
/etc/pki/consumer The directory which contains the identity certificates used by the system to identify itself to the subscription service.
/etc/pki/consumer/cert.pem The base-64 identity certificate file for the system.
/etc/pki/consumer/key.pem The base-64 identity key file for the system.
/etc/pki/entitlement The directory which contains the certificates for the available subscriptions.
/etc/pki/product/product_serial#.pem The product certificates for installed software products.
/var/run/subsys/rhsm Runtime files for Red Hat Subscription Manager
/etc/init.d/rhsmcertd The subscription certificate daemon.
/etc/cron.daily/rhsm-complianced and /usr/libexec/rhsm-complianced Files to run daily checks and notifications for subscription validity.
/etc/yum/pluginconf.d/rhsmplugin.conf The configuration file to include the Red Hat Subscription Manager plug-in in the yum configuration.
/usr/share/rhsm All of the Python and script files used by both Red Hat Subscription Manager tool to perform subscription tasks.
/usr/share/rhsm/gui All of the Python script and image files used to render the Red Hat Subscription Manager GUI.

7.1.2. About the rhsm.conf File

The main configuration file for the Subscription Manager is rhsm.conf. This file configures several important aspects of how Red Hat Subscription Manager interacts with both subscriptions and content services:
  • The subscription service connection information, including the server host and port
  • The content service to use, in the form of a web address
  • The location of all of the different certificates used by the subscription service, including CA certificates for SSL authentication, identity certificates for the system, and subscription and product certificates
The rhsm.conf file is divided into three sections. Two major sections define the subscription service ([server]) and content and product delivery ([rhsm]). The third section relates to the rhsmcertd daemon. Each assertion is a simple attribute= value pair. Any of the default values can be edited; all possible attributes are present and active in the default rhsm.conf file.

Example 10. Default rhsm.conf File

# Red Hat Subscription Manager Configuration File:

[server]
# Server hostname:
hostname = subscription.rhn.redhat.com

# Server prefix:
prefix = /subscription

# Server port:
port = 443

# Set to 1 to disable certificate validation:
insecure = 0

# Set the depth of certs which should be checked
# when validating a certificate
ssl_verify_depth = 3

# Server CA certificate location:
ca_cert_dir = /etc/rhsm/ca/

# an http proxy server to use
proxy_hostname =

# port for http proxy server
proxy_port = 

# user name for authenticating to an http proxy, if needed
proxy_user =

# password for basic http proxy auth, if needed
proxy_password =

[rhsm]
# Content base URL:
baseurl= https://cdn.redhat.com

# Default CA cert to use when generating yum repo configs:
repo_ca_cert = %(ca_cert_dir)sredhat-uep.pem

# Where the certificates should be stored
productCertDir = /etc/pki/product
entitlementCertDir = /etc/pki/entitlement
consumerCertDir = /etc/pki/consumer

# Manage generation of yum repositories for subscribed content:
manage_repos = 1

[rhsmcertd]
# Frequency of certificate refresh (in minutes):
certFrequency = 240
# Frequency of autoattach check (1440 min = 1 day):
autoattachFrequency = 1440

Table 7. rhsm.conf Parameters

Parameter Description Default Value
[server] Parameters
hostname Gives the IP address or fully-qualified domain name of the subscription service. subscription.rhn.redhat.com
prefix Gives the directory, in the URL, to use to connect to the subscription service. /subscription
port Gives the port to use to connect to the subscription service. 443
insecure Sets whether to use a secure (0) or insecure (1) connection for connections between the Subscription Manager clients and the subscription service. 0
ssl_verify_depth Sets how far back in the certificate chain to verify the certificate. 3
proxy_hostname Gives the hostname of the proxy server. This is required.
proxy_port Gives the port of the proxy server. This is required.
proxy_user Gives the user account to use to access the proxy server. This may not be required, depending on the proxy server configuration.
proxy_password Gives the password credentials to access the proxy server. This may not be required, depending on the proxy server configuration.
ca_cert_dir Gives the location for the CA certificate for the CA which issued the subscription service's certificates. This allows the client to identify and trust the subscription service for authentication for establishing an SSL connection. /etc/rhsm/ca
[rhsm] Parameters
baseurl Gives the full URL to access the content delivery system. https://cdn.redhat.com
repo_ca_cert Identifies the default CA certificate to use to set the yum repo configuration. %(ca_cert_dir)sredhat-uep.pem
productCertDir Sets the root directory where the product certificates are stored and can be accessed by Subscription Manager. /etc/pki/product
consumerCertDir Sets the directory where the identity certificate for the system is stored and can be accessed by Subscription Manager. /etc/pki/consumer
entitlementCertDir Sets the directory where the subscription certificates for the system are stored and can be accessed by Subscription Manager. Each subscription has its own subscription certificate. /etc/pki/entitlement
manage_repos Sets whether the system creates and uses a redhat.repo yum file. This can be 0 for off or 1 for on. 1
[rhsmcertd] Parameters
certFrequency Sets the interval, in minutes, to check and update subscription certificates used by Subscription Manager. 240
autoattachFrequency Sets the interval, in minutes, to check for change subscriptions and installed products and to attach subscriptions, as necessary, to maintain subscription status for all products. 1440

7.2. Starting and Stopping the Subscription Service

The Red Hat Subscription Manager daemon, rhsmcertd, runs as a service on the system. The daemon, by default, starts with the system, and it can be started, stopped, or checked with the service command.
service rhsmcertd status
rhsmcertd (pid 13084) is running...
Red Hat Enterprise Linux has a tool called chkconfig which manages the automatic startup and shutdown settings for each process on the server. When a system reboots, some services can be automatically restarted. chkconfig also defines startup settings for different run levels of the server.
The Red Hat Subscription Manager service, which runs routinely to check for changes in the subscriptions for an account, can be controlled by chkconfig. By default, the Red Hat Subscription Manager daemon, rhsmcertd, is configured to run at levels 3, 4, and 5, so that the service is started automatically when the server reboots.
The run level settings can be reset using chkconfig. For example, to enable run level 2:
chkconfig --level 2345 rhsmcertd on
To remove the rhsmcertd from the start list, change the run level settings off:
chkconfig --level 2345 rhsmcertd off
Red Hat Enterprise Linux also has a GUI console that can manage the service and chkconfig settings.
  1. In the main menu, select the System link and open the Administration submenu.
  2. Open the Services link.

    Note

    The system-config-services package must be installed for the Services wizard to be available.
  3. Scroll to the rhsmcertd item in the list of services on the left, and then edit the service as desired.

7.3. Checking the Red Hat Subscription Manager and Subscription Service Version

The version command returns the package versions for Red Hat Subscription Manager and its associated Python libraries.
If the system is not yet registered, then it returns only the package information. For example:
[root@server ~]# subscription-manager version
registered to: Unknown
server type: Unknown
subscription-manager: 1.1.2-1.el6
python-rhsm: 1.1.3-1.el6
If the system is yet registered, then the version command also returns information about the subscription service which the system is registered to.
[root@server ~]# subscription-manager version
registered to: subscription.rhn.redhat.com
server type: subscription management service
subscription-manager: 1.1.2-1.el6
python-rhsm: 1.1.3-1.el6

7.4. Using the config Command

subscription-manager has a subcommand that can change the rhsm.conf configuration file. Almost all of the connection information used by Subscription Manager to access the subscription server, content server, and any proxies is set in the configuration file, as well as general configuration parameters like the frequency Subscription Manager checks for subscription updates. There are major divisions in the rhsm.conf file, such as [server] which is used to configure the subscription server. When changing the Subscription Manager configuration, the settings are identified with the format section.parameter and then the new value. For example:
server.hostname=newsubscription.example.com
When changing the value for a parameter, the parameter is passed as an argument to the config command:
[root@server1 ~]# subscription-manager config --section.parameter=newValue
For example, to change the hostname of the subscription service:
[root@server1 ~]# subscription-manager config --server.hostname=subscription.example.com
All of the rhsm.conf file parameters are listed in Table 7, “rhsm.conf Parameters”. This is most commonly used to change connection settings:
  • server.hostname (subscription server)
  • server.proxy_hostname
  • server.proxy_port
  • server.proxy_user
  • server.proxy_password
  • rhsm.baseurl (content server)
  • rhsm.certFrequency
The config command also has a --remove option. This deletes the current value for the parameter without supplying a new parameter. A blank value tells Subscription Manager to use any default values that are set for that parameter rather than a user-defined value. For example:
[root@server1 ~]# subscription-manager config --remove=rhsm.certFrequency

You have removed the value in section rhsm for parameter certFrequency.
The default value for rhsm.certFrequency will now be used.
If a value does not have a default, then the command returns simply that the value has been removed:
[root@server1 ~]# subscription-manager config --remove=server.proxy_hostname

You have removed the value in section server for parameter proxy.
The default value for server.proxy_hostname will now be used.

7.5. Changing the Autoattaching Check Frequency

Subscription Manager can monitor all of the active subscriptions for a system. Along with passively warning that a subscription is close to expiration (Section 5.2, “Managing Subscription Expiration and Notifications”), Subscription Manager can be configured to re-attach the subscriptions, automatically and actively, as one nears its expiry. This is system autoattach.
System autoattach prevents a system from having products without an attached subscription as long as any valid subscription is available for it.
System autoattach is configured as part of the Subscription Manager daemon, rhsmcertd. This daemon checks the certificate validity dates daily. If a subscription is within 24 hours of expiring, then Subscription Manager will check for any available compatible subscriptions and automatically re-attaches subscriptions to the system, much like autoattaching during registration.

Note

Autoattaching cannot be disabled by changing the time interval. Setting the autoattachFrequency parameter to zero means that Subscription Manager simply uses the default time setting.
The rhsmcertd daemon can reset the autoattach frequency using the -i|--auto-attach-interval command-line argument. The --now option runs the certificate and autoattach checks immediately, rather than waiting for the next scheduled run.
[root@server ~]# rhsmcertd --auto-attach-interval=1440 --now

7.6. Using an HTTP Proxy

Some network environments may only allow external Internet access or access to content servers by going through an HTTP proxy.

7.6.1. Configuring an HTTP Proxy in the UI

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:
  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. Open the System menu, and select the Configure Proxy item.
  3. Check the ...Connect to Red Hat Network via an HTTP Proxy checkbox and enter the server location, in the format hostname:port.
  4. If the proxy requires a username/password to allow access, then also select the authentication checkbox and fill in the user credentials.
  5. The configuration is automatically applied, so when the proxy is configured, simply close the window.

7.6.2. Configuring HTTP Proxy in the CLI

The HTTP proxy settings can be configured in the rhsm.conf file; this is the same as configuring it in the Subscription Manager GUI. The proxy configuration is stored and used for every connection between the subscription service and the local system.
[root@server1 ~]# subscription-manager config --server.proxy_hostname=proxy.example.com --server.proxy_port=8080 --server.proxy_user=admin --server.proxy_password=secret
All the proxy parameters are described in Table 7, “rhsm.conf Parameters”. There are four parameters directly related to the HTTP proxy:
  • proxy_hostname for the IP address or fully-qualified domain name of the proxy server; this is required.

    Note

    Leaving the proxy_hostname argument blank means that no HTTP proxy is used.
  • proxy_port for the proxy server port.
  • proxy_user for the user account to connect to the proxy; this may not be required, depending on the proxy server's configuration.
  • proxy_password for the password for the user account to connect to the proxy; this may not be required, depending on the proxy server's configuration.

7.6.3. Passing HTTP Proxy Information with subscription-manager Commands

Rather than using a permanently-configured HTTP proxy, as the GUI does, HTTP proxy information can be passed with a command invocations. The arguments listed in Table 8, “Proxy Arguments” are available to every command used with subscription-manager.

Table 8. Proxy Arguments

Argument Description Required for a Proxy Connection?
--proxy Gives the proxy server to connect to, in the format hostname:port. Yes
--proxyuser Gives the username to use to authenticate. This is only required if user authentication is required. No
--proxypassword Gives the password to use with the user account. This is only required if user authentication is required. No
The proxy information can be passed with any subscription-manager operation. For example:
[root@server1 ~]# subscription-manager attach --pool=ff8080812bc382e3012bc3845ca000cb --proxy=proxy.example.com:8443 --proxyuser=jsmith --proxypassword=secret

7.7. Managing Secure Connections to the Subscription Server

Red Hat Subscription Manager assumes, by default, that the subscription clients connect to the subscription service using a secure (SSL) connection. This requires that the CA certificate of the subscription service be downloaded and available locally for the client and that the appropriate connections be configured.
For example:
[root@server1 ~]# subscription-manager config --server.insecure=1 --server.proxy_port=8080 --server.ca_cert_dir=/etc/rhsm/ca --server.port=443
All connection parameters are described in Table 7, “rhsm.conf Parameters”. There are three parameters directly related to the secure connection:
  • insecure to set whether to use a secure (0) or insecure (1) connection
  • ca_cert_dir for the directory location for the CA certificate for authentication and verification
  • port for the subscription service port; this should be an SSL port if a secure connection is required
There is also an optional parameter to set how far in a certificate chain to go to validate a certificate. By default, this is three, meaning the server validates three CAs back in the issuing chain.
ssl_verify_depth = 3

7.8. Checking Logs

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 the Subscription Manager GUI or CLI
  • rhsmcertd.log shows every time a new certificate is generated, which happens on a schedule defined by the certFrequency 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.

Example 11. rhsm.log Entry

2010-10-01 17:27:57,874 [INFO] _request() @connection.py:97 - status code: 200
2010-10-01 17:27:57,875 [INFO] perform() @certlib.py:132 - updated:
Total updates: 0
Found (local) serial# []
Expected (UEP) serial# []
Added (new)
  <NONE>
Deleted (rogue):
  <NONE>
Expired (not deleted):
  <NONE>
Expired (deleted):
  <NONE>
2010-10-01 17:27:57,878 [INFO] __init__() @connection.py:193 - Using certificate authentication: key = /etc/pki/consumer/key.pem, cert = /etc/pki/consumer/cert.pem, ca = /etc/pki/CA/candlepin.pem, insecure = True
2010-10-01 17:27:57,878 [INFO] __init__() @connection.py:196 - Connection Established: host: candlepin.example.com, port: 443, handler: /candlepin
The entries in the rhsmcertd.log file are much simpler. The log only records when the rhsmcertd daemon starts or stops and every time a certificate is updated.

Example 12. rhsmcertd.log Entry

Fri Oct  1 13:27:44 2010: started: interval = 240 minutes
Fri Oct  1 13:27:50 2010: certificates updated

7.9. Checking and Adding System Facts

Subscriptions are available to a system based on whether the software is compatible with the system's architecture. For example, there are different products and subscriptions for 32-bit and 64-bit platforms. Red Hat Subscription Manager determines compatibility by collecting a range of facts about the system's hardware and architecture and then comparing it with all available subscriptions.
The collected facts can be viewed, updated to acknowledge a hardware or configuration change, or overridden to force compatibility in the specified areas.
The system facts are very similar to the information in /etc/redhat-release or /etc/sysconfig. In both the Red Hat Subscription Manager GUI and CLI, the facts are represented as simple attribute: value pairs.

Note

Updating the facts resends the information about the system to the Red Hat subscription service so that it can update the list of subscriptions which match the system architecture. Updating the facts is a very good thing to do after hardware upgrades or other important system changes.

7.9.1. Checking Facts from the Red Hat Subscription Manager UI

  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. Open the System menu, and select the View Facts item.
  3. All of the current facts for the system are listed in the table, broken down into categories. Each category is in a closed list; to reveal all of the facts in that category, click the arrow by the category name.
    To update the facts, click the Update Facts button in the bottom right of the window.

7.9.2. Checking Facts with subscription-manager

To simply list the facts, run the facts command with the --list option.
[root@server1 ~]# subscription-manager facts --list

cpu.architecture: i686
cpu.core(s)_per_socket: 4
cpu.cpu(s): 4
cpu.cpu_family: 6
cpu.cpu_mhz: 2000.010
cpu.cpu_op-mode(s): 32-bit, 64-bit
cpu.cpu_socket(s): 1
cpu.l1d_cache: 32K
cpu.l1i_cache: 32K
cpu.l2_cache: 6144K
cpu.model: 23
cpu.stepping: 6
cpu.thread(s)_per_core: 1
cpu.vendor_id: GenuineIntel
cpu.virtualization: VT-x
distribution.id: Santiago
distribution.name: Red Hat Enterprise Linux Workstation
distribution.version: 6
dmi.baseboard.manufacturer: IBM
dmi.baseboard.product_name: Server Blade
... [snip] ...
To update the facts after a system change, use the --update option with the facts command.
[root@server1 ~]# subscription-manager facts --update

7.9.3. Overriding the Default System Facts

The system facts, as collected after registration, are cached in /var/lib/rhsm/facts/facts.json. The file is formatted in attribute: value pairs, in a comma-separated list.
{"fact1": "value1","fact2": "value2"}
The primary file is generated and maintained by the Subscription Manager service. However, these facts can be expanded by creating additional JSON facts files and dropping them in the /etc/rhsm/facts directory. These JSON files can override existing facts or even add custom facts to be used by the subscription service.

Example 13. Example Facts Override File

vim /etc/rhsm/facts/my-example.facts

{"uname.machine": "x86","kernel_version": "2.6.32","physical_location": "MTV colo rack 5"}

7.10. 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: jsmith@example.com
Password:
Identity certificate has been regenerated.

7.11. Getting 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. In the GUI (Section 7.9.1, “Checking Facts from the Red Hat Subscription Manager UI”), this is listed as one of the system facts, under the system category:
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

7.12. 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's 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.

7.12.1. Updating Subscription Certificates

  1. Open the Red Hat Customer Portal.
    https://access.redhat.com/
  2. Click the Subscriptions tab to open the subscriptions menu, and select the Registered Consumers option under Certificate-based Management.
  3. Click the system name in the list of systems.
  4. Open the Applied Subscriptions tab for the list of all active, attached subscriptions for the system.
  5. Click the Download All Certificates button above the list of all attached subscriptions for the system. If there is only one subscription, then click the Download button by the certificate.
    To retrieve an individual subscription certificate, click the Download link in the subscription row.
  6. If all subscription certificates were downloaded in an archive file, then there are multiple archives in the downloaded certificates.zip file. Unzip the directories until the PEM files for the subscription certificates are available.
  7. Import the certificate PEM file. This can be done by using the Import Certificates menu option in the System menu of the Subscription Manager UI or by using the import command:
    # 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

7.12.2. Updating Subscription Information

The refresh command updates all of the subscription information that is available to the system. This removes expired subscriptions and adds new subscriptions to the list. This does not attach any subscriptions to the system, but it does pull in the newest data for administrators to use.
[root@server1 ~]# subscription-manager refresh

7.13. Retrieving the System ID, Registration Tokens, and Other Information

Some pieces of information are used frequently when managing subscriptions using the subscription-manager script. Information like the system ID or subscription pool ID is pulled up and referenced automatically in the Red Hat Subscription Manager UI, but it has to be entered manually in the command line.
Table 9, “Locations and Descriptions of Subscription Data” lists common information that is used to manage subscriptions, the operations they are used in, and the places to find the data.

Table 9. Locations and Descriptions of Subscription Data

Information Description Operations Used In Find It In ...
System ID A unique identifier for each system that is registered to the subscription service. identity The simplest method is to use the identity command to return the current UUID.
[root@server1 ~]# subscription-manager identity
Current identity is: 63701087-f625-4519-8ab2-633bb50cb261
name: server-1.example.com
org name: 6340056
org id: 8a85f981302cbaf201302d89931e059a
The Subject CN element of the identity certificate for the system, /etc/pki/consumer/cert.pem. The UUID can also be returned by using openssl to pretty-print the certificate.
openssl x509 -text -in /etc/pki/consumer/cert.pem

Certificate:
... snip ...
Subject: CN=7d133d55 876f 4f47 83eb 0ee931cb0a97
Pool ID An identifier for a specific set of subscriptions. This set is created when subscriptions are purchased. Whenever a system needs to attach a subscription for a product, it references a pool ID to identify which purchased set of subscriptions to use. attach The PoolID value given for a product when listing available subscriptions. For example:
[root@server1 ~]# subscription-manager list --available
+----------------------+
Available Subscriptions
+----------------------+
ProductName: Red Hat Enterprise Linux, Standard (up to 2 sockets) 3 year
ProductId: MCT0346F3
PoolId: ff8080812bc382e3012bc3845ca000cb
Quantity: 2
Expires: 2011-02-28
Product certificate serial number The identification used for a specific, installed product. A certificate with a unique serial number is generated when a product is installed; this serial number is used to identify that specific product installation when managing subscriptions. remove The SerialNumber line in the product subscription information. This can be returned by running list --consumed.
[root@server1 ~]# subscription-manager list --consumed

+-----------------------------+
Consumed Product Subscriptions
+-----------------------------+

ProductName: High availability (cluster suite)
ContractNumber: 0
SerialNumber: 11287514358600162
....
Product ID The internal identifier used to identify a type of product. The ProductID value given for a product when listing available subscriptions. For example:
[root@server1 ~]# subscription-manager list --available
+----------------------+
Available Subscriptions
+----------------------+

ProductName: RHEL for Physical Servers
ProductId: MKT-rhel-server
... snip ...

8. 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:
-----BEGIN CERTIFICATE-----
MIIDaTCCAtKgAwIBAgICBZYwDQYJKoZIhvcNAQEFBQAwSzEqMCgGA1UEAxMhY2Fu
ZGxlcGluMS5kZXZsYWIucGh4MS5yZWRoYXQuY29tMQswCQYDVQQGEwJVUzEQMA4G
A1UEBxMHUmFsZWlnaDAeFw0xMDEwMDYxNjMyMDVaFw0xMTEwMDYyMzU5NTlaMC8x
LTArBgNVBAMMJDQ4ODFiZDJmLTg2OGItNDM4Yy1hZjk2LThiMWQyODNkYWZmYzCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKNyLw6+IMtjY03F7Otxj2GL
GTz5VKx1kfWY7q4OD4w+XlBHTkt+2tQV9S+4TFkUZ7XoI80LDL/BONpy/gq5c5cw
yKvjv2gjSS/pihgYNXc5zUOIfSj1vb3fHGHOkzdCcZMyWq1z0N/zaLClp/zP/pcM
og4NTAg2niNPjFYvkQ+oIl16WmQpefM0y0SY7N7oJd2T8dZjOiuLV2cVZLfwjrwG
9UpkT2J03g+n1ZA9q95ibLD5NVOdTy9+2lfRhdDViZaVoFiQXvg86qBHQ0ieENuF
a6bCvGgpTxcBuVXmsnl2+9dnMiwoDqPZp1HB6G2uNmyNe/IvkTOPFJ/ZVbtBTYUC
AwEAAaOB8zCB8DARBglghkgBhvhCAQEEBAMCBaAwCwYDVR0PBAQDAgSwMHsGA1Ud
IwR0MHKAFGiY1N2UtulxcMFy0j6gQGLTyo6CoU+kTTBLMSowKAYDVQQDEyFjYW5k
bGVwaW4xLmRldmxhYi5waHgxLnJlZGhhdC5jb20xCzAJBgNVBAYTAlVTMRAwDgYD
VQQHEwdSYWxlaWdoggkA1s54sVacN0EwHQYDVR0OBBYEFGbB5fqOzh32g4Wqrwhc
/96IupIgMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdEQQWMBSkEjAQMQ4wDAYD
VQQDDAV4ZW9wczANBgkqhkiG9w0BAQUFAAOBgQANxHRsev4fYfnHO9kYcHo4UeK7
owN+fq92gl76iRHRnhzkPlhWL+uV2tyqGG9zJASOX+qEDOqN5sVAB4iNQTDGiUbK
z757igD2hsQ4ewv9Vq3QtnajWnfdaUZH919GgWs09Etg6ucsKwgfx1fqjSRLBbOo
lZuvBTYROOX6W2vKXw==
-----END CERTIFICATE-----
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 Deployment Guide.

8.1. Summary of Certificates Used by Subscription Services

Table 10. 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.

8.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 14. Identity Certificate

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1430 (0x596)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=subscription.server.example.com, C=US, L=Raleigh  
        Validity
            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)
                Modulus:
                    00:a3:72:2f:0e:be:20:cb:63:63:4d:c5:ec:eb:71:
                    8f:61:8b:19:3c:f9:54:ac:75:91:f5:98:ee:ae:0e:
                    0f:8c:3e:5e:50:47:4e:4b:7e:da:d4:15:f5:2f:b8:
                    4c:59:14:67:b5:e8:23:cd:0b:0c:bf:c1:38:da:72:
                    fe:0a:b9:73:97:30:c8:ab:e3:bf:68:23:49:2f:e9:
                    8a:18:18:35:77:39:cd:43:88:7d:28:f5:bd:bd:df:
                    1c:61:ce:93:37:42:71:93:32:5a:ad:73:d0:df:f3:
                    68:b0:a5:a7:fc:cf:fe:97:0c:a2:0e:0d:4c:08:36:
                    9e:23:4f:8c:56:2f:91:0f:a8:22:5d:7a:5a:64:29:
                    79:f3:34:cb:44:98:ec:de:e8:25:dd:93:f1:d6:63:
                    3a:2b:8b:57:67:15:64:b7:f0:8e:bc:06:f5:4a:64:
                    4f:62:74:de:0f:a7:d5:90:3d:ab:de:62:6c:b0:f9:
                    35:53:9d:4f:2f:7e:da:57:d1:85:d0:d5:89:96:95:
                    a0:58:90:5e:f8:3c:ea:a0:47:43:48:9e:10:db:85:
                    6b:a6:c2:bc:68:29:4f:17:01:b9:55:e6:b2:79:76:
                    fb:d7:67:32:2c:28:0e:a3:d9:a7:51:c1:e8:6d:ae:
                    36:6c:8d:7b:f2:2f:91:33:8f:14:9f:d9:55:bb:41:
                    4d:85
                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:
                keyid:68:98:D4:DD:94:B6:E9:71:70:C1:72:D2:3E:A0:40:62:D3:CA:8E:82
                DirName:/CN=subscription.server.example.com/C=US/L=Raleigh
                serial:D6:CE:78:B1:56:9C:37:41

            X509v3 Subject Key Identifier:
                66:C1:E5:FA:8E:CE:1D:F6:83:85:AA:AF:08:5C:FF:DE:88:BA:92:20
            X509v3 Extended Key Usage:
                TLS Web Client Authentication
            X509v3 Subject Alternative Name:  
                DirName:/CN=admin-example  
    Signature Algorithm: sha1WithRSAEncryption
        0d:c4:74:6c:7a:fe:1f:61:f9:c7:3b:d9:18:70:7a:38:51:e2:
        bb:a3:03:7e:7e:af:76:82:5e:fa:89:11:d1:9e:1c:e4:3e:58:
        56:2f:eb:95:da:dc:aa:18:6f:73:24:04:8e:5f:ea:84:0c:ea:
        8d:e6:c5:40:07:88:8d:41:30:c6:89:46:ca:cf:be:7b:8a:00:
        f6:86:c4:38:7b:0b:fd:56:ad:d0:b6:76:a3:5a:77:dd:69:46:
        47:f7:5f:46:81:6b:34:f4:4b:60:ea:e7:2c:2b:08:1f:c7:57:
        ea:8d:24:4b:05:b3:a8:95:9b:af:05:36:11:38:e5:fa:5b:6b:
        ca:5f

8.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.

Note

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.
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            3c:da:6c:06:90:7f:ff
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=candlepin.example.com, C=US, L=City
        Validity
            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:
1.3.6.1.4.1.2312.9.2.product_#.config_#:
   ..config_value
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.

Note

Every subscriptions-related extension begins with the OID base 1.3.6.1.4.1.2312.9. 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 15, “Annotated Red Hat Enterprise Linux High Availability Product Extensions in a Subscription Certificate”.

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

            content repository type  
            1.3.6.1.4.1.2312.9.2.30393.1:
                ..yum
            product  
            1.3.6.1.4.1.2312.9.2.30393.1.1:
                .HRed Hat Enterprise Linux High Availability (for RHEL Subscription) (RPMs)
            channel name  
            1.3.6.1.4.1.2312.9.2.30393.1.2:
                .Dred-hat-enterprise-linux-high-availability-for-rhel-entitlement-rpms
            vendor  
            1.3.6.1.4.1.2312.9.2.30393.1.5:
                ..Red Hat
            download URL  
            1.3.6.1.4.1.2312.9.2.30393.1.6:
                .Q/content/dist/rhel/entitlement/releases/$releasever/$basearch/highavailability/os
            key download URL  
            1.3.6.1.4.1.2312.9.2.30393.1.7:
                .2file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
            flex quantity  
            1.3.6.1.4.1.2312.9.2.30393.1.4:
                ..0
            quantity  
            1.3.6.1.4.1.2312.9.2.30393.1.3:
                ..25
            repo enabled setting  
            1.3.6.1.4.1.2312.9.2.30393.1.8:
                ..1

8.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.

8.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.

8.5.1. 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 11. 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

8.5.2. 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]

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.
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
+-------------------------------------------+

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

Subject:
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
+-------------------------------------------+

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

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

Product:
       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
+-------------------------------------------+

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

Subject:
       CN: 8a99f9843adc8b8f013ae5f9de022b73

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

Order:
      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
      Subscription:
      Stacking ID:
      Warning Period: 0
      Provides Management: 0

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

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

Important

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>
  <rhn-cert-signature>
-----BEGIN PGP SIGNATURE-----
Version: Crypt::OpenPGP 1.03

iQBGBAARAwAGBQJJ22C+AAoJEJ5ynaAAAAkyyZ0An18+4hK5Ozt4HWieFvahsTnF
aPcaAJ0e5neOfdDZRLOgDE+Tp/Im3Hc3Rg==
=gqP7
-----END PGP SIGNATURE-----
</rhn-cert-signature>
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"/>

9. Revision History

Revision History
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.

Legal Notice

Copyright © 2013 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.