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 Bootstrap Script

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

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

Prerequisites
  • If you use a self-signed certificate on your orcharhino, ensure hosts trust the SSL certificate before running the bootstrap.py script.

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

  • A host group must be configured accordingly to have orcharhino manage the host completely.

    Ensure to select a host group without any predefined deploy on compute resource. Otherwise, attaching an existing host starts 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.

  • Synchronize the required orcharhino client repository and create a content view.

  • (Debian, SLES, and Ubuntu only) Use --deps-repository-url to specify the repository containing the required dependencies. Navigate to Content > Products, click on your orcharhino clients product, choose the orcharhino client repository on the Repositories tab, and select the appropriate client repository. Pass the Published At URL using --deps-repository-url, for example --deps-repository-url https://orcharhino.example.com/pulp/deb/Example/Library/custom/Debian_Client/Debian_10_Client/.

  • (CentOS 8 using an HTTP(S) proxy only) Use the http_proxy environment variable to provide the HTTP(S) proxy configuration.

  • (Oracle Linux 7 only) Provide the required content credentials from your orcharhino to your 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 public 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 Linux 8 only) Hosts running Oracle Linux 8 must only use the provided repository which requires the --only-deps-repository flag.

  • (Debian 9, Ubuntu 16.04, and Ubuntu 18.04) Explicitly use python2 to run the bootstrap.py script.

  • (Debian and Ubuntu only) Use --deps-repository-gpg-key to specify the corresponding GPG public key, for example --deps-repository-gpg-key https://orcharhino.example.com/pub/pulp_deb_signing.key.

  • (Ubuntu without universe component only) Provide a repository containing httpie, jq, and gnupg. These packages are installed when running the bootstrap.py script.

  • (Ubuntu without security component only) Provide a repository containing openssl and python. These packages are upgraded when running the bootstrap.py script.

  • (SLES only) Ensure to provide the managed host with the dependencies of subscription-manager:

    Operating System SUSE Repository

    SLES 11 SP4

    Pool Repository, Update Repository

    SLES 12 SP5

    Pool Repository

    SLES 15

    Pool Repository, Module-Basesystem Repository

    SLES 15 SP1

    Pool Repository, Module-Basesystem Repository, Module-Python2 Repository

    SLES 15 SP2

    Pool Repository, Module-Basesystem Repository, Module-Python2 Repository

    SLES 15 SP3

    Pool Repository, Module-Basesystem Repository, Module-Python2 Repository

    Ensure the necessary SUSE repositories are available using the activation key.

Procedure
  1. Download the bootstrap.py script using wget:

    # wget https://orcharhino.example.com/pub/bootstrap.py
  2. Use the --help option to display a list of mandatory options:

    # python bootstrap.py --help
  3. Attach an existing host to orcharhino. This example attaches an existing host running CentOS 7:

    # ./bootstrap.py \
        -s "orcharhino.example.com" \
        -a "centos7_base" \
        -o "Example" \
        -L "Munich" \
        -l "admin" \
        -p "password" \
        -g "CentOS7" \
        --fqdn "my-host.example.com" \
        --skip "puppet"
    • Use -s to specify the orcharhino FQDN, for example -s orcharhino.example.com.

    • Use -a to specify the activation key, for example -a centos7_base or -a centos7_puppet.

    • Use -o to specify the organization, for example -o Example.

    • Use -L to specify the location, for example -L Munich.

    • Use -l to specify the orcharhino user, for example -l admin.

    • Use -p to specify the corresponding password, for example -p password.

    • Use -g to add the host to a host group, for example -g "CentOS 7 with Puppet".

    • Use --fqdn to specify the FQDN of the new host, for example --fqdn my-host.example.com.

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

      You may use additional options to have orcharhino manage DHCP, provisioning, and configuration management for your existing host.

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

Use the following options to attach an existing host running SLES 11 to orcharhino:

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

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

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

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

  • 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/".

Attaching Hosts via Register Host

We recommend using the bootstrap.py script to attach existing hosts to orcharhino.

The Register Host feature is considered a technical preview and only works for managed hosts running CentOS and Red Hat Enterprise Linux.

Register hosts to orcharhino using the Register Host page.

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 an 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 SSH public key of your orcharhino or orcharhino proxy to your existing host to allow for SSH based remote execution.

    • 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 Copy to clipboard to copy the generated command.

  4. Attach your host.

    Connect to your existing host using SSH and run the previously generated command to register it with orcharhino.

Attaching Hosts Manually

Alternatively, you can manually attach existing hosts to use orcharhino as a source of content.

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

  2. Install the subscription-manager using 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:

Hosts Running CentOS, Oracle Linux, or Red Hat Enterprise Linux

Procedure
  1. Install the subscription-manager:

    # yum install -y subscription-manager
  2. Install the necessary certificates to connect to your orcharhino:

    # rpm -Uvh http://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
  3. Register your host with an activation key:

    # subscription-manager register --name="centos7.example.com" --org="Example" --activationkey="my-centos7-activation-key"
  4. Install the katello-host-tools:

    # yum install -y katello-host-tools katello-host-tools-tracer
  5. Continue with adding SSH keys for remote execution.

Hosts Running Debian or Ubuntu

Procedure
  1. 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 -
  2. Create a 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
  3. 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
  4. 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
  5. Register your host with an activation key:

    # subscription-manager register --org="Example" --name="ubuntu20.example.com" --activationkey="my-focal-activation-key"
  6. Continue with adding SSH keys for remote execution.

Hosts Running SUSE Linux Enterprise Server

Procedure
  1. Add a repository containing the subscription-manager package:

    # zypper addrepo -G --check "http://orcharhino.example.com/pulp/repos/Example/Library/custom/SLES_Client_V2/SLES_Client_15SP2_V2/" or_sles_client
  2. Install the subscription-manager:

    # zypper --non-interactive --no-gpg-checks --quiet install --auto-agree-with-licenses subscription-manager
  3. Install a package from your orcharhino bundling all necessary certificates:

    # rpm -ivh http://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
  4. Register your host with an activation key:

    # subscription-manager register --org="Example" --name="sles15sp2.example.com" --activationkey="my-sles15sp2-activation-key"
  5. Install the katello-host-tools:

    # zypper --non-interactive --no-gpg-checks --quiet install --auto-agree-with-licenses katello-host-tools
  6. Continue with 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.

Procedure
  1. Create the required directory:

    # mkdir -p ~root/.ssh
  2. 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

    Use a user with root privileges, which can either be root or any user being part of the sudo group.