Configuring Smart Proxies with a load balancer

1. Overview of load balancing in Foreman

You can configure your Foreman environment to use a load balancer to distribute host requests and network load across multiple Smart Proxy servers. This results in an improved performance on Smart Proxy servers and improved performance and stability for host connections to Foreman. In a load-balanced setup, Smart Proxy functionality supported for load balancing continues to work as expected when one Smart Proxy server is down for planned or unplanned maintenance.

1.1. Components of a load-balanced setup

A load-balanced setup in a Foreman environment consists of the following components:

Foreman server
Two or more Smart Proxy servers
A load balancer
Multiple hosts

A host sends a request to the TCP load balancer. The load balancer receives the request and determines which Smart Proxy server will handle the request to ensure optimal performance and availability.

Figure 1. Components of a load-balanced setup

1.2. Services and features supported in a load-balanced setup

A load balancer in Foreman distributes load only for the following services and features:

Registering hosts
Providing content to hosts
Configuring hosts by using Puppet

Other Foreman services, such as provisioning, virt-who, or remote execution, go directly through the individual Smart Proxies on which these services are running.

1.3. Additional maintenance required for load balancing

Configuring Smart Proxies to use a load balancer results in a more complex environment and requires additional maintenance.

The following additional steps are required for load balancing:

You must ensure that all Smart Proxies have the same content. If you publish a content view version on Foreman, synchronize it to all Smart Proxy servers.
You must upgrade each Smart Proxy in sequence.

2. Preparing Smart Proxy servers for load balancing

Foreman does not support configuring existing Smart Proxy servers for load balancing. You must create a new Smart Proxy server for this purpose.

2.1. Registering to Foreman server

Use this procedure to register the base operating system on which you want to install Smart Proxy server to Foreman server.

Registering your Smart Proxy server as a content host is optional unless you wish to download the installation packages from your synced repositories.

Red Hat subscription manifest prerequisites

On Foreman server, a manifest must be installed and it must contain the appropriate repositories for the organization you want Smart Proxy to belong to.
The manifest must contain repositories for the base operating system on which you want to install Smart Proxy, as well as any clients that you want to connect to Smart Proxy.
The repositories must be synchronized.

For more information on manifests and repositories, see Managing Red Hat Subscriptions in Managing content.

Proxy and network prerequisites

The Foreman server base operating system must be able to resolve the host name of the Smart Proxy base operating system and vice versa.
Ensure HTTPS connection using client certificate authentication is possible between Smart Proxy server and Foreman server. HTTP proxies between Smart Proxy server and Foreman server are not supported.
You must configure the host and network-based firewalls accordingly. For more information, see Port and firewall requirements in Installing a Smart Proxy Server nightly on Enterprise Linux. You can register hosts with Foreman using the host registration feature in the Foreman web UI, Hammer CLI, or the Foreman API. For more information, see Registering Hosts in Managing hosts.

Prerequisites

You have set the load balancer for host registration. For more information, see Setting the load balancer for host registration.

Procedure

In the Foreman web UI, navigate to Hosts > Register Host.
From the Smart Proxy dropdown list, select the load balancer.
Select Force to register a host that has been previously registered to a Smart Proxy server.
From the Activation Keys list, select the activation keys to assign to your host.
Click Generate to create the registration command.
Click on the files icon to copy the command to your clipboard.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Enterprise Linux: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

CLI procedure

Generate the host registration command using the Hammer CLI:
```
# hammer host-registration generate-command \
--activation-keys "My_Activation_Key"
```
If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.
```
# hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true
```
Include the --smart-proxy-id My_Smart_Proxy_ID option. You can use the ID of any Smart Proxy server that you configured for host registration load balancing. Foreman will apply the load balancer to the registration command automatically.

Include the --force option to register a host that has been previously registered to a Smart Proxy server.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Enterprise Linux: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

API procedure

Generate the host registration command using the Foreman API:
```
# curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"] }}'
```
If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.
```
# curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"], "insecure": true }}'
```
Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in Managing content.

Include { "smart_proxy_id": My_Smart_Proxy_ID }. You can use the ID of any Smart Proxy server that you configured for host registration load balancing. Foreman will apply the load balancer to the registration command automatically.

Include { "force": true } to register a host that has been previously registered to a Smart Proxy server.

To enter a password as a command line argument, use username:password syntax. Keep in mind this can save the password in the shell history. Alternatively, you can use a temporary personal access token instead of a password. To generate a token in the Foreman web UI, navigate to My Account > Personal Access Tokens.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Enterprise Linux: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

2.2. Installing Smart Proxy server packages

Before installing Smart Proxy server packages, you must update all packages that are installed on the base operating system.

Procedure

To install Smart Proxy server, complete the following steps:

Update all packages:
```
# dnf update
```
Install foreman-proxy-content:
```
# dnf install foreman-proxy-content
```

