Customer Portal Subscription Management

Red Hat Customer Portal 1

for managing subscriptions

Abstract

This guide provides a quick-start look into subscriptions and system management in the Red Hat Customer Portal.

Effective asset management requires a mechanism to handle the software inventory — both the type of products and the number of systems that the software is installed on. The subscription management service of Red Hat Network provides that mechanism and gives transparency into both global allocations of subscriptions for an entire account and specific subscriptions assigned to a single system.

This guide gives a quick view into using Customer Portal Subscription Management to manage your subscriptions and systems. For more information on the Red Hat Subscription Manager local tools and subscription concepts in general, see the Subscription Management Guide.

1. What We Mean by "Managing Subscriptions"

Many software companies base access to their products on licenses that are sold. At Red Hat, our software is already available under a GNU Public License v2, which allows general access to our source. Our products are available through subscriptions, which define services that we deliver (such as content delivery, updates, knowledgebase, and support levels) for these products. Our subscriptions are granted to individual servers and this entitles the server to receive support.

Red Hat Network Subscription Management establishes the relationship between the product subscriptions that you have available and the elements of your IT infrastructure where those subscriptions are allocated. Customer Portal Subscription Management is one means to manage systems in connection with subscriptions.

Figure 1. Customer Portal Subscription Management

An IT administrator has to know what products he has available, where these product subscriptions are assigned, and what systems are being managed. For this, Red Hat has a subscription management service through Red Hat Network Subscription Management, which is managed locally (an individual system) or globally (all servers in the environment) through Red Hat Subscription Manager. The ultimate goal of subscription management is to allow administrators to see where their products are allocated within their infrastructure. There are several reasons for this:

First, to make sure that all of the products on your systems have valid and active subscriptions, so administrators can maintain compliance with any regulatory requirements (like PCI-DSS or SAS-70) and internal mandates.
Next, to help with procuring the right number and type of software products for the infrastructure. Over-subscribing a system or purchasing too many subscriptions for what your environment actually uses can cost your business money. Tracking used and available subscriptions and managing expirations and renewals more effectively can possibly lower your IT budget.
Last, subscription management makes it easier for you to know what products your systems need to access and to make sure they are assigned the right subscriptions.

Customer Portal Subscription Management is the web version of Red Hat Subscription Manager. It provides an organization-wide method to track the software products and subscriptions deployed across an account, such as what systems are being managed, the effective contract dates for subscriptions, and where subscriptions are attached. Customer Portal Subscription Management helps give a view into subscriptions and products in the infrastructure — it does not limit installations or provide proactive enforcement of installations.

1.1. The Subscription Process

Subscription management is a way of identifying and creating relationships between the systems in your IT environment and the software products that you have available through Red Hat.

Subscription management is the way of defining a relationship between the subscriptions that a company has, its local machines, and the products installed on those machines:

An account buys a subscription to a product, which gives them access to Red Hat's Content Delivery Network, errata and patches, upgrades, and support.
A subscription defines a quantity, meaning the number of systems that are allowed to have access to the product and all its support services because of that subscription.
A server is added, or registered, to the inventory for the subscription management service. This means that the subscription service can manage the server and attach it subscriptions.
A subscription is attached to a system, so that the system is entitled to support services and content for that product.

Customer Portal Subscription Management allows administrators to add and remove units (managed systems, domains, and other entities) to the inventory, and to attach subscriptions to those units. Local Red Hat Subscription Manager tools are available on Red Hat Enterprise Linux systems to manage that specific system by registering it and attaching or removing subscriptions. (Since the GUI and subscription-manager are limited to the local machine, they cannot be used to manage other systems in the inventory.)

1.2. Hosted Services and On-Premise Subscription Management Applications

The simplest way to attach subscriptions and deliver content is for local systems to connect directly to Red Hat's hosted network.

However, for large environments, highly-secure environments, and many other situations, that hosted arrangement is not feasible. Companies need a way to attach subscriptions and deliver software content locally.

In that case, an organization entry with an on-premise subscription management application organization is added to the inventory in Customer Portal Subscription Management. A block of subscriptions attached to that organization. The list of attached subscriptions is defined in a manifest which outlines all of the subscriptions, products, and content repositories for that organization (and, therefore, for all of the systems it manages). The subscription management application then directly manages all of the systems and units at its local site.

This has performance benefits by lowering bandwidth, and it offers significant management benefits to administrators by allowing local and flexible control over subscription management.

1.3. Red Hat Network and RHN Classic

Some of the processes with subscription management may sound familiar, and there is a reason — subscriptions could be assigned to systems in previous releases of Red Hat Network. In RHN Classic, access to subscriptions was based on access to channels, or content delivery streams. Customer Portal Subscription Management manages subscriptions by looking at the available and installed products for a system. This treats both subscriptions and systems as individual entities, rather than opaque blocks defined by access to channels.

