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.comand203.0.113.10. - A user with
sudorights.
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 upgradeSet the fully qualified hostname:
sudo hostnamectl set-hostname foreman.example.comThe 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/hostsCheck 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 --reloadThe full list from the Foreman manual:
| Port | Protocol | Used for |
|---|---|---|
| 80, 443 | TCP | Web interface and provisioning templates (Apache) |
| 8140 | TCP | Puppet server, for agents on managed hosts |
| 8443 | TCP | Smart Proxy; needs to be reachable only by Foreman itself |
| 53 | TCP and UDP | DNS server, if the Smart Proxy manages DNS |
| 67, 68 | UDP | DHCP server, if the Smart Proxy manages DHCP |
| 69 | UDP | TFTP server for network boot |
| 5910–5930 | TCP | VNC consoles of virtual machines |
| 5432 | TCP | PostgreSQL, 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.rpmAdd the Foreman 5.0 repository:
sudo dnf -y install https://yum.theforeman.org/releases/5.0/el9/x86_64/foreman-release.rpmStep 4: Install and run the Foreman installer
Install the installer package:
sudo dnf -y install foreman-installerRun it. By default it is non-interactive and installs Foreman, the Smart Proxy and a Puppet server with sensible defaults:
sudo foreman-installerThe run takes several minutes. Useful variations:
sudo foreman-installer -istarts an interactive, menu-driven mode where you can review and change settings before anything is applied.sudo foreman-installer -vreplaces 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 --helplists the common options and--full-helplists 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.logWrite 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 --testA 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/ntpThen make the class known to Foreman and assign it:
- Go to Configure > Classes and click Import from your Foreman host (top right). The
ntpclass appears in the list. - Click the
ntpclass, open the Smart Class Parameters tab, selectservers, tick Override and set the time servers you want. Submit. - Go to Hosts, click Edit on the Foreman host, open the Puppet Classes tab and add the
ntpclass with the plus icon. Save. - Run
sudo puppet agent --testagain; 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.socketAfterwards 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.