2.3. Synchronizing the system clock with chronyd

To minimize the effects of time drift, you must synchronize the system clock on the base operating system on which you want to install Smart Proxy server with Network Time Protocol (NTP) servers. If the base operating system clock is configured incorrectly, certificate verification might fail.

For more information about the chrony suite, Using the Chrony suite to configure NTP in Red Hat Enterprise Linux 9 Configuring basic system settings or Using the Chrony suite to configure NTP in Red Hat Enterprise Linux 8 Configuring basic system settings.

Procedure

Install the chrony package:
```
# dnf install chrony
```
Start and enable the chronyd service:
```
# systemctl enable --now chronyd
```

2.4. Next steps

After preparing a Smart Proxy server for load balancing, proceed with Configuring Smart Proxy servers for load balancing.

2.5. Additional resources

For more information about installing Smart Proxy servers, see Installing a Smart Proxy Server nightly on Enterprise Linux.

3. Configuring Smart Proxy servers for load balancing

This chapter outlines how to configure Smart Proxy servers for load balancing. Proceed to one of the following sections depending on your Foreman server configuration:

Configuring Smart Proxy server with default SSL certificates for load balancing without Puppet
Configuring Smart Proxy server with default SSL certificates for load balancing with Puppet
Configuring Smart Proxy server with custom SSL certificates for load balancing without Puppet
Configuring Smart Proxy server with custom SSL certificates for load balancing with Puppet

Use different file names for the Katello certificates you create for each Smart Proxy server. For example, name the certificate archive file with Smart Proxy server FQDN.

3.1. Configuring Smart Proxy server with default SSL certificates for load balancing without Puppet

The following section describes how to configure Smart Proxy servers that use default SSL certificates for load balancing without Puppet. Complete this procedure on each Smart Proxy server that you want to configure for load balancing.

Procedure

On Foreman server, generate Katello certificates for Smart Proxy server:
```
# foreman-proxy-certs-generate \
--certs-tar "/root/smartproxy.example.com-certs.tar" \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn smartproxy.example.com
```
Retain a copy of the example foreman-installer command that is output by the foreman-proxy-certs-generate command for installing Smart Proxy server certificate.

Copy the certificate archive file from Foreman server to Smart Proxy server.

# scp /root/smartproxy.example.com-certs.tar root@smartproxy.example.com:/root/smartproxy.example.com-certs.tar

Append the following options to the foreman-installer command that you obtain from the output of the foreman-proxy-certs-generate command:
```
--certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script
```

On Smart Proxy server, enter the foreman-installer command:

# foreman-installer --scenario foreman-proxy-content \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "smartproxy.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://foreman.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-register-in-foreman "true" \
--foreman-proxy-trusted-hosts "foreman.example.com" \
--foreman-proxy-trusted-hosts "smartproxy.example.com"

3.2. Configuring Smart Proxy server with default SSL certificates for load balancing with Puppet

The following section describes how to configure Smart Proxy servers that use default SSL certificates for load balancing with Puppet.

If you use Puppet in your Foreman configuration, you must complete the following procedures:

Configuring Smart Proxy server with default SSL certificates to generate and sign Puppet certificates
Configuring remaining Smart Proxy servers with default SSL certificates for load balancing

3.2.1. Configuring Smart Proxy server with default SSL certificates to generate and sign Puppet certificates

Complete this procedure only for the system where you want to configure Smart Proxy server to generate and sign Puppet certificates for all other Smart Proxy servers that you configure for load balancing.

Procedure

On Foreman server, generate Katello certificates for the system where you configure Smart Proxy server to generate and sign Puppet certificates:
```
# foreman-proxy-certs-generate \
--certs-tar "/root/smart-proxy-ca.example.com-certs.tar" \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn smart-proxy-ca.example.com
```
Retain a copy of the example foreman-installer command that is output by the foreman-proxy-certs-generate command for installing Smart Proxy server certificate.

Copy the certificate archive file from Foreman server to Smart Proxy server:

# scp /root/smart-proxy-ca.example.com-certs.tar root@smart-proxy-ca.example.com:smart-proxy-ca.example.com-certs.tar

Append the following options to the foreman-installer command that you obtain from the output of the foreman-proxy-certs-generate command:

--certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "true" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "true"

On Smart Proxy server, enter the foreman-installer command:

# foreman-installer --scenario foreman-proxy-content \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "smart-proxy-ca.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--enable-puppet \
--foreman-proxy-foreman-base-url "https://foreman.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "true" \
--foreman-proxy-register-in-foreman "true" \
--foreman-proxy-trusted-hosts "foreman.example.com" \
--foreman-proxy-trusted-hosts "smart-proxy-ca.example.com" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server true \
--puppet-server-ca "true"

On Smart Proxy server, stop the Puppet server:

# puppet resource service puppetserver ensure=stopped

