Important

The foremanctl deployment utility is a Technology Preview feature only. Technology Preview features are not supported by Foreman community. Foreman community does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

1. Planning Foreman server installation

Review the following guidelines, requirements, and considerations before proceeding with the installation.

1.1. Operating system requirements

Your operating system and installation method must meet the following requirements before you can 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.

Additional resources

1.2. System requirements

Your system must meet the following general requirements before you can install Foreman server.

Follow these system requirements when installing Foreman server:

  • Install Foreman server on a freshly provisioned system that serves no other function except to run Foreman server. Do not use an existing system because the Foreman installer will affect 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

    • 20 GB RAM 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 Foreman server creates.

1.3. Storage requirements

Your system must meet the following storage requirements before you can install Foreman server.

Follow these storage requirements when installing Foreman server:

  • Ensure that the directories used by Foreman server have sufficient disk space available:

    Table 1. Storage requirements for a Foreman server installation
    Directory Installation Size Runtime Size

    /var/log

    10 MB

    10 GB

    /var/lib/pgsql

    1 GB

    20 GB

    /usr

    10 GB

    Not Applicable

    /opt/puppetlabs

    500 MB

    Not Applicable

    /var/lib/pulp

    1 MB

    300 GB

    /var/lib/containers

    20 GB

    30 GB

    These values are based on expected use case scenarios and can vary according to individual environments. The runtime size was measured with Enterprise Linux 7, 8, and 9 repositories synchronized.

  • If you mount the /tmp directory as a separate file system, use the exec mount option in the /etc/fstab file.

    If /tmp is already mounted with the noexec option, change the option to exec and remount the file system. This is a requirement for the puppetserver service to work.

  • If you mount the /var/lib/pulp directory as an NFS share, specify the SELinux context of the /var/lib/pulp directory in the file system table. Add the following lines to /etc/fstab:

    nfs.example.com:/nfsshare  /var/lib/pulp  nfs  context="system_u:object_r:pulpcore_var_lib_t:s0"  1 2

    If the NFS share is already mounted, remount it using the above configuration and restore the SELinux context:

    # restorecon -R /var/lib/pulp

  • Do not use symbolic links for /var/lib/pulp/.

Additional resources

1.4. Best practices for optimizing storage

Consider the following storage guidelines for increased storage efficiency.

  • 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 Foreman 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. IPv4 and IPv6 requirements

You can install Foreman in an IPv4 network or in an IPv6 network. Your system must meet the following requirements for a successful installation and operation.

The following requirements apply to installations in an IPv4 network:

  • Ensure an IPv6 loopback is configured on the base system. The loopback is typically configured by default. Do not disable it. Using the ipv6.disable=1 kernel parameter or the net.ipv6.conf.lo.disable_ipv6 = 1 sysctl option will break the installation.

The following requirements apply to installations in an IPv6 network:

  • If you rely on content from IPv4-only networks, use an external dual-stack HTTP proxy. Configure Foreman to use this dual-stack (supporting both IPv4 and IPv6) HTTP proxy as the default HTTP proxy.

  • Foreman does not support configuring an HTTP proxy using a direct IPv6 address. Instead, configure the HTTP proxy with a FQDN that resolves to the IPv6 address.

If you intend to provision hosts in an IPv6 network, the following requirements also apply:

  • Deploy an external DHCPv6 server and configure it manually to communicate with the network boot process and to manage IP address assignment because Foreman cannot integrate with a DHCPv6 server and manage its configuration. For more information about DHCPv6 server configuration, see Options in unmanaged DHCPv6 in Provisioning hosts.

  • Configure Foreman for UEFI HTTP boot provisioning. Although Foreman provisioning templates include IPv6 support for PXE and HTTP (iPXE) provisioning, the UEFI HTTP Boot provisioning is the only tested and certified provisioning workflow.

1.6. AWS Requirements

Additional resources

Installing and running Foreman server and Smart Proxy servers on Amazon Web Services (AWS) has additional requirements to your environment.

