↓Skip to main content

Foreman: Setup a Foreman Server, Export Root CA Certificate & Add Hosts with Puppet Agent

1365 words·
Foreman Puppet
Table of Contents
Puppet - This article is part of a series.
Part 1: Puppet Open Source: Install Puppet Server, Add Hosts / Deploy Puppet Agent, Puppet Modules Examples, Deploy Apache Webserver, Deploy LAMP Stack
Part 2: This Article

Overview
#

In this tutorial I’m using the following VMs based on Ubuntu 22.04:

192.168.30.90 foreman.jklug.local # Foreman / Puppet Server
192.168.30.91 host1.jklug.local # Example host with Puppet Agent

Foreman Server Installation
#

Define Hostname
# 

# Set a custom hostname for the Forman server
sudo hostnamectl set-hostname foreman.jklug.local

# Verify the hostname
hostname

# Shell output:
foreman.jklug.local

DNS / Hosts Entry
# 

# Open the hosts file
sudo vi /etc/hosts

# Add the following hosts entry:
127.0.0.1 localhost
127.0.1.1 foreman-server

192.168.30.90 foreman.jklug.local foreman

Verify the hostname resolves to the real IP of the VM:

# ping hostname
ping $(hostname -f)

# Shell output:
PING foreman.jklug.local (192.168.30.90) 56(84) bytes of data.
64 bytes from foreman.jklug.local (192.168.30.90): icmp_seq=1 ttl=64 time=0.013 ms
64 bytes from foreman.jklug.local (192.168.30.90): icmp_seq=2 ttl=64 time=0.027 ms

Add Repositories & Install Foreman Installer
# 

# Add Puppet repository
sudo apt-get -y install ca-certificates
cd /tmp && wget https://apt.puppet.com/puppet8-release-jammy.deb
sudo apt-get install /tmp/puppet8-release-jammy.deb
sudo apt update

# Add Foreman repository
sudo wget https://deb.theforeman.org/foreman.asc -O /etc/apt/trusted.gpg.d/foreman.asc
echo "deb http://deb.theforeman.org/ jammy 3.11" | sudo tee /etc/apt/sources.list.d/foreman.list
echo "deb http://deb.theforeman.org/ plugins 3.11" | sudo tee -a /etc/apt/sources.list.d/foreman.list

# Download & install the Foreman installer
sudo apt update && sudo apt -y install foreman-installer

Install Foreman
#

Note: Foreman requires PostgreSQL for it’s backend database, if it’s not installed on the host, the Forman installer automatically installs it.

# List Foreman installation help / commands
sudo foreman-installer --help

# Install Foreman: Non-interactive mode
sudo foreman-installer

# Shell output:
Executing: foreman-rake upgrade:run
  Success!
  * Foreman is running at https://foreman.jklug.local
      Initial credentials are admin / 9kqQx8rKNZL35PA3
  * Foreman Proxy is running at https://foreman.jklug.local:8443

The full log is at /var/log/foreman-installer/foreman.log

Verify Foreman & Postgres Status
# 

# Verify the Foreman status
sudo systemctl status foreman

# Verify the Postgres status
sudo systemctl status postgresql

Export Puppet Path Variable
# 

# Switch to root user
sudo su
  • Add the Puppet path variable for the root user
# Add the Puppet binaries to your PATH environment variable (User specific)
echo 'export PATH=/opt/puppetlabs/bin:$PATH' >> ~/.bashrc

# Apply changes / reload the .bashrc file
source ~/.bashrc

Verify Root CA Certificate
#

List Certificate
# 

# List certificates
ls -la /etc/puppetlabs/puppet/ssl/certs

# Shell output:
-rw-r--r-- 1 puppet puppet 3862 Sep 12 12:42 ca.pem
-rw-r--r-- 1 puppet puppet 2045 Sep 12 12:42 foreman.jklug.local.pem

List Certificate Details
#

  • Make sure to check the root certificate, to see if there are any errors with the DNS configuration
# Check the root certificate
puppetserver ca list --all

# Shell output:
Signed Certificates:
    foreman.jklug.local       (SHA256)  EC:A0:8F:28:57:02:13:A7:B2:14:C1:4C:06:14:C8:C4:62:BD:CC:F7:CE:74:BB:67:6C:7F:4E:CC:B1:77:DA:CD alt names: ["DNS:puppet", "DNS:foreman.jklug.local"]    authorization extensions: [pp_cli_auth: true]