Generate Puppet certificates for all other Smart Proxy servers that you configure for load balancing, except the first system where you configure Puppet certificates signing:
```
# puppetserver ca generate \
--ca-client \
--certname smartproxy.example.com \
--subject-alt-names loadbalancer.example.com
```
This command creates the following files on the system where you configure Smart Proxy server to sign Puppet certificates:
- /etc/puppetlabs/puppet/ssl/certs/smartproxy.example.com.pem
- /etc/puppetlabs/puppet/ssl/certs/ca.pem
- /etc/puppetlabs/puppet/ssl/private_keys/smartproxy.example.com.pem
- /etc/puppetlabs/puppet/ssl/public_keys/smartproxy.example.com.pem

Resume the Puppet server:

# puppet resource service puppetserver ensure=running

3.2.2. Configuring remaining Smart Proxy servers with default SSL certificates for load balancing

Complete this procedure on each Smart Proxy server excluding the system where you configure Smart Proxy server to sign Puppet certificates.

Procedure

On Foreman server, generate Katello certificates for Smart Proxy server:
```
# foreman-proxy-certs-generate \
--certs-tar "/root/smartproxy.example.com-certs.tar" \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn smartproxy.example.com
```
Retain a copy of the example foreman-installer command that is output by the foreman-proxy-certs-generate command for installing Smart Proxy server certificate.

Copy the certificate archive file from Foreman server to Smart Proxy server:

# scp /root/smartproxy.example.com-certs.tar root@smartproxy.example.com:/root/smartproxy.example.com-certs.tar

On Smart Proxy server, install the puppetserver package:
```
# dnf install puppetserver
```

On Smart Proxy server, create directories for puppet certificates:

# mkdir -p /etc/puppetlabs/puppet/ssl/certs/ \
/etc/puppetlabs/puppet/ssl/private_keys/ \
/etc/puppetlabs/puppet/ssl/public_keys/

On Smart Proxy server, copy the Puppet certificates for this Smart Proxy server from the system where you configure Smart Proxy server to sign Puppet certificates:

# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/smartproxy.example.com.pem /etc/puppetlabs/puppet/ssl/certs/smartproxy.example.com.pem
# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/ca.pem /etc/puppetlabs/puppet/ssl/certs/ca.pem
# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/private_keys/smartproxy.example.com.pem /etc/puppetlabs/puppet/ssl/private_keys/smartproxy.example.com.pem
# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/public_keys/smartproxy.example.com.pem /etc/puppetlabs/puppet/ssl/public_keys/smartproxy.example.com.pem

On Smart Proxy server, change the /etc/puppetlabs/puppet/ssl/ directory ownership to user puppet and group puppet:
```
# chown -R puppet:puppet /etc/puppetlabs/puppet/ssl/
```
On Smart Proxy server, set the SELinux context for the /etc/puppetlabs/puppet/ssl/ directory:
```
# restorecon -Rv /etc/puppetlabs/puppet/ssl/
```

Append the following options to the foreman-installer command that you obtain from the output of the foreman-proxy-certs-generate command:

--certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "false" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"

On Smart Proxy server, enter the foreman-installer command:

# foreman-installer --scenario foreman-proxy-content \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "smartproxy.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://foreman.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "false" \
--foreman-proxy-register-in-foreman "true" \
--foreman-proxy-trusted-hosts "foreman.example.com" \
--foreman-proxy-trusted-hosts "smartproxy.example.com" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"

3.3. Configuring Smart Proxy server with custom SSL certificates for load balancing without Puppet

The following section describes how to configure Smart Proxy servers that use custom SSL certificates for load balancing without Puppet.

3.3.1. Creating a custom SSL certificate for Smart Proxy server

This procedure outlines how to create a configuration file for the Certificate Signing Request and include the load balancer and Smart Proxy server as Subject Alternative Names (SAN). Complete this procedure on each Smart Proxy server that you want to configure for load balancing.

Procedure

To store all the source certificate files, create a directory that is accessible only to the root user:
```
# mkdir /root/smart-proxy_cert
```
Create a private key with which to sign the certificate signing request (CSR).

Note that the private key must be unencrypted. If you use a password-protected private key, remove the private key password.

If you already have a private key for this Smart Proxy server, skip this step.
```
# openssl genrsa -out /root/smart-proxy_cert/smart-proxy_cert_key.pem 4096
```
Create the /root/smart-proxy_cert/openssl.cnf configuration file for the CSR and include the following content:
```
[ req ]
req_extensions = v3_req
distinguished_name = req_distinguished_name
x509_extensions = usr_cert
prompt = no

[ req_distinguished_name ]
commonName = smartproxy.example.com (1)

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
subjectAltName = @alt_names

[alt_names] (2)
DNS.1 = loadbalancer.example.com
DNS.2 = smartproxy.example.com
```
1. The certificate’s common name must match the FQDN of Smart Proxy server. Ensure to change this when running the command on each Smart Proxy server that you configure for load balancing. You can also set a wildcard value *. If you set a wildcard value, you must add the -t foreman-proxy option when you use the katello-certs-check command.
2. Under [alt_names], include the FQDN of the load balancer as DNS.1 and the FQDN of Smart Proxy server as DNS.2.

