Chapter 8. Managing Activation Keys

At this point, we have published some Content Views, which resulted in Satellite Server publishing repositories. Systems now can register to Satellite Server and consume content from these repositories. Systems register in a similar way to how they register to the Red Hat Customer Portal. For example, users can use Red Hat Subscription Manager (subscription-manager) with the --baseurl pointing to Satellite Server instead of the Red Hat Content Delivery Network.

There are two methods to register a system. The first is to authenticate with a Satellite Server user name and password, which we explored in the previous chapter. An alternative and preferred method is to use an activation key, which acts as an authentication token. Activation keys provide a method for easy system registration and subscription attachment. Users can create multiple keys and associate them with different environments and Content Views. For example, you might create a basic activation key with a subscription for Red Hat Enterprise Linux workstations and associate it with Content Views from a particular environment.

Activation keys define selected properties of content hosts. You can use activation keys during content host registration to improve the speed, simplicity and consistency of the process. Activation can specify:

  • Associated subscriptions and subscription attach behavior.
  • Available products and repositories.
  • A life cycle environment and a Content View.
  • Host collection membership.

The same activation key can be applied to multiple content hosts, as long as it contains enough subscriptions. However, activation keys only set the initial configuration for a content host. When it is registered to an organization, other content which that organization possesses can be attached to the content host manually.

A content host can be associated with multiple activation keys that are combined to define the host settings. In case of conflicting settings, the last specified activation key takes precedence.

Note that activation keys are only used when hosts are registered. If changes are made to an activation key, it is only applicable to hosts that are registered with the amended activation key in the future. The changes are not made to existing hosts.

For more information about activation keys and more use case examples outside of this guide, see "Activation Key Enhancements with Red Hat Satellite 6.1" on the Red Hat Customer Portal.

8.1. Creating an Activation Key

With activation keys you can define how the content host is subscribed during registration. The subscription behavior defined by the activation key depends on two factors:

  • Are there any subscriptions associated with the activation key?
  • Is the auto-attach option enabled?

Based on the above factors, there are three possible scenarios for subscribing with activation keys:

  • Activation key with no subscriptions specified. With no subscriptions specified and auto-attach enabled, hosts using the activation key search for the best fitting subscription from the ones provided by Satellite Server. This is similar to entering the subscription-manager --auto-attach command.
  • Activation key providing a custom subscription pool for auto-attach. If there are subscriptions specified and auto-attach is enabled, hosts using the activation key select the best fitting subscription from the list specified in the activation key.
  • Activation key with the exact set of subscriptions. If there are subscriptions specified and auto-attach is disabled, hosts using the activation key are associated with all subscriptions specified in the activation key.
Note

If a custom product (typically containing content not provided by Red Hat) is assigned to an activation key, this product is always enabled for the registered content host regardless of the auto-attach setting.

For Web UI Users

  1. Navigate to ContentActivation keys and click Create Activation Key. Provide the activation key with the following information:

    • Name - The name of the activation key. We use this name during the system registration process. In the Name field, type development-stack.
    • Limit - Defines the maximum number of systems you can register with the activation key. Select the Unlimited Hosts check box.
    • Description - A plain text description for the activation key. In the Description field, type Exampleware Stack in the Development Environment.
    • Environment - The environment to use. In the Environment area, select Development.
    • Content View - The Content View (and, by extension, the repository) in the environment to use. From the Content View list, select Stack.

    Click Save. The activation key details screen displays.

  2. To define which products to attach and repositories to enable upon registration, navigate to the Subscriptions tab. Click Add, select both the Red Hat Enterprise Linux subscription and the PostgreSQL product, and click Add Selected.

    Note

    The Auto-Attach option is enabled. This automatically attaches these products to the system upon registration and enables the required repositories. If Auto-Attach is disabled for the activation key, the system only registers to Satellite Server without attaching any subscriptions or content.

  3. Navigate to the Product Content page. As default, Satellite Server only enables:

    • The repository that best matches the system requirements. In this case, it is only the Red Hat Enterprise Linux 7 Server RPMs.
    • Any custom content.

    Our scenario must have the following defaults set:

    PostgreSQL:

    • PostgreSQL 9.5 - Enabled: Yes (Default)
    • PostgreSQL Puppet Modules - Enabled: Yes (Default)

    Red Hat Enterprise Linux Server:

    • Red Hat Enterprise Linux 7 Server (Kickstart) - Enabled: No (Default)
    • Red Hat Satellite Tools 6.3 (for RHEL 7 Server) (RPMs) - Enabled: No (Default)
    • Red Hat Enterprise Linux 7 Server (RPMs) - Enabled: Yes (Default)

    However, we want to enable the Red Hat Satellite Tools repository because that contains our configuration tools (such as katello-agent and puppet). Change it to the following:

    • Red Hat Satellite Tools 6.3 (for RHEL 7 Server) (RPMs) - Enabled: Override to Yes
  4. Click Save