Import Root CA Certificate
#

Copy Root CA Certificate
# 

# Copy the Root CA certificate to the client
sudo cp /etc/puppetlabs/puppet/ssl/certs/ca.pem ...

Import Certificate into Windows Trusted Root Store
#

Open the MMC Certificate Manager for local computer:

  • Run certlm.msc

  • Select “Trusted Root Certification Authorities” > “Certificates”

  • Right click “All Tasks” > “Import”

  • Import the “ca.pem” certificate


DNS Entry
# 

# Create a DNS entry for the Forman server
192.168.30.90 foreman.jklug.local

Access Foreman Webinterface
# 

# Access the Foreman webinterface
https://foreman.jklug.local

# Default user:
admin

# Password: (From installation shell output)
9kqQx8rKNZL35PA3

Puppet Server
#

Enable Diffs
# 

# Open the Puppet configuration
sudo vi /etc/puppetlabs/puppet/puppet.conf

# file managed by puppet
[main]
    basemodulepath = /etc/puppetlabs/code/environments/common:/etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules:/usr/share/puppet/modules
    certname = foreman.jklug.work
    codedir = /etc/puppetlabs/code
    environmentpath = /etc/puppetlabs/code/environments
    hiera_config = $confdir/hiera.yaml
    hostprivkey = $privatekeydir/$certname.pem { mode = 640 }
    logdir = /var/log/puppetlabs/puppet
    pluginfactsource = puppet:///pluginfacts
    pluginsource = puppet:///plugins
    privatekeydir = $ssldir/private_keys { group = service }
    reports = foreman
    rundir = /var/run/puppetlabs
    server = foreman.jklug.work
    show_diff = true # Set to true
    ssldir = /etc/puppetlabs/puppet/ssl
    vardir = /opt/puppetlabs/puppet/cache

[agent]
    classfile = $statedir/classes.txt
    default_schedules = false
    environment = production
    localconfig = $vardir/localconfig
    masterport = 8140
    noop = false
    report = true
    runinterval = 1800
    splay = false
    splaylimit = 1800
    usecacheonfailure = true

[server]
    autosign = /etc/puppetlabs/puppet/autosign.conf { mode = 0664 }
    ca = true
    certname = foreman.jklug.work
    external_nodes = /etc/puppetlabs/puppet/node.rb
    logdir = /var/log/puppetlabs/puppetserver
    node_terminus = exec
    parser = current
    rundir = /var/run/puppetlabs/puppetserver
    ssldir = /etc/puppetlabs/puppet/ssl
    storeconfigs = false
    strict_variables = false
    vardir = /opt/puppetlabs/server/data/puppetserver
  • show_diff = true This Puppet setting is used to show the differences between the current state of a file and the state Puppet will apply during a configuration change. This is useful for tracking changes made by Puppet, as it provides a detailed view of what is being modified on the system.

Verify Puppet Master Installation
# 

# Verify the Puppetmaster status
sudo systemctl status puppetserver

Verify Puppet Agent
# 

# Verify Puppet agent installation / version
/opt/puppetlabs/bin/puppet --version

# Shell output:
8.9.0

Manually Initiate Puppet Agent Run
# 

# Initiate communication between the agent and the Puppet master
sudo /opt/puppetlabs/bin/puppet agent --test

# Shell output:
Info: Using environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Notice: Requesting catalog from foreman.jklug.local:8140 (192.168.30.90)
Notice: Catalog compiled by foreman.jklug.local
Info: Caching catalog for foreman.jklug.local
Info: Applying configuration version '1726145771'
Notice: Applied catalog in 0.03 seconds



Add Hosts / Install Puppet Agent
#

Define Hostname
# 

# Set a hostname for the host server
sudo hostnamectl set-hostname host1.jklug.local

# Verify the hostname
hostname

# Shell output:
host1.jklug.local

DNS Entry
#

Make sure the new Hosts can resolve the following DNS names:

# Edit the hosts file
sudo vi /etc/hosts

# Add the following hosts entry:
127.0.0.1 localhost
127.0.1.1 host1

192.168.30.90 foreman.jklug.local foreman
192.168.30.90 host1.jklug.local host1

Install Puppet Agent
#

Install the Puppet agent on the new host:

# Add Puppet repository
sudo apt-get -y install ca-certificates
cd /tmp && wget https://apt.puppet.com/puppet8-release-jammy.deb
sudo apt-get install /tmp/puppet8-release-jammy.deb