Customer Portal Subscription Management provides transparency both into what products are installed on a system (when using local Red Hat Subscription Manager tools) and what subscriptions are available to a system. This helps IT administrators to maintain software inventories and to plan their infrastructures in a way that wasn't possible under the traditional channel-based system.

Note

Customer Portal Subscription Management is certificate-based because each system is issued an X.509 certificate which identifies it to the subscription service and to the CDN (an identity certificate). When a new subscription is attached to a system, Customer Portal Subscription Management issues an X.509 entitlement certificate which contains the subscription information. When a product is installed, then Customer Portal Subscription Management issues an X.509 product certificate which identifies that unique product installation on that system.

Using certificates simplifies the process for managing individual subscriptions and products for a system while making the process more secure.

Customer Portal Subscription Management and RHN Classic are mutually exclusive. A system is either managed under one subscription management service or the other, not both, but these systems do "work together." If a system is registered with Customer Portal Subscription Management, then there won't be any errors registered in the legacy RHN Classic tools, and vice versa. Both services will recognize the subscriptions granted to the system.

1.4. Customer Portal Subscription Management and Access Control

Customer Portal Subscription Management is only available if a user has the appropriate user permissions on the Red Hat login. Otherwise, access to the Customer Portal Subscription Management area is restricted.

The user account must have the Customer Portal: Manage subscriptions permission. By default, all users are granted this permission, but it can be changed by administrators in the User Management area.

Figure 2. Subscription Management Permission

2. A Quick Reference of Subscription-Related Terms

system

Any entity — a physical or virtual machine — which is in the subscription service inventory and which can have subscriptions attached to it.

subcriptions

A subscription defines the products that are available, the support levels, the quantities (or number) of servers that the product can be installed on, architectures that the product is available for, content repositories which supply the product, and other information related to the products.

attach

Assigning a subscription to a system.

utilization

A summary of the total number of subscriptions available to an organization, and the total number of subscriptions that are attached to Customer Portal Subscription Management, RHN Classic, and different subscription management applications.

overusage

A state for an organization when they have more subscriptions attached than they have purchased. This can occur when infrastructures are using both Customer Portal Subscription Management and RHN Classic to register systems, since they draw from the same subscription pools but use separate tallies.

service level preference

A preference based on what service level to use for installed products.

release preference

A preference that restricts products and updates to a specific operating system minor release.

organization or subscription management application organization

A local subdivision that contains a subset of subscriptions. This is a way to define a subscription structure that reflects the IT environment. An organization can be aligned with a physical location or an organizational division in a company.

hosted

Subscription and content services provided by Red Hat, rather than an on-premise application.

available

A subscription which has quantities that have not been attached to a system yet.

Customer Portal Subscription Management

The hosted subscription management service. In this service, subscriptions are managed based on the product (and verified through issued certificates), rather than access to channels.

CDN

The Content Delivery Network.

channel

A collection of packages based around a software product, a group of related products, or a version of product. The channel-based way of defining subscriptions is used only by RHN Classic.

compatible

Available and active subscriptions which match the architecture of the system.

unit

Any entity — a physical or virtual machine, a domain, or a person — which is in the subscription management service inventory and which can have subscriptions attached to it.

content

Software downloads and updates.

Content Delivery Network (CDN)

The Red Hat-hosted content repositories and technology to deliver software, updates, and packages.

entitlement certificate

An X.509 certificate that contains a list of subscriptions for a system, including information about the products and quantities, content repositories, roles, and different namespaces.

identity certificate

An X.509 certificate which is issued to a system when the system is registered with the subscription management service. This certificate is used to authenticate and identify the system to the subscription management service.

inventory

A list of units (systems, domains, people, or applications) which have been registered to the subscription management service and a list of all subscriptions (current, expired, and future) which have been purchased by an organization.

license

A legal statement that defines how software can be used. Red Hat products are licensed under GPLv2. A subscription determines how many instances (quantities) or a product can be updated through Red Hat content streams and will be provided support but they do not restrict the ability to install or use software products.

product

The individual software product, like Red Hat Enterprise Linux or Directory Server.

product certificate

An X.509 certificate that is generated and installed on a system once a product is installed. This contains information about the specific system that the product is installed on (such as its hardware and architecture) and the product name, version, and namespace. This identifies that specific product installation to the subscription management service and CDN.

register (verb)

To add a system (physical or virtual) to the subscription management service inventory.

RHN Classic

The traditional RHN system. This will be available for a few years but is being phased out.

status

Whether all of the products installed on a system are fully covered with active subscriptions.

Subscription Manager

