orcharhino Proxy Installation Guide

We refer to orcharhino and orcharhino proxies throughout the documentation. These terms describe the machines running your orcharhino (FQDN e.g. orcharhino.example.com) and their attached orcharhino proxies (FQDN e.g. orcharhino-proxy.example.com). Both the orcharhino as well as the orcharhino proxy may incorporate smart proxy functionality depending on their configuration.

An orcharhino proxy allows you to deliver content and manage hosts in additional networks. It may be configured to either mirror synced content from your orcharhino or pass-through content using Squid from your orcharhino to its hosts. This is called smart proxy functionality and includes DNS, DHCP, TFTP and CA capabilities.

The term smart proxy is used throughout the management UI. It describes the smart proxy functionality present on both your orcharhino as well as any attached orcharhino proxies.

When looking at the upstream documentation for Foreman and Katello, you might come across the terms smart proxy, Foreman proxy, and Katello proxy. These terms are used ambiguously to describe the software component or the attached host with smart proxy functionality in different variations. By contrast, Red Hat named their Foreman downstream product Satellite and any attached smart proxies Capsules.

Additionally, there are HTTP proxies as a way of relaying network traffic from one machine to another. They are often part of more advanced internal network architectures.

This guide describes the installation of an external orcharhino proxy to go along with your orcharhino. If you want to use orcharhino to manage hosts in additional networks, you need an orcharhino proxy installed in each network you want to manage. This allows you to orchestrate the process of managing hosts in different networks, i.e. networks spanning across different data centres and regions.

The orcharhino installation will always come bundled with internal smart proxy functionality. It is sufficient for managing hosts in the same network the orcharhino is in.

In orcharhino, clicking Infrastructure > Smart Proxies >> Create Smart Proxy does not actually create a machine functioning as an orcharhino proxy, but solely attach the orcharhino proxy to your orcharhino. Refer to the smart proxy page for more information.

Usage Scenario

There are different reasons on why to use an orcharhino proxy:

  • To manage infrastructure that is not part of the same network as the orcharhino.

  • To manage traffic across firewalls so as to deploy hosts into isolated networks. This helps you simplifying firewall rules and therefore making it more robust, as only the orcharhino proxy needs to be accessible from outside its network.

  • To centrally manage infrastructure differentiated by location.

  • To reduce traffic and latency.

There are two variants of orcharhino proxies on how to deliver content from the orcharhino to its hosts. An orcharhino proxy can either have the synced content mirrored or be set up as a cached content proxy. This results in a trade-off between storage space and network traffic.

By default, an orcharhino proxy installation will come bundled with Pulp. Pulp mirrors the synced content from the orcharhino to the orcharhino proxy. Synced content implies that the orcharhino proxy has a mirrored version of the orcharhino content stored locally. This results in the need for additional storage capacity analogue to the orcharhino system requirements. On the other hand, there is significantly less traffic between the orcharhino proxy and the orcharhino.

Optionally, you may install Squid to provide cached content. Squid is a caching and forwarding proxy to relay network traffic. Cached means all content comes from the orcharhino and is sent directly to the orcharhino proxy, which stores and relays it to the hosts in its network. There is no need for a complete duplication of data from the orcharhino to the orcharhino proxy, but additional traffic. Therefore, only actually used content is temporarily stored on the orcharhino proxy by Squid.

Optionally, the orcharhino proxy can also handle DHCP and DNS for its network.

System and Network Requirements

The orcharhino proxy installation depends on a working orcharhino installation. It is recommended using the same operating system for orcharhino as well as for the orcharhino proxy itself. The subscription manager needs to be installed on both machines and an activation key needs to be available.

This guide presumes a working orcharhino installation as well as a suitable host for the orcharhino proxy. Regardless of whether it will run on virtualized hardware or on bare metal, the orcharhino proxy machine must meet the following requirements:

Minimum Recommended

OS

CentOS 7, Oracle Linux 7, or Red Hat Enterprise Linux 7

Refer to the OS requirements for more information.

CPU

4 cores

8 cores

RAM

12 GB

32 GB

HDD 1 (/)

30 GB

50 GB

HDD 2 (/var)

~ 40 GB for each CentOS, Oracle Linux, or Red Hat Enterprise Linux distribution

~ 80 GB for each Debian or Ubuntu distribution

~ 500 GB (or as appropriate) if you plan to maintain additional repositories or keep multiple versions of packages

If you are running your orcharhino proxy with Squid only, a second HDD for /var with 30 GB to 50GB is sufficient.

In addition to the system requirements, the orcharhino proxy also needs its own domain and subnet, which can be set up via orcharhino’s management UI. The network configuration and firewall rules must allow for communication from the orcharhino to the orcharhino proxy and vice versa.

For communication from the orcharhino to the orcharhino proxy, the following ports must be open:

