Smart Proxy Installation Guide

This guide describes the installation of an external smart proxy for orcharhino. If you want to use orcharhino to manage hosts in additional networks, you need a smart 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 main orcharhino installation will always come bundled with an internal smart proxy. 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 a smart proxy, but solely attach the smart proxy to orcharhino. Refer to the smart proxy page for more information.

Usage Scenario

There are different reasons on why to use a smart 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 smart 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 smart proxies on how to deliver content from the orcharhino to its hosts. A smart 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, a smart proxy installation will come bundled with Pulp. Pulp mirrors the synced content from the orcharhino to the smart proxy. Synced content implies that the smart 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 smart proxy and the orcharhino host.

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 smart 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 smart proxy, but additional traffic. Therefore, only actually used content is temporarily stored on the smart proxy by Squid.

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

System and Network Requirements

The smart proxy installation depends on a working orcharhino installation. It is recommended using the same operating system for orcharhino as well as the smart 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 smart proxy. Regardless of whether it will run on virtualized hardware or on bare metal, the smart proxy machine must meet the following requirements:




CentOS 7, RHEL 7, Oracle Linux 7 (See also OS requirements.)





12 GB

32 GB

HDD 1 (/)

30 GB

50 GB

Default scenario with Pulp

HDD 2 (/var)

~ 40 GB for each CentOS/RHEL/Oracle distribution

~ 80 GB for each Debian distribution

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

Scenario 2 with Squid only

HDD 1 (/var)

30 GB

50 GB

In addition to the system requirements, the smart 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 host to the smart proxy and vice versa.

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



Required for



boot disk






Proxy in the smart proxy

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



Required for



Anaconda, yum, Katello certificates



yum, Katello, API, Pulp



Katello for Docker registry



Pulp mirror (Qpid dispatcher)



Deprecated (has been used by Qpid for Katello agent)

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



Required for



DNS service



DHCP service



PXE boot



Anaconda, yum, templates, iPXE



yum, Katello






Katello for Docker registry



Deprecated (has been used by Qpid for Katello agent)



Anaconda, iPXE



Puppet agent to Puppet master



subscription manager



OpenSCAP reports

The orcharhino and the smart 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 ( for the main orcharhino (called orcharhino), and network2 ( for the smart proxy (called smartproxy). The orcharhino is the and the smart proxy the in the default scenario and in network3 when opting for Squid.

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

In case the orcharhino uses a proxy itself, it’s necessary to add the smart proxy machine to the no_proxy entries.

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

  2. Edit the last line in /etc/sysconfig/foreman-proxy:

  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,,, orcharhino, *,, * ]


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

Smart Proxy Installation


Refer to the smart proxy upgrade guide on how to upgrade your smart 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 smart proxy: Either by editing the foreman-proxy-content-answers.yaml file or by passing arguments to the foreman-installer command.

Installation Instructions

A smart 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 to the machine you’re installing the smart proxy on.


On request, we can provide you a .tar.gz file containing an Ansible role to create the necessary content view automatically. It bundles the required repositories and content credentials to a product specifically made for a smart proxy and creates an activation key. The role is to be run on the orcharhino itself. It 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 in Ansible. The role needs to be run after every update of your orcharhino. This is currently a technical preview.

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

  1. Installing Katello on the smart 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:


    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 proxy.cert -out proxy.csr -signkey server.key

    Run the following command to compile the tar file:

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

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

    foreman-proxy-certs-generate \
      --foreman-proxy-fqdn "" \
      --certs-tar ""


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

  3. Importing certificates from orcharhino

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

    scp /root/
  4. Installing the orcharhino smart proxy

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

    foreman-installer \
      --scenario foreman-proxy-content \
      --certs-tar-file                              "/root/" \
      --foreman-proxy-content-parent-fqdn           "" \
      --foreman-proxy-register-in-foreman           "true" \
      --foreman-proxy-foreman-base-url              "" \
      --foreman-proxy-trusted-hosts                 "" \
      --foreman-proxy-trusted-hosts                 "" \
      --foreman-proxy-oauth-consumer-key            "mGZxEukJVvdL89ySA6Ymk3bAuGSF7jJj" \
      --foreman-proxy-oauth-consumer-secret         "g2tNnBR7qNHg9Gptt4XMcsFnh9c3kDSg" \
      --puppet-server-foreman-url                   ""
  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 smart proxy, go to Infrastructure > Smart Proxies and select

    • Add Organization: YOUR ORGANIZATION

    • Add Location: YOUR LOCATION

    • Add Lifecycle Environment: Production

    • Download Policy: Immediate

By now, you have a fully functional smart 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 smart 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 \ \

This enables pass-through content from Pulp, sets the Pulp master to the main 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 a smart proxy with Pulp.

Optional: Activating DHCP and DNS


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

This subsection describes the steps necessary to activate DHCP and DNS on the smart proxy. First, DHCP and DNS capabilities are enabled on the smart proxy.

To activate DHCP and DNS on your smart 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: true

dns: true

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

On the main orcharhino’s web GUI, click Infrastructure > Domains and select Select the new smart proxy

On Infrastructure > Subnets, select vlan60 and change the primary DNS to with IPAM to DHCP and Boot Mode to DHCP. Under Proxies, set everything but the last to

Additional Debian configuration steps


This is only relevant when using Pulp for mirrored content. Also, synchronizing Debian and Ubuntu content to smart proxies will only work for orcharhino version >= 4.5.

These additional steps are necessary to deploy hosts running Debian or Ubuntu via the smart proxy. Without manual intervention, a smart proxy installation will not sign Debian and Ubuntu repositories. Therefore, host deployments will fail because apt does so by default. The smart 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 the orcharhino to the smart 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 smart proxy

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

    scp -r /var/lib/pulp/gpg-home/ root@<smart_proxy_fqdn_or_ip>:/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 smart proxy.

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

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

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

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

    scp /etc/pulp/server/plugins.conf.d/deb_distributor.json root@<smart_proxy_fqdn_or_ip>:/etc/pulp/server/plugins.conf.d/deb_distributor.json
  6. Transfer from the orcharhino to the smart proxy

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

    scp /opt/orcharhino/ root@<smart_proxy_fqdn_or_ip>:/opt/orcharhino/

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