---
title: Installing and configuring Foreman on Ubuntu Jammy Jellyfish (22.04 LTS)
description: Discover how to install and configure Foreman on Ubuntu Jammy Jellyfish (22.04 LTS)
tags: Foreman puppet Ubuntu Jammy Jellyfish
products:
  - instances
dates:
  validation: 2025-04-22
  posted: 2018-08-06
  validation_frequency: 12
difficulty: beginner
usecase:
  - resource-management
ecosystem:
  - third-party
---
import image from './assets/scaleway-foreman_login.webp'
import image2 from './assets/scaleway-dashboard.webp'
import image3 from './assets/scaleway-configure_classes.webp'
import image4 from './assets/scaleway-import.webp'
import image5 from './assets/scaleway-ntp_prod.webp'
import image6 from './assets/scaleway-ntp_servers.webp'
import image7 from './assets/scaleway-hosts.webp'
import image8 from './assets/scaleway-ntp_add.webp'
import image9 from './assets/scaleway-ntp_included.webp'
import image10 from './assets/scaleway-hosts_dashboard.webp'

import Requirements from '@macros/iam/requirements.mdx'


Foreman is a tool 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, available as open source software, becomes even more powerful when integrated with other open source projects such as [Puppet](https://puppet.com/ecosystem/devx/), [Chef](/tutorials/configure-chef-ubuntu-xenial/), [Salt](https://docs.saltproject.io/en/latest/), and [Ansible](/tutorials/ansible-bionic-beaver/).

Foreman helps to automatize the OS installation. After that, through its integration with Puppet, the new system will be configured to the desired state. Finally, Puppet will send facts about the system to Foreman which helps to monitor the whole system over its complete lifecycle. With a discovery plugin, Foreman can also discover new machines in the network based on their MAC address.

This tutorial assumes that Foreman is being installed on a fresh Instance, which will also act as the Puppet primary server.

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/glossary/#owner) status or [IAM permissions](/iam/concepts/glossary/#permission) allowing you to perform actions in the intended Organization
- An [SSH key](/iam/security/create-ssh-key/)
- An [Instance](/instances/how-to/create-an-instance/) running on Ubuntu Jammy Jellyfish (22.04 LTS) or later
- Root access to all the servers you want to manage
- A reachable port 8140 on the Puppet primary Instance
- A working Puppet installation to perform the configuration management of hosts

  <Message type="note">
    We recommend running Foreman on a machine with at least 8 GB of RAM for optimal performance.
  </Message>

## Creating your Foreman server

The installation tool is a collection of Puppet modules that install everything required for a full working Foreman setup.

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

1. Connect to the Instance using SSH:
    ```
    ssh root@SERVER_IP
    ```

  To retrieve the Instance's IP, list your existing servers using `scw ps` (Scaleway CLI). For more information on the Scaleway CLI, refer to the tutorial on the [Scaleway Command Line Interface](https://github.com/scaleway/scaleway-cli/).

  The Instance's IP can also be retrieved from the Scaleway console. Once logged in, check the **IP addresses** in the **CPU & GPU Instances** tab of the left menu.
2. Check your Instance's full hostname to ensure the hostname is set to a valid [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name).
    ```
    hostname
    ```

  You should see the complete hostname of your Instance (e.g. `foreman.example.com`). If this is the case, skip the remaining steps and jump directly to the next section.
3. (Optional) In case a short name is returned (e.g. `foreman`), configure the complete hostname. To do so, edit the `hosts` file in a text editor:
    ```
    sudo nano /etc/hosts
    ```
4. (Optional) Add the FQDN before the short hostname.
    ```
    foreman.example.com foreman
    ```
5. Save and exit nano.
6. Edit the hostname file:
    ```
    sudo nano /etc/hostname
    ```
7. Change the entry in the file to the Instances FQDN, e.g. `foreman.example.com`. Then save and exit the editor.
8. Run the following command to reconfigure the Instance's hostname according to the changes made in the previous steps:
    ```
    sudo hostname --file /etc/hostname
    ```

## Installing Foreman on Ubuntu Focal

The fastest way to install Foreman is by using the installer, which installs and configures automatically all the required components to run Foreman, these include:

- Foreman
- Puppet primary/agent
- The Apache Web Server with SSL and Passenger modules

1. Install Puppet 6.x from the Puppetlabs repository as follows:
    ```
    apt-get -y install ca-certificates
    wget https://apt.puppetlabs.com/puppet8-release-focal.deb
    sudo dpkg -i puppet8-release-focal.deb
    apt-get update
    apt-get -y install puppet-agent
    ```
2. Add the Foreman repository to the [APT package manager sources list](https://en.wikipedia.org/wiki/APT_(Debian)):
    ```
    echo "deb http://deb.theforeman.org/ focal 3.12" | sudo tee /etc/apt/sources.list.d/foreman.list
    echo "deb http://deb.theforeman.org/ plugins 3.12" | sudo tee -a /etc/apt/sources.list.d/foreman.list
    wget -q https://deb.theforeman.org/pubkey.gpg -O- | sudo apt-key add -
    ```
3. Download the installer via APT:
    ```
    sudo apt-get update && sudo apt-get -y install foreman-installer
    ```
4. Run the Foreman Installer by typing the following command:
    ```
    foreman-installer
    ```

    Upon completion, you will see:
    ```
    Success!
    * Foreman is running at https://<your_foreman_url>
      Initial credentials: admin / <random_password>
    * Puppet server is running at port 8140
    ```

## Managing Puppet

During installation, the installation wizard sets up a puppet primary on the host, which is fully integrated with Foreman. Run the Puppet agent on the Instance to send the first Puppet report to Foreman, This creates the host automatically in Foreman's database.

1. Install `puppet-agent` with the following command:
    ```
    apt-get install puppet-agent
    ```
2. Add the host to Foreman's database by running the puppet agent command:
    ```
    sudo puppet agent --test
    ```

    This adds the local Foreman host as the first Puppet agent node, managed by Foreman.

## The Foreman web interface

The web interface of Foreman can be accessed on the public IP address of your Instance.
By default, Foreman uses Puppets self-signed certificates, which are probably not trusted by your browser. Accept the notification about the certificate and proceed.

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

- Username: admin
- Password: random

<Lightbox image={image} alt="" />

## Foreman dashboard

After login, the Foreman dashboard displays an overview of your Puppet environment.

A summary of "Host Configuration Status" displays the amount of Puppet agent nodes and their statuses. Upon first connection, one single Instance should be visible in the "good host" section.

<Lightbox image={image2} alt="" />

## Changing the admin password

Before doing anything else, change the admin user password for security reasons.

1. Go to **Admin User** and select **My Account**.
2. In the **User** section, fill in the **current password** and set a new password in the **password** and **verify** tabs.
3. Click **Submit**.

## Adding NTP module to Foreman

Puppet requires accurate time-keeping, therefore the [NTP service](https://en.wikipedia.org/wiki/Network_Time_Protocol) runs on the Foreman host (which acts also as Puppet primary).

1. Install NTP and [Stdlib](https://forge.puppet.com/puppetlabs/stdlib) on the Puppet primary:
    ```
    puppet module install -i /etc/puppet/environments/production/modules puppetlabs/ntp
    ```

    The command returns

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

    The module requires to be added to Foreman before being usable.
2. When connected to the Foreman web UI, click **Configure**> **Puppet**> **Classes**:
    <Lightbox image={image3} alt="" />
3. Click the `Import environments from foreman.example.com` button.
    <Lightbox image={image4} alt="" />

    This imports the environment and displays the **Changed environments** panel.
4. Tick the NTP checkbox next to the item and click **Update** to import the NTP module.
    <Lightbox image={image5} alt="" />

## Overriding default NTP pool

Update the settings and configure the NTP module to use the [French NTP pool](https://www.pool.ntp.org/zone/fr) by default.

1. In the **Puppet Classes** screen, click **ntp** class to edit it.
2. Click the **Smart Class Parameter** tab.
3. Scroll down to find the **servers** item in the left sidebar, and select it.
    <Lightbox image={image6} alt="" />
4. Tick the **Override** checkbox. In the **Parameter type** menu, choose **array** and change the **Default value** from the default NTP pool to the desired one:
    ```
    ["0.fr.pool.ntp.org","1.fr.pool.ntp.org","2.fr.pool.ntp.org","3.fr.pool.ntp.org"]
    ```
5. Click **Submit** to update the configuration and to use the French NTP pool as default.

## Configuring Foreman host to use NTP module

Configure 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.
    <Lightbox image={image7} alt="" />
3. Click the **Puppet Classes** tab. Within the Available Classes section, click the ntp class, then click the plus sign next to "ntp":
    <Lightbox image={image8} alt="" />

    The NTP class is being moved to the Included Classes section. The next time the Puppet agent checks in, it will have this module applied to it.

    <Lightbox image={image9} alt="" />
4. Click **Submit** to activate the configuration.

## Viewing Puppet configuration

After editing Foreman host's configuration, a redirection to Foreman host's summary page applies.

  <Lightbox image={image10} alt="" />

Click the **YAML** button, to see the information provided to Puppet when an agent node checks in.

## Running the Puppet agent

Run the Puppet agent on the Foreman Instance to apply all the changes that were made above.

```
sudo puppet agent --test
```

The command returns the following output:

```
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 foreman.example.com
Info: Applying configuration version '1533720851'
Notice: Applied catalog in 0.42 seconds
```

In the web UI, go back to the Foreman host and click the **Reports** button.

A new report entry indicates that some changes were applied, and a service was restarted.
Click the report. Several notices indicate that the NTP service was installed, configured, and restarted.