Port Protocol SSL Required for

80

TCP

yes

bootdisk

443

TCP

yes

Pulp

9090

TCP

yes

Querying the orcharhino proxy feature set

For communication from the orcharhino proxy to the orcharhino, the following ports must be open:

Port Protocol SSL Required for

80

TCP

no

Anaconda, yum, Katello certificates

443

TCP

yes

yum, Katello, API, Pulp

5000

TCP

yes

Katello for Docker registry

5646

TCP

yes

Pulp mirror (Qpid dispatcher)

5647

TCP

yes

Deprecated (has been used by Qpid for Katello agent)

For communication from the clients to the orcharhino proxy, the following ports must be open:

Port Protocol SSL Required for

53

TCP & UDP

no

DNS Services

67

UDP

no

DHCP Service

69

UDP

no

PXE boot

80

TCP

no

Anaconda, yum, templates, iPXE

443

TCP

yes

yum, Katello

3129

TCP

no

Squid (proxies traffic to repositories if Pulp pass-through is activated)

5000

TCP

yes

Katello for Docker registry

5647

TCP

yes

Deprecated (has been used by Qpid for Katello agent)

8000

TCP

yes

Anaconda for downloading Kickstart templates, iPXE

8140

TCP

yes

Puppet agent to Puppet master

8443

TCP

yes

Subscription Management

9090

TCP

yes

OpenSCAP reports

The orcharhino and the orcharhino proxy need to be reachable by name. If they are not yet resolvable via DNS, make sure to add them to each others /etc/hosts file as follows. If you are using an HTTP proxy, ensure it is properly configured as well.

This guide uses the network1 (192.168.50.0) for the orcharhino (called orcharhino), and network2 (192.168.60.0) for the orcharhino proxy (called orcharhino-proxy). The orcharhino is the 192.168.50.10 and the orcharhino proxy the 192.168.60.10 in the default scenario and 192.168.70.10 in network3 when opting for Squid.

To do so, edit the etc/hosts file on both the orcharhino and the orcharhino proxy and add the following lines:

192.168.50.10 orcharhino.network1.example.com
192.168.60.10 orcharhino-proxy.network2.example.com orcharhino-proxy

In case the orcharhino uses an HTTP proxy itself, it’s necessary to add the orcharhino proxy to the no_proxy entries.

  1. Edit the last line in /etc/sysconfig/httpd:

    no_proxy='localhost,127.0.0.1,orcharhino.network1.example.com,orcharhino,*.network1.example.com,orcharhino-proxy.network2.example.com,*.network2.example.com'
  2. Edit the last line in /etc/sysconfig/foreman-proxy:

    no_proxy='localhost,127.0.0.1,orcharhino.network1.example.com,orcharhino,*.network1.example.com,orcharhino-proxy.network2.example.com,*.network2.example.com'
  3. Edit the settings in orcharhino via its management UI:

    To do so, click on Administer > Settings and edit HTTP(S) proxy except hosts:

    [ localhost, 127.0.0.1, orcharhino.network1.example.com, orcharhino, *.network1.example.com, orcharhino-proxy.network2.example.com, *.network2.example.com ]

If there are persisting problems, check your networking and firewall settings.

orcharhino Proxy Installation

Refer to the orcharhino proxy upgrade guide on how to upgrade your orcharhino proxy.

The basic installation contains four steps. Optionally, you may choose to activate DHCP and DNS or run Squid to provide cached content.

There are two ways to configure the orcharhino proxy: Either by editing the foreman-proxy-content-answers.yaml file or by passing arguments to the foreman-installer command.

Installation Instructions

An orcharhino proxy requires the same packages as the orcharhino itself. They can be listed by running subscription-manager repos --list-enabled on your orcharhino. Add these repositories to products and publish them as a composite content view. This content must be available on the host you’re installing the orcharhino proxy on.

Alternatively, you may run the orcharhino Proxy Content job template. This job template runs an Ansible role on your orcharhino to automatically create the necessary content view. It bundles the required repositories and content credentials to a product specifically made for an orcharhino proxy and creates an activation key. The job template is to be run on the orcharhino and picks up any repositories in /etc/yum.repos.d/redhat.repo and possible HTTP proxy settings. Synchronization of the new content view can be controlled via a variable.

This job template is only available if the Ansible plugin is installed.

The job template needs to be run after every orcharhino upgrade and looks as follows:

Sync content required for orcharhino proxy via job template
  • Select orcharhino Configuration in the Job category drop down menu (1).

  • The Job template drop down menu (2) contains the orcharhino Proxy Content job template.

  • Use the Search Query field (3) to search for your orcharhino host via the name filter.

  • The sync_repos drop down menu (4) allows you to automatically sync the required repositories after bundling them to the orcharhino Proxy Content content view.

  • The use_proxy drop down menu (5) allows you to use an HTTP proxy to connect to the repositories.

  • The use_proxy_credentials drop down menu (6) allows you to use the HTTP proxy credentials that are read from your orcharhino.

  • Clicking the Submit button (7) starts the execution of the job template.

