Managing activation keys

Activation keys provide a method to automate system registration. You can create multiple keys and associate them with different environments and content views. For example, you might create a basic activation key that enables certain Red Hat repositories and associate it with the appropriate content view.

You can use activation keys during content host registration to improve the speed, simplicity and consistency of the process. 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.

Activation keys can define the following properties for content hosts:

Available products and repositories
A lifecycle environment and a content view
Host collection membership
System purpose

Content view conflicts between host creation and registration

When you provision a host, orcharhino 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 orcharhino 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.

Using multiple activation keys with a content host

A 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. You can specify the order of precedence by setting a host group parameter as follows:

$ hammer hostgroup set-parameter \
--hostgroup "My_Host_Group" \
--name "My_Activation_Key" \
--value "name_of_first_key", "name_of_second_key", ...

Best practices for activation keys

Create an activation key for each use case. This structures, modularizes, and simplifies content management on hosts.
Use a naming convention for activation keys to indicate the content and lifecycle environment, for example, debian-webserver.
Automate activation key management by using a Hammer script or an Ansible Playbook.

Creating an activation key

Create an activation key to assign various attributes to hosts during registration.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure

In the orcharhino management UI, navigate to Content > Lifecycle > Activation Keys and click Create Activation Key.
In the Name field, enter the name of the activation key.
If you want to set a limit, clear the Unlimited hosts checkbox, 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 checkbox is selected.
Optional: In the Description field, enter a description for the activation key.
From the Environment list, select the environment to use.
From the Content View list, select a content view to use.
Click Save.

CLI procedure

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"

List the product content associated with the activation key:

$ hammer activation-key product-content \
--content-access-mode-all true \
--name "My_Activation_Key" \
--organization "My_Organization"

Override the default auto-enable status for the orcharhino Client for Debian 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 orcharhino Client \
--value 1 \
--organization "My_Organization"
```

Using activation keys for host registration

You can use activation keys to complete the following tasks:

Registering new hosts during provisioning through orcharhino. The Kickstart provisioning templates in orcharhino contain commands to register the host using an activation key that is defined when creating a host.
Registering existing Debian hosts.

You can register hosts with orcharhino using the host registration feature in the orcharhino management UI, Hammer CLI, or the orcharhino API. For more information, see Registering Hosts in Managing Hosts.

Procedure

In the orcharhino management UI, navigate to Hosts > Register Host.
From the Activation Keys list, select the activation keys to assign to your host.
Click Generate to create the registration command.
Click on the files icon to copy the command to your clipboard.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

CLI procedure

Generate the host registration command using the Hammer CLI:
```
$ hammer host-registration generate-command \
--activation-keys "My_Activation_Key"
```
If your hosts do not trust the SSL certificate of orcharhino Server, you can disable SSL validation by adding the --insecure flag to the registration command.
```
$ hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true
```
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

API procedure

Generate the host registration command using the orcharhino API:
```
$ curl -X POST https://orcharhino.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"] }}'
```
If your hosts do not trust the SSL certificate of orcharhino Server, you can disable SSL validation by adding the --insecure flag to the registration command.
```
$ curl -X POST https://orcharhino.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"], "insecure": true }}'
```
Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in Managing Content.

To enter a password as a command line argument, use username:password syntax. Keep in mind this can save the password in the shell history. Alternatively, you can use a temporary personal access token instead of a password. To generate a token in the orcharhino management UI, navigate to My Account > Personal Access Tokens.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

Multiple activation keys

You can use multiple activation keys when registering a content host. For example, you can use one activation key to enable specific repositories and another to assign a content view and lifecycle environment.

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: Host Collections.
Settings that influence the behavior of the key itself and not the host configuration: Content Host Limit.

Enabling and disabling repositories on activation key

You can enable or disable repositories on an activation key in the orcharhino management UI.

Procedure

In the orcharhino management UI, navigate to Content > Lifecycle > Activation Keys.
Select an activation key.
Select the Repository Sets tab.
Optional: Clear the Limit to Environment checkbox to view repositories that are available in the lifecycle environment of the activation key.
Optional: Use the Repository type dropdown menu to filter repositories by type.
Optional: Use the Status dropdown menu to filter repositories by status.
Select the desired repositories or click the Select All checkbox to select all repositories.
From the Select Action list, select Override to Enabled, Override to Disabled, or Reset to Default.

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").