1. Preparing your environment for Smart Proxy installation

For a successful installation and operation of Smart Proxy server, ensure your environment meets the operating system requirements, system requirements, storage requirements, and network port configurations.

1.1. Operating system requirements

Ensure that your operating system and installation method meet the necessary requirements before you install Foreman.

The following operating system is supported for deploying Foreman:

  • Enterprise Linux 9 (x86_64)

Installing Foreman on a system with Extra Packages for Enterprise Linux (EPEL) is not supported.

Do not register Smart Proxy server to the Red Hat Content Delivery Network (CDN).

Additional resources

1.2. System requirements

System requirements for Smart Proxy server include minimum CPU, RAM, storage, hostname format, SELinux configuration, and time synchronization to ensure proper installation and operation.

Follow these system requirements when installing Smart Proxy server:

  • Install Smart Proxy server on a freshly provisioned system that serves no other function except to run Smart Proxy server. Do not use an existing system because foreman-installer affects the configuration of several components.

  • Ensure you have administrative user (root) access to the system.

  • Ensure the system meets the following requirements:

    • 4 CPU cores

    • 4 GB or higher

    • A unique host name, which can contain lower-case letters, numbers, dots (.) and hyphens (-)

  • If you use custom certificates, ensure that the Common Name (CN) of the custom certificate is a fully qualified domain name (FQDN). Foreman server and Smart Proxy server do not support shortnames in the hostnames.

  • Ensure SELinux is enabled, either in enforcing or permissive mode. Installation with disabled SELinux is not supported. For more information, see Security considerations in Planning for Foreman.

  • Ensure the system clock on the system is synchronized across the network. If the system clock is not synchronized, SSL certificate verification might fail.

  • Ensure the system uses the UTF-8 encoding. If your territory is USA and your language is English, set en_US.utf-8 as the system-wide locale settings. For more information about configuring system locale in Enterprise Linux, see Configuring the system locale in Red Hat Enterprise Linux 9 Configuring basic system settings.

  • If you use an external identity provider in your deployment, ensure the provider did not create the following user accounts on the system. These user accounts can cause conflicts with the local users that Smart Proxy server creates:

    • apache

    • foreman-proxy

    • postgres

    • puppet

    • redis

Warning

The version of Smart Proxy must match the version of Foreman installed. For example, the Smart Proxy version nightly cannot be registered with the Foreman version 3.19.

1.3. Opening required ports

Open the required network ports to enable communication between Foreman components across your infrastructure, including firewall configurations for both host-based and network-based firewalls.

Note

Some cloud solutions must be specifically configured to allow communications between machines because they isolate machines similarly to network-based firewalls. If you use an application-based firewall, ensure that the application-based firewall permits all applications that are listed in the tables and known to your firewall. If possible, disable the application checking and allow open port communication based on the protocol.

If you do not use firewall-cmd to configure the Linux firewall, implement using the tool of your choice.

Procedure

  1. Allow access to services on Smart Proxy server:

    # firewall-cmd \
--add-service=dns \
--add-service=dhcp \
--add-service=tftp \
--add-service=puppetmaster \
--add-service=foreman-proxy \
--add-service=http \
--add-service=https

  2. Make the changes persistent:

    # firewall-cmd --runtime-to-permanent
Verification

  • View all firewall zones and allowed services:

    # firewall-cmd --list-all
Additional resources

2. Installing Smart Proxy server

To install Smart Proxy server, register the server to Foreman server, configure repositories, install packages, and set up SSL certificates to enable content management and remote execution capabilities in distributed environments.

2.1. Configuring repositories

Enable the necessary repositories on your Foreman host to access installation packages and dependencies.

Procedure

  1. Clear any metadata:

    # dnf clean all

  2. Install the foreman-release.rpm package:

    # dnf install https://yum.theforeman.org/releases/nightly/el9/x86_64/foreman-release.rpm

  3. Install the openvox-release package:

    # dnf install https://yum.voxpupuli.org/openvox8-release-el-9.noarch.rpm
