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. Preparing Foreman for using external databases

By default, the Foreman installation process 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.

Prerequisites
Procedure

  • Install PostgreSQL on an external database host you prepared. For more information, see Installing PostgreSQL in Administering Foreman.

Additional resources

3. Installing Foreman server

4. Customize the installation

Pre-release version Report issue