A set of tools used to view and attach subscriptions and to manage systems in the inventory. There are two Subscription Manager tools:

Subscription Manager GUI which is installed on the local system and manages that local system. It can be opened by running subscription-manager-gui or in the System => Administration menu.
Subscription Manager CLI which is also installed on the local system and manages that local system. Different operations can be invoked by running subscription-manager command. This tool can also be used to script interactions for subscriptions, such as for kickstart installations.

subscription management service

The backend server which interacts with the individual systems by creating an inventory of systems. It also keeps the inventory of subscriptions, including contracts, quantities, and expiration dates. When a new system is registered, when subscriptions are attached, and when products are installed. The subscription management service manages the changes and issues a corresponding X.509 certificate to the system to mark the change. The subscription management service also defines rules for products, such as hardware/architecture restrictions, to help with attaching subscriptions.

X.509 certificate

A specific certificate standard that is used to determine the format of certificates used for SSL communication and within a public key infrastructure. This is used to delineate the certificates used by the new subscription management service from the Satellite certificates used in the RHN Classic system.

3. High-Level Subscription Information

3.1. The Overview Page

The ultimate goal of subscription management is to allow administrators to identify the relationship between their systems and the subscriptions used by those systems. This can be done from two different perspectives: from the perspective of the local system looking externally to potential subscriptions and from the perspective of the primary account, looking down at the total infrastructure of systems and all subscriptions.

The Red Hat Subscription Manager GUI and CLI are both local clients which manage only the local machine. These tools are somewhat limited in their view; they only disclose information (such as available subscriptions) from the perspective of that one system, so expired and depleted subscriptions or subscriptions for other architectures are not displayed.

Customer Portal Subscription Management is a global tool which is intended to give complete, account-wide views into subscriptions and systems. It shows all subscriptions and all systems for the entire account. Customer Portal Subscription Management can perform many of the tasks of the on-premise tools, like registering systems, attaching subscriptions, and viewing system facts and UUID. It can also manage the subscriptions themselves, such as viewing contract information and renewing subscriptions — a task not possible in the local clients.

Customer Portal Subscription Management provides two different perspectives on subscriptions:

A view of all subscriptions in use for an account
A view of all systems within the inventory

Customer Portal Subscription Management establishes the relationship between the infrastructure (servers) and the subscriptions; Customer Portal Subscription Management is an inventory tool that manages systems and attaches existing subscriptions. Customer Portal Subscription Management also intuitively connects with subscription procurement, which allows administrators to buy and renew subscriptions for the account.

The overview page in Subscription Management summarizes the total number of systems and other units, by type, in the inventory. It also shows the numbers of systems that are managed under Subscription Management and the number managed under RHN Classic.

Note

Customer Portal Subscription Management gives a global view of all systems and units, of all types, for an account, which is crucial for planning and effectively attaching subscriptions. However, it does not provide any insight into what products are installed on a system and whether subscriptions are attached for those products. To track subscriptions for installed software, you must use the local Red Hat Subscription Manager tools.

Figure 4. Customer Portal Subscription Management Overview Page

3.2. Subscription Utilization

Administrators need to have a sense of all of the subscriptions, altogether, regardless of whether they match the architecture or installed products on any of the systems in inventory. The Customer Portal provides three ways of looking at subscriptions, with slightly different perspectives:

All subscriptions that are active and attached (total counts)
All available subscriptions that can be used by systems in Customer Portal Subscription Management
Subscriptions in Customer Portal Subscription Management that match a specific system's architecture, socket count, installed products, or other characteristics

In the Subscriptions Overview page has a link to the utilization summary. The Subscription Utilization page 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 management service.

The total counts are broken down by type first, and then the number of subscriptions of that type per subscription management service.

Figure 5. Total Counts of Subscriptions for All Subscription Services

3.3. Managing Expired and Expiring Subscriptions

The top of the subscription overview page gives three simple, clear numbers related to subscriptions: how many are active, how many will expire within 120 days, and how many have expired in the past 30 days (and are eligible for renewal).

These are total numbers for the entire account. It does not matter how many subscriptions are attached, how many systems there are, and whether the subscription is registered with Customer Portal Subscription Management, RHN Classic, or a subscription management application.

Figure 6. Subscription Overview

Clicking on any of the numbers opens the tab in the subscription inventory for that category of subscriptions.

active subscriptions goes to the Active tab.
subscriptions expiring in the next 120 days goes to the Available for Renewal tab.
recently expired subscriptions goes to the Recently Expired tab.

The tab lists the subscription names, contract numbers, and start/end dates to make it easier to track and manage subscriptions.

Figure 7. Recently Expired Tab

