Registering hosts and setting up host integration

You must register hosts that have not been provisioned through orcharhino to be able to manage them with orcharhino. You can register hosts through orcharhino Server or orcharhino Proxy Server.

You must also install and configure tools on your hosts, depending on which integration features you want to use. Use the following procedures to install and configure host tools:

Registering a host to orcharhino temporarily adds repository files on your host to install subscription-manager and its dependencies. Those temporary repositories are removed before registering your host to orcharhino. After your host is registered to orcharhino, it has access to the content depending on its activation key.

Supported clients in registration

orcharhino supports the following operating systems and architectures for registration.

Supported host operating systems

The hosts can use the following operating systems:

  • AlmaLinux

  • Amazon Linux

  • CentOS

  • Debian

  • Oracle Linux

  • Red Hat Enterprise Linux

  • Rocky Linux

  • SUSE Linux Enterprise Server

  • Ubuntu

Supported host architectures

The hosts can use the following architectures:

  • AMD and Intel 64-bit architectures are supported for all operating systems

  • The 64-bit ARM architecture and IBM Power Systems, Little Endian, are supported for certain operating systems

    For more information, see orcharhino Clients gen3 in the ATIX Service Portal.

Registration methods

You can use the following methods to register hosts to orcharhino:

Global registration

You generate a registration command from orcharhino and run this command on an unlimited number of hosts to register them by using provisioning templates over the orcharhino API. For more information, see Registering Hosts by Using Global Registration.

By using this method, you can also deploy orcharhino SSH keys to hosts during registration to orcharhino to enable hosts for remote execution jobs. For more information, see Configuring and Setting Up Remote Jobs.

Registering hosts by using global registration

You can register a host to orcharhino by generating a curl or wget command on orcharhino and running this command on hosts. This method uses two provisioning templates: Global Registration template and Linux host_init_config default template. That gives you complete control over the host registration process.

You can also customize the default templates if you need greater flexibility. For more information, see Customizing the Registration Templates.

If you use the Resource Quota plugin, registered hosts are automatically assigned to the Unassigned resource quota. However, if you have the setting Resource Quota optional assignment set to No and no quotas to that a host can be assigned to, the host registration will fail because there is no valid quota the host can be assigned to. For more information, see Limiting host resources in Administering orcharhino.

Global parameters for registration

You can configure the following global parameters by navigating to Configure > Global Parameters:

  • The host_registration_insights parameter is used in the insights snippet. If the parameter is set to true, the registration installs and enables the Red Hat Insights client on the host. If the parameter is set to false, orcharhino prevents the installation and registration of the Red Hat Insights client. The default value is false. When overriding the parameter value, set the parameter type to boolean.

  • The host_registration_insights_inventory parameter controls Inventory uploads. If the parameter is set to true, the host is included in the Insights Inventory report uploaded to the Red Hat Hybrid Cloud Console. If the parameter is set to false, the host is excluded from the Insights Inventory report upload. To upload inventory data without registering the host with the Insights client, set the host_registration_insights parameter to false and set the host_registration_insights_inventory to true.

  • The host_packages parameter is for installing packages on the host.

  • The host_registration_remote_execution parameter is used in the remote_execution_ssh_keys snippet. If it is set to true, the registration enables remote execution on the host. The default value is true.

  • The remote_execution_ssh_keys, remote_execution_ssh_user, remote_execution_create_user, and remote_execution_effective_user_method parameters are used in the remote_execution_ssh_keys snippet. For more details, see the snippet.

  • The skip_unmanaged_repositories_cleanup parameter is used to skip removing unmanaged repositories on hosts. By default, the value is false and orcharhino removes all Deb content as part of the registration process.

    Set the parameter to true if you want hosts to still have access to their original content after registration, for example, upstream Debian repositories.

You can navigate to snippets in the orcharhino management UI through Hosts > Templates > Provisioning Templates.

Configuring a host for registration

Configure your host for registration to orcharhino Server or orcharhino Proxy Server. You can use a configuration management tool to configure multiple hosts at once.