Since this job template needs to be run against the orcharhino server itself, you will need to provide SSH access as described in the orcharhino security guide.


This section describes the steps necessary to attach an orcharhino proxy to your orcharhino. It consists of five steps: installing Katello, creating a .tar file containing certificates, copying the certificates to the orcharhino proxy, installing the orcharhino proxy, and setting the appropriate organization and location context.

  1. Installing Katello on the orcharhino proxy

    To install Katello, run:

    yum -y install -t foreman-installer-katello
  2. Creating a tar file with certificates

    In case your organization already has certificates in place, you will need the following four files on your orcharhino:

    • A private key: proxy.key

    • A certificate: proxy.cert

    • A certificate signing request: proxy.csr

    • The authority’s certificate: proxy.ca

      In case you have no certificate signing request, you may create one with the private key and certificate by running the following command:

      openssl x509 -x509toreq -in orcharhino-proxy.cert -out orcharhino-proxy.csr -signkey orcharhino.key

      Run the following command to compile the tar file:

      foreman-proxy-certs-generate \
        --foreman-proxy-fqdn "orcharhino-proxy.network2.example.com" \
        --certs-tar "/root/orcharhino-proxy.network2.example.com-certs.tar" \
        --server-cert /root/certs/orcharhino-proxy.cert \
        --server-cert-req /root/certs/orcharhino-proxy.csr \
        --server-key /root/certs/orcharhino-proxy.key \
        --server-ca-cert /root/certs/orcharhino-proxy.ca

      In case there are no existing certificates, you can create them by running the following command on your orcharhino:

      foreman-proxy-certs-generate \
        --foreman-proxy-fqdn "orcharhino-proxy.network2.example.com" \
        --certs-tar "orcharhino-proxy.network2.example.com-certs.tar"

      Save the standard output describing how to import certificates. This helps later on when installing the orcharhino proxy.

  3. Importing certificates from orcharhino

    Copy the generated certificates from the orcharhino to the orcharhino proxy. This allows for a secure certificate based connection:

    scp /root/orcharhino-proxy.network2.example.com-certs.tar root@orcharhino-proxy.network2.example.com:/root/orcharhino-proxy.network2.example.com-certs.tar
  4. Installing the orcharhino proxy

    To install the orcharhino proxy with the proper certificates, run:

    foreman-installer \
      --scenario foreman-proxy-content \
      --certs-tar-file                              "/root/orcharhino-proxy.network2.example.com-certs.tar" \
      --foreman-proxy-content-parent-fqdn           "orcharhino.network1.example.com" \
      --foreman-proxy-register-in-foreman           "true" \
      --foreman-proxy-foreman-base-url              "https://orcharhino.network1.example.com" \
      --foreman-proxy-trusted-hosts                 "orcharhino.network1.example.com" \
      --foreman-proxy-trusted-hosts                 "orcharhino-proxy.network2.example.com" \
      --foreman-proxy-oauth-consumer-key            "mGZxEukJVvdL89ySA6Ymk3bAuGSF7jJj" \
      --foreman-proxy-oauth-consumer-secret         "g2tNnBR7qNHg9Gptt4XMcsFnh9c3kDSg" \
      --puppet-server-foreman-url                   "https://orcharhino.network1.example.com"
  5. Setting organization and location

    After the installation, the organization and location tags potentially must be set by hand.

    To add the organization and location to the orcharhino proxy, go to Infrastructure > Smart Proxies and select orcharhino-proxy.network2.example.com.

    • Add Organization: your organization

    • Add Location: your location

    • Add Lifecycle Environment: Production

    • Download Policy: Immediate

      One way to distinguish between orcharhino administrators and regular users is to place the orcharhino server as well as any attached orcharhino proxies into a separate location and/or organization context.

      Alternatively, you can achieve a fine grained permissions concept using roles and filters.

By now, you have a fully functional orcharhino proxy. There are two optional possibilities: you may install Squid for cached content or you may want to run DHCP and DNS services on the orcharhino proxy.

Optional: Installing Squid Proxy

This subsection describes the installation of a Squid proxy. We can pass the necessary arguments to foreman when running the installer to enable Squid.

foreman-installer \
  --foreman-proxy-content-enable-passthrough-pulp=true \
  --foreman-proxy-content-passthrough-pulp-master-host=orcharhino.network1.example.com \
  --foreman-proxy-content-passthrough-pulp-allowed-net=192.168.70.0/24

This enables pass-through content from Pulp, sets the Pulp master to the orcharhino, and defines its network.