Verification

  • Verify that the required repositories are enabled:

    # dnf repolist enabled

2.2. Installing Smart Proxy packages

Install Smart Proxy server packages to set up the core software components needed for Smart Proxy functionality.

Procedure

  1. Upgrade all packages:

    # dnf upgrade

  2. Install the packages:

    # dnf install foreman-installer

2.3. Installing Smart Proxy server

With Smart Proxy packages installed, you can proceed to install the Smart Proxy server.

Procedure

  • To install Smart Proxy server, enter the following command:

    # foreman-installer \
--enable-foreman-proxy \
--enable-puppet \
--foreman-proxy-foreman-base-url https://foreman.example.com \
--foreman-proxy-oauth-consumer-key My_oAuth_Consumer_Key \
--foreman-proxy-oauth-consumer-secret My_oAuth_Consumer_Secret \
--foreman-proxy-puppetca false \
--foreman-proxy-tftp false \
--foreman-proxy-trusted-hosts foreman.example.com \
--no-enable-foreman \
--no-enable-foreman-cli \
--puppet-server-ca false

2.4. Assigning organization and location to Smart Proxy server

Assign the correct organization and location to Smart Proxy server to properly manage your Smart Proxy server within your organizational structure.

Prerequisites

  • Your user account has the assign_organizations and assign_locations permissions.

  • You belong to the organization and location that you want to assign to the Smart Proxy.

Procedure

  1. Log into the Foreman web UI.

  2. From the Organization list in the upper-left of the screen, select Any Organization.

  3. From the Location list in the upper-left of the screen, select Any Location.

  4. In the Foreman web UI, navigate to Hosts > All Hosts and select Smart Proxy server.

  5. From the options menu, select Change associations > Organization.

  6. Select the organization where you want to assign this Smart Proxy.

  7. Select Fix on mismatch.

  8. Click Change organization.

  9. From the options menu, select Change associations > Location.

  10. Select the location where you want to assign this Smart Proxy.

  11. Select Fix on mismatch.

  12. Click Change location.

  13. In the Foreman web UI, navigate to Administer > Organizations and click the organization to which you have assigned Smart Proxy.

  14. Click Smart Proxies tab and ensure that Smart Proxy server is listed under the Selected items list, then click Submit.

  15. In the Foreman web UI, navigate to Administer > Locations and click the location to which you have assigned Smart Proxy.

  16. Click Smart Proxies tab and ensure that Smart Proxy server is listed under the Selected items list, then click Submit.

Verification

Optionally, you can verify if Smart Proxy server is correctly listed in the Foreman web UI.

  1. Select the organization from the Organization list.

  2. Select the location from the Location list.

  3. In the Foreman web UI, navigate to Hosts > All Hosts.

  4. In the Foreman web UI, navigate to Infrastructure > Smart Proxies.

3. Performing additional configuration on Smart Proxy server

If you plan to register hosts to Smart Proxy servers, configure your Smart Proxy servers to provide remote execution, lifecycle environments, and power management functionalities.

3.1. Configuring Smart Proxy server for host registration and provisioning

Configure Smart Proxy server to register and provision hosts through your Smart Proxy server instead of your Foreman server.

Procedure

  1. Enable the Registration and Templates features on your Smart Proxy server and set the template URL:

    # foreman-installer \
--foreman-proxy-registration true \
--foreman-proxy-templates true \
--foreman-proxy-template-url "http://smartproxy.example.com:8000"

  2. On your Smart Proxy server, open the corresponding ports:

    # firewall-cmd --permanent --zone=public --add-port=8000/tcp

  3. On your Smart Proxy server, reload the firewall configuration:

    # firewall-cmd --reload

  4. On Foreman server, add the Smart Proxy to the list of trusted proxies.

    This is required for Foreman to recognize hosts' IP addresses forwarded over the X-Forwarded-For HTTP header set by Smart Proxy. For security reasons, Foreman recognizes this HTTP header only from localhost by default. You can enter trusted proxies as valid IPv4 or IPv6 addresses of Smart Proxies, or network ranges.

    Warning

    Do not use a network range that is too broad because that might cause a security risk.

    Enter the following command. Note that the command overwrites the list that is currently stored in Foreman. Therefore, if you have set any trusted proxies previously, you must include them in the command as well:

    # foreman-installer \