# Install Puppet Agent
sudo apt update && sudo apt install puppet-agent -y

Verify Installation
# 

# Verify installation / check version
sudo /opt/puppetlabs/bin/puppet --version

# Shell output:
8.9.0

Start Puppet Agent
# 

# Start the Puppet agent service
sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true

# Shell output:
Notice: /Service[puppet]/ensure: ensure changed 'stopped' to 'running'
service { 'puppet':
  ensure   => 'running',
  enable   => 'true',
  provider => 'systemd',
}

Export Path Variable
# 

# Switch to root user
sudo su
  • Add the Puppet path variable for the root user
# Add the Puppet binaries to your PATH environment variable (User specific)
echo 'export PATH=/opt/puppetlabs/bin:$PATH' >> ~/.bashrc

# Apply changes / reload the .bashrc file
source ~/.bashrc

Connect Agent to Server
#

Define Server Hostname
# 

# Define the Foreman / Puppet server hostname
puppet config set server foreman.jklug.local --section main

Configuration File
#

Alternative manually define the Foreman / Puppet server hostname:

# Open Puppet Agent main configuration
sudo vi /etc/puppetlabs/puppet/puppet.conf

# Add the Puppet Server hostname
[main]
server = puppet.jklug.local

Connect Agent to Server
#

  • Request SSL certificate for the Puppet Agent
# Connect Agent to Server: Creating SSL certificate request for hos1.jklug.local
puppet ssl bootstrap
  • Switch to Foreman / Puppet Server
# List the pending certificate signing requests
puppetserver ca list

# Shell output:
Requested Certificates:
    host1.jklug.local       (SHA256)  3A:05:EE:78:E7:4A:2B:75:04:21:AE:91:AA:1D:EB:6F:CF:3E:A4:C9:F5:71:AB:4B:D7:12:B2:B1:1A:80:80:61

# Sign the agent's certificate request
puppetserver ca sign --certname host1.jklug.local

# Shell output:
Successfully signed certificate request for host1.jklug.local
  • Switch to Puppet Agent and wait till the certificate exchange is Complete
# Shell output:
Notice: Completed SSL initialization

# Optional rerun the bootstrap command to verify the certificate exchange
sudo /opt/puppetlabs/bin/puppet ssl bootstrap

# Shell output:
Notice: Completed SSL initialization

# Verify the connection to the Puppet Server
puppet agent --test

# Shell output:
Info: Using environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Notice: Requesting catalog from foreman.jklug.local:8140 (192.168.30.90)
Notice: Catalog compiled by foreman.jklug.local
Info: Caching catalog for host1.jklug.local
Info: Applying configuration version '1726147002'
Notice: Applied catalog in 0.00 second

Verify Signed Certificate on Server
# 

# List certificates
/opt/puppetlabs/bin/puppetserver ca list --all

# Shell output:
Signed Certificates:
    foreman.jklug.local       (SHA256)  EC:A0:8F:28:57:02:13:A7:B2:14:C1:4C:06:14:C8:C4:62:BD:CC:F7:CE:74:BB:67:6C:7F:4E:CC:B1:77:DA:CD alt names: ["DNS:puppet", "DNS:foreman.jklug.local"]    authorization extensions: [pp_cli_auth: true]
    host1.jklug.local         (SHA256)  FF:1A:43:CF:AD:56:AB:EA:FA:FE:0B:D7:24:91:1D:DD:9F:6F:11:B3:93:CD:D3:B5:7F:7A:60:35:E9:98:33:E2 alt names: ["DNS:host1.jklug.local"]

Optional: Puppet Server Logs
#

Optional, for troubleshooting check the Puppet server logs:

# List Puppet server logs
sudo tail -f /var/log/puppetlabs/puppetserver/puppetserver.log

Verify Host in Foreman GUI
#

Go to the “Hosts” > “All Hosts” section, the new Puppet host is now available in the list:


List / Verify Certificate in Foreman GUI
#

  • Go to: “Infrastructure” > “Smart Proxies”

  • Select “Edit / Certificates”

  • Select the “Puppet CA” tab



Links # 

# Foreman Official Documentation
https://theforeman.org/manuals/3.11/index.html#2.1Installation
Puppet - This article is part of a series.
Part 1: Puppet Open Source: Install Puppet Server, Add Hosts / Deploy Puppet Agent, Puppet Modules Examples, Deploy Apache Webserver, Deploy LAMP Stack
Part 2: This Article