Chapter 9. Managing Activation Keys

Activation keys provide a method to automate system registration and subscription attachment. You 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.

You can use activation keys during content host registration to improve the speed, simplicity and consistency of the process.

Activation keys can define the following properties for content hosts:

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

You can apply the same activation key to multiple content hosts if it contains enough subscriptions. However, activation keys set only the initial configuration for a content host. When the content host is registered to an organization, the organization’s content 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 used only when hosts are registered. If changes are made to an activation key, it is applicable only to hosts that are registered with the amended activation key in the future. The changes are not made to existing hosts.

Content View Conflicts between Host Creation and Registration

When you provision a host, Satellite uses provisioning templates and other content from the Content View that you set in the host group or host settings. When the host is registered, the Content View from the activation key overwrites the original Content View from the host group or host settings. Then Satellite uses the Content View from the activation key for every future task, for example, rebuilding a host.

When you rebuild a host, ensure that you set the Content View that you want to use in the activation key and not in the host group or host settings.

9.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 previous factors, there are three possible scenarios for subscribing with activation keys:

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

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

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

Custom Products

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.

Procedure

To create an activation key, complete the following steps:

  1. In the Satellite web UI, navigate to Content > Activation keys and click Create Activation Key.
  2. In the Name field, enter the name of the activation key.
  3. If you want to set a limit, clear the Unlimited hosts check box, and in the Limit field, enter the maximum number of systems you can register with the activation key. If you want unlimited hosts to register with the activation key, ensure the Unlimited Hosts check box is selected.
  4. In the Description field, enter a description for the activation key.
  5. From the Environment list, select the environment to use.
  6. From the Content View list, select a Content View to use.
  7. Click Save and when your new activation key appears in the Activation Keys window, click the name to edit.
  8. To define which products to attach and repositories to enable upon registration, click the Subscriptions tab, select the subscriptions that you want to add, then click Add.
  9. In the Satellite web UI, navigate to the Product Content page. For example, to enable the Red Hat Satellite Tools repository, for Red Hat Satellite Tools 6.4 (for RHEL 7 Server) (RPMs) - Enabled select Override to Yes.
  10. Click Save.

For CLI Users

  1. Create the activation key:

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

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

    # hammer activation-key add-subscription \
    --name "My_Activation_Key" \
    --subscription-id ff808181533518d50152354246e901aa \
    --organization "My_Organization"
  4. List the product content associated with the activation key:

    # hammer activation-key product-content \
    --name "My_Activation_Key" \
    --organization "My_Organization"
  5. Override the default auto-enable status for the Red Hat Satellite Tools 6.4 repository. The default status is set to disabled. To enable, enter the following command:

    # hammer activation-key content-override \
    --name "My_Activation_Key" \
    --content-label rhel-7-server-satellite-tools-6.4-rpms \
    --value 1 \
    --organization "My_Organization"

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

Note that changes to an activation key apply only to machines provisioned after the change. To update subscriptions on existing content hosts, see Section 4.2.6, “Bulk Updating Content Hosts' Subscriptions”.

Procedure

To update the subscriptions associated with an activation key, complete the following steps:

  1. In the Satellite web UI, navigate to Content > Activation keys and click the name of the activation key.
  2. Click the Subscriptions tab.
  3. To remove subscriptions, select List/Remove, and then select the check boxes to the left of the subscriptions to be removed and then click Remove Selected.
  4. To add subscriptions, select Add, and then select the check boxes to the left of the subscriptions to be added and then click Add Selected.
  5. Click the Repository Sets tab 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. Click the Details tab, select a Content View for this activation key, and then click Save.

For CLI Users

  1. List the subscriptions that the activation key currently contains:

    # hammer activation-key subscriptions \
    --name My_Activation_Key \
    --organization "My_Organization"
  2. Remove the required subscription from the activation key:

    # hammer activation-key remove-subscription \
    --name "My_Activation_Key" \
    --subscription-id ff808181533518d50152354246e901aa \
    --organization "My_Organization"

    For the --subscription-id option, you can use either the UUID or the ID of the subscription.

  3. Attach new subscription to the activation key:

    # hammer activation-key add-subscription \
    --name "My_Activation_Key" \
    --subscription-id ff808181533518d50152354246e901aa \
    --organization "My_Organization"

    For the --subscription-id option, you can use either the UUID or the ID of the subscription.

  4. List the product content associated with the activation key:

    # hammer activation-key product-content \
    --name "My_Activation_Key" \
    --organization "My_Organization"
  5. Override the default auto-enable status for the required repository:

    # hammer activation-key content-override \
    --name "My_Activation_Key" \
    --content-label content_label \
    --value 1 \
    --organization "My_Organization"

    For the --value option, enter 1 for enable, 0 for disable.

9.3. Updating Subscriptions Associated with an Activation Key Using a CSV File

You can update the subscriptions associated with an activation key by downloading a CSV file, making changes to the Activation Key settings, and then uploading the changed CSV file.

Subscription information in the CSV File

In the CSV file, the last column contains the subscription information. Subscription information is one field in the CSV file and can include a comma in quoted text.

The entries in the CSV file have the following format:

Name  Organization  Description  Limit  Environment  Content View  Host Collections  Auto-Attach  Service Level  Release Version  Subscriptions

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. This can be set to Automatic.
  • The subscription’s identification number.
  • The subscription’s name.
  • The contract number.
  • The account number.

Procedure

To update the subscription list using a CSV file, complete the following procedure:

  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 "My_Organization"
  2. To view the columns of the file, enter the following command:

    # column -s, -t < a_keys.csv | less -S
  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.
  4. Make a backup of the file.

    # cp a_keys.csv a_keys.csv.backup
  5. 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
  6. Confirm only the required changes were made. For example:

    # diff a_keys.csv a_keys.csv.backup
  7. Upload the changed file to Satellite Server.

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

9.4. Using Activation Keys for Host Registration

You can use activation keys to complete the following tasks:

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

Procedure

To use an activation key for host registration with an existing Red Hat Enterprise Linux 7 host to Satellite Server, complete the following steps:

  1. Download the consumer RPM for your Satellite Server. This is 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 host 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.

  2. On the host, enter the following command to register the host to Satellite using the activation key:

    # subscription-manager register --activationkey="My_Activation_Key" \
    --org="My_Organization"
  3. To view a list of hosts for an organization, on Satellite Server, enter the following command:

    # hammer host list --organization "My_Organization"
  4. After registering a host to Satellite Server, install the katello-agent package on the host so that it can report back to Satellite Server:

    # yum install katello-agent

    The Red Hat Satellite Tools 6.4 repository provides this package.

Multiple Activation Keys

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

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

Settings Conflicts

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.

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

Procedure

To enable auto-attach, complete the following steps:

  1. In the Satellite web UI, navigate to 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.

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:

# hammer activation-key update --name "My_Activation_Key" \
--organization "My_Organization" --auto-attach true

9.6. Setting the Service Level

You can configure an activation key 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.

Procedure

To set the service level, complete the following steps:

  1. In the Satellite web UI, navigate to 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:

# hammer activation-key update --name "My_Activation_Key" \
--organization "My_Organization" --service-level premium