Prerequisites

  • The host must be using a supported operating system. For more information, see supported clients in registration.

  • The system clock on your orcharhino Server and any orcharhino Proxy Servers must be synchronized across the network. If the system clock is not synchronized, SSL certificate verification might fail. For example, you can use the Chrony suite for timekeeping.

Procedure

  1. Enable and start a time-synchronization tool on your host. The host must be synchronized with the same NTP server as orcharhino Server and any orcharhino Proxy Servers.

  2. Deploy the SSL CA file on your host so that the host can make a secured registration call.

    1. Find where orcharhino stores the SSL CA file by navigating to Administer > Settings > Authentication and locating the value of the SSL CA file setting.

    2. Transfer the SSL CA file to your host securely, for example by using scp.

    3. Login to your host by using SSH.

    4. Copy the certificate to the truststore:

      • On Debian:

        $ cp My_SSL_CA_file.pem /usr/local/share/ca-certificates/

    5. Update the truststore:

      • On Debian:

        $ update-ca-certificates

Registering a host

You can register a host by using registration templates and set up various integration features and host tools during the registration process.

Prerequisites

  • Your orcharhino account has the Register hosts role assigned or a role with equivalent permissions.

  • You must have root privileges on the host that you want to register.

  • You must have installed either curl or wget on the host that you want to register.

  • You have configured your host for registration. For more information, see Configuring a Host for Registration.

  • An activation key must be available for your host. For more information, see Managing Activation Keys in Managing Content.

  • orcharhino Client for Debian repository for the operating system version of the host is synchronized on orcharhino Server and enabled in the activation key you use. This repository is required for the remote execution pull client, Puppet agent, Tracer, and other tools.

  • If you want to use orcharhino Proxy Servers instead of your orcharhino Server, ensure that you have configured your orcharhino Proxy Servers accordingly. For more information, see Configuring orcharhino Proxy for Host Registration and Provisioning in Installing orcharhino Proxy Server.

  • If your orcharhino Server or orcharhino Proxy Server is behind an HTTP proxy, configure the Subscription Manager on your host to use the HTTP proxy for connection.

  • Ensure that your host has gpg installed to import the GPG public key.

  • You have configured the operating system entry on orcharhino for Debian.

    You can use a script to add operating system entries to your orcharhino Server.

    On your orcharhino Server, uncomment the operating systems and orcharhino Client for Debian that you want to add in /etc/orcharhino-ansible/or_operating_systems_vars.yaml, replace the default organization and location names, and run /opt/orcharhino/automation/play_operating_systems.sh. For more information, see /usr/share/orcharhino-ansible/README.md on your orcharhino Server.
Procedure

  1. In the orcharhino management UI, navigate to Hosts > Register Host.

  2. Enter the details for how you want the registered host to be configured.

    • If you select a host group from the Host Group list, the following fields inherit their values from the host group:

      • Operating system

      • Activation Keys

      • Lifecycle environment

    • A orcharhino Proxy behind a load balancer takes precedence over the orcharhino Proxy selected in the orcharhino management UI as the content source of the host.

  3. On the General tab, in the Activation Keys field, enter one or more activation keys to assign to your host.

  4. On the Advanced tab, in the Repositories field, enter the orcharhino Client for Debian repository.

    • In the Repository field, enter the orcharhino Client for Debian repository, for example, deb http://orcharhino.example.com/pulp/content/Example/Library/custom/debian_client/debian_client/ stable main.

    • In the Repository GPG key URL field, enter the URL of the pulp_deb_signing.key file on your orcharhino Proxy as GPG public key to verify synchronized Deb content, for example, https://orcharhino.example.com/pub/pulp_deb_signing.key.

  5. Click Generate to generate a curl command.

  6. Run the curl command as root on the host that you want to register. After registration completes, any Ansible roles assigned to a host group you specified when configuring the registration template will run on the host.