--foreman-trusted-proxies "127.0.0.1/8" \
--foreman-trusted-proxies "::1" \
--foreman-trusted-proxies "My_IP_address" \
--foreman-trusted-proxies "My_IP_range"

    The localhost entries are required, do not omit them.

Verification

  1. List the current trusted proxies using the full help of Foreman installer:

    # foreman-installer --full-help | grep -A 2 "trusted-proxies"

  2. The current listing contains all trusted proxies you require.

3.2. Enabling remote execution

Use this procedure to enable remote execution on your Smart Proxy.

Prerequisites
Procedure

  • On your Smart Proxy, enable remote execution:

    # foreman-installer --enable-foreman-proxy-plugin-remote-execution-script
Additional resources

3.3. Enabling power management on hosts

Enable the baseboard management controller (BMC) module on Smart Proxy server to perform remote power management tasks on hosts, including power cycling and monitoring power states.

Foreman supports the following BMC providers:

  • Intelligent Platform Management Interface (IPMI)

  • Redfish

Foreman supports the following IPMI implementations:

  • freeipmi

  • ipmitool (default)

Prerequisites

  • Your host has a network interface of the BMC type. Smart Proxy server uses this NIC to pass credentials to the host.

Procedure

  1. Enable the BMC module:

    # foreman-installer --foreman-proxy-bmc "true"

  2. Optional: Select the IPMI implementation:

    # foreman-installer --foreman-proxy-bmc-default-provider "freeipmi"

  3. In the Foreman web UI, navigate to Infrastructure > Subnets.

  4. Select the subnet of your host.

  5. On the Proxies tab, select your Smart Proxy server as BMC Proxy.

  6. Click Submit.

Next steps

Appendix A: Smart Proxy server scalability considerations when managing Puppet clients

Smart Proxy server scalability when managing Puppet clients depends on the number of CPUs, the run-interval distribution, and the number of Puppet managed resources.

Smart Proxy server has a limitation of 100 concurrent OpenVox agents running at any single point in time. Running more than 100 concurrent OpenVox agents results in a 503 HTTP error.

For example, assuming that OpenVox agent runs are evenly distributed with less than 100 concurrent OpenVox agents running at any single point during a run-interval, a Smart Proxy server with 4 CPUs has a maximum of 1250 – 1600 Puppet clients with a moderate workload of 10 Puppet classes assigned to each Puppet client. Depending on the number of Puppet clients required, the Foreman installation can scale out the number of Smart Proxy servers to support them.

If you want to scale your Smart Proxy server when managing Puppet clients, the following assumptions are made:

  • There are no external Puppet clients reporting directly to your Foreman server.

  • All other Puppet clients report directly to Smart Proxy servers.

  • There is an evenly distributed run-interval of all OpenVox agents.

Note

Deviating from the even distribution increases the risk of overloading Foreman server. The limit of 100 concurrent requests applies.

The following table describes the scalability limits using the recommended 4 CPUs.

Table 1. Puppet scalability using 4 CPUs
Puppet Managed Resources per Host Run-Interval Distribution

1

3000 – 2500

10

2400 – 2000

20

1700 – 1400

The following table describes the scalability limits using the minimum 2 CPUs.

Table 2. Puppet scalability using 2 CPUs
Puppet Managed Resources per Host Run-Interval Distribution

1

1700 – 1450

10

1500 – 1250

20

850 – 700
Pre-release version Report issue