Clicking the name of any subscription in the Available for Renewal or Recently Expired tabs opens the details page for that contract, with renewal information. If the subscription was purchased directly from Red Hat, then it can renewed through that page; if it was purchased from a vendor, then there is contact and ordering information supplied.

Figure 8. (Expired) Product Renewal Information

3.4. Resolving Over-Utilizing Subscriptions

Red Hat does not restrict how you attach subscriptions — which means that you run the risk of attaching more subscriptions than you actually have purchased.

Warning

Attaching more subscriptions than you have is the same as running systems without subscriptions.

Along with potentially violating your service contract, this situation can also run afoul of regulations and industry standards — including Sarbanes-Oxley, PCI-DSS, and SAS-70 — that require appropriate licenses for all software in an IT infrastructure.

If you have over-used subscriptions, then the Utilization area in the Overview page shows a bright yellow warning. The Utilization page then shows the subscription counts per type, with a bright yellow bar and a negative number indicating how many subscriptions are over-used for any given type.

Figure 9. Overutilizing Subscriptions

There is no automatic remediation and Red Hat does not make assumptions or rules about what systems or subscriptions should be changed. That is entirely at the discretion of the administrator. Clicking the Total value opens up a list of registered systems or units. Administrators can then edit system entries and attach and remove subscriptions manually.

Figure 10. Reviewing Systems

Clicking the name of any system opens up its details page (as in Section 5.3, “System Details: Viewing System Information”), so that you can change the subscriptions for it.

Note

You must have org admin permissions to be able to see the Review Registrations page. Even then, you will only be able to view systems to which you have access — not necessarily every system within the account.

4. Activating Subscriptions

Systems or packages can be purchased that come with their own set of predefined subscriptions. This can be for machines purchased from a hardware vendor or even for machines and software provided internally, with subscriptions granted through a subscription management application.

Rather than attaching new subscriptions to a system, these existing subscriptions can be redeemed or activated. A 16-digit number called an subscription number is generated when these subscriptions are created, and that key is then submitted to redeem those subscriptions.

In the Subscriptions > Overview page, click the Activate a subscription link in the upper right of the Summary area.
In the Subscription Activation page, enter the 16-digit subscription number.
Continue through the activation wizard.

5. Managing Systems and Units

5.1. Registering a New System

Before a system can have any subscriptions attached to it, it has to be added into the inventory in the Customer Portal Subscription Management. This process is called registering. While registering is frequently a local operation as part of setting up or administering a machine, registering and unregistering through Customer Portal Subscription Management can be very useful when you are managing the entire infrastructure and need a more global perspective or when you need to manage systems that are not connected to an external network.

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.

Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
In the Usage area on the right, click the Subscription Management link.
In the Units area on the left, click the Register link.
Fill in the information for the new system.
A system requires information about the architecture and hardware in order to ascertain what subscriptions are available to that system.
- 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 cover to a certain number of sockets, and multiple subscriptions may be required to cover larger systems.
Once the system is created, attach the appropriate subscriptions to that system.
1. Open the Attached Subscriptions tab.
2. Click the Attach a subscription link.
3. Click the check boxes by all of the subscriptions to attach, and then click the Attach Selected button.
Click the Download link to download the entitlement certificate for each subscription. Save the file to some kind of portable media, like a flash drive.
Optionally, open the Identity Certificate tab and click the Download button. The identity certificate for the registered system could be used by the system to connect to the subscription management service. If the system will permanently be offline, then this is not necessary, but if the system could ever be brought onto the network, then this is useful.
Copy the entitlement certificates from the media device over to the system.

Import the entitlement certificates. This can be done by using the Import Certificates item in the System menu in the Subscription Manager UI or by 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

If you downloaded an identity certificate, copy the cert.pem file directly into the /etc/pki/consumer directory. For example:
```
cp /tmp/downloads/cert.pem /etc/pki/consumer
```

5.2. The System List: Viewing the Inventory

Every system which is registered with Customer Portal Subscription Management is listed in the inventory. That system inventory for Customer Portal Subscription Management, which covers the entire account, can be viewed in Customer Portal Subscription Management. There are several ways to navigate to the system list. The simplest is by selecting the Consumers List item from the Subscriptions menu.

Alternatively, click the unit typein the Subscription Management page.

Figure 12. Subscription Management Page

The system table shows the system name (usually the fully-qualified domain name or system name) and the type of system. By default, all systems and units are listed. Filters can be set to narrow the results by type or system name.

Figure 13. The System List

5.3. System Details: Viewing System Information

Clicking the system name in the Units > Type list opens the details page for that system. The details shows a list of subscriptions, system facts, and other subscription settings.

Figure 14. The System Details

The System Facts tab shows system information that has been gathered about the system. This information can be about the hardware, the architecture, system settings, and operating system information. The type of information varies depending on the platform, whether it is a virtual or physical machine, operating system version, and system settings. The system facts are used to determine the compatible subscriptions which are available to the system, meaning subscriptions for that architecture, hardware, and operating system version.