Optional: If you want to add Distinguished Name (DN) details to the CSR, add the following information to the [ req_distinguished_name ] section:

[req_distinguished_name]
CN = smartproxy.example.com
countryName =My_Country_Name (1)
stateOrProvinceName = My_State_Or_Province_Name (2)
localityName = My_Locality_Name (3)
organizationName = My_Organization_Or_Company_Name
organizationalUnitName = My_Organizational_Unit_Name (4)

Two letter code
Full name
Full name (example: New York)
Division responsible for the certificate (example: IT department)

Generate CSR:

# openssl req -new \
-key /root/smart-proxy_cert/smart-proxy_cert_key.pem \ (1)
-config /root/smart-proxy_cert/openssl.cnf \ (2)
-out /root/smart-proxy_cert/smart-proxy_cert_csr.pem (3)

Path to the private key
Path to the configuration file
Path to the CSR to generate

Send the certificate signing request to the certificate authority (CA). The same CA must sign certificates for Foreman server and Smart Proxy server.

When you submit the request, specify the lifespan of the certificate. The method for sending the certificate request varies, so consult the CA for the preferred method. In response to the request, you can expect to receive a CA bundle and a signed certificate, in separate files.
Copy the Certificate Authority bundle and Smart Proxy server certificate file that you receive from the Certificate Authority, and Smart Proxy server private key to your Foreman server.
On Foreman server, validate Smart Proxy server certificate input files:
```
# katello-certs-check \
-c /root/smart-proxy_cert/smart-proxy_cert.pem \ (1)
-k /root/smart-proxy_cert/smart-proxy_cert_key.pem \ (2)
-b /root/smart-proxy_cert/ca_cert_bundle.pem (3)
```
1. Smart Proxy server certificate file, provided by your Certificate Authority
2. Smart Proxy server’s private key that you used to sign the certificate
3. Certificate Authority bundle, provided by your Certificate Authority
  
  If you set the commonName= to a wildcard value *, you must add the -t foreman-proxy option to the katello-certs-check command.
  
  Retain a copy of the example foreman-proxy-certs-generate command that is output by the katello-certs-check command for creating the Certificate Archive File for this Smart Proxy server.

3.3.2. Configuring Smart Proxy server with custom SSL certificates for load balancing without Puppet

The following section describes how to configure Smart Proxy servers that use custom SSL certificates for load balancing without Puppet. Complete this procedure on each Smart Proxy server that you want to configure for load balancing.

Procedure

Append the following option to the foreman-proxy-certs-generate command that you obtain from the output of the katello-certs-check command:
```
--foreman-proxy-cname loadbalancer.example.com
```

On Foreman server, enter the foreman-proxy-certs-generate command to generate Smart Proxy certificates:

# foreman-proxy-certs-generate \
--certs-tar /root/smart-proxy_cert/smart-proxy.tar \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn smartproxy.example.com \
--server-ca-cert /root/smart-proxy_cert/ca_cert_bundle.pem \
--server-cert /root/smart-proxy_cert/smart-proxy.pem \
--server-key /root/smart-proxy_cert/smart-proxy.pem

Retain a copy of the example foreman-installer command from the output for installing Smart Proxy server certificates.

Copy the certificate archive file from Foreman server to Smart Proxy server:

# scp /root/smartproxy.example.com-certs.tar root@smartproxy.example.com:smartproxy.example.com-certs.tar

Append the following options to the foreman-installer command that you obtain from the output of the foreman-proxy-certs-generate command:
```
--certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script
```

On Smart Proxy server, enter the foreman-installer command:

# foreman-installer --scenario foreman-proxy-content \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "smartproxy.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://foreman.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-register-in-foreman "true" \
--foreman-proxy-trusted-hosts "foreman.example.com" \
--foreman-proxy-trusted-hosts "smartproxy.example.com"

3.4. Configuring Smart Proxy server with custom SSL certificates for load balancing with Puppet

If you use Puppet in your Foreman configuration, then you must complete the following procedures:

Configuring Smart Proxy server with custom SSL certificates to generate and sign Puppet certificates
Configuring remaining Smart Proxy servers with custom SSL certificates for load balancing

3.4.1. Creating a custom SSL certificate for Smart Proxy server

Procedure

To store all the source certificate files, create a directory that is accessible only to the root user:
```
# mkdir /root/smart-proxy_cert
```
Create a private key with which to sign the certificate signing request (CSR).

Note that the private key must be unencrypted. If you use a password-protected private key, remove the private key password.

