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 foremanctl 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

    • 12 GB or higher

    • 4 GB RAM of swap space 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 that the provider did not create the apache user account on the system. This user account can cause conflicts with the local users that Smart Proxy server creates.

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

1.3. Smart Proxy storage requirements

Ensure sufficient storage is allocated to the required directories for successful installation and operation of Smart Proxy server. Note that the values can vary according to individual environments.

The runtime size was measured with Enterprise Linux 7, 8, and 9 repositories synchronized.

Table 1. Storage requirements for Smart Proxy server installation
Directory Installation Size Runtime Size

/var/lib/pulp

1 MB

300 GB

/var/lib/pgsql

100 MB

20 GB

/usr

3 GB

Not Applicable

The size of the PostgreSQL database on your Smart Proxy server can grow significantly with an increasing number of lifecycle environments, content views, or repositories that are synchronized from your Foreman server. In the largest Foreman environments, the size of /var/lib/pgsql on Smart Proxy server can grow to double or triple the size of /var/lib/pgsql on your Foreman server.

1.4. Best practices for optimizing storage

You can optimize your storage by following the storage best practices. These include using LVM for /var, high-bandwidth storage for critical directories, and appropriate file systems to improve I/O performance and scalability.

  • The exact amount of storage you require for log messages depends on your installation and setup. You can manage the size of the log files by using logrotate.

  • Consider mounting /var on LVM storage. This can help the system to scale because most Smart Proxy server data is stored in the /var directory.

  • Use high-bandwidth, low-latency storage for the /var/lib/pulp/ and /var/lib/pgsql directories. Using high latency, low-bandwidth storage causes performance degradation because Foreman has many operations that are I/O intensive.

  • Use a file system with low input-output latency. Do not use the GFS2 file system because the input-output latency is too high.

Additional resources

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

Prerequisites
Procedure

  1. Open the ports for clients on Smart Proxy server:

    # firewall-cmd \
--add-port="8000/tcp" \
--add-port="8443/tcp"

  2. Allow access to services on Smart Proxy server:

    # firewall-cmd \
--add-service=http \
--add-service=https

  3. 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 katello-repos-latest.rpm package:

    # dnf install https://yum.theforeman.org/katello/nightly/katello/el9/x86_64/katello-repos-latest.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 foremanctl

2.3. Configuring Smart Proxy server with SSL certificates

Foreman uses SSL certificates to enable encrypted communications between Foreman server, Smart Proxy servers, and all hosts. Depending on the requirements of your organization, you must configure your Smart Proxy server with a default or custom certificate.

2.3.1. Configuring Smart Proxy server with a default SSL certificate

If your Foreman server is configured with the default certificate, you must configure your Smart Proxy server with the SSL certificate that is signed by Foreman server default Certificate Authority (CA).

Prerequisites
Procedure

  1. On your Foreman server, generate an authentication bundle for the Smart Proxy server:

    # foremanctl auth-bundle smartproxy.example.com

    To regenerate the bundle for an existing Smart Proxy server, add the --certificate-renew option to the foremanctl auth-bundle command.

  2. On your Foreman server, copy the authentication bundle to Smart Proxy server:

    # scp /var/lib/foremanctl/certs/bundles/smartproxy.example.com.tar.gz \
root@smartproxy.example.com:/root/smartproxy.example.com.tar.gz
    Important

    The authentication bundle contains TLS private keys and OAuth credentials. Treat the bundle as highly sensitive and delete any copies after deployment.

  3. On the Smart Proxy server, deploy the configuration:

    # foremanctl deploy-proxy \
--flavor foreman-proxy-content \
--auth-bundle /root/smartproxy.example.com.tar.gz \
--foreman-fqdn foreman.example.com
    Important

    Do not delete the certificate archive file after you deploy the certificate. It is required, for example, when upgrading Smart Proxy server.

2.3.2. Configuring Smart Proxy server with a custom SSL certificate

If you configure Foreman server to use a custom SSL certificate, you must also configure each of your Smart Proxy servers with a distinct custom SSL certificate.

Creating a custom SSL certificate for Smart Proxy server

On Foreman server, create a custom certificate for your Smart Proxy server. If you already have a custom SSL certificate for Smart Proxy server, skip this procedure.

Procedure

  1. To store all the source certificate files, create a directory that is accessible only to the root user:

    # mkdir /root/smart-proxy_cert

  2. Create a private key with which to sign the certificate signing request (CSR). The private key must be unencrypted:

    # openssl genrsa -out /root/smart-proxy_cert/smart-proxy_cert_key.pem 4096

    If you already have a private key, skip this step.

  3. Optional: Verify that the key is unencrypted:

    # openssl pkey -noout -in /root/smart-proxy_cert/smart-proxy_cert_key.pem

    If the command does not ask for a password, the key is unencrypted. If your private key is password-protected, remove the password.

  4. 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
