Documentation & Tutorials

How to Install and Configure Foreman on Ubuntu Xenial

Foreman Overview

Foreman is an open source project that helps system administrators manage servers throughout their lifecycle, from provisioning and configuration to orchestration and monitoring. In short, it is a complete lifecycle management tool for physical and virtual servers. Foreman becomes even more powerful when integrated with other open source projects such as Puppet, Chef, Salt, Ansible.

Foreman helps us with the automatization of the OS installation. After that – through a very good integration with puppet – the new system will be configured to our specification. Finally Puppet will send facts about the system to Foreman which helps us to monitor the whole system over its complete life span. With a discovery plugin Foreman can also discover new machines in your network based on their mac address.

This tutorial assumes you will install Foreman on a fresh server, which will also act as the Puppet master server. Because Foreman depends on Puppet to perform the configuration management of hosts, it requires everything that is needed for a Puppet agent/master setup.


  • You have an account and are logged into
  • You have an Ubuntu Xenial server
  • You have configured your SSH Key
  • You have root access to all of the servers you want to manage
  • The Puppet master must be reachable on port 8140
  • It is recommended to run Foreman on a machine with at least 8GB of RAM for optimal performances.

Creating your Foreman Server

The Foreman installer is a collection of Puppet modules that installs everything required for a full working Foreman setup.

The Foreman installer uses Puppet (> 3.x required) to install Foreman.

1 . Connect to your server using SSH:

ssh root@SERVER_IP

If you do not know your server IP, you can list your exiting servers using scw ps (Scaleway CLI). For more information on the Scaleway CLI, refer to the tutorial on the Scaleway Command Line Interface.

The server IP can also be retrieved from the Scaleway Console. Once logged in, check the IP Adresses in the Servers tab of the left menu.

2 . Check your server’s full hostname to ensure the hostname is set to FQDN


You should see the long version of your server’s name, e.g. You can skip the remaining steps and jump directly to the next section.

3 . (Optional) If a short name is returned e.g. foreman, you need to set your hostname to the long name. To do so, edit your hosts file:

sudo nano /etc/hosts

4 . (Optional) Add the FQDN before the first entry for your short hostname. foreman

5 . Save and exit

6 . Edit your hostname file:

sudo nano /etc/hostname

7 . Change the entry in the file to your server’s FQDN, e.g. Then save and exit.

8 . Run the following command to immediately read in the configuration change you just made:

sudo hostname --file /etc/hostname

Installing Foreman on Ubuntu Xenial

The easiest way to install Foreman is to use the Foreman Installer. The Foreman Installer installs and configures all of the necessary components to run Foreman, including the following:

  • Foreman
  • Puppet master and agent
  • Apache Web Server with SSL and Passenger module

1 . Download the Foreman Installer. Using Puppet 5.x is recommended, which is available from the Puppet Labs repository.

apt-get -y install ca-certificates
-O /tmp && wget
dpkg -i /tmp/puppet5-release-xenial.deb

2 . Enable the Foreman repository

echo "deb xenial 1.18" | sudo tee /etc/apt/sources.list.d/foreman.list
echo "deb plugins 1.18" | sudo tee -a /etc/apt/sources.list.d/foreman.list
sudo apt-get -y install ca-certificates
wget -q -O- | sudo apt-key add -

3 . Download the installer

sudo apt-get update && sudo apt-get -y install foreman-installer

4 . Run the Foreman Installer


which returns

Installing             Done                                               [100%] [..]
  * Foreman is running at
      Initial credentials are admin / 6fHtmSWpqNbGo7nn
  * Foreman Proxy is running at
  * Puppetmaster is running at port 8140
  The full log is at /var/log/foreman-installer/foreman.log

Managing Puppet

After installation, the Foreman installer will have set up a puppet master on the host, fully integrated with Foreman. First run the Puppet agent on the Foreman host which will send the first Puppet report to Foreman, automatically creating the host in Foreman’s database.

1 . Install puppet-agent Command

apt-get install puppet-agent

2 . Add the Foreman host to Foreman’s database by running the puppet agent command