The registration details that you can specify include the following:

  • On the General tab, in the orcharhino Proxy field, you can select the orcharhino Proxy to register your host through. A orcharhino Proxy behind a load balancer takes precedence over a orcharhino Proxy selected in the orcharhino management UI as the content source of the host.

  • On the General tab, in the Download utility field, you can select wget if you want to register your host by using a wget command. By default, orcharhino generates a curl command.

  • On the General tab, you can select the Insecure option to make the first call insecure. During this first call, your host downloads the CA file from orcharhino. Your host will use this CA file to connect to orcharhino with all future calls making them secure.

    ATIX AG recommends that you avoid insecure calls.

    If an attacker, located in the network between orcharhino and your host, fetches the CA file from the first insecure call, the attacker will be able to access the content of the API calls to and from your host and the JSON Web Tokens (JWT). Therefore, if you have chosen to deploy SSH keys during registration, the attacker will be able to access your host using the SSH key.

  • On the Advanced tab, you can configure remote execution, Red Hat Insights, and packages to be installed.

  • On the Advanced tab, in the Token lifetime (hours) field, you can change the validity duration of the JSON Web Token (JWT) that orcharhino uses for authentication. The duration of this token defines how long the generated registration command works.

    Note that orcharhino applies the permissions of the user who generates the registration command to authorization of your host. If the user loses or gains additional permissions, the permissions of the JWT change too. Therefore, do not delete, block, or change permissions of the user during the token duration.

    The scope of the JWTs is limited to the registration endpoints only and cannot be used anywhere else.

orcharhino generates the registration command with parameters that search resources by ID. You can edit the registration command to search the following resources by title:

Organization

URL fragment example: organization=My%20Organization or organization=My+Organization

Location

URL fragment example: location=My%20Location or location=My+Location

Host group

If a host group is nested, include the parent group separated with the slash character (/).

URL fragment example: hostgroup=Parent%20Group%2FMy%20Host%20Group

Operating system

URL fragment example: operatingsystem=My%20Operating%20System or operatingsystem=My+Operating+System

The parameter values must be URL encoded.
CLI procedure

  1. Use the hammer host-registration generate-command to generate the registration command to register your host.

  2. On your host that you want to register, run the registration command as root.

For more information, see the Hammer CLI help with hammer host-registration generate-command --help.

Ansible procedure

  • Use the "`theforeman.foreman`".registration_command module.

For more information, see the Ansible module documentation with ansible-doc "`theforeman.foreman`".registration_command.

API procedure

  • Use the POST /api/registration_commands resource.

For more information, see the full API reference at https://orcharhino.example.com/apidoc/v2.html.

Next steps

If running remote execution jobs fail on your registered host due to Could not resolve hostname: Name or service not known, disable Ignore interfaces facts for provisioning.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > All hosts.

  2. Locate your registered host and click Edit.

  3. On the Interfaces tab, check if the host has an IP address. If the host has no IP address, continue with this procedure.

  4. In the orcharhino management UI, navigate to Administer > Settings.

  5. On the Facts tab, set Ignore interfaces facts for provisioning to No. This ensures that an IP address is assigned to the host during registration.

Customizing host registration by using snippets

You can customize the registration process by creating snippets with pre-defined names. The Global Registration template includes these snippets automatically. Therefore, you do not have to edit the template.

To add custom steps to registration, create one or both of the following snippets:

before_registration

This snippet is loaded and executed by the Global Registration template before registering your host to orcharhino.

after_registration

This snippet is loaded and executed by the Global Registration template after registering your host to orcharhino.

Ensure you name the snippets precisely. Otherwise, the Global Registration template cannot load them.

Prerequisites

  • Your orcharhino account has a role that grants the permissions view_provisioning_templates, create_provisioning_templates, assign_organizations, and assign_locations.

  • You have selected a particular organization and location context.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates.

  2. Click Create Template.

  3. In the Name field, enter the name of the required snippet: before_registration or after_registration.

  4. In the template editor, create your snippet.

  5. On the Type tab, select Snippet.

  6. On the Locations tab, assign the snippet to required locations.

  7. On the Organizations tab, assign the snippet to required organizations.

  8. Click Submit.

Additional resources

Customizing the registration templates

