# &app; Manual

## Introduction

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 provides that mechanism and gives transparency into both global allocations of subscriptions for an entire organization and the specific subscriptions assigned to a single system.

The basis of software management is a subscription. A subscription contains both the products that are available, the support levels, and the quantities, or number of servers, that the product can be installed on. A subscription is roughly analogous to a user license, in that it grants all of the rights to that product to that system. Unlike a user license, a subscription does not grant the right to use the software; with the subscription model, a subscription grants the ability to download the packages and receive updates.

Subscriptions are managed though a subscription management service such as the Customer Portal Subscription Management (hosted) or an on-premise service like Subscription Asset Manager. A second service delivers the actual software bits, in tandem with the subscriptions managed for a system.

The subscription management service maintains a list of every subscription or set of subscriptions for an organization. The list of subscriptions is a pool, identified by a unique ID (called a pool ID). A system is registered, or added, to the subscription management service to allow it to manage the subscriptions for that system. Like the subscription, the system is also added to the subscription management service inventory and is assigned a unique ID within the service. The subscriptions and system entries, together, comprise the inventory.

A system allocates, or attaches, one of the quantities of a product in a subscription to itself.

The repository where the product software is located is organized according to the product. Each product group within the repository may contain the primary software packages and then any required dependencies or associated packages. Altogether, the product and its associated packages are called a content set. (A content set for a product even includes other versions of the product.) When a subscription grants access to a product, it includes access to all of the associated packages in that content set.

A single subscription can have multiple products, and each system can have multiple different subscriptions, depending on how many entitlement certificates are loaded on the machine.

Any number of products, for any number of different architectures, can be contained in a single subscription. The subscription options that are visible to a consumer are filtered, by default, according to whether the architecture for the product matches the architecture of the system. This is compatibility. Depending on compatible subscriptions makes sure that subscriptions are allocated efficiently, only to systems which can actually use the products.

Some subscriptions define some element count on the system, like the number of sockets, the number of virtual guests on a host, or the number of clients in a domain. Multiple subscriptions can be combined together to cover the counts on the system.

The subscription tools can display even incompatible subscriptions. Alternatively, the architecture definition for the system can be overridden by defining custom system facts for the subscription tools to use.

It is important to distinguish between attaching a subscription for a product and installing a product. A subscription is essentially a statement of whatever products an organization has purchased. The act of attaching a subscription means that a system is allowed to install the product with a valid certificate, but attaching a subscription does not actually perform any installation or updates. In the reverse, a product can also be installed apart from any subscriptions for the system; the system is just does not have a valid product certificate. Red Hat Subscription Manager simplifies product installation by using `yum` plug-ins that come with its tools.

The Red Hat Subscription Manager GUI 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 applying and removing subscriptions from the system.

Red Hat Subscription Manager has three main areas to manage products and subscriptions:

- The My Subscriptions area shows all of the current subscriptions applied to the system.

- The Available Subscriptions area 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.

- The My Installed Products area 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

The Subscription Manager Main Window, annotated.

## Launching Red Hat Subscription Manager

Red Hat Subscription Manager is listed as one of the administrative tools in the System => Administration menu in 6.x and in the Applications => System Tools menu in 5.x and 7.x.

Alternatively, the Red Hat Subscription Manager GUI can be opened from the command line with a single command:

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

### NOTE

Both the GUI and the CLI for Subscription Manager must be run as `root`.

## Registering, Unregistering, and Reregistering a System

### Registering Systems with Customer Portal Subscription Management

1. Launch the Subscription Manager UI. This must be run as root.

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

2. Click the Register button in the My Installed Products tab.

3. Enter the username and password of the user account on the subscription management service; this is the account used to access the Customer Portal.

#### TIP

Use the `--register` with `subscription-manager-gui` to open the registration pages immediately.

### Registering with Subscription Asset Manager

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-sam.example.com-1.0-1.noarch.rpm

2. Launch the Subscription Manager UI. This must be run as root.

3. Click the Register button in the My Installed Products tab.

4. Enter the username and password of the user account for the subscription management application.

5. Subscription Manager scans the network for available organizations.

   When the configured organizations are detected, Subscription Manager prompts for the organization for the system to join.

### Registering to Subscription Asset Manager with an Activation Key

An on-premise Subscription Asset Manager can preconfigure subscriptions to use for a system, and that preconfigured set of subscriptions is identified by an activation key. That key can then be used to attach those subscriptions on a local system.

Activation keys for &SAM; 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 to point Subscription Manager to the subscription application. For example:

       [root@server ~]# rpm -ivh \
            http://sam.example.com/pub/candlepin-cert-consumer-sam.example.com-1.0-1.noarch.rpm