Figure 15. The System Facts

Note

If a system is manually added to the inventory through the Customer Portal Subscription Management, then only a limited set of system facts are displayed, dependent on what was entered about the system when it was registered.

Systems which are registered using the local Red Hat Subscription Manager tools can have a great many system facts listed, dependent on the result of system scans performed by the on-premise Red Hat Subscription Manager system service.

5.4. Attaching Subscriptions to a System

Basically, a subscription grants access to software downloads and updates, along with defining support levels. For a system to be able to use software, it must have a subscription which grants it that access. The Attached Subscriptions tab controls what subscriptions are attached to a system.

The Attached Subscriptions tab shows what subscriptions are currently attached to a system. Clicking the Attach a subscription link shows all of the subscriptions that are available to the system, based on what subscriptions are compatible with the hardware.

Note

Available subscriptions can also be determined by subscriptions which are compatible with currently installed products. This view of subscriptions is only available in the Red Hat Subscription Manager local clients, since Customer Portal Subscription Management has no perspective into what products are currently installed on the system. It only knows what its subscriptions are based on the subscription service inventory.

The list of available subscriptions provides three important pieces of information for the product (aside from its name):

The service level for the subscription.
The contract number for the purchase of the subscription, which is important for record keeping and tracking.
The quantity still available for that subscription. Subscriptions are purchased in quantities; this number tells how many are still left of the total quantity purchased.
The start and end dates of the subscription. This keeps you from attaching a subscription that may only be valid a few days before it expires or which are not yet active.

Note

Using the Filter box can help narrow down the list of subscriptions, which is useful if the account has many subscriptions, which can require navigating through pages of results.

Open the Attached Subscriptions tab.
Click the Attach a subscription link.
Click the checkboxes by all of the subscriptions to attach.
Normally, subscriptions are listed only if they are compatible with the system, meaning they match the system's recognized hardware, architecture, and preferences (service level or release version). To list all subscriptions, even those that aren't compatible with the system's hardware or service level preference, then deselect the appropriate Only Show... checkbox.
Click the Attach Selected button.

5.5. Checking Status

The portal provides a way to make sure that a system has all of its subscriptions up-to-date. The system's details page has a Certificate Status summary that shows whether all of the installed products on that system have the appropriate subscriptions attached.

Figure 16. Subscription Status

The status shows how long the current subscriptions are valid and the last time that the subscription certificates were updated.

The status of the system subscriptions is color-coded:

Green means all products have a valid subscription.
Yellow means that some products may not have active subscriptions but updates are still in effect.
Red means that updates are disabled.

The system status is determined by the local system itself, based on its system facts, installed products, and local subscription certificates. This information is synced with the subscription service every 24 hours (by default). The Customer Portal does not store the information about installed products; it relies on the information from the system itself. If a system is offline and cannot send its information, then the Customer Portal reflects an unknown status.

Figure 17. Unknown Subscription Status

5.6. Setting a Preferred Service Level

Part of a subscription is a defined service level for that product on a given system. 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.

There are three basic support levels:

Premium
Standard
None (self-supported)

An account can have multiple levels of support available, even for the same product, and, obviously, not every system within an IT environment demands the same response times and support as other systems. For example, 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.

When a system is configured, it can be assigned a preferred service level. When subscriptions are autoattached to the system and the preferred service level is available, then the subscription matching that preference is used. (Service-level preferences are not evaluated or enforced for manually selecting and attaching subscriptions.)

Note

Service-level preferences must first be set locally on the client when it is registered, by autoattaching, or when editing the configuration later. For example:

[root#server ~]# subscription-manager attach --auto --servicelevel Premium

After the service-level preference is set for the system, then that preference can be viewed and edited through the Portal.

The service-level preference is set in the system details page.

Figure 18. Service-Level Preference

5.7. Viewing the Operating System Release Release Preference

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.

A release version preference can only be set using the local Red Hat Subscription Manager tools. However, if a release preference is set for the local system, that preference is viewable for that system in the portal.

Figure 19. Operating System Release Version Preference Setting

5.8. Autoattaching Subscriptions

The subscription service can monitor the subscriptions that are attached to a system and track when they near their expiration dates. Within 24 hours of when the subscription expires, the Subscription Manager automatically re-attaches the system to a matching new subscription so that the subscription status remains green.

Autoattaching prevents a system from having uncovered products as long as any active, compatible subscription is available for it.

Autoattaching is enabled by default on systems to ensure that they maintain their subscription status. Autoattaching can be disabled and re-enabled by toggling the Disable/Enable buttons on the system's details page.

Figure 20. Toggling Autoattaching

5.9. Viewing Subscriptions for a System

When a subscription is attached to a system, then it is listed on the Attached Subscriptions tab with its contract number and expiration date.

Figure 21. Subscription Details Link

Clicking the View link for that subscription opens up much more detail about the subscription, including a list of products that the subscription provides, its order information, the quantity and type of subscriptions available in that one subscription, and its certificate (which can be regenerated on the system or downloaded for view).

Figure 22. Subscription Details

5.10. Removing Subscriptions for a System

A subscription can be removed from a system to free up that quantity for another system. To remove a subscription from a system, click the Remove link by the subscription on the Attached Subscriptions tab.

5.11. Removing a System

A system can be removed or unregistered from the subscription management service through Customer Portal Subscription Management. This is equivalent to running the unregister command with Red Hat Subscription Manager.

For an offline system, it may not be possible to use the local tools to unregister the system. Removing the system manually though the Portal will remove the system and free any attached subscriptions.

Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management area.
In the Usage area on the right, click the Subscription Management link.
Click the link for the system type in the Subscription Management page.
Select the checkboxes by the systems to delete.
Note
You cannot delete more than five (5) systems at a time.

Note

You can also remove a single system by clicking the Delete this system button in its details page.

5.12. Viewing and Regenerating Identity Certificates for a System

Customer Portal Subscription Management is certificate based. Standard SSL certificates are used to authenticate systems and application organizations to the subscription management service. These are called identity certificates.

The identity certificate contains the UUID for the system or application organization in the inventory (in the CN of the certificate), a serial number for the certificate, and the creation and expiration dates for the identity certificate (with creation being the day the system was registered).

The identity certificate tab has all of the relevant information in the identity certificate (the serial number and creation/expiration dates). The UUID for the system or application organization is used to identify it in the certificate.

Figure 23. Identity Certificate Details

There can be times when the identity certificate for a system is lost, perhaps because it was deleted or corrupted or because the system was changed. The identity certificate can be downloaded directly through Customer Portal Subscription Management, in a base 64-encoded PEM file like the one that was initially generated on the system.

Alternatively, the original identity certificate can be revoked and a new identity certificate generated in its place; this is called regenerating the certificate. The regenerated identity certificate will have the same UUID as the original (so its place in the inventory and all its subscriptions are preserved) but with a different serial number and new creation/expiration dates.

6. Managing Errata Notifications for Registered Systems

Part of subscription management is tracking updates and new releases of software. Whenever an update is available — from a bug fix to a new release — a notification email can be sent to an administrator.

The notifications are smart, so they are only sent for 1) registered systems which 2) have subscriptions for that product attached to them. If there are no systems with attached subscriptions for that product, even if the account does have subscriptions for it, then no notification is sent.

Errata notifications are set as a preference for the user account, not for an individual system. So, when checking for potential errata updates, Subscription Management checks the entire inventory, not specific systems.

An errata notification is sent if any registered system is affected, but the email does not list what systems are actually affected.

Note

Because Red Hat Network Subscription Management and RHN Classic have separate inventories, they each have their own errata notification setting. Even if errata notifications are already enabled for RHN Classic, they must still be enabled for Red Hat Network Subscription Management, or no errata notifications will be sent for systems managed in the Red Hat Network Subscription Management inventory.

To configure errata notifications for a user account:

In the upper right corner of the Customer Portal, expand the details for the logged in user.
Click the Account settings link.
In the settings main page, click the Account Details link in the middle of the Your Red Hat Account box.
In the Your Preferences menu on the left, click the Errata Notifications link.
Select the checkboxes for each type of errata for which to receive an update. Security errata relate to critical security issues. Bug fixes and enhancement notifications relate to incremental updates to the product.
Set the frequency to receive errata notifications. This applies to all selected types of errata notifications.
Click the Save button.

7. Managing On-Premise Subscription Management Applications

A subscription management application organization is a special type of entity in Red Hat Network — it is an on-premise entity that manages local systems. Red Hat Network registers the subscription management application organization and attaches large blocs of subscriptions to it. The application organization itself then manages inventory, subscriptions, and systems locally.

Customer Portal Subscription Management transfers subscriptions from the company's global Red Hat account to the local application. The subscription management application organization entry is the method Customer Portal Subscription Management uses to transfer those subscriptions.

A subscription management application organization entry in Customer Portal Subscription Management has direct parity with an organization entry in the on-premise application. The organization structure can be flat, with a single local organization. Alternatively, it can be multi-tenant, with multiple organizations managed by the same application but independent from each other. Multi-tenancy within the on-premise application allows multiple, independent groups to be attached and to manage their own subscriptions and systems through local services. (The organization structure in the on-premise application is transparent to Customer Portal Subscription Management. Customer Portal Subscription Management works with each subscription management application organization entry separately.)