Amazon Web Service requirements

  • Use Storage requirements in Installing Foreman Server with Katello nightly plugin (containerized) on Enterprise Linux to understand and assign the correct storage to your AWS EBS volumes. See also an AWS storage optimized instance for further guidance.

  • Create EBS volumes for directories expected to contain larger amounts of data like /var/lib/pulp and ensure they are correctly mounted on start-up and before continuing the installation.

  • Optional: Store other data on a separate EBS volume.

  • If you want Foreman server and Smart Proxy server to communicate using external DNS hostnames, open the required ports for communication in the AWS Security Group that is associated with the instance.

AWS permission requirements

  • Create and access Enterprise Linux images in AWS

  • Edit network access in AWS Security

  • Create EC2 instances and EBS volumes

  • Launch EC2 instances

  • Import and export of virtual machines in AWS

  • Usage of AWS Direct Connect

Foreman requirements

Ensure that your Amazon EC2 instance meets or exceeds requirements for Foreman:

Additional resources

2. Preparing environment for Foreman server installation

Ensure that your network environment is ready for the Foreman server installation.

2.1. Opening required ports

By opening the required ports, you ensure that the components of Foreman architecture can communicate. You must also ensure that the required network ports are open on any 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. Open the ports for clients on Foreman server:

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

  2. Allow access to services on Foreman server:

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

  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.2. Verifying DNS resolution

Verify the full forward and reverse DNS resolution using a fully-qualified domain name to prevent issues while installing Foreman.

Procedure

  1. Ensure that the host name and local host resolve correctly:

    # ping -c1 localhost
# ping -c1 `hostname -f` # my_system.domain.com

    Successful name resolution results in output similar to the following:

    # ping -c1 localhost
