Attach Existing Hosts Guide

In most data centre environments, orcharhino needs to manage hosts which are already installed and in use. To do so, existing hosts need to be attached to orcharhino.

There are three methods to attach an existing host to orcharhino: running the bootstrap script, manually installing the subscription manager, or by using the register host page.

Attaching Hosts via Register Host

Register hosts to orcharhino using the Register Host page with the following procedure:

  1. Associate the Linux registration default template.

    Navigate to Hosts > Provisioning Templates and select the Linux registration default template. On the Association tab, select any desired operating systems. On the Locations and Organizations tabs, select any desired organization and location contexts.

  2. Navigate to Hosts > All Hosts and click the Register Host button in the top right corner.

    attach existing hosts register host generate command
    • The Organization and Location context (1) depends on your currently selected organization and location context.

    • The Host Group drop down menu (2) allows you to associate the existing host to a host group.

    • The Operating System drop down menu (3) allows you to associate the existing host to a operating system.

    • The Proxy drop down menu (4) allows you to select either your orcharhino or any attached orcharhino proxy that has the Host Registration feature enabled.

    • The Setup Insights drop down menu (5) allows you to activate the insights plugin. Note that this is currently considered a technical preview and not recommended for production usage.

    • The Remote Execution drop down menu (6) allows you to add the orcharhino or orcharhino proxy SSH key to your existing host to allow for SSH based remote execution on the existing host.

    • The Token Lifetime field (7) allows you to define the lifetime of a token in hours. Once the token has expired, a host using this token cannot be registered with orcharhino anymore due to security reasons.

    • The Remote Execution Interface field (8) allows you to define a specific network interface for remote execution.

    • The Activation Key(s) field (9) allows you to set an activation key.

    • Click the Generate command button (10) to display the assembled command which lets you register your existing host to orcharhino.

  3. Generate command.

    attach existing hosts register host command
    • Click the Copy to clipboard button to copy the generated command.

  4. Attach host.

    Connect to your existing host using SSH and run this command to register it with your orcharhino.

Attaching Hosts via Bootstrap Script

orcharhino comes with a bootstrap script to attach existing hosts. It is available on your orcharhino at

You will need root access on any hosts you want to attach to orcharhino and they need to be able to communicate with orcharhino via HTTP(S). Consider creating a backup or snapshot of your host before running the bootstrap script.

There are three prerequisites in order to use the script:

  • An activation key for the host needs to exist and contain the necessary software content for this host.

  • A host group must be configured accordingly to be able to use a full registration, i.e. orcharhino managing the host completely.

    Make sure to select a host group without any predefined deploy on compute resource. Otherwise, this will start deploying a new host to the compute resource selected in the deploy on drop down menu. Refer to creating a host group for more information.

  • (Debian, Ubuntu, and SLES only) The Debian, Ubuntu, or SLES orcharhino client repository needs to exist and be reachable.

  • (CentOS 8 using an HTTP proxy only) CentOS 8 hosts need to provide the HTTP proxy configuration via the http_proxy environment variable.

  • (Oracle 7 only) Hosts running Oracle 7 require content credentials to be provided as a file. Copy the required content credentials from your orcharhino and save them on your Oracle 7 host:

    curl --insecure https://<user>:<password><ID>/content > /etc/pki/rpm-gpg/RPM-GPG-KEY-kt-bootstrap

    Provide the required GPG key for the dependency repository using the --deps-repository-gpg-key option: --deps-repository-gpg-key file:///etc/pki/rpm-gpg/RPM-GPG-KEY-kt-bootstrap.

  • (Oracle 8 only) Hosts running Oracle 8 must only use the provided repository which requires the --only-deps-repository flag.

  • Hosts running Debian 9, Ubuntu 16.04, and Ubuntu 18.04 must explicitly use python2 to run the script.

Download the script using curl, wget, or similar:


The help instructions displays a list of mandatory options:

python --help