For CLI Users

  1. Create the activation key:

    # hammer activation-key create \
    --name "development-stack" \
    --unlimited-hosts true \
    --description "Exampleware Stack in the Development Environment" \
    --lifecycle-environment "Development" \
    --content-view "Stack"  \
    --organization "ACME"
  2. Obtain a list of your subscription IDs:

    # hammer subscription list --organization "ACME"
  3. Attach the Red Hat Enterprise Linux subscription UUID to the activation key:

    # hammer activation-key add-subscription \
    --name "development-stack" \
    --subscription-id ff808181533518d50152354246e901aa \
    --organization "ACME"
  4. Attach the PostgreSQL product to the activation key:

    # hammer activation-key add-subscription \
    --name "development-stack" \
    --subscription-id ff8081815239acdc015238fefaa10002 \
    --organization "ACME"
  5. List the product content associated with the activation key:

    # hammer activation-key product-content \
    --name "development-stack" \
    --organization "ACME"
  6. Override the default auto-enable status for the Red Hat Satellite Tools 6.3 repository. The default status is set to disabled. To enable, enter the following command:

    # hammer activation-key content-override \
    --name "development-stack" \
    --content-label rhel-7-server-satellite-tools-6.3-rpms \
    --value 1 \
    --organization "ACME"

8.2. Using Activation Keys

The activation keys are used for registration. This includes:

  • Registering new systems during provisioning through Red Hat Satellite 6. The kickstart provisioning templates in Red Hat Satellite 6 contain commands to register the system using an activation key defined when creating a new host.
  • Registering existing Red Hat Enterprise Linux systems. Configure Red Hat Subscription Manager to use Satellite Server for registration and specify the activation key when running the subscription-manager register command.

You can test the activation key we created. Register an existing Red Hat Enterprise Linux 7 system to Satellite Server.

First, download the consumer RPM for your Satellite Server. This is usually located in the pub directory on the host’s web server. For example, for a Satellite Server with the host name satellite.example.com, enter the following command on the client to register:

# rpm -Uvh http://satellite.example.com/pub/katello-ca-consumer-latest.noarch.rpm

This RPM installs the necessary certificates for accessing repositories on Satellite Server and configures Red Hat Subscription Manager to use the server’s URL.

Next, run Red Hat Subscription Manager on the client:

# subscription-manager register --activationkey="development-stack" \
--org="ACME"
The system has been registered with id: 744fb31c-c983-00f5-ca14-bddd0f711353

Check Satellite Server to confirm the registration.

For Web UI Users

Navigate to Hosts > Content Hosts and the system appears in the list.

For CLI Users

Enter the following command:

# hammer host list --organization "ACME"
Important

After registering a client system to Satellite Server, install the katello-agent package on the system so that it can report back to Satellite Server:

# yum install katello-agent

The Red Hat Satellite Tools 6.3 repository provides this package.

You can use multiple activation keys when registering a content host. This allows you to create activation keys for specific subscription sets and then combine them according to content host requirements. For example, the following command registers a content host to the ACME organization with both VDC and OpenShift subscriptions:

# subscription-manager register --org="ACME" \
--activationkey="ak-VDC,ak-OpenShift"

If there are conflicting settings in activation keys, the rightmost key takes precedence.

  • Settings that conflict: Service Level, Release Version, Environment, Content View, and Product Content.
  • Settings that do not conflict and the host gets the union of them: Subscriptions and Host Collections.
  • Settings that influence the behavior of the key itself and not the host configuration: Content Host Limit and Auto-Attach.

8.3. Updating Subscriptions Associated with an Activation Key

You can change the subscriptions associated with an Activation Key using the web UI or using the Hammer command-line tool. The Hammer CLI method requires downloading a CSV file, making changes to the Activation Key settings, and then uploading the changed CSV file.

Note that changes to an Activation Key applies only to machines provisioned after the change. To update subscriptions on existing content hosts, see Section 3.8, “Bulk Updating Content Hosts' Subscriptions”.