If you already have a private key for this Smart Proxy server, skip this step.
```
# openssl genrsa -out /root/smart-proxy_cert/smart-proxy_cert_key.pem 4096
```
Create the /root/smart-proxy_cert/openssl.cnf configuration file for the CSR and include the following content:
```
[ req ]
req_extensions = v3_req
distinguished_name = req_distinguished_name
x509_extensions = usr_cert
prompt = no

[ req_distinguished_name ]
commonName = smartproxy.example.com (1)

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
subjectAltName = @alt_names

[alt_names] (2)
DNS.1 = loadbalancer.example.com
DNS.2 = smartproxy.example.com
```
1. The certificate’s common name must match the FQDN of Smart Proxy server. Ensure to change this when running the command on each Smart Proxy server that you configure for load balancing. You can also set a wildcard value *. If you set a wildcard value, you must add the -t foreman-proxy option when you use the katello-certs-check command.
2. Under [alt_names], include the FQDN of the load balancer as DNS.1 and the FQDN of Smart Proxy server as DNS.2.

Optional: If you want to add Distinguished Name (DN) details to the CSR, add the following information to the [ req_distinguished_name ] section:

[req_distinguished_name]
CN = smartproxy.example.com
countryName =My_Country_Name (1)
stateOrProvinceName = My_State_Or_Province_Name (2)
localityName = My_Locality_Name (3)
organizationName = My_Organization_Or_Company_Name
organizationalUnitName = My_Organizational_Unit_Name (4)

Two letter code
Full name
Full name (example: New York)
Division responsible for the certificate (example: IT department)

Generate CSR:

# openssl req -new \
-key /root/smart-proxy_cert/smart-proxy_cert_key.pem \ (1)
-config /root/smart-proxy_cert/openssl.cnf \ (2)
-out /root/smart-proxy_cert/smart-proxy_cert_csr.pem (3)

Path to the private key
Path to the configuration file
Path to the CSR to generate

Send the certificate signing request to the certificate authority (CA). The same CA must sign certificates for Foreman server and Smart Proxy server.

When you submit the request, specify the lifespan of the certificate. The method for sending the certificate request varies, so consult the CA for the preferred method. In response to the request, you can expect to receive a CA bundle and a signed certificate, in separate files.
Copy the Certificate Authority bundle and Smart Proxy server certificate file that you receive from the Certificate Authority, and Smart Proxy server private key to your Foreman server.
On Foreman server, validate Smart Proxy server certificate input files:
```
# katello-certs-check \
-c /root/smart-proxy_cert/smart-proxy_cert.pem \ (1)
-k /root/smart-proxy_cert/smart-proxy_cert_key.pem \ (2)
-b /root/smart-proxy_cert/ca_cert_bundle.pem (3)
```
1. Smart Proxy server certificate file, provided by your Certificate Authority
2. Smart Proxy server’s private key that you used to sign the certificate
3. Certificate Authority bundle, provided by your Certificate Authority
  
  If you set the commonName= to a wildcard value *, you must add the -t foreman-proxy option to the katello-certs-check command.
  
  Retain a copy of the example foreman-proxy-certs-generate command that is output by the katello-certs-check command for creating the Certificate Archive File for this Smart Proxy server.

3.4.2. Configuring Smart Proxy server with custom SSL certificates to generate and sign Puppet certificates

Complete this procedure only for the system where you want to configure Smart Proxy server to generate Puppet certificates for all other Smart Proxy servers that you configure for load balancing.

Procedure

Append the following option to the foreman-proxy-certs-generate command that you obtain from the output of the katello-certs-check command:
```
--foreman-proxy-cname loadbalancer.example.com
```

On Foreman server, enter the foreman-proxy-certs-generate command to generate Smart Proxy certificates:

# foreman-proxy-certs-generate \
--certs-tar /root/smart-proxy_cert/smart-proxy-ca.tar \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn smart-proxy-ca.example.com \
--server-ca-cert /root/smart-proxy_cert/ca_cert_bundle.pem \
--server-cert /root/smart-proxy_cert/smart-proxy-ca.pem \
--server-key /root/smart-proxy_cert/smart-proxy-ca.pem

Retain a copy of the example foreman-installer command from the output for installing Smart Proxy server certificates.

Copy the certificate archive file from Foreman server to Smart Proxy server.

Append the following options to the foreman-installer command that you obtain from the output of the foreman-proxy-certs-generate command:

--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "true" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "true"

On Smart Proxy server, enter the foreman-installer command:

# foreman-installer --scenario foreman-proxy-content \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "certs.tgz" \
--enable-foreman-proxy-plugin-remote-execution-script \
--enable-puppet \
--foreman-proxy-foreman-base-url "https://foreman.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "true" \
--foreman-proxy-register-in-foreman "true" \
--foreman-proxy-trusted-hosts "foreman.example.com" \
--foreman-proxy-trusted-hosts "smart-proxy-ca.example.com" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server true \
--puppet-server-ca "true"

