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 two methods to attach an existing host: either by running the bootstrap script or by manually installing the subscription manager.

Attaching Hosts via Bootstrap Script

orcharhino comes with a bootstrap script to attach existing hosts. It is available on your orcharhino at https://orcharhino.example.com/pub/bootstrap.py.

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 bootstrap.py 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>@orcharhino.example.com/katello/api/content_credentials/<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 bootstrap.py script.

Download the bootstrap.py script using curl, wget, or similar:

wget https://orcharhino.example.com/pub/bootstrap.py

The help instructions will display a list of mandatory options:

python bootstrap.py --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 orcharhino.example.com)

  • -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 my-host.example.com)

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

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

./bootstrap.py \
  -s "orcharhino.example.com" \
  -a "centos7_puppet" \
  -o "Example" \
  -L "Munich" \
  -l "admin" \
  -p "changeme" \
  -g "CentOS7 with Puppet" \
  --fqdn "my-host.example.com" \
  --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:

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:

./bootstrap.py \
  -s "orcharhino.example.com" \
  -a "sles11" \
  -o "Example" \
  -L "Munich" \
  -l "admin" \
  -p "changeme" \
  -g "SLES 11 SP4" \
  --fqdn "my-host.example.com" \
  --deps-repository-url "https://orcharhino.example.com/pulp/repos/Example/Library/custom/SLES_Client/SLES_Client_11SP4/" \
  --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 orcharhino.example.com/pub/

  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 http://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm

Register your host with an appropriate activation key:

subscription-manager register --name="centos7.example.com" --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 "https://orcharhino.example.com/pub/pulp_deb_signing.key" -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 http://orcharhino.example.com/pulp/deb/Example/Library/custom/Ubuntu_Client/Ubuntu_Client_20_04/ default all
EOF

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 - https://orcharhino.example.com/pub/katello-rhsm-consumer | /bin/bash -x 2> /root/katello-rhsm-consumer.log

Register your host with an appropriate activation key:

subscription-manager register --org="Example" --name="ubuntu20.example.com" --activationkey="my-focal-activation-key"

SLES Hosts

Add a repository containing the subscription-manager package:

zypper addrepo -G --check "http://orcharhino.example.com/pulp/repos/ATIX/Library/custom/SLES_Client_V2/SLES_Client_15SP2_V2/" 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 appropriate activation key:

subscription-manager register --org="Example" --name="sles15sp2.example.com" --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> foreman-proxy@orcharhino.example.com
EOF

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