Operating System CentOS

How to Install Foreman 5.0 on AlmaLinux 9 or CentOS Stream 9

Install Foreman 5.0 with the official installer on AlmaLinux 9 or CentOS Stream 9, open the right ports, log in and manage a first Puppet class.

Foreman is an open source lifecycle management tool for physical and virtual servers: it provisions hosts, applies configuration through Puppet, Ansible or Salt, and collects reports in one web interface. This guide installs Foreman 5.0 on AlmaLinux 9 with the official foreman-installer, which sets up the web application, PostgreSQL, Apache, a Smart Proxy and a Puppet server on one machine. The same steps apply to CentOS Stream 9 and RHEL 9; the Foreman project tests its packages on AlmaLinux and CentOS Stream and notes that other RHEL derivatives may need extra work.

CentOS 7 reached end of life in June 2024 and current Foreman releases do not support it. For the RHEL family the Foreman project supports Enterprise Linux 9 on x86_64 with the installer; it also publishes packages for Debian 12 and 13 and Ubuntu 22.04 and 24.04.

Requirements

  • A freshly installed AlmaLinux 9 server (x86_64). Run the installer on a clean system: it takes over Apache, PostgreSQL and Puppet configuration.
  • At least 4 GB of memory and 2 GB of free disk space for the default installation that includes the Puppet server.
  • A fully qualified hostname that resolves to the server's real IP address; the examples use foreman.example.com and 203.0.113.10.
  • A user with sudo rights.

Step 1: Update the system and set the hostname

Apply all pending updates. The Foreman manual specifically asks for current SELinux policy packages on Enterprise Linux:

sudo dnf -y upgrade

Set the fully qualified hostname:

sudo hostnamectl set-hostname foreman.example.com

The installer builds TLS certificates and service URLs from this name, so it must resolve to the server's routable address, not to a loopback address. If you have no DNS record for it yet, add a line to /etc/hosts:

echo "203.0.113.10 foreman.example.com foreman" | sudo tee -a /etc/hosts

Check the result. The reply must come from the real IP address; if it shows 127.0.0.1 or 127.0.1.1, remove the entry that maps the hostname to that address from /etc/hosts:

hostname -f
ping -c 1 $(hostname -f)

Step 2: Open the firewall

Which ports you need depends on the features you use. The web interface, the Puppet server and the Smart Proxy are enough for a basic installation:

sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --permanent --add-port=8140/tcp
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

The full list from the Foreman manual:

PortProtocolUsed for
80, 443TCPWeb interface and provisioning templates (Apache)
8140TCPPuppet server, for agents on managed hosts
8443TCPSmart Proxy; needs to be reachable only by Foreman itself
53TCP and UDPDNS server, if the Smart Proxy manages DNS
67, 68UDPDHCP server, if the Smart Proxy manages DHCP
69UDPTFTP server for network boot
5910–5930TCPVNC consoles of virtual machines
5432TCPPostgreSQL, only when the database runs on a separate host

Open the DNS, DHCP and TFTP ports only if you enable those Smart Proxy features for provisioning. PostgreSQL stays on the local machine in the default setup and needs no firewall rule.

Step 3: Add the repositories

The installer is a set of Puppet modules, and Foreman 5.0 runs them with OpenVox, the community-maintained Puppet implementation published by Vox Pupuli; version 8 or later is required. Add the OpenVox 8 repository:

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

Add the Foreman 5.0 repository:

sudo dnf -y install https://yum.theforeman.org/releases/5.0/el9/x86_64/foreman-release.rpm

Step 4: Install and run the Foreman installer

Install the installer package:

sudo dnf -y install foreman-installer

Run it. By default it is non-interactive and installs Foreman, the Smart Proxy and a Puppet server with sensible defaults:

sudo foreman-installer

The run takes several minutes. Useful variations:

  • sudo foreman-installer -i starts an interactive, menu-driven mode where you can review and change settings before anything is applied.
  • sudo foreman-installer -v replaces the progress bar with a list of every change.
  • sudo foreman-installer --foreman-initial-admin-password 'your-password' sets the admin password instead of generating a random one.
  • sudo foreman-installer --help lists the common options and --full-help lists all of them.