On Smart Proxy server, generate Puppet certificates for all other Smart Proxies that you configure for load balancing, except this first system where you configure Puppet certificates signing:
```
# puppet cert generate smartproxy.example.com \
--dns_alt_names=loadbalancer.example.com
```
This command creates the following files on the Puppet certificate signing Smart Proxy server instance:
- /etc/puppetlabs/puppet/ssl/certs/ca.pem
- /etc/puppetlabs/puppet/ssl/certs/smartproxy.example.com.pem
- /etc/puppetlabs/puppet/ssl/private_keys/smartproxy.example.com.pem
- /etc/puppetlabs/puppet/ssl/public_keys/smartproxy.example.com.pem

3.4.3. Configuring remaining Smart Proxy servers with custom SSL certificates for load balancing

Complete this procedure for each Smart Proxy server excluding the system where you configure Smart Proxy server to sign Puppet certificates.

Procedure

Append the following option to the foreman-proxy-certs-generate command that you obtain from the output of the katello-certs-check command:
```
--foreman-proxy-cname loadbalancer.example.com
```

On Foreman server, enter the foreman-proxy-certs-generate command to generate Smart Proxy certificates:

# foreman-proxy-certs-generate \
--certs-tar /root/smart-proxy_cert/smart-proxy.tar \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn smartproxy.example.com \
--server-ca-cert /root/smart-proxy_cert/ca_cert_bundle.pem \
--server-cert /root/smart-proxy_cert/smart-proxy.pem \
--server-key /root/smart-proxy_cert/smart-proxy.pem

Retain a copy of the example foreman-installer command from the output for installing Smart Proxy server certificates.

Copy the certificate archive file from Foreman server to Smart Proxy server.

# scp /root/smartproxy.example.com-certs.tar root@smartproxy.example.com:smartproxy.example.com-certs.tar

On Smart Proxy server, install the puppetserver package:
```
# dnf install puppetserver
```

On Smart Proxy server, create directories for puppet certificates:

# mkdir -p /etc/puppetlabs/puppet/ssl/certs/ \
/etc/puppetlabs/puppet/ssl/private_keys/ \
/etc/puppetlabs/puppet/ssl/public_keys/

On Smart Proxy server, copy the Puppet certificates for this Smart Proxy server from the system where you configure Smart Proxy server to sign Puppet certificates:

# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/smartproxy.example.com.pem /etc/puppetlabs/puppet/ssl/certs/smartproxy.example.com.pem
# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/ca.pem /etc/puppetlabs/puppet/ssl/certs/ca.pem
# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/private_keys/smartproxy.example.com.pem /etc/puppetlabs/puppet/ssl/private_keys/smartproxy.example.com.pem
# scp root@smart-proxy-ca.example.com:/etc/puppetlabs/puppet/ssl/public_keys/smartproxy.example.com.pem /etc/puppetlabs/puppet/ssl/public_keys/smartproxy.example.com.pem

On Smart Proxy server, change the /etc/puppetlabs/puppet/ssl/ directory ownership to user puppet and group puppet:
```
# chown -R puppet:puppet /etc/puppetlabs/puppet/ssl/
```
On Smart Proxy server, set the SELinux context for the /etc/puppetlabs/puppet/ssl/ directory:
```
# restorecon -Rv /etc/puppetlabs/puppet/ssl/
```

Append the following options to the foreman-installer command that you obtain from the output of the foreman-proxy-certs-generate command:

--certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "false" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"

On Smart Proxy server, enter the foreman-installer command:

# foreman-installer --scenario foreman-proxy-content \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "smartproxy.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://foreman.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "false" \
--foreman-proxy-register-in-foreman "true" \
--foreman-proxy-trusted-hosts "foreman.example.com" \
--foreman-proxy-trusted-hosts "smartproxy.example.com" \
--puppet-ca-server "smart-proxy-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"

4. Managing Puppet limitations with load balancing in Foreman

If you use Puppet, Puppet certificate signing is assigned to the first Smart Proxy that you configure. If the first Smart Proxy is down, hosts cannot obtain Puppet content.

Puppet Certificate Authority (CA) management does not support certificate signing in a load-balanced setup. Puppet CA stores certificate information, such as the serial number counter and CRL, on the file system. Multiple writer processes that attempt to use the same data can corrupt it.

To manage this Puppet limitation, complete the following steps:

Configure Puppet certificate signing on one Smart Proxy server, typically the first system where you configure Smart Proxy server for load balancing.
Configure the clients to send CA requests to port 8141 on a load balancer.
Configure a load balancer to redirect CA requests from port 8141 to port 8140 on the system where you configure Smart Proxy server to sign Puppet certificates.

To troubleshoot issues, reproduce the issue on each Smart Proxy, bypassing the load balancer. This solution does not use Pacemaker or other similar HA tools to maintain one state across all Smart Proxies.