PING localhost (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.043 ms

--- localhost ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.043/0.043/0.043/0.000 ms

# ping -c1 `hostname -f`
PING hostname.gateway (XX.XX.XX.XX) 56(84) bytes of data.
64 bytes from hostname.gateway (XX.XX.XX.XX): icmp_seq=1 ttl=64 time=0.019 ms

--- localhost.gateway ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.019/0.019/0.019/0.000 ms

  2. To avoid discrepancies with static and transient host names, set all the host names on the system by entering the following command:

    # hostnamectl set-hostname name
    Warning

    Name resolution is critical to the operation of Foreman. If Foreman cannot properly resolve its fully qualified domain name, tasks such as content management, subscription management, and provisioning will fail.

2.3. Configuring the HTTP proxy to connect to Red Hat CDN

You can configure an HTTP proxy to connect to Red Hat CDN when your network requires proxy access for subscription management and content delivery.

Prerequisites

  • Your network gateway and the HTTP proxy must allow access to the following hosts:

    Host name Port Protocol

    subscription.rhsm.redhat.com

    443

    HTTPS

    cdn.redhat.com

    443

    HTTPS

Foreman server uses SSL to communicate with the Red Hat CDN securely. An SSL interception proxy interferes with this communication. These hosts must be allowlisted on your HTTP proxy.

For a list of IP addresses used by the Red Hat CDN (cdn.redhat.com), see the Knowledgebase article Public CIDR Lists for Red Hat on the Red Hat Customer Portal.

To configure the Subscription Manager with the HTTP proxy, follow the procedure below.

Procedure

  • On Foreman server, complete the following details in the /etc/rhsm/rhsm.conf file:

    # an http proxy server to use (enter server FQDN)
proxy_hostname = http-proxy.example.com

# port for http proxy server
proxy_port = 8080

# user name for authenticating to an http proxy, if needed
proxy_user =

# password for basic http proxy auth, if needed
proxy_password =

2.4. Configuring repositories

Configure the required repositories.

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

  4. Enable the required additional repositories:

    # dnf copr enable @theforeman/foremanctl rhel-9-x86_64
Verification

  • Verify that the required repositories are enabled:

    # dnf repolist enabled

3. Installing Foreman server

Use the following procedures to install Foreman server and perform the initial configuration.

Note

You cannot register Foreman server to itself.

3.1. Deploy Foreman server configuration with the default database

You can deploy a Foreman server in a default configuration by using the foremanctl deploy command.

To extend the default deployment, you can select one or more features or add one or more configuration options.

The initial deployment also installs PostgreSQL databases on the same server.

Note

Any additional run of the foremanctl deploy command overwrites the corresponding configuration options and records them in the parameters.yaml file. This way, you can restore a broken system or add additional settings to your deployment.
Prerequisites
Procedure

  1. Update the system to the latest available version:

    # dnf upgrade

  2. Optional: Inspect the features available for deployment:

    # foremanctl features

    You can enable one or more features by adding the --add-feature Feature-1 Feature-2 option to the foremanctl deploy command.

  3. Deploy the configuration on the server:

    # foremanctl deploy \
--foreman-initial-admin-username My_Admin_User_Name \
--foreman-initial-admin-password My_Admin_Password \
--initial-organization "My_Organization" \
--initial-location "My_Location"
    Note

    Specify a meaningful value for the --initial-organization option. This can be your company name. The foremanctl tool creates an internal label that matches the value, and you cannot change it later. If you do not specify a value, an organization called Default Organization with the label Default_Organization is created. You can rename the organization name but not the label.

    The script displays its progress and writes logs to /var/log/foreman-installer/katello.log.

3.2. Deploy Foreman server configuration with an external database

By default, the Foreman deployment includes installing a PostgreSQL database on the same host as Foreman server. However, in certain Foreman deployments, using external databases instead of the default local databases can help with the server load or have other benefits.

To extend the default deployment, you can select one or more features or add one or more configuration options.

Note

Any additional run of the foremanctl deploy command overwrites the corresponding configuration options and records them in the parameters.yaml file. This way, you can restore a broken system or add additional settings to your deployment.
Prerequisites
Procedure

  1. Update the system to the latest available version:

    # dnf upgrade

  2. Optional: Inspect the features available for deployment:

    # foremanctl features

    You can enable one or more features by adding the --add-feature Feature-1 Feature-2 option to the foremanctl deploy command.

  3. Deploy the configuration on the server:

    # foremanctl deploy \
--foreman-initial-admin-username My_Admin_User_Name \
--foreman-initial-admin-password My_Admin_Password \
--initial-organization "My_Organization" \
--initial-location "My_Location" \
--database-mode external \
--database-host My_Database_Host \
--database-port My_Database_Port \
--database-ssl-mode {disable,allow,prefer,require,verify-ca,verify-full} \
--database-ssl-ca My_Database_SSL_CA \
--candlepin-database-name My_Candlepin_Database_Name \
--candlepin-database-password My_Candlepin_Database_Password \
--candlepin-database-user My_Candlepin_Database_User \
--pulp-database-name My_Pulp_Database_Name \
--pulp-database-password My_Pulp_Database_Password \
--pulp-database-user My_Pulp_Database_User \
--pulp-worker-count My_Pulp_Worker_Count \
--foreman-database-name My_Foreman_Database_Name \
--foreman-database-user My_Foreman_Database_User \
--foreman-database-password My_Foreman_Database_Password
    Note

    Specify a meaningful value for the --initial-organization option. This can be your company name. The foremanctl tool creates an internal label that matches the value, and you cannot change it later. If you do not specify a value, an organization called Default Organization with the label Default_Organization is created. You can rename the organization name but not the label.

    The script displays its progress and writes logs to /var/log/foreman-installer/katello.log.

3.3. Importing Red Hat subscription manifests into Foreman

You can import a Red Hat subscription manifest into Foreman to provide subscription allocation to your organization in Foreman.

Note

Simple Content Access (SCA) is set on the organization, not the manifest. Importing a manifest does not change your organization’s Simple Content Access status.

Simple Content Access simplifies the subscription experience for administrators.

Additional resources

3.3.1. Obtaining a Red Hat subscription manifest

You can create and export a Red Hat subscription manifest to prepare subscriptions for import into Foreman.

Procedure

3.3.2. Importing a Red Hat subscription manifest by using Foreman web UI

You can import a Red Hat subscription manifest into Foreman server by using Foreman web UI. Import the manifest so that you can enable and synchronize Red Hat repositories in your organization.

Prerequisites
Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. Navigate to Content > Subscriptions.

  3. Click Manage Manifest.

  4. In the Manage Manifest window, click Choose File.

  5. Navigate to the location that contains the Red Hat subscription manifest file, then click Open.

3.3.3. Importing a Red Hat subscription manifest by using Hammer CLI

You can import a Red Hat subscription manifest into Foreman server by using Hammer CLI. Import the manifest so that you can enable and synchronize Red Hat repositories in your organization.

Prerequisites
Procedure

  1. Copy the Red Hat subscription manifest file from your local machine to Foreman server:

    $ scp ~/manifest_file.zip root@foreman.example.com:~/.

  2. Log in to Foreman server over SSH as the root user.

  3. Import the Red Hat subscription manifest file:

    $ hammer subscription upload \
--file ~/manifest_file.zip \
--organization "My_Organization"

4. Customize the installation

4.1. Configuring an alternate CNAME for Foreman

You can configure an alternate CNAME for Foreman. This might be useful if you want to deploy the Foreman web interface on a different domain name than the one that is used by client systems to connect to Foreman. You must plan the alternate CNAME configuration in advance prior to installing Smart Proxies and registering hosts to Foreman to avoid redeploying new certificates to hosts.

4.1.1. Configuring Foreman with an alternate CNAME

You can configure an alternate CNAME for Foreman with the default Foreman certificate. Note that the procedures for users of a default Foreman certificate and custom certificate differ.

Procedure

  1. Add an alternate CNAME to a new installation or an existing deployment of Foreman with a default Foreman certificate:

    # foremanctl --certificate-cname My-Alternate-FQDN.example.com

  2. If you use Foreman with a custom certificate, when creating a custom certificate, include the alternate CNAME records to the custom certificate. For more information, see Creating a Custom SSL Certificate for Foreman server.

4.1.2. Configuring hosts to use an alternate Foreman CNAME for content management

If Foreman is configured with an alternate CNAME, you can configure hosts to use the alternate Foreman CNAME for content management. To do this, you must point hosts to the alternate Foreman CNAME prior to registering the hosts to Foreman. You can do this using the bootstrap script or manually.

Perform these steps on the hosts you want to configure.

Procedure

  • If you want to configure the host with the bootstrap script, run the bootstrap script with the --server My-Alternate-FQDN.example.com option to register the host to the alternate Foreman CNAME:

    # ./bootstrap.py --server My-Alternate-FQDN.example.com

  • If you want to configure the host manually, edit the /etc/rhsm/rhsm.conf file to update hostname and baseurl settings to point to the alternate host name, for example:

    [server]
# Server hostname:
hostname = My-Alternate-FQDN.example.com

content omitted

[rhsm]
# Content base URL:
baseurl=https://My-Alternate-FQDN.example.com/pulp/content/
Next steps

  • Now you can register the host with the subscription-manager.

Appendix A: Restoring manual changes overwritten by a Puppet run

If your manual configuration has been overwritten by a Puppet run, you can restore the files to the previous state.

For example, when you install and configure Foreman for the first time by using foreman-installer, you can use the --foreman-proxy-dns-managed false and --foreman-proxy-dhcp-managed false options to specify that the DNS and DHCP configuration files are not to be managed by Puppet. If you do not use these options during the initial foreman-installer run, rerunning foreman-installer overwrites all manual changes. The following example shows you how to restore a DHCP configuration file overwritten by a Puppet run.

Procedure

  1. Copy the file you intend to restore. This allows you to compare the files to check for any mandatory changes required by the upgrade. This is not common for DNS or DHCP services.

    # cp /etc/dhcp/dhcpd.conf /etc/dhcp/dhcpd.backup

  2. Check the log files to note down the md5sum of the overwritten file. For example:

    # journalctl -xe
...
/Stage[main]/Dhcp/File[/etc/dhcp/dhcpd.conf]: Filebucketed /etc/dhcp/dhcpd.conf to puppet with sum 622d9820b8e764ab124367c68f5fa3a1
...

  3. Restore the overwritten file:

    # puppet filebucket restore --local --bucket \
/var/lib/puppet/clientbucket /etc/dhcp/dhcpd.conf \ 622d9820b8e764ab124367c68f5fa3a1

  4. Compare the backup file and the restored file, and edit the restored file to include any mandatory changes required by the upgrade.

Pre-release version Report issue