Quick Registration for RHEL

Red Hat Subscription Management 1

quickly register and subscribe Red Hat Enterprise Linux systems

Red Hat Subscription Management Documentation Team

October 1, 2013

Abstract

This guide covers basic information to register a Red Hat Enterprise Linux system quickly and to attach and manage subscriptions effectively. Advanced Subscription Manager configuration is covered in Using and Configuring Red Hat Subscription Manager.
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.
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.
Red Hat Subscription Manager works with content management tools (yum) to help install and update content on the local system.
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. It is also possible to register a system with Subscription Asset Manager or with another subscription service, with some modification to the Subscription Manager configuration. More advanced Subscription Manager configuration and usage is covered in Using and Configuring Red Hat Subscription Manager in the subscription management documentation set.

1. Using Red Hat Subscription Manager Tools

Both registration and subscriptions are managed on the local system through UI and CLI tools called Red Hat Subscription Manager.

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.

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

1.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. Common subscription-manager Commands

Command Description
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 Attaches a specific subscription to the machine.
redeem Auto-attaches a machine to a pre-specified subscription that was purchased from a vendor, based on its hardware and BIOS information.
remove Removes a specific subscription or all subscriptions from the machine.
list Lists all of the subscriptions that are compatible with a machine, either subscriptions that are actually attached to the machine or unused subscriptions that are available to the machine.

2. Registering and Unregistering 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 service.

2.1. Registering from the UI

  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. To use a different subscription service, such as Subscription Asset Manager, enter the hostname of the local server.
    There are several 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 or Satellite 6, 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 3, “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 a local 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 Subscribe button for the wizard to complete.

2.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”.

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 Subscribing 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 or Satellite 6
--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

2.3. Registering a System to Subscription Asset Manager

  1. Install the configuration RPM to configure Red Hat Subscription Manager to point to the Subscription Asset Manager instance. Every Subscription Asset Manager server has a configuration RPM available at a standard URL: 
    http://sam_server_hostname/pub/candlepin-cert-consumer.noarch.rpm
    For example: 
    [root@server ~]# rpm -ivh http://sam.example.com/pub/candlepin-cert-consumer.noarch.rpm
  2. Register the system using the subscription-manager command. The organization name is required; if the username or password are not passed with the command, then the command prompts for them. Using --auto-attach to apply subscriptions automatically is not required, but it simplifies setting up the new system. 
    [root@server ~]# subscription-manager register --username=jsmith --password=secret --org="IT Dept" --auto-attach
    This command must be run as root.

2.4. 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 UI:
  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. 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.

3.1. Attaching and Removing Subscriptions through the UI

3.1.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 Subscribe button.

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

3.2. Attaching and Removing Subscriptions through the Command Line

3.2.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 3, “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 3. 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

3.2.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 X.509 certificate installed with it. The product subscription to remove is identified in the remove command by referencing the ID number of that X.509 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. 
    [root@server1 ~]# subscription-manager remove --serial=11287514358600162

4. 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.1. Redeeming Subscriptions through the UI

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 2.1, “Registering from the UI”.
  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.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. Attaching Subscriptions from a Subscription Asset Manager Activation Key

A local 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.
The Subscription Asset Manager activation key can be used as part of the registration process for the new system: 
# subscription-manager register --username=jsmith --password=secret --org="IT Dept" --activationkey=abcd1234
If there are multiple organizations, it is still necessary to specify the organization for the system. That information is not defined in the activation key.

6. Setting Preferences for Systems

Auto-attaching 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 when autoattach is scheduled as a job, which runs daily to ensure that all installed products and current subscriptions remain active.

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

6.2. Setting Service Levels Through the Command Line

A general service level preference can be set using the service-level --set command.

Example 4. 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 5. 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.

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

Example 6. 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 7. 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 organization. 
[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

7. Managing Subscription Expiration and Notifications

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 for it to be fully subscribed. 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 2. Valid Until...

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 UI, the status of the system subscriptions is color-coded, where green means all products are fully subscribed, yellow means that some products may not be subscribed but updates are still in effect, and red means that updates are disabled.
Color-Coded Status Views

Figure 3. 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 4. 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 a subscription is not 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 UI to view and update subscriptions.
Subscription Warning Message

Figure 5. Subscription Warning Message

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 Autoattach button.
Autoattach Button

Figure 6. Autoattach Button

The Subscribe System dialog shows a targeted list of available subscriptions that apply to the specific products that do not have valid certificates (assuming subscriptions are available).

8. Revision History

Revision History
Revision 1.3-5September 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.