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.

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.

For more information, see Provisioning guide.

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.

  • (Alma Linux 8, Amazon Linux 2, Oracle Linux 7, and Rocky Linux 8) 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 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 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

    • Install the SCC Manager Plugin on your orcharhino.

    • Add your 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 attach 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, and SLE-Module-Basesystem15-SP3-Pool for sle-15-x86_64 repositories.

    • Synchronize SUSE content to your orcharhino.

      Ensure the necessary SUSE repositories are available to the host you want to attach to orcharhino 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.

Associate Attached Hosts with a Compute Resource

If you attach 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 them again.

Procedure
  1. Navigate to Hosts > All Hosts and select your host.

  2. In the Select Action menu, click Disassociate Hosts.

  3. Navigate to Infrastructure > Compute Resources and select your compute resource.

  4. Click Associate VMs.

  5. In case your orcharhino Server or orcharhino Proxies run on the same compute resource, disassociate the VMs on the All Hosts page again.

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 one or multiple operating systems. On the Locations and Organizations tabs, select one or multiple 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.

      For more information, see configuring and setting up remote jobs in the Managing Hosts guide.

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

Associate Attached Hosts with a Compute Resource

If you attach 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.

Procedure
  1. 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
  2. Navigate to Hosts > All Hosts, select your host, and click Edit.

  3. On the Interfaces tab, click Edit and enter the MAC address, IPv4 address, and the device identifier.

  4. Click Submit to save your changes.

  5. Navigate to Hosts > All hosts and tick the checkbox of your host.

  6. In the Select Action drop down menu, click Disassociate Hosts.

  7. Navigate to Infrastructure > Compute Resources and select the compute resource your host runs on.

  8. On the Compute Resources tab, click Associate VMs.

  9. Optional: Navigate to Hosts > All Hosts, select your host, and verify your change by changing the power status of the host.

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.