For Web UI Users

  1. Navigate to Content > Activation keys and click the name of the Activation Key.
  2. Select the Subscriptions tab.
  3. To remove subscriptions, select List/Remove, select the check boxes to the left of the subscriptions to be removed and then click Remove Selected.
  4. To add subscriptions, select Add, select the check boxes to the left of the subscriptions to be added and then click Add Selected.
  5. Select Repository Sets and review the repositories' status settings.
  6. To enable or disable a repository, select the check box for a repository and then change the status using the Select Action list.
  7. Select the Details tab, select a Content View for this Activation Key, and then click Save.

For CLI Users

  1. Export the subscriptions from Satellite Server to a CSV file. For this example, a_keys.csv:

    # hammer --server https://satellite.example.com csv activation-keys \
    --export --file a_keys.csv --organization "Default Organization"
  2. You can view the columns of the file as follows:

    # column -s, -t < a_keys.csv | less -S
    Name  Organization  Description  Limit  Environment  Content View  Host Collections  Auto-Attach  Service Level  Release Version  Subscriptions

    The last column has the subscription information. Note that it is one field in the CSV file and can include a comma in quoted text. Examples of the Subscriptions field include:

    • '"""Automatic|RH1234|Red Hat Enterprise Linux Server, Standard (Physical or Virtual Nodes)|11223344|55667788"""'
    • '1|MCT0369|Red Hat Satellite Capsule Server|11223344|55667788'

      The Subscriptions field has the following format:

      • Number of subscriptions allocated (can be set to Automatic).
      • The subscription’s identification number.
      • The subscription’s name.
      • The contract number.
      • The account number.
  3. Change the required values in the CSV file. You can use an editor, with a CSV plug-in, or sed to change strings in the Subscriptions field.

    1. Make a backup of the file.

      # cp a_keys.csv a_keys.csv.backup
    2. Edit the string you want to change. For example:

      # sed -i "s/Automatic|RH1234|Red Hat Enterprise Linux Server/Automatic|RH4567|Red Hat Enterprise Linux Server/g" a_keys.csv
    3. Confirm only the required changes were made. For example:

      # diff a_keys.csv a_keys.csv.backup
      2c2
      < """Automatic|RH4567|Red Hat Enterprise Linux Server, Standard (Physical or Virtual Nodes)|11223344|55667788"""
      ---
      > """Automatic|RH1234|Red Hat Enterprise Linux Server, Standard (Physical or Virtual Nodes)|11223344|55667788"""
  4. Upload the changed file to Satellite Server.

    # hammer --server https://satellite.example.com csv activation-keys \
    --file a_keys.csv

8.4. Enabling Auto-Attach

When auto-attach is enabled on an activation key and there are subscriptions associated with the key, the subscription management service selects and attaches the best-matched associated subscriptions based on a set of criteria like currently-installed products, architecture, and preferences like service level.

You can enable auto-attach and have no subscriptions associated with the key. This type of key is commonly used to register virtual machines when you do not want the virtual machine to consume a RHEL subscription but to inherit a RHEL Virtual Data Center (VDC) subscription from the hypervisor.

Auto-attach is enabled by default. Disable the option if you want to force attach all subscriptions associated with the activation key.

For Web UI Users

  1. Click Content > Activation Keys.
  2. Click the activation key name that you want to edit.
  3. Click the Subscriptions tab.
  4. Click the edit icon next to Auto-Attach.
  5. Select or clear the check box to enable or disable auto-attach.
  6. Click Save.
Note

To register virtual content hosts to Satellite Server using an auto-attach activation key, first use the virt-who utility to map those hosts to a hypervisor entitled with the Virtual Datacenter (VDC) subscription. Without this prerequisite, virtual hosts are registered only with a temporary virtual subscription for 24 hours. For more information, see Applying Virtual Guest Subscriptions in the Virtual Instances Guide.

For CLI Users

To enable auto-attach on the activation key development-stack:

# hammer activation-key update --name "development-stack" \
--organization "ACME" --auto-attach true

8.5. Setting the Service Level

An activation key can be configured to define a default service level for the new host created with the activation key. Setting a default service level selects only the matching subscriptions to be attached to the host. For example, if the default service level on an activation key is set to Premium, only subscriptions with premium service levels are attached to the host upon registration.

For Web UI Users

  1. Click Content > Activation Keys.
  2. Click the activation key name you want to edit.
  3. Click the edit icon next to Service Level.
  4. Select the required service level from the list. The list only contains service levels available to the activation key.
  5. Click Save.

For CLI Users

To set a default service level to Premium on the activation key development-stack:

# hammer activation-key update --name "development-stack" \
--organization "ACME" --service-level premium

8.6. Chapter Summary

This chapter discussed activation keys, demonstrated how to create them, and how systems register to a Satellite Server with them.

The next chapter explores errata management, including how to apply errata to a system.