You can customize the registration process by editing the provisioning templates. Note that all default templates in orcharhino are locked. If you want to customize the registration templates, you must clone the default templates and edit the clones.

ATIX AG only provides support for the original unedited templates. Customized templates do not receive updates released by ATIX AG.

The registration process uses the following provisioning templates:

  • The Global Registration template contains steps for registering hosts to orcharhino. This template renders when hosts access the /register orcharhino API endpoint.

  • The Linux host_init_config default template contains steps for initial configuration of hosts after they are registered.

Procedure

  1. Navigate to Hosts > Templates > Provisioning Templates.

  2. Search for the template you want to edit.

  3. In the row of the required template, click Clone.

  4. Edit the template as needed. For more information, see Template Writing Reference.

  5. Click Submit.

  6. Navigate to Administer > Settings > Provisioning.

  7. Change the following settings as needed:

    • Point the Default Global registration template setting to your custom global registration template,

    • Point the Default 'Host initial configuration' template setting to your custom initial configuration template.

Invalidating registration tokens

When you generate a registration command in global host registration, orcharhino also generates a unique JSON Web Token (JWT) that is used to authorize the registration call from a host to orcharhino Server. This JWT is bound to the user that generated the registration command.

Users can configure a custom validity duration for the JWT. If the validity duration is too long or if the JWT has been compromised, the JWT poses a security concern. To mitigate this concern, the orcharhino administrator or users with adequate permissions can invalidate existing JWTs.

You can also temporarily disable registration tokens by disabling a user. When you reenable the user, the user will be able to continue using their registration tokens.

Invalidating your own JWTs

You can invalidate all registration JSON Web Tokens of the current user.

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

To use the API, see the API procedure.

Procedure

  1. In the orcharhino management UI, click the user menu in the top bar and select My Account.

  2. Select the Registration Tokens tab.

  3. Click Invalidate JWTs.

  4. In the confirmation window, click Confirm.

Verification

  • The orcharhino management UI displays the following message: Successfully invalidated registration tokens.

CLI procedure

  • Invalidate all your registration tokens by running Hammer:

    $ hammer user registration-token invalidate --user-id My_User_ID
API procedure

  • Use the DELETE /api/users/:user_id/registration_tokens resource.

For more information, see the full API reference at https://orcharhino.example.com/apidoc/v2.html.

Invalidating JWTs of other users

You can invalidate all registration JSON Web Tokens of one or more users.

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

To use the API, see the API procedure.

Prerequisites

  • Your orcharhino user has a role that grants the edit_users permissions. For orcharhino management UI, you also require the view_users permission.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Users.

  2. In the row of the user whose registration tokens you want to invalidate, from the actions menu, select Invalidate JWTs.

  3. In the confirmation window, click Confirm.

Verification

  • The orcharhino management UI displays the following message: Successfully invalidated registration tokens for the user.

CLI procedure

  • Invalidate all registration tokens of a single user by running Hammer:

    $ hammer user registration-token invalidate --user-id User_ID

  • Invalidate all registration tokens of multiple users by running Hammer:

    $ hammer user registration-token invalidate-multiple --search "My_Search_Query"
API procedure

  • Invalidate all registration tokens of a single user by using the DELETE /api/users/:user_id/registration_tokens resource.

  • Invalidate all registration tokens of multiple users by using the DELETE /api/registration_tokens?search=url-encoded-search-query resource.

For more information, see the full API reference at https://orcharhino.example.com/apidoc/v2.html.

Additional resources

Invalidating JWTs of all users

You can invalidate all registration JSON Web Tokens of all users at once in the orcharhino management UI.

Prerequisites

  • Your orcharhino user has a role that grants the view_users and edit_users permissions.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Users.

  2. Click Invalidate JWTs for all users.

  3. In the confirmation window, click Confirm.

Verification

  • The orcharhino management UI displays the following message: Successfully invalidated registration tokens for all users.

Installing and configuring Puppet agent during host registration

You can install and configure the Puppet agent on the host during registration. A configured Puppet agent is required on the host for Puppet integration with your orcharhino. For more information about Puppet, see Configuring hosts by using Puppet.

