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.
Note that the entitlement-based subscription model is deprecated and will be removed in a future release. ATIX AG recommends that you use the access-based subscription model of Simple Content Access instead.
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 |
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:
-
x86_64/amd64 is supported for all operating systems
-
aarch64 and ppc64le is supported for certain operating systems
For more information, see orcharhino Client for AlmaLinux in the ATIX Service Portal.
-
Registration methods
You can use the following methods to register hosts to orcharhino:
- Global registration
-
You generate a
curl
orwget
command from orcharhino and run this command from an unlimited number of hosts to register them 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.
- Katello RHSM Consumer script
-
You download and install the consumer script from
orcharhino.example.com/pub/katello-rhsm-consumer
on the host and then run the script. This method is suitable for hosts that run Debian/Ubuntu. - (Deprecated) Katello CA Consumer
-
You download and install the consumer RPM from
orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
on the host and then runsubscription-manager
. - Bootstrap script
-
You download the bootstrap script from
orcharhino.example.com/pub/bootstrap.py
on the host and then run the script. For more information, see Registering Hosts by Using the Bootstrap Script.
ATIX AG recommends using the The Register Host feature is considered a technical preview and only works for managed hosts running AlmaLinux, CentOS, Red Hat Enterprise Linux, and Rocky Linux. |
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.
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 theinsights
snippet. If the parameter is set totrue
, the registration installs and enables the Red Hat Insights client on the host. If the parameter is set tofalse
, it prevents orcharhino and the Red Hat Insights client from uploading Inventory reports to your Red Hat Hybrid Cloud Console. The default value isfalse
. When overriding the parameter value, set the parameter type toboolean
. -
The
host_packages
parameter is for installing packages on the host. -
The
host_registration_remote_execution
parameter is used in theremote_execution_ssh_keys
snippet. If it is set totrue
, the registration enables remote execution on the host. The default value istrue
. -
The
remote_execution_ssh_keys
,remote_execution_ssh_user
,remote_execution_create_user
, andremote_execution_effective_user_method
parameters are used in theremote_execution_ssh_keys
snippet. For more details, see the snippet.
You can navigate to snippets in the orcharhino management UI through Hosts > Templates > Provisioning Templates.
ATIX does not support provisioning AlmaLinux hosts using the minimal ISO image because it does not contain the |
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.
-
Your user account has a role assigned that has the
create_hosts
permission. -
You must have root privileges on the host that you want to register.
-
You must either install
curl
orwget
on the host that you want to register. -
orcharhino Server, any orcharhino Proxy Servers, and your host must be synchronized with the same NTP server, and have a time synchronization tool enabled and running.
-
An activation key must be available for your host. For more information, see Managing Activation Keys in Managing Content.
-
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.
-
You have configured the operating system entry on orcharhino for AlmaLinux.
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 AlmaLinux 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.
-
In the orcharhino management UI, navigate to Hosts > Register Host.
-
Optional: Select a different Organization.
-
Optional: Select a different Location.
-
Optional: From the Host Group list, select the host group to associate your host with. Fields that inherit value from Host group: Operating system, Activation Keys and Lifecycle environment.
-
Optional: From the Operating system list, select the operating system of the host that you want to register.
-
Optional: From the orcharhino Proxy list, 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 host’s content source.
-
In the Activation Keys field, enter one or more activation keys to assign to your host.
-
If you want to use
wget
to register your host to orcharhino, selectwget
in the Download Utility dropdown. By default, orcharhino generates acurl
command. -
If your host does not trust the SSL certificate of your orcharhino Server, select the Insecure option. During the first call, your host downloads the CA file from orcharhino. Your host will use this CA file to connect to orcharhino Server with all future calls.
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.
Instead, you can manually copy and install the CA file on each host before registration.
To do this, find where orcharhino stores the CA file by navigating to Administer > Settings > Authentication and locating the value of the SSL CA file setting.
Copy the CA file to the
/etc/pki/ca-trust/source/anchors/
directory on your host and enter the following commands:# update-ca-trust enable # update-ca-trust
-
Select the Advanced tab.
-
Optional: From the Setup REX list, select whether you want to deploy orcharhino SSH keys to your host or not.
If set to
Yes
, public SSH keys will be installed on the registered host. The inherited value is based on thehost_registration_remote_execution
parameter. It can be inherited, for example from a host group, an operating system, or an organization. When overridden, the selected value will be stored on host parameter level. -
Optional: In the Install packages field, list the packages (separated with spaces) that you want to install on your host upon registration. This can be set by the
host_packages
parameter. -
Optional: Select the Update packages option to update all packages on your host upon registration. This can be set by the
host_update_packages
parameter. -
In the Repositories field, click Add repositories for registration.
On the Repository list window, add content that is required before performing the registration. For example, it can be useful to make the
subscription-manager
package available for the purpose of the registration.-
In the Repository field, enter a repository to be added before the registration is performed. For AlmaLinux, enter the path to the orcharhino Client for AlmaLinux repository, for example
http://orcharhino.example.com/pulp/content/Example/Library/custom/almalinux_client/almalinux_client/
. -
Optional: In the Repository GPG key URL field, specify the public key to verify the signatures of GPG-signed packages. It needs to be specified in the ASCII form with the GPG public key header.
You do not have to specify repositories if you provide them in an activation key.
-
-
Optional: In the Token lifetime (hours) field, 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. You can set the duration to 0 – 999 999 hours or unlimited.
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.
-
Optional: In the Remote Execution Interface field, enter the identifier of a network interface that your host must use for the SSH connection. If you keep this field blank, orcharhino uses the default network interface.
-
Optional: From the REX pull mode list, select whether you want to deploy orcharhino remote execution pull client.
If set to
Yes
, the remote execution pull client is installed on your host. The inherited value is based on thehost_registration_remote_execution_pull
parameter. It can be inherited, for example from a host group, an operating system, or an organization. When overridden, the selected value is stored on the host parameter level.The registered host must have access to the ATIX AG orcharhino Client for AlmaLinux repository.
For more information about the pull mode, see Transport Modes for Remote Execution in Managing Hosts.
-
Optional: Select the Ignore errors option if you want to ignore subscription manager errors.
-
Optional: Select the Force option if you want to remove any
katello-ca-consumer
packages before registration and runsubscription-manager
with the--force
argument. -
Click Generate.
-
Copy the generated registration command.
-
On the host that you want to register, run the copied command as
root
.
If running remote execution jobs fail on your registered host due to Procedure
|
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.
-
Your orcharhino account has a role that grants the permissions
view_provisioning_templates
,create_provisioning_templates
,assign_organizations
, andassign_locations
. -
You have selected a particular organization and location context.
-
In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates.
-
Click Create Template.
-
In the Name field, enter the name of the required snippet:
before_registration
orafter_registration
. -
In the template editor, create your snippet.
-
On the Type tab, select Snippet.
-
On the Locations tab, assign the snippet to required locations.
-
On the Organizations tab, assign the snippet to required organizations.
-
Click Submit.
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.
-
Navigate to Hosts > Templates > Provisioning Templates.
-
Search for the template you want to edit.
-
In the row of the required template, click Clone.
-
Edit the template as needed. For more information, see Template Writing Reference.
-
Click Submit.
-
Navigate to Administer > Settings > Provisioning.
-
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.
-
Registering Hosts Using the Bootstrap Script
orcharhino comes with a bootstrap.py
script to register existing hosts to orcharhino.
It is available on your orcharhino Server at https://orcharhino.example.com/pub/bootstrap.py
.
ATIX AG recommends creating a backup or snapshot of your host before running the bootstrap script.
-
You need root access on any hosts you want to register to orcharhino.
-
Hosts need to be able to communicate with orcharhino Server or orcharhino Proxy Servers through HTTP(S).
-
If you use a self-signed certificate on your orcharhino, ensure that hosts trust the SSL certificate before running the
bootstrap.py
script. -
You have created an activation key for the host that contains the necessary software content. For more information, see Creating an Activation Key.
-
You have configured a host group to manage the hosts through orcharhino. For more information, see Creating a Host Group.
Ensure to select a host group without any predefined deploy on compute resource. Otherwise, registering an existing host starts deploying a new host to the compute resource selected in the deploy on drop down menu.
-
You have synchronized the orcharhino Client for AlmaLinux. Navigate to Content > Products, select the orcharhino Clients product, select the orcharhino Client repository on the Repositories tab, and select the appropriate orcharhino Client repository. Pass the Published At URL using
--deps-repository-url
, for example--deps-repository-url https://orcharhino.example.com/pulp/content/Example/Library/custom/almalinux_Client/almalinux_9_Client/
. For more information, see Adding orcharhino Clients. -
Your host has access to the BaseOS repository that provides
subscription-manager
and its dependencies. -
You have provided the required content credentials from your orcharhino Server to your host:
# curl --insecure https://My_User_Name:My_Password@orcharhino.example.com/katello/api/content_credentials/My_ID/content > /etc/pki/rpm-gpg/RPM-GPG-KEY-kt-bootstrap
-
Download the
bootstrap.py
script usingwget
:# wget https://orcharhino.example.com/pub/bootstrap.py
-
Use the
--help
option to display a list of mandatory options:# python bootstrap.py --help
-
Register an existing host to orcharhino:
# ./bootstrap.py \ --fqdn "my-host.example.com" \ --skip "puppet" \ -L "Munich" \ -a "almalinux" \ -g "AlmaLinux" \ -l "admin" \ -o "Example" \ -p "password" \ --deps-repository-url https://orcharhino.example.com/pulp/content/Example/Library/custom/almalinux_Client/almalinux_9/ \ --deps-repository-gpg-key file:///etc/pki/rpm-gpg/RPM-GPG-KEY-kt-bootstrap \ -s "orcharhino.example.com"
You can provide multiple dependency repositories and GPG public keys for dependency repositories. Ensure that the number and order of the GPG public keys matches the number and order of the repository URLs.
-
Use
--deps-repository-url
with the Published At URL of the orcharhino Client repository. -
Use
--deps-repository-gpg-key
with the required GPG public key of the orcharhino Client repository. -
Optional: Add further instances of
--deps-repository-url
and--deps-repository-gpg-key
if you require additional dependency repositories. -
Use
--fqdn
to specify the FQDN of the new host, for example--fqdn my-host.example.com
. -
Use
-L
to specify the location, for example-L Munich
. -
Use
-a
to specify the activation key, for example-a almalinux
or-a almalinux_puppet
. -
Use
-g
to add the host to a host group, for example-g "AlmaLinux with Puppet"
. -
Use
-l
to specify your orcharhino user, for example-l admin
. -
Use
-o
to specify your organization, for example-o Example
. -
Use
-p
to specify your corresponding password, for example-p password
. -
Use
-s
to specify your orcharhino FQDN, for example-s orcharhino.example.com
. -
Optional: Use
--skip "puppet"
to skip the installation of Puppet.You can use additional options to have orcharhino manage DHCP, provisioning, and configuration management for your existing host.
-
Using a Custom User for Remote Execution for bootstrap.py
If you set the remote execution user, you must create that user prior to running the bootstrap.py
script on the host.
-
Install
sudo
on your managed host:# dnf install -y sudo
-
Add your custom user:
# useradd -m My_Custom_User
-
Set up SSH for your custom user:
# mkdir -p ~My_Custom_User/.ssh # chmod 0700 ~My_Custom_User/.ssh # chown -R My_Custom_User: ~My_Custom_User/.ssh
-
Add your custom user to the
sudoers
file:# echo "My_Custom_User ALL = (root) NOPASSWD : ALL" >> /etc/sudoers # echo "Defaults:_My_Custom_User_ My_Custom_User_Password" >> /etc/sudoers
-
Run the
bootstrap.py
script:# ./bootstrap.py --force
Add required flags and options as described in Registering Hosts Using the Bootstrap Script.
Associating Registered Hosts with a Compute Resource
If you register hosts to orcharhino using the bootstrap.py
script, the hosts are not automatically associated with their compute resource.
You have to manually disassociate the host and then reassociate it again.
-
Navigate to Hosts > All Hosts and select your host.
-
In the Select Action menu, click Disassociate Hosts.
-
Navigate to Infrastructure > Compute Resources and select your compute resource.
-
Click Associate VMs.
-
In case your orcharhino Server or orcharhino Proxies run on the same compute resource, disassociate the VMs on the All Hosts page again.
Registering Hosts Running AlmaLinux Manually
-
Install
subscription-manager
on your host:# dnf install subscription-manager
-
Install the necessary certificates to connect to orcharhino:
# rpm -Uvh http://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
-
Register your host with an activation key:
# subscription-manager register \ --activationkey="Myalmalinux_Activation_Key_" \ --name="almalinux.example.com" \ --org="My_Organization"
-
Install
katello-host-tools
on your host:# dnf install katello-host-tools katello-host-tools-tracer
-
To use remote execution, add the SSH public key from orcharhino Server. For more information, see Adding SSH Keys for Remote Execution.
Adding SSH Keys for Remote Execution
Add the SSH public key from orcharhino to your managed hosts to use remote execution and to patch your hosts.
-
Create the required directory:
# mkdir -p ~root/.ssh
-
Add the SSH public key from your orcharhino:
# cat << EOF >> ~root/.ssh/authorized_keys ssh-rsa My_SSH_Public_Key foreman-proxy@orcharhino.example.com EOF
Ensure that you use a user with root privileges. This can either be
root
or any user being part of thesudo
group.
Associating Registered Hosts with a Compute Resource
If you register hosts to orcharhino manually, the hosts are not automatically associated with their compute resource. You have to manually enter networking information before you can associate the VMs.
-
On your managed hosts, view the MAC address, IP address, and device identifier of the network interface providing a connection to your orcharhino:
# ip a
-
Navigate to Hosts > All Hosts, select your host, and click Edit.
-
On the Interfaces tab, click Edit and enter the MAC address, IPv4 address, and the device identifier.
-
Click Submit to save your changes.
-
Navigate to Hosts > All hosts and tick the checkbox of your host.
-
In the Select Action drop down menu, click Disassociate Hosts.
-
Navigate to Infrastructure > Compute Resources and select the compute resource your host runs on.
-
On the Compute Resources tab, click Associate VMs.
-
Optional: Navigate to Hosts > All Hosts, select your host, and verify your change by changing the power status of the host.
Installing Tracer
Use this procedure to install Tracer on orcharhino and access Traces. Tracer displays a list of services and applications that are outdated and need to be restarted. Traces is the output generated by Tracer in the orcharhino management UI.
-
The host must be registered to orcharhino.
-
The ATIX AG orcharhino Client for AlmaLinux repository must be enabled and synchronized on orcharhino Server, and enabled on the host.
-
On the content host, install the
katello-host-tools-tracer
RPM package:# yum install katello-host-tools-tracer
-
Enter the following command:
# katello-tracer-upload
-
In the orcharhino management UI, navigate to Hosts > All Hosts, then click the required host name.
-
Click the Traces tab to view Traces. If it is not installed, an Enable Traces button initiates a remote execution job that installs the package.
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 Using Puppet.
-
Puppet must be enabled in your orcharhino. For more information, see Enabling Puppet integration with orcharhino in Configuring Hosts 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.
-
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.
-
Enable the Puppet agent using a host parameter in global parameters or a host group. Add a host parameter named
enable-puppet7
, select the boolean type, and set the value totrue
. -
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 aspuppet.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 aspuppet-ca.example.com
. Ifpuppet_ca_server
is not set, the Puppet agent will use the same server aspuppet_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.
-
-
Navigate to Hosts > Register Host and register your host using an appropriate activation key. For more information, see Registering Hosts in Managing Hosts.
-
Navigate to Infrastructure > orcharhino Proxies.
-
From the list in the Actions column for the required orcharhino Proxy Server, select Certificates.
-
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 Using Puppet.
-
Puppet must be enabled in your orcharhino. For more information, see Enabling Puppet Integration with orcharhino in Configuring Hosts Using Puppet.
-
The host must have a Puppet environment assigned to it.
-
Ensure a repository containing the Puppet agent is enabled on the host, for example Puppet agent for AlmaLinux.
-
Log in to the host as the
root
user. -
Install the Puppet agent package:
# dnf install puppet-agent
-
Add the Puppet agent to
PATH
in your current shell using the following script:. /etc/profile.d/puppet-agent.sh
-
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
-
Start the Puppet agent service:
# puppet resource service puppet ensure=running enable=true
-
Create a certificate for the host:
# puppet ssl bootstrap
-
In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.
-
From the list in the Actions column for the required orcharhino Proxy Server, select Certificates.
-
Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.
-
On the host, run the Puppet agent again:
# puppet ssl bootstrap
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"). |