sudo puppet agent --test

This adds the Foreman host as the first Puppet agent node that is managed by Foreman.

The Foreman Web Interface

The Foreman web interface can be accessed by the public network interface of your VPS (either its public FQDN or public IP address). By default, Foreman uses your Puppet certificates, which are probably not trusted by your browser. Accept the warning about the certificate and proceed.

You can login to Foreman using the credentials that were returned once it was installed.

  • Username: admin
  • Password: random


Foreman Dashboard

When you first log in, you see the Foreman dashboard, which displays an overview of your Puppet environment.

Here you will see a summary of “Host Configuration Status”, which shows the number of Puppet agent nodes and their respective statuses. When you first start Foreman, you should see a single server in the “good host” section.


Changing your Admin Password

Before doing anything else, you will want to change your admin user password.

1 . Go to Admin User and select My Account

2 . In the User section, fill in the current password and add your new password in the password and verify tabs.

3 . Click Submit

Adding NTP Module To Foreman

Puppet requires accurate time-keeping, we will use Foreman to manage the NTP service on the Foreman host (which is also the Puppet master). To learn more about NTP, refer to puppetforge

1 . Install NTP and Stdlib in the production environment of our Puppet master

puppet module install -i /etc/puppet/environments/production/modules puppetlabs/ntp

which returns

Notice: Created target directory /etc/puppet/environments/production/modules
Notice: Downloading from ...
Notice: Installing -- do not interrupt ...
└─┬ puppetlabs-ntp (v7.2.0)
  └── puppetlabs-stdlib (v4.25.1)

The module has been installed in the Puppet master, but it must be added to Foreman before we can use it.

2 . In the Foreman web UI, click Configure> Puppet> Classes: configure_classes

3 . Click on the Import environments from button.


It will import the environment to display the Changed environments panel.

4 . Tick the ntp checkbox next to the item and click Update. The ntp module is now imported into Foreman, and ready to be used with a host.


Overriding Default NTP Pool

We need to override the NTP module’s default settings, and configure the NTP module to use the US NTP pool by default.

1 . In the Puppet Classes screen, click the ntp class to enter edit mode.

2 . Click the Smart Class Parameter tab.

3 . Scroll down to find the servers item in the left sidebar, and select it


4 . Tick the Override checkbox. Change the Parameter type drop down to array. Then change the Default value from the default NTP pool to one of your choosing, in array form. We will use the US NTP pool:


5 . Click Submit. Now any hosts or hosts groups that use this module will use the US NTP pool by default.

Configuring Foreman Host to Use NTP Module

Now we are ready to use the NTP module to manage NTP on the Foreman host.

1 . Click Hosts on the side menu and select All hosts

2 . Click Edit on the far right of your Foreman host.


3 . Click on the Puppet Classes tab . Under Available Classes, click on the ntp class to expand it, then click the plus sign next to “ntp”:


This moves the ntp class to the Included Classes section. This means that the next time the Foreman host’s Puppet agent checks in, it will have this Puppet module applied to it.


4 . Click Submit.

Viewing Puppet Configuration

After editing the Foreman host’s configuration, you will be directed to the Foreman host’s summary page.


To see the information given to Puppet when an agent node checks in, click on the YAML button.

Running the Puppet Agent

On the Foreman server, run the Puppet agent to apply all the changes that we made above

sudo puppet agent --test

which returns

root@foreman:~# puppet agent --test
Info: Using configured environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Retrieving locales
Notice: /File[/opt/puppetlabs/puppet/cache/locales/ja/puppetlabs-ntp.po]/ensure: defined content as '{md5}7265ff57e178feb7a65835f7cf271e2c'
Info: Loading facts
Info: Caching catalog for
Info: Applying configuration version '1533720851'
Notice: Applied catalog in 0.42 seconds

In the web UI, go back to your Foreman host, then click on the Reports button.

You should see a new report entry that indicates some changes were applied and a service was restarted; click on the report. Here you will see several notices that indicate that the NTP package was installed, configured, and restarted.

Discover a New Cloud Experience

Deploy SSD Cloud Servers in seconds.