Prerequisites

  • Puppet must be enabled in your orcharhino. For more information, see Enabling Puppet integration with orcharhino in Configuring hosts by using Puppet.

  • You created a product and repository containing the Puppet agent and synchronized the repository to orcharhino. For more information, see Importing content in Managing Content.

  • You created an activation key that enables the Puppet agent repository for hosts. For more information, see Managing activation keys in Managing Content.

Procedure

  1. In the orcharhino management UI, navigate to Configure > Global Parameters to add host parameters globally. Alternatively, you can navigate to Configure > Host Groups and edit or create a host group to add host parameters only to a host group.

  2. Enable the Puppet agent using a host parameter in global parameters or a host group.

    • To use Puppet 8, add a host parameter named enable-puppet8, select the boolean type, and set the value to true.

    • To use Puppet 7, add a host parameter named enable-puppet7, select the boolean type, and set the value to true.

  3. Specify configuration for the Puppet agent using the following host parameters in global parameters or a host group:

    • Add a host parameter named puppet_server, select the string type, and set the value to the hostname of your Puppet server, such as puppet.example.com.

    • Optional: Add a host parameter named puppet_ca_server, select the string type, and set the value to the hostname of your Puppet CA server, such as puppet-ca.example.com. If puppet_ca_server is not set, the Puppet agent will use the same server as puppet_server.

    • Optional: Add a host parameter named puppet_environment, select the string type, and set the value to the Puppet environment you want the host to use.

  4. Navigate to Hosts > Register Host and register your host using an appropriate activation key. For more information, see Registering hosts by using global registration in Managing Hosts.

  5. Navigate to Infrastructure > orcharhino Proxies.

  6. From the list in the Actions column for the required orcharhino Proxy Server, select Certificates.

  7. Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.

Installing and configuring Puppet agent manually

You can install and configure the Puppet agent on a host manually. A configured Puppet agent is required on the host for Puppet integration with your orcharhino. For more information about Puppet, see Configuring hosts by using Puppet.

Prerequisites
Procedure

  1. Log in to the host as the root user.

  2. Install the Puppet agent package:

    $ apt-get install puppet-agent

  3. Add the Puppet agent to PATH in your current shell using the following script:

    . /etc/profile.d/puppet-agent.sh

  4. Configure the Puppet agent. Set the environment parameter to the name of the Puppet environment to which the host belongs:

    $ puppet config set server orcharhino.example.com --section agent
$ puppet config set environment My_Puppet_Environment --section agent

  5. Start the Puppet agent service:

    $ puppet resource service puppet ensure=running enable=true

  6. Create a certificate for the host:

    $ puppet ssl bootstrap

  7. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.

  8. From the list in the Actions column for the required orcharhino Proxy Server, select Certificates.

  9. Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.

  10. On the host, run the Puppet agent again:

    $ puppet ssl bootstrap

Running Ansible roles during host registration

You can run Ansible roles when you are registering a host to orcharhino.

Prerequisites
Procedure

  1. Create a host group with Ansible roles. For more information, see Creating a Host Group.

  2. Register the host by using the host group with assigned Ansible roles. For more information, see registering a host.

Using custom SSL certificate for hosts

You can use custom SSL certificate on your hosts to enable encrypted communications between orcharhino Server, orcharhino Proxy Server, and hosts. Before deploying it to your hosts, ensure that you have configured the custom SSL certificate to your orcharhino Server.

Deploying a custom SSL certificate to hosts

After you configure orcharhino to use a custom SSL certificate, you must deploy the certificate to hosts registered to orcharhino.

Procedure

  • Update the SSL certificate on each host:

    $ wget http://orcharhino.example.com/pub/katello-rhsm-consumer
$ chmod +x katello-rhsm-consumer
$ ./katello-rhsm-consumer

Resetting custom SSL certificate to default self-signed certificate on hosts

To reset the custom SSL certificate on your hosts to default self-signed certificate, you must re-register your hosts through Global Registration. For more information, see Registering Hosts by Using Global Registration.

Additional resources

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").