5. Upgrading Smart Proxy servers in a load-balancing setup

There are no additional steps required for Smart Proxy servers in a load-balancing configuration.

6. Setting the load balancer for host registration

You can configure Foreman to register clients through a load balancer when using the host registration feature.

You will be able to register hosts to the load balancer instead of Smart Proxy. The load balancer will decide through which Smart Proxy to register the host at the time of request. Upon registration, the subscription manager on the host will be configured to manage content through the load balancer.

Prerequisites

You configured SSL certificates on all Smart Proxy servers. For more information, see Configuring Smart Proxy servers for load balancing.

You enabled Registration and Templates plugins on all Smart Proxy servers:

# foreman-installer --scenario foreman-proxy-content \
--foreman-proxy-registration true \
--foreman-proxy-templates true

Procedure

On all Smart Proxy servers, set the registration and template URLs using foreman-installer:

# foreman-installer --scenario foreman-proxy-content \
--foreman-proxy-registration-url "https://loadbalancer.example.com:9090" \
--foreman-proxy-template-url "https://loadbalancer.example.com:8000"

In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
For each Smart Proxy, click the dropdown menu in the Actions column and select Refresh.

7. Installing the load balancer

The following example provides general guidance for configuring an HAProxy load balancer using Enterprise Linux 9 or Enterprise Linux 8. However, you can install any suitable load balancing software solution that supports TCP forwarding.

Procedure

Install HAProxy:
```
# dnf install haproxy
```
Install the following package that includes the semanage tool:
```
# dnf install policycoreutils-python-utils
```

Configure SELinux to allow HAProxy to bind any port:

# semanage boolean --modify --on haproxy_connect_any

Configure the load balancer to balance the network load for the ports as described in Ports configuration for the load balancer. For example, to configure ports for HAProxy, edit the /etc/haproxy/haproxy.cfg file to correspond with the table.

Table 1. Ports configuration for the load balancer
Service	Port	Mode	Balance Mode	Destination
HTTP	80	TCP	roundrobin	port 80 on all Smart Proxy servers
HTTPS and RHSM	443	TCP	source	port 443 on all Smart Proxy servers
Anaconda for template retrieval	8000	TCP	roundrobin	port 8000 on all Smart Proxy servers
Puppet (Optional)	8140	TCP	roundrobin	port 8140 on all Smart Proxy servers
PuppetCA (Optional)	8141	TCP	roundrobin	port 8140 only on the system where you configure Smart Proxy server to sign Puppet certificates
Smart Proxy HTTPS for Host Registration and optionally OpenSCAP	9090	TCP	roundrobin	port 9090 on all Smart Proxy servers

Configure the load balancer to disable SSL offloading and allow client-side SSL certificates to pass through to back end servers. This is required because communication from clients to Smart Proxy servers depends on client-side SSL certificates.
Start and enable the HAProxy service:
```
# systemctl enable --now haproxy
```

8. Verifying the load balancing configuration

Use this procedure to verify the load balancing configuration for each Smart Proxy server.

Procedure

Shut down the base operating system for your Smart Proxy server.
Verify that content or subscription management features are available on clients registered to this Smart Proxy. For example, enter the subscription-manager refresh command on a client.
Restart the base operating system for your Smart Proxy server.

9. Registering clients to the load balancer

To balance the load of network traffic from clients, you must register the clients to the load balancer.

You can register hosts with Foreman using the host registration feature in the Foreman web UI, Hammer CLI, or the Foreman API. For more information, see Registering Hosts in Managing hosts.

Prerequisites

You have set the load balancer for host registration. For more information, see Setting the load balancer for host registration.

Procedure

In the Foreman web UI, navigate to Hosts > Register Host.
From the Smart Proxy dropdown list, select the load balancer.
Select Force to register a host that has been previously registered to a Smart Proxy server.
From the Activation Keys list, select the activation keys to assign to your host.
Click Generate to create the registration command.
Click on the files icon to copy the command to your clipboard.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Enterprise Linux: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

CLI procedure

Generate the host registration command using the Hammer CLI:
```
# hammer host-registration generate-command \
--activation-keys "My_Activation_Key"
```
If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.
```
# hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true
```
Include the --smart-proxy-id My_Smart_Proxy_ID option. You can use the ID of any Smart Proxy server that you configured for host registration load balancing. Foreman will apply the load balancer to the registration command automatically.

Include the --force option to register a host that has been previously registered to a Smart Proxy server.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Enterprise Linux: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

API procedure

Generate the host registration command using the Foreman API:
```
# curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"] }}'
```
If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.
```
# curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"], "insecure": true }}'
```
Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in Managing content.

Include { "smart_proxy_id": My_Smart_Proxy_ID }. You can use the ID of any Smart Proxy server that you configured for host registration load balancing. Foreman will apply the load balancer to the registration command automatically.