2. Launch the Subscription Manager UI.

3. Click the Register button in the My Installed Products tab.

4. Check the I will use an Activation Key checkbox and click the Next button.

5. 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 &SAM;.

6. Click the Register button.

After the registration completes, all of the preconfigured subscriptions are attached to the system.

### Unregistering

Unregistering a system removes the system's entry from the subscription management service, removes any subscriptions, and, locally, deletes its identity and entitlement certificates. It does not change or uninstall any currently-installed products.

Select the Unregister menu item from the task menu in the GUI.

## Attaching and Removing Subscriptions

### Attaching Subscriptions

1. Open the All Available Subscriptions tab.

2. Click the Filters button.

3. 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 system is already subscribed to a subscription for a specific product or if multiple subscriptions supply the same product, then the subscription management service filters those subscriptions and shows only the best fit.

4. Select the desired subscription.

5. Click the Attach button.

### Removing Subscriptions

1. Open the My Subscriptions tab.

   All of the active subscriptions which are currently attached to the system are listed. (The products available through the subscription may or may not be installed.)

2. Select the subscription to remove.

3. Click the Remove button in the bottom right of the window.

### Manually Importing a New Subscription

In certain situations, new product subscriptions can be added by uploading the X.509 entitlements certificate directly rather than polling the subscription management service. For example, systems which are offline must have subscriptions manually added because they cannot connect to the subscription management service directly.

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 Subscription Management area.

   2. In the summary of systems, click the name of the offline system.

   3. If necessary, assign the subscriptions to the system.

   4. Open the My Subscriptions tab.

   5. Click the Download All Certificates button. This exports all of the entitlement certificates, for each product, to a single `.zip` file. Save the file to some kind of portable media, like a flash drive.

      To download individual entitlement certificates, click the Download link on the row for the subscription.

2. Copy the certificates over to the system, and unzip the archive.

3. Launch the Subscription Manager GUI.

4. Open the System menu, and select the Import Certificate item.

5. Click the file folder icon at the right of the field to navigate to the `.pem` file of the product certificate.

6. Click the Import Certificate button.

All of the subscriptions that were uploaded are then attached to the system.

## Redeeming Vendor Subscriptions

Systems purchased from vendors can be set up with pre-existing subscriptions already available to that system. 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.

If the machine does not have any subscriptions to be redeemed, then the Redeem a Subscription menu item is not there.

1. Open the System menu in the top left of the window, and click the Redeem item.

2. 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 preconfigured subscriptions, the notification message is sent through email rather than through the Subscription Manager dialog window.

3. Click the Redeem button.

It can take up to ten minutes for the confirmation email to arrive.

## Viewing Available and Used Subscriptions

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

The Red Hat Subscription Manager tools give a more detailed view of subscriptions than is available through the global tools of the Customer Portal. Three tabs summarize each of the subscriptions and products for the specific machine: installed products (with subscriptions), applied subscriptions, and available subscriptions.

These summaries are always displayed in the Red Hat Subscription Manager GUI.

## Attached Subscriptions

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

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

The filters dynamically search for available subscriptions.

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.

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

## Setting Service Level Preferences

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 .

The service information for each subscription is part of the subscription details. Two attributes are displayed, per subscription: its support level and its support 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.

An account can have multiple levels of support available, even for the same product. A system can be set up to select subscriptions based on a preferred service level. This is used as a component in autoattaching subscriptions to the system.

To assign a service level:

1. Open the System menu in the Subscription Manager window.

2. Select the Preferences item.

3. In the dialog box, select the desired service level from the drop-down menu.

## Setting Release Version Preferences

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 can't simply run `yum update` and move from version to version.

The preferences dialog can set a preferred minor, or y-stream, release number for the system to stick to. This limits the system to content repositories associated with that operating system version instead of moving to the newest or latest version repositories. For example, if the preferred operating system version is 6.3, then 6.3 content repositories are preferred for all installed and subscribed products for the system, even if other repositories are available.

To assign a preferred operating system version:

1. Open the System menu in the Subscription Manager window.

2. Select the Preferences item.

3. In the dialog box, select the desired operating system version from the drop-down menu.

## Responding to Subscription 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.

### Subscription Status Information

Subscription status information.

Whenever there is a warning about subscription changes, a small icon appears in the notification area of the desktop, similar to a fuel gauge.

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

Subscription desktop warning notification.

Clicking the Auto-attach button in the Subscription Manager GUI automatically applies the appropriate subscriptions for the products on the system.