Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

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

15.2.1. Registering from the GUI

  1. Launch Subscription Manager. For example:
    [root@server ~]# subscription-manager-gui
  2. If the system is not already registered, then there will be a Register button at the top of the window in the top right corner of the My Installed Products tab.
  3. To identify which subscription server to use for registration, enter the hostname of the service. The default service is Customer Portal Subscription Management, with the hostname To use a different subscription service, such as Subscription Asset Manager, enter the hostname of the local server.
    There are seveal different subscription services which use and recognize certificate-based subscriptions, and a system can be registered with any of them in firstboot:
    • Customer Portal Subscription Management, hosted services from Red Hat (the default)
    • Subscription Asset Manager, an on-premise subscription server which proxies content delivery back to the Customer Portal's services
    • CloudForms System Engine, 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 CloudForms System engine, 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 15.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.

15.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 15.2, “register Options”.

Example 15.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 15.2. Automatically Subscribing While Registering

The register command has an option, --autosubscribe, 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 --autosubscribe
This is the same behavior as when registering with the default settings in the Subscription Manager UI.

Example 15.3. Registering a System with Subscription Asset Manager

With Subscription Asset Managr or CloudForms System Engine, an account can have multiple, independent subdivisions called organizationst is required that you specify which organization (essentially an independent group or unit within the main account) to join the system to. This is done by using the --org option in addition to the username and password. The given user must also have the access permissions to add systems to that organization.
To register with a subscription service other than Customer Portal Subscription Management, several additional options must be used to identify the environment and organizational divisions that the system is being registered to:
  • The username and password for the user account withint the subscription service itself
  • --serverurl to give the hostname of the subscription service
  • --baseurl to give the hostname of the content delivery service (for CloudForms System Engine only)
  • --org to give the name of the organization under which to register the system
  • --environment to give the name of an environment (group) within the organization to which to add the system; this is optional, since a default environment is set for any organization
    A system can only be added to an environment during registration.
[root@server1 ~]# subscription-manager register --username=admin-example --password=secret --org="IT Department" --environment="dev"

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


If the system is in a multi-org environment and no organization is given, the register command returns a Remote Server error.

Table 15.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 Subcription Management, If this option is not used, the system is registered with Customer Portal Subscription Management. Required for Subscription Asset Manager or CloudForms System Engine
--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 Since CloudForms System Engine hosts its own content, the URL must be used for systems registered with System Engine. Required for CloudForms System Engine
--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
--autosubscribe Automatically ataches 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 --autosubscribe 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 --autosubscribe 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

15.2.3. 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 15.4. Unregistering a System

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