Include { "force": true } to register a host that has been previously registered to a Smart Proxy server.

To enter a password as a command line argument, use username:password syntax. Keep in mind this can save the password in the shell history. Alternatively, you can use a temporary personal access token instead of a password. To generate a token in the Foreman web UI, navigate to My Account > Personal Access Tokens.
Connect to your host using SSH and run the registration command.
Ensure that the appropriate repositories have been enabled:
- On Enterprise Linux: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.
- On Debian: Check the /etc/apt/sources.list file and ensure that the appropriate repositories have been enabled.

10. Propagating SCAP content through the load balancer

If you use OpenSCAP to manage security compliance on your clients, you must configure the SCAP client to send ARF reports to the load balancer instead of Smart Proxy. The configuration procedure depends on the method you have selected to deploy compliance policies.

10.1. Propagating SCAP content using Ansible deployment

Using this procedure, you can promote Security Content Automation Protocol (SCAP) content through the load balancer in the scope of the Ansible deployment method.

Prerequisites

Ensure that you have configured Foreman for Ansible deployment of compliance policies. For more information, see Configuring Compliance Policy Deployment Methods in Managing security compliance.

Procedure

In the Foreman web UI, navigate to Configure > Ansible > Variables.
Search for the foreman_scap_client_port variable and click its name.
In the Default Behavior area, ensure that the Override checkbox is selected.
In the Parameter Type list, ensure that integer is selected.
In the Default Value field, enter 9090.
In the Specify Matchers area, remove all matchers that override the default value.
Click Submit.
Search for the foreman_scap_client_server variable and click its name.
In the Default Behavior area, ensure that the Override checkbox is selected.
In the Parameter Type list, ensure that string is selected.
In the Default Value field, enter the FQDN of your load balancer, such as loadbalancer.example.com.
In the Specify Matchers area, remove all matchers that override the default value.
Click Submit.
Continue with deploying a compliance policy using Ansible. For more information, see:
- Deploying a Policy in a Host Group Using Ansible in Managing security compliance
- Deploying a Policy on a Host Using Ansible in Managing security compliance

Verification

On the client, verify that the /etc/foreman_scap_client/config.yaml file contains the following lines:
```
# Foreman proxy to which reports should be uploaded
:server: 'loadbalancer.example.com'
:port: 9090
```

10.2. Propagating SCAP content using Puppet deployment

Using this procedure, you can promote Security Content Automation Protocol (SCAP) content through the load balancer in the scope of the Puppet deployment method.

Prerequisites

Ensure that you have configured Foreman for Puppet deployment of compliance policies. For more information, see Configuring Compliance Policy Deployment Methods in Managing security compliance.

Procedure

In the Foreman web UI, navigate to Configure > Puppet ENC > Classes.
Click foreman_scap_client.
Click the Smart Class Parameter tab.
In the pane to the left of the Smart Class Parameter window, click port.
In the Default Behavior area, select the Override checkbox.
From the Key Type list, select integer.
In the Default Value field, enter 9090.
In the pane to the left of the Smart Class Parameter window, click server.
In the Default Behavior area, select the Override checkbox.
From the Key Type list, select string.
In the Default Value field, enter the FQDN of your load balancer, such as loadbalancer.example.com.
In the lower left of the Smart Class Parameter window, click Submit.
Continue with deploying a compliance policy using Puppet. For more information, see:
- Deploying a Policy in a Host Group Using Puppet in Managing security compliance
- Deploying a Policy on a Host Using Puppet in Managing security compliance

Verification

On the client, verify that the /etc/foreman_scap_client/config.yaml file contains the following lines:
```
# Foreman proxy to which reports should be uploaded
:server: 'loadbalancer.example.com'
:port: 9090
```

Appendix A: Troubleshooting DNF modules

If DNF modules fails to enable, it can mean an incorrect module is enabled. In that case, you have to resolve dependencies manually as follows. List the enabled modules:

# dnf module list --enabled

Ruby

If Ruby module fails to enable, it can mean an incorrect module is enabled. In that case, you have to resolve dependencies manually as follows:

List the enabled modules:

# dnf module list --enabled

If the Ruby 2.5 module has already been enabled, perform a module reset:

# dnf module reset ruby

PostgreSQL

If PostgreSQL module fails to enable, it can mean an incorrect module is enabled. In that case, you have to resolve dependencies manually as follows:

List the enabled modules:

# dnf module list --enabled

If the PostgreSQL 10 module has already been enabled, perform a module reset:

# dnf module reset postgresql

If a database was previously created using PostgreSQL 10, perform an upgrade:

Enable the DNF modules:
```
# dnf module enable katello:el8
```
Install the PostgreSQL upgrade package:
```
# dnf install postgresql-upgrade
```
Perform the upgrade:
```
# postgresql-setup --upgrade
```