prompt = no

[ req_distinguished_name ]
commonName = smartproxy.example.com

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

[ alt_names ]
DNS.1 = smartproxy.example.com

    For more information about the [ v3_req ] parameters and their purpose, see RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

  5. 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]
commonName = smartproxy.example.com
countryName = My_Country_Name
stateOrProvinceName = My_State_Or_Province_Name
localityName = My_Locality_Name
organizationName = My_Organization_Or_Company_Name
organizationalUnitName = My_Organizational_Unit_Name

    The options used in the configuration file include the following:

    countryName

    The country represented by a two-letter code

    stateOrProvinceName

    Full name of the state or province

    localityName

    Full name of the locality (example: New York)

    organizationalUnitName

    Division responsible for the certificate (example: IT department)

  6. Generate the CSR:

    # openssl req -new \
-key /root/smart-proxy_cert/smart-proxy_cert_key.pem \
-config /root/smart-proxy_cert/openssl.cnf \
-out /root/smart-proxy_cert/smart-proxy_cert_csr.pem

    The options used in the configuration file include the following:

    -key

    Path to the private key

    -config

    Path to the configuration file

    -out

    Path to the CSR to generate

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

Deploying a custom SSL certificate to Smart Proxy server

If your Foreman server is configured with a custom certificate, you must configure your Smart Proxy server with a custom SSL certificate signed by the same Certificate Authority.

Prerequisites
Procedure

  1. On your Foreman server, generate an authentication bundle for the Smart Proxy server:

    # foremanctl auth-bundle smartproxy.example.com \
--certificate-source custom_server \
--certificate-server-certificate "/root/smart-proxy_cert/smart-proxy_cert.pem" \
--certificate-server-key "/root/smart-proxy_cert/smart-proxy_cert_key.pem"

    The options used in the command include the following:

    --certificate-source custom_server

    Sets the certificate source to custom server certificates provided by the user.

    --certificate-server-certificate

    Path to Smart Proxy server certificate file that is signed by a Certificate Authority.

    --certificate-server-key

    Path to the private key for the Smart Proxy server certificate.

    To regenerate the bundle for an existing Smart Proxy server, add the --certificate-renew option to the foremanctl auth-bundle command.

  2. On your Foreman server, copy the authentication bundle to Smart Proxy server:

    # scp /var/lib/foremanctl/certs/bundles/smartproxy.example.com.tar.gz \
root@smartproxy.example.com:/root/smartproxy.example.com.tar.gz
    Important

    The authentication bundle contains TLS private keys and OAuth credentials. Treat the bundle as highly sensitive and delete any copies after deployment.

  3. On the Smart Proxy server, deploy the configuration:

    # foremanctl deploy-proxy \
--flavor foreman-proxy-content \
--auth-bundle /root/smartproxy.example.com.tar.gz \
--foreman-fqdn foreman.example.com
    Important

    Do not delete the certificate archive file after you deploy the certificate. It is required, for example, when upgrading Smart Proxy server.
Deploying a custom SSL certificate to hosts

After you configure Foreman to use a custom SSL certificate, you must deploy the certificate to hosts registered to Foreman.

Important

The katello-ca-consumer RPM package and katello-rhsm-consumer script is a deprecated feature. Deprecated functionality is still included in Foreman and continues to be supported. However, it will be removed in a future release of this product and is not recommended for new deployments.

Use refreshing the self-signed CA certificate on hosts instead.

For the most recent list of major functionality that has been deprecated or removed within Foreman, refer to the Deprecated features section of the Foreman release notes.
Procedure

  • Update the SSL certificate on each host:

    • On Enterprise Linux:

      # dnf install http://smartproxy.example.com/pub/katello-ca-consumer-latest.noarch.rpm

    • On Debian/Ubuntu:

      # wget http://smartproxy.example.com/pub/katello-rhsm-consumer
# chmod +x katello-rhsm-consumer
# ./katello-rhsm-consumer

    • On openSUSE/SUSE Linux Enterprise Server:

      # zypper install http://smartproxy.example.com/pub/katello-ca-consumer-latest.noarch.rpm
Additional resources

2.4. Resetting custom SSL certificate to default self-signed certificate on Smart Proxy server

If you want to revert to the default certificate configuration, you can reset a custom SSL certificate to the default self-signed certificate on your Smart Proxy server by re-registering your Smart Proxy server to Foreman.

Procedure

  • To reset the custom SSL certificate to default self-signed certificate on your Smart Proxy server, you must re-register your Smart Proxy server through Global Registration. For more information, see Registering hosts by using global registration in Managing hosts.

Verification

  1. In the Foreman web UI, navigate to Infrastructure > Smart Proxies and select any Smart Proxy server.

  2. On the Overview tab, click Refresh features.

Additional resources

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

Pre-release version Report issue