Squid is a caching and forwarding proxy to relay network traffic. Content based on lifecycle environments can only be synced to an orcharhino proxy with Pulp.

Optional: Activating DHCP, DNS, and TFTP

We generally recommend having the orcharhino proxy provide DHCP, DNS, and TFTP services on its respective network.

This subsection describes the steps necessary to activate DHCP, DNS, and TFTP on the orcharhino proxy. First, TFTP capabilities are enabled on the orcharhino proxy using the following command:

foreman-installer --foreman-proxy-tftp true

This activates TFTP capabilities on your orcharhino proxy which is necessary for provisioning hosts using PXE.

To activate DHCP and DNS on your orcharhino proxy, configure /etc/foreman-installer/scenarios.d/foreman-proxy-content-answers.yaml. DHCP and DNS should be activated simultaneously. This is a sample configuration:

#DHCP:
dhcp: true
dhcp_gateway: 192.168.60.254
dhcp_range: 192.168.60.50 192.168.60.200
dhcp_option_domain: network2.example.com

#DNS:
dns: true
dns_zone: network2.example.com
dns_reverse:
- 60.168.192.in-addr.arpa
dns_forwarder:
- 192.168.50.10

Rerun the foreman-installer to automatically fetch the configuration from the edited yaml file. After that, the orcharhino proxy can be set up as DHCP and DNS server in the corresponding subnet and domain.

Navigate to Infrastructure > Domains and select network2.example.com. Select the new orcharhino proxy orcharhino-proxy.network2.example.com.

On Infrastructure > Subnets, select vlan60 and change the primary DNS to 192.168.60.10 with IPAM to DHCP and Boot Mode to DHCP. Under Proxies, set everything but the last to orcharhino-proxy.network2.example.com.

Optional: Activating Remote Execution via SSH

On orcharhino, the remote execution plugin is installed by default. It can be installed on orcharhino proxies as follows:

  1. Run the following command on the orcharhino proxy to install this plugin:

    foreman-installer --enable-foreman-proxy-plugin-remote-execution-ssh
  2. Next, navigate to Infrastructure > Subnets and select the subnet of the orcharhino proxy.

  3. On the Remove Execution tab, activate the orcharhino proxy and click the Submit button.

  4. You can now schedule remote jobs on hosts in the subnet of the orcharhino proxy.

Additional Debian Configuration Steps

This is only relevant when using Pulp for mirrored content.

These additional steps are necessary to deploy hosts running Debian or Ubuntu via the orcharhino proxy. Without manual intervention, an orcharhino proxy installation will not sign Debian and Ubuntu repositories. Therefore, host deployments will fail because apt does so by default. The orcharhino proxy will be configured manually to use the same signing key as the orcharhino.

Doing so has two prerequisites:

  • The orcharhino must be configured to sign APT repositories (for new installations this is always the case).

  • You need a (one time) way to transfer files from your orcharhino to the orcharhino proxy. In this guide, we assume scp is an option.

  1. Check which key is used

    To display the GPG key id, run the following command on the orcharhino:

    grep 'gpg_key_id' /etc/pulp/server/plugins.conf.d/deb_distributor.json
  2. Verify the matching key is also present in /var/lib/pulp/gpg-home/

    To see if the GPG key id matches, run the following command on the orcharhino:

    su apache -s /bin/bash -c 'gpg --list-secret-keys --homedir /var/lib/pulp/gpg-home/'

    This should display the same GPG key id as seen in the first step.

  3. Transfer the gpg-home directory from your orcharhino to the orcharhino proxy

    To do so, recursively copy the folder from the orcharhino to the orcharhino proxy via scp. Run the following command on the orcharhino:

    scp -r /var/lib/pulp/gpg-home/ root@orcharhino-proxy.example.com:/var/lib/pulp/gpg-home

    You may verify the correctness once more by running gpg --list-secret-keys --homedir /var/lib/pulp/gpg-home/ on the orcharhino proxy.

  4. Transfer the ownership of the copied folder to the apache user

    To do so, run the following command on the orcharhino proxy:

    chown -R apache:apache /var/lib/pulp/gpg-home/
  5. Transfer the config file from your orcharhino to the orcharhino proxy

    Use scp to copy the file from your orcharhino to the orcharhino proxy. To do so, run the following command on the orcharhino:

    scp /etc/pulp/server/plugins.conf.d/deb_distributor.json root@orcharhino-proxy.example.com:/etc/pulp/server/plugins.conf.d/deb_distributor.json
  6. Transfer apt_sign.sh from your orcharhino to the orcharhino proxy

    To do so, run the following command on the orcharhino:

    scp /opt/orcharhino/apt_sign.sh root@orcharhino-proxy.example.com:/opt/orcharhino/apt_sign.sh

Following these six steps allows you to deploy Debian and Ubuntu hosts via a syncing orcharhino proxy.