Arguments you pass are saved in /etc/foreman-installer/scenarios.d/foreman-answers.yaml and reused on later runs, so you can re-run the installer at any time to change one setting without repeating the others.

When the installer finishes it prints where Foreman is running and the login details, in this form:

  * Foreman is running at https://foreman.example.com
      Initial credentials are admin / (generated password)
  * Foreman Proxy is running at https://foreman.example.com:8443
  The full log is at /var/log/foreman-installer/foreman-installer.log

Write the password down: it is shown only in this output.

Step 5: Log in

Open https://foreman.example.com in a browser and log in as admin with the password from the installer output. The installer creates the HTTPS certificate from its own Puppet certificate authority, so the browser warns about an untrusted issuer until you import that CA or configure Foreman with a certificate from a public authority. Change the admin password under the user menu after the first login.

Step 6: Register the Foreman host and add a Puppet module

The installer leaves a Puppet server on the machine that is already integrated with Foreman. Run the agent once on the Foreman host; it sends its first report and the host appears in Foreman automatically:

sudo puppet agent --test

A warning that the node cannot be found is expected on the first run. If sudo reports that the puppet command does not exist, call it by its full path, /opt/puppetlabs/bin/puppet. In the web interface, open Hosts: the server is listed with an OK status.

To manage something with Puppet, install a module from the Puppet Forge into the default production environment. This example uses the NTP module:

sudo puppet module install puppetlabs/ntp

Then make the class known to Foreman and assign it:

  1. Go to Configure > Classes and click Import from your Foreman host (top right). The ntp class appears in the list.
  2. Click the ntp class, open the Smart Class Parameters tab, select servers, tick Override and set the time servers you want. Submit.
  3. Go to Hosts, click Edit on the Foreman host, open the Puppet Classes tab and add the ntp class with the plus icon. Save.
  4. Run sudo puppet agent --test again; Puppet configures the NTP service with the parameters Foreman supplied.

Other servers with a Puppet agent can use this Puppet server in the same way; they show up under Hosts after their first run, once their certificate has been signed.

Upgrading later

Foreman upgrades go one release at a time; skipping versions is not supported. The outline for Enterprise Linux is: stop the services, switch the repository package to the next release, upgrade the packages, migrate the database, clear caches and start the services again:

sudo systemctl stop httpd foreman.service foreman.socket dynflow\*
sudo dnf -y upgrade https://yum.theforeman.org/releases/X.Y/el9/x86_64/foreman-release.rpm
sudo dnf clean metadata
sudo dnf -y upgrade ruby\* foreman\*
sudo foreman-rake db:migrate
sudo foreman-rake db:seed
sudo foreman-rake tmp:cache:clear
sudo foreman-rake db:sessions:clear
sudo systemctl start httpd foreman.service foreman.socket

Afterwards you can preview what the installer would change with sudo foreman-installer --noop --verbose and then run it normally to bring the configuration up to date. Replace X.Y with the release you are moving to, back up first, and read the upgrade section of the Foreman manual for that release, because each one lists its own warnings.

Frequently asked questions

Can I install Foreman without the Puppet server?

Yes. Run the installer with --puppet-server=false --foreman-proxy-puppet=false --foreman-proxy-puppetca=false. Without the Puppet server the minimum drops to about 2 GB of memory and 1 GB of disk space, which suits a setup that uses Foreman only for provisioning or with Ansible.

What is OpenVox and why not Puppet's own repository?

OpenVox is the community-maintained continuation of open source Puppet, released by the Vox Pupuli project. The Foreman 5.0 installation instructions use its packages; the commands (puppet agent, puppet module) and file locations stay the same.

Does Foreman run on Enterprise Linux 10?

Foreman 5.0 introduced support for EL10 only for containerized deployments. Installing with foreman-installer on EL10 is not supported, so use an EL9 system for the package-based installation described here.

What is Katello and do I need it?

Katello is a Foreman plugin for content management: repository mirroring, content views and subscription handling. It has its own installation scenario and much higher resource requirements, and it is available on Enterprise Linux only, not on Debian or Ubuntu. For provisioning and configuration management alone, plain Foreman is enough.

Share story:

Continue reading other guides on How VPS.