This example attaches a CentOS host to orcharhino. You may use additional options to have orcharhino manage DHCP, provisioning, and configuration management for the new host:

  • -s for the orcharhino FQDN (e.g. -s

  • -a for the activation key (e.g. -a centos7_base or -a centos7_puppet)

  • -o for the organization (e.g. -o Example)

  • -L for the location (e.g. -L Munich)

  • -l to specify the orcharhino user (e.g. -l admin)

  • -p for the corresponding password (e.g. -p changeme)

  • -g to add the host to a host group (e.g. -g "CentOS 7 with Puppet")

  • --fqdn for the FQDN of the new host (e.g. --fqdn

  • --skip "puppet" to optionally skip the installation of Puppet.

Run the following command on your host to attach it to orcharhino:

./ \
  -s "" \
  -a "centos7_puppet" \
  -o "Example" \
  -L "Munich" \
  -l "admin" \
  -p "changeme" \
  -g "CentOS7 with Puppet" \
  --fqdn "" \
  --skip "puppet"

This allows you to attach an existing host to your orcharhino.

To attach a host running Debian, Ubuntu, or SLES, there are additional options required:

  • (Debian, Ubuntu, and SLES) --deps-repository-url to specify the repository containing the required dependencies (e.g. --deps-repository-url Navigate to products, click on your orcharhino clients product, choose an individual repository on the repositories tab and select the appropriate client repository. You need to pass the published at URL.

  • (Debian and Ubuntu only) --deps-repository-gpg-key with the corresponding GPG public key (e.g.

Using Katello Agent on SLES 11

We generally recommend using the katello-host-tools on CentOS, Oracle Enterprise Linux, Red Hat Enterprise Linux, as well as SUSE Linux Enterprise Server version 12 and 15 as shown above.

However, SLES 11 hosts only work with katello-agent. This requires four additional options:

  • --install-katello-agent to install the katello-agent package

  • --skip "katello-host-tools" to not install the katello-host-tools package

  • --install-packages "or-sles-client" to specify the necessary meta package with dependencies to other required packages

  • --download-method="http" to specify the download method

Hosts running SLES 11 can be attached to orcharhino with the following command:

./ \
  -s "" \
  -a "sles11" \
  -o "Example" \
  -L "Munich" \
  -l "admin" \
  -p "changeme" \
  -g "SLES 11 SP4" \
  --fqdn "" \
  --deps-repository-url "" \
  --install-katello-agent \
  --skip "katello-host-tools" \
  --install-packages "or-sles-client" \
  --download-method="http" \
  --skip "puppet"

Attaching Hosts Manually

This alternative way is best used in case you only want to attach hosts to orcharhino as source of content.

There are six steps necessary to manually attach existing hosts to orcharhino:

  1. Add a repository containing the subscription-manager package (Debian, Ubuntu, and SLES only)

  2. Install the subscription-manager using the appropriate package manager (i.e. apt, yum, or zypper)

  3. Install the katello-consumer certificate from

  4. Register your host with orcharhino using an activation key

  5. Install the katello-host-tools

  6. Add SSH keys for remote execution

The following subsections will explain each step -if required- for the three types of operating systems supported by orcharhino:

CentOS/Oracle Linux/RHEL Hosts

Run the following command to install the subscription-manager:

yum install -y subscription-manager

Install a package from your orcharhino bundling all necessary certificates:

rpm -Uvh

Register your host with an appropriate activation key:

subscription-manager register --name="" --org="Example" --activationkey="my-centos7-activation-key"

Install the katello-host-tools:

yum install -y katello-host-tools katello-host-tools-tracer

Debian/Ubuntu Hosts

Add the GPG public key used to sign deb packages from your orcharhino to download the Debian/Ubuntu client from your orcharhino:

apt-get -y install gnupg
mkdir -p /etc/apt/trusted.gpg.d
wget "" -O - | apt-key add -

Create a new repository file which contains the Debian/Ubuntu client. This example chooses Ubuntu 20.04:

mkdir -p /etc/apt/sources.list.d
cat > /etc/apt/sources.list.d/orcharhino.list <<'EOF'
deb default all

Install apt-transport-katello and katello-upload-profile. This depends on and automatically installs the subscription-manager for Debian/Ubuntu, which replaces the katello-host-tools:

apt-get update && apt-get -y install apt-transport-katello katello-upload-profile

Download and execute a script from your orcharhino to install all necessary certificates:

wget --no-check-certificate -O - | /bin/bash -x 2> /root/katello-rhsm-consumer.log

Register your host with an appropriate activation key:

subscription-manager register --org="Example" --name="" --activationkey="my-focal-activation-key"

SLES Hosts

Add a repository containing the subscription-manager package:

zypper addrepo -G --check "" 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

Register your host with an appropriate activation key:

subscription-manager register --org="Example" --name="" --activationkey="my-sles15sp2-activation-key"

Install the katello-host-tools:

zypper --non-interactive --no-gpg-checks --quiet install --auto-agree-with-licenses katello-host-tools

Adding SSH Keys for Remote Execution

Run the following commands to add the SSH public key from your orcharhino to your host. This is required for remote execution and patching your hosts.

First, create the required directory:

mkdir -p ~root/.ssh

Next, add the SSH public key from your orcharhino:

cat << EOF >> ~root/.ssh/authorized_keys
ssh-rsa <ssh-public-key>

Make sure to utilize a user with root privileges, which can either be root or any user being part of the sudo group.