The subscriptions attached to the application organization are the entirety of the subscriptions and products available to the systems within that organization. The subscriptions, products, and quantities are listed in the subscription management application organization's manifest.

Local organizations and environments can be managed through a variety of different subscription management applications, such as Subscription Asset Manager and CloudForms System Engine..

7.1. Registering Application Organizations

Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
In the Usage area on the right, click the Subscription Management link.
In the Subscription Management Applications column, click the Register link.
Select the application type and fill in the name of the new subscription management application organization.
Note
This name should correspond to the organization name in the on-premise application.
Click the Register button.

After the subscription management application organization is created, attach subscriptions to it, and download and install the manifest so that the organization can begin attaching subscriptions to its client systems.

7.2. The Subscription Management Application List and Details

The bottom of the Subscription Management page lists the applications, by type and number of registered organizations. Clicking the number in the count column opens up the list of organizations configured for that application type.

Figure 24. Subscription Management Applications in the Overview

The Subscription Management Applications inventory has tabs for each available and configured application type, and each organization for that type is listed.

Figure 25. Viewing the Subscription Management Application Inventory

The columns have three important pieces of information:

The organization name, which links to the entry details page
The total number of subscriptions (across products and contracts) attached to that organization
The UUID for the organization, analogous to the UUID for a system

The organization details page is for managing the organization. Like the system details, has tabs for managing subscriptions for that organization and a tab for the identity certificate. It also has a button to download the manifest, which is the file imported into the on-premise application which informs the application what subscriptions it has.

Figure 26. Organization Details

7.3. Attaching Subscriptions to Organizations

7.3.1. About Manifests

As the introduction to Section 7, “Managing On-Premise Subscription Management Applications” covers briefly, there is a direct relationship between the subscription management application organization in Red Hat Network and the organization definition in an on-premise application like Subscription Asset Manager. This relationship is the method that Red Hat Network uses to transfer subscriptions from Red Hat to the on-premise application to administer locally.

This transferred block of subscriptions is listed in the subscription management application organization manifest. This manifest is a ZIP archive which is downloaded directly from Red Hat Network from the subscription management application organization entry and then is uploaded to the on-premise application.

Important

Any changes to the subscriptions for the organization are made to the subscription attached to the subscription management application organization entry in Red Hat Network. The manifest is then regenerated, downloaded, and re-uploaded to the application.

The manifest itself is a collection of directories and JSON files which contain the subscriptions, entitlement certificates, products, and list of rules for the subscription management application organization.

manifest.zip
      |
      |- consumer_export.zip
                   |
		   |- export/
		         |
			 |- consumer_types/
			 |
			 |- entitlements/
			 |
			 |- entitlement_certificates/
			 |
			 |- products/
			 |
			 |- rules/
			 |
			 |- consumer.json
			 |
			 |- meta.json

consumer.json and meta.json

These JSON files contain a little information about the application organization entry (the UUID) and the manifest itself (version and creation date).

consumer_types/

consumer_types/ contains a list of JSON files, one for each supported application type. The JSON files indicate which type the subscriptions are attached to. For example, for Subscription Asset Manager, the sam.json has a manifest value of true.

{"id":"5","label":"sam","manifest":true}

entitlements/

entitlements/ contains a JSON file for each subscription attached to the application organization. Each filed is named UUID.json.

The file contains the complete subscription information, including the contract number, pool ID, contract start/end dates, keys and certificates for the subscription, the product ID for each included product, quantities, and any other information associated with the subscriptions.

For example, this is the information for a single Red Hat Enterprise Linux product in a subscription JSON:

...
{"id":"8a878dcd3520d43501353f6f98f911e9","productName":"Red Hat Enterprise Linux Server","productId":"69","updated":"2012-02-02T18:59:32.000+0000","created":"2012-02-02T18:59:32.000+0000"}],"endDate":"2012-10-13T03:59:59.000+0000","quantity":50,"productName":"Red Hat Enterprise Linux Server, Premium (4 sockets) (Up to 4 guests)","contractNumber":"2625891","accountNumber":"1506376","productId":"RH0153936","subscriptionId":"2267347","consumed":31,"exported":30,"sourceEntitlement":null,"activeSubscription":true,"restrictedToUsername":null,"productAttributes":[{"productId":"RH0153936","name":"support_type","value":"L1-L3","id":"8a878dcd3520d43501353f6f98f811de","updated":"2012-02-02T18:59:32.000+0000","created":"2012-02-02T18:59:32.000+0000"}
...

entitlement_certificates/

entitlement_certificates/ contain PEM files with the base 64-encoded blob of the entitlement certificate for each subscription.

products/

products/ contains JSON file for every product included with the subscriptions. This contains detailed information about supported versions and content sets, dependencies, repositories, and other product-specific (but not necessarily subscription-specific) information.

For example, for part of the JSON file for one version with a basic Red Hat Enterprise Linux product:

...
{"name":"Red Hat Enterprise Linux Server","id":"69","attributes":[{"name":"type","value":"SVC"},{"name":"arch","value":"i386,ia64,x86_64"},{"name":"name","value":"Red Hat Enterprise Linux Server"}],"multiplier":1,"href":"/products/69","productContent":[{"content":{"name":"Red Hat Enterprise Linux 5 Server Beta (Source ISOs)","id":"861","type":"file","vendor":"Red Hat","modifiedProductIds":[],"contentUrl":"/content/beta/rhel/server/5/$releasever/$basearch/source/iso","label":"rhel-5-server-beta-source-isos","gpgUrl":"http://","metadataExpire":86400,"requiredTags":"rhel-5-server"},"enabled":false}
...

rules/

rules/ contains a single JavaScript file which sets the functions that the application uses to interact with the backend Red Hat subscription management service.

7.3.2. Attaching Subscriptions to Organizations

Attaching subscriptions to an organization sets the number of that type of subscription which the organization can attach to the systems it manages. (This is in contrast to a system, which attaches the subscription to itself for its own, local installed products.)

The Attached Subscriptions tab shows what subscriptions are currently attached to the organization. Clicking the Attach a subscription link shows all of the subscriptions that are available to the application organization, based on the overall account subscriptions.

To attach subscriptions to an organization:

Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
In the Usage area on the right, click the Subscription Management link.
In the Subscription Management Applications column, click the organization type.
Click the organization name in the application inventory.
Open the Attached Subscriptions tab.
Click the Attach a subscription link to open the subscription selection window.
Select the checkboxes by the subscriptions to attach and set the total quantity for the application organization in the Quantity column.
The list of available subscriptions provides three important pieces of information:
- The contract number for the purchase of the subscription, which is important for record keeping and tracking.
- The quantity still available for that subscription. Subscriptions are purchased in quantities; this number tells how many are still left of the total quantity purchased.
- The start and end dates of the subscription. This keeps you from attaching a subscription that may only be valid a few days before it expires or which are not yet active.
  There should probably be a mix of subscriptions, with different end dates, attached to the organization to make it easier to renew subscriptions without having to update the manifest.
Note
The quantity defaults to be the total number of subscriptions available for that contract. Be aware of how many subscriptions are being attached to a single application organization so that the subscriptions can be attached appropriately among other units and subscription management applications.
Click the Attach selected button in the lower left corner.

7.3.3. Downloading the Manifest

Once subscriptions are attached to a application organization, the complete list of subscriptions and products, including product certificates and entitlement certificates, are bundled together in a single manifest. The manifest is essentially a master list of everything that the application organization requires to handle local subscription management services.

The manifest can be downloaded from the application organization's details page simply by clicking the Download manifest button. This saves the manifest.zip archive to the local filesystem, so it can then be uploaded to Subscription Asset Manager or CloudForms System Engine.

Figure 27. Downloading the Application Organization Manifest

7.3.4. Updating the Manifest and Changing Subscriptions

If the organization needs to change its subscriptions — by altering quantities, adding products, or renewing subscriptions — this is done by editing the subscriptions attached to the organizatin in Customer Portal Subscription Management.

Important

Do no attempt to update the on-premise organization entry by creating a new organization in Customer Portal Subscription Management. Change the subscriptions attached to the existing organization in Customer Portal Subscription Management, and then have the on-premise organization entry use the updated manifest.

Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
In the Usage area on the right, click the Subscription Management link.
In the Subscription Management Applications column, click the organization type.
Click the organization name in the application inventory.
Open the Attached Subscriptions tab.
Delete any previous subscriptions which need to be updated. Select the checkbox by the subscription, and click the Remove Selected button.
A subscription quantity attached to a subscription management application organization cannot be changed directly. If additional numbers need to be added or removed from an attached subscription, delete the original assignment and then attach the subscription with the new quantity.
For example, if your subscription bloc has a quantity of 30 and it should increase to 35, you can delete the old bloc and add a new one with a quantity of 35; that leaves you with one subscription and a quantity of 35. Alternatively, you can simply add a new bloc with a quantity of 5; that results in two separate subscription entries, one with a quantity of 30 and one with a quantity of 5.
Add any new subscriptions, as in Section 7.3.2, “Attaching Subscriptions to Organizations”.
Click the Download manifest button and save the updated manifest, as in Section 7.3.3, “Downloading the Manifest”.
Upload the updated manifest to the on-premise application.

Legal Notice

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.