Registering Hosts
You can register existing hosts with orcharhino. There are three methods to register an existing host with orcharhino: running the bootstrap script, manually installing the subscription manager, or by using the register host page.
For a better understanding of provisioning hosts using orcharhino, see our glossary for terminology and key terms. Key terms include deployment, compute resource, provisioning template, and virtualization. |
We recommend using the The Register Host feature is considered a technical preview and only works for managed hosts running Alma Linux, CentOS, Red Hat Enterprise Linux, and Rocky Linux. |
Registering Hosts
Hosts can be registered to orcharhino by generating a curl
command on orcharhino and running this command on hosts.
This method uses two templates: global registration
template and host initial configuration
template.
That gives you complete control over the host registration process.
You can set default templates by navigating to Administer > Settings, and clicking the Provisioning tab.
-
The orcharhino user that generates the
curl
command must have thecreate_hosts
permission. -
You must have root privileges on the host that you want to register.
-
orcharhino Server, any orcharhino Proxies, and all hosts must be synchronized with the same NTP server, and have a time synchronization tool enabled and running.
-
The daemon rhsmcertd must be running on the hosts.
-
An activation key must be available for the host. For more information, see Managing Activation Keys in Managing Content.
-
If you want to use orcharhino Proxies instead of your orcharhino Server, ensure that you have configured your orcharhino Proxies accordingly. For more information, see Configuring orcharhino Proxy for Host Registration and Provisioning in Installing orcharhino Proxy.
-
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 the hosts 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 hosts that you want to register.
-
Optional: From the orcharhino Proxy list, select the orcharhino Proxy to register hosts through.
-
Optional: Select the Insecure option, if you want to make the first call insecure. During this first call, hosts download the CA file from orcharhino. Hosts 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 a 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 the registered 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 the host using the SSH key.
Instead, you can manually copy and install the CA file on each host before registering the host.
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 hosts and enter the following commands:$ update-ca-trust enable $ update-ca-trust
Then register the hosts with a secure
curl
command, such as:$ curl -sS https://orcharhino.example.com/register ...
The following is an example of the
curl
command with the--insecure
option:$ curl -sS --insecure https://orcharhino.example.com/register ...
-
Select the Advanced tab.
-
From the Setup REX list, select whether you want to deploy orcharhino SSH keys to hosts 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 the host upon registration. This can be set by the
host_packages
parameter. -
Optional: Select the Update packages option to update all packages on the host upon registration. This can be set by the
host_update_packages
parameter. -
Optional: In the Repository field, enter a repository to be added before the registration is performed. For example, it can be useful to make the
subscription-manager
package available for the purpose of the registration. For SUSE Linux Enterprise Server, enter the path to the orcharhino Client for SUSE Linux Enterprise Server repository, for examplehttp://orcharhino.example.com/pulp/content/Example/Library/custom/suse_linux_enterprise_server_client/suse_linux_enterprise_server_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.
-
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
curl
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
curl
command to authorization of hosts. 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 hosts must use for the SSH connection. If you keep this field blank, orcharhino uses the default network interface.
-
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 the registered 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 SUSE Linux Enterprise Server repository.
For more information about the pull mode, see Transport Modes for Remote Execution in Managing Hosts.
-
In the Activation Keys field, enter one or more activation keys to assign to hosts.
-
Optional: Select the Lifecycle environment.
-
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
rpms before registration and runsubscription-manager
with the--force
argument. -
Click the Generate button.
-
Copy the generated
curl
command. -
On the hosts that you want to register, run the
curl
command asroot
.
If running remote execution jobs fail on your registered host due to Procedure
|
Customizing the Registration Templates
Use information in this section if you want to customize the registration process.
Note that all default templates in orcharhino are locked. If you want to customize the registration process, you need to clone the default templates and edit the clones. Then, in Administer > Settings > Provisioning change the Default Global registration template and Default 'Host initial configuration' template settings to point to your custom templates.
The registration process uses the following registration templates:
-
The Global Registration template contains steps for registering hosts to orcharhino. This template renders when hosts access the
/register
endpoint. -
The Linux host_init_config default template contains steps for initial configuration of hosts after they are registered.
You can configure the following global parameters by navigating to Configure > Global Parameters:
-
The
host_registration_remote_execution
parameter is used in theremote_execution_ssh_keys
snippet, the default value istrue
. -
The
host_packages
parameter is for installing packages on the host. -
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
. For more details se the details of the snippet. -
The
encrypt_grub
parameter is to enable setting of an encrypted bootloader password for the host, the default value isfalse
.To actually set the password, use the
grub_pass
macro in your template.
Snippet is used in the Linux host_init_config default template:
-
The
remote_execution_ssh_keys
snippet deploys SSH keys to the host only when thehost_registration_remote_execution
parameter istrue
. -
The
puppetlabs_repo
andpuppet_setup
snippets download and install Puppet agent on the host (only when a Puppet server is assigned) -
The
host_init_config_post
is empty snippet for user’s custom actions on during host initial configuration.
This table describes what variables are used in the Global Registration
template.
Variable | Command argument | Description |
---|---|---|
|
none |
Current authenticated user object. |
|
|
If |
|
|
If |
|
|
Host group of the host. |
|
|
Host operating system. |
|
|
Override the value of |
|
|
Set default interface of host for the remote execution. |
|
|
Packages to install |
|
|
Add repository on the host |
|
|
Set repository GPG key form URL |
|
|
Host activation keys. |
|
|
Remove any |
|
|
Ignore subscription-manager errors |
|
|
Life cycle environment id |
|
none |
URL for the |
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
.
We recommend 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 or any orcharhino Proxy through HTTP(S).
-
If you use a self-signed certificate on your orcharhino, ensure 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 SUSE Linux Enterprise Server. 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/suse_linux_enterprise_server_Client/suse_linux_enterprise_server_15_Client/
. For more information, see Adding orcharhino Clients. -
Ensure that you provide the managed host with the dependencies of
subscription-manager
:Operating System SUSE Repositories SLES 11 SP4
SLES11-SP4-Pool for sle-11-x86_64
,SLES11-SP4-Updates for sle-11-x86_64
SLES 12 SP5
SLES12-SP5-Pool for sle-12-x86_64
SLES 15
SLE-Product-SLES15-Pool for sle-15-x86_64
,SLE-Module-Basesystem15-Pool for sle-15-x86_64
SLES 15 SP1
SLE-Product-SLES15-SP1-Pool for sle-15-x86_64
,SLE-Module-Python2-15-SP1-Pool for sle-15-x86_64
,SLE-Module-Basesystem15-SP1-Pool for sle-15-x86_64
SLES 15 SP2
SLE-Product-SLES15-SP2-Pool for sle-15-x86_64
,SLE-Module-Python2-15-SP2-Pool for sle-15-x86_64
,SLE-Module-Basesystem15-SP2-Pool for sle-15-x86_64
SLES 15 SP3
SLE-Product-SLES15-SP3-Pool for sle-15-x86_64
,SLE-Module-Python2-15-SP3-Pool for sle-15-x86_64
,SLE-Module-Basesystem15-SP3-Pool for sle-15-x86_64
SLES 15 SP4
SLE-Product-SLES15-SP4-Pool for sle-15-x86_64
,SLE-Module-Basesystem15-SP4-Pool for sle-15-x86_64
SLES 15 SP5
SLE-Product-SLES15-SP5-Pool for sle-15-x86_64
,SLE-Module-Basesystem15-SP5-Pool for sle-15-x86_64
-
Install the SCC Manager Plugin on your orcharhino. For more information, see Installing the SCC Manager Plug-in.
-
Add your SCC account to orcharhino. For more information, see Adding an SCC Account to orcharhino.
-
Import SUSE products, including the base operating system and the required repositories as described above. For example, if you want to register hosts running SLES 15 SP3, include the
SLE-Product-SLES15-SP3-Pool for sle-15-x86_64
,SLE-Module-Python2-15-SP3-Pool for sle-15-x86_64
, andSLE-Module-Basesystem15-SP3-Pool for sle-15-x86_64
repositories. For more information, see Importing SUSE Products. -
Synchronize SUSE content to your orcharhino. Ensure the necessary SUSE repositories are available to the host you want to register to orcharhino using an activation key. For more information, see Synchronizing SUSE Content.
-
-
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 "suse_linux_enterprise_server" \ -g "SUSE Linux Enterprise Server" \ -l "admin" \ -o "Example" \ -p "password" \ --deps-repository-url https://orcharhino.example.com/pulp/content/Example/Library/custom/suse_linux_enterprise_server_Client/suse_linux_enterprise_server_15/ \ --deps-repository-gpg-key file:///etc/pki/rpm-gpg/RPM-GPG-KEY-kt-bootstrap \ -s "orcharhino.example.com"
-
Use
--deps-repository-url
to provide the Upstream URL to the orcharhino Client repository. -
Use
--deps-repository-gpg-key
to provide the required GPG public key for the dependency repository. -
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 suse_linux_enterprise_server
or-a suse_linux_enterprise_server_puppet
. -
Use
-g
to add the host to a host group, for example-g "SUSE Linux Enterprise Server with Puppet"
. -
Use
-l
to specify the orcharhino user, for example-l admin
. -
Use
-o
to specify the organization, for example-o Example
. -
Use
-p
to specify the corresponding password, for example-p password
. -
Use
-s
to specify the 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:$ zypper 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 SUSE Linux Enterprise Server Manually
-
Add a repository containing the
subscription-manager
package:$ zypper addrepo -G --check "http://orcharhino.example.com/pulp/repos/My_Organization/Library/custom/SLES_Client/SLES_Client_15SP5/" or_sles_client
-
Install the
subscription-manager
:$ zypper --non-interactive --no-gpg-checks --quiet install --auto-agree-with-licenses subscription-manager
-
Install a package from your orcharhino bundling all necessary certificates:
$ rpm -ivh http://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
-
Register your host with an activation key:
$ subscription-manager register --org="My_Organization" --name="sles15sp5.example.com" --activationkey="My_SLES15SP5_Activation_Key"
-
Install the
katello-host-tools
:$ zypper --non-interactive --no-gpg-checks --quiet install --auto-agree-with-licenses katello-host-tools
-
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.
Registering Hosts Running SUSE Linux Enterprise Server 11 Using Katello Agent
We recommend using the katello-host-tools
on SUSE Linux Enterprise Server 12 and 15.
However, SLES 11 hosts only work with katello-agent
.
Hosts running SLES 12 and below cannot signal orcharhino that they need to be rebooted after a Linux Kernel update or that services need to be restarted.
SLES 11 is EoL and the Katello Agent is deprecated. |
Use the following options to register an existing host running SLES 11 using the bootstrap.py
script to orcharhino:
-
Use
--deps-repository-url
to specify the client repository, for example--deps-repository-url "https://orcharhino.example.com/pulp/repos/Example/Library/custom/SLES_Client/SLES_Client_11SP4/"
. -
Use
--download-method="http"
to specify the download method. -
Use
--install-katello-agent
to install thekatello-agent
package. -
Use
--install-packages "or-sles-client"
to specify the necessary meta package with dependencies to other required packages. -
Use
--skip "katello-host-tools"
to not install thekatello-host-tools
package.
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.
Migrating From Katello Agent to Remote Execution
Remote Execution is the preferred way to manage package content on hosts. The Katello Agent is deprecated and will be removed in a future orcharhino version. Follow these steps to switch to Remote Execution.
-
You have previously installed the
katello-agent
package on content hosts.
-
If you have Remote Execution configured to use
ssh
mode, distribute the remote execution SSH keys to the hosts. For more information, see Distributing SSH Keys for Remote Execution. -
If you have Remote Execution configured to use
pull-mqtt
mode, deploy the remote execution pull client to the hosts. For more information, see Configuring a Host to Use the Pull Client. -
Stop the goferd service on content hosts:
$ systemctl stop goferd
-
Disable the goferd service on content hosts:
$ systemctl disable goferd
-
Remove the Katello agent on content hosts:
If your host is installed on oVirt version 4.4 or lower, do not remove the katello-agent
package because the removed dependencies corrupt the host.$ dnf remove katello-agent
-
In the orcharhino management UI, navigate to Administer > Settings.
-
Select the Content tab.
-
Set the Use remote execution by default parameter to Yes.
The orcharhino server now uses host management by remote execution instead of Katello Agent.
The following table shows the remote execution equivalent commands to perform specific package actions.
See hammer job-invocation create --help
to learn how to specify search queries to determine the target hosts or host collections.
Action | Katello Agent | Remote Execution |
---|---|---|
Install a package |
|
|
Install a package (host collection) |
|
|
Remove a package |
|
|
Remove a package (host collection) |
|
|
Update a package |
|
|
Update a package (host collection) |
|
|
Update all packages |
|
|
Install errata |
|
|
Install errata (host collection) |
|
|
Install a package group |
|
|
Install a package group (host collection) |
|
|
Remove a package group |
|
|
Remove a package group (host collection) |
|
|
Update a package group |
|
|
Update a package group (host collection) |
|
|
The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution–Share Alike 3.0 Unported ("CC-BY-SA") license. This page also contains text from the official Foreman documentation which uses the same license ("CC-BY-SA"). |