Puppet

How to install Puppet Server (Puppetmaster) on Ubuntu 16.04 / 18.04 / 20.04.

Prerequisites

• Ubuntu server with at least 2 GB RAM (Puppet Server is JVM-based)
• Java 8 or 11 installed
• Hostname resolving correctly

Step 1 — Install Java

sudo apt-get install -y openjdk-11-jdk

Step 2 — Add Puppet Repository

# Ubuntu 20.04 (Focal)
wget https://apt.puppetlabs.com/puppet6-release-focal.deb
sudo dpkg -i puppet6-release-focal.deb
sudo apt-get update

# Ubuntu 18.04 (Bionic)
wget https://apt.puppetlabs.com/puppet6-release-bionic.deb
sudo dpkg -i puppet6-release-bionic.deb
sudo apt-get update

Step 3 — Install Puppet Server

sudo apt-get install -y puppetserver

Step 4 — Configure Memory (Optional)

# Edit /etc/default/puppetserver
# Default: JAVA_ARGS="-Xms2g -Xmx2g"
# For low-memory VMs, reduce to 512 MB:
sudo sed -i 's/-Xms2g -Xmx2g/-Xms512m -Xmx512m/' /etc/default/puppetserver

Step 5 — Set Hostname

# /etc/hosts should resolve "puppet" to the server IP
echo "127.0.0.1 localhost puppet puppetserver" | sudo tee -a /etc/hosts

Step 6 — Start and Enable

sudo systemctl start puppetserver
sudo systemctl enable puppetserver
sudo systemctl status puppetserver

Step 7 — Install Puppet Agent on Nodes

sudo apt-get install -y puppet-agent
echo "server = puppetserver.example.com" | sudo tee -a /etc/puppetlabs/puppet/puppet.conf
sudo /opt/puppetlabs/bin/puppet agent --test

Common Puppet commands for managing resources, applying manifests, and querying system state.

Resource Commands

# List all file resources
puppet resource file

# List all services
puppet resource service

# List all users
puppet resource user

# List all packages
puppet resource package

# Show a specific resource
puppet resource service nginx
puppet resource user root

Apply Manifests

# Apply a manifest file (dry run — no changes made)
puppet apply site.pp --noop

# Apply a manifest file
puppet apply site.pp

# Apply inline manifest (ad-hoc)
puppet apply -e 'package { "chrony": ensure => installed } service { "chrony": ensure => running, enable => true }'

Agent Commands

# Test connection to Puppet Server and apply catalog
puppet agent --test

# Run in verbose mode
puppet agent --test --verbose

# Run in no-op (dry run) mode
puppet agent --test --noop

# Disable the Puppet agent
puppet agent --disable "Maintenance in progress"

# Enable the Puppet agent
puppet agent --enable

Certificate Management

# On agent: show pending CSR
puppet ssl show

# On server: list pending certificate requests
puppetserver ca list

# On server: sign a certificate
puppetserver ca sign --certname agent.example.com

# On server: sign all pending certificates
puppetserver ca sign --all

A Puppet manifest to install Apache, deploy a virtual host configuration, and ensure the service is running.

Manifest

# apache.pp
node default {
  package { 'apache2':
    ensure => installed,
  }

  file { '/etc/apache2/sites-enabled/000-default.conf':
    ensure  => file,
    content => "
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html
    ErrorLog \${APACHE_LOG_DIR}/error.log
    CustomLog \${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
",
    notify  => Service['apache2'],
    require => Package['apache2'],
  }

  service { 'apache2':
    ensure  => running,
    enable  => true,
    require => Package['apache2'],
  }
}

Apply the Manifest

# Dry run
puppet apply apache.pp --noop

# Apply
puppet apply apache.pp

Verify

systemctl status apache2
curl -I http://localhost

The site.pp file is the main entry point for Puppet manifests. It defines which classes and resources apply to which nodes.

Basic site.pp — Apply to All Nodes

# /etc/puppetlabs/code/environments/production/manifests/site.pp

node default {
  # Install the tree package on all nodes
  package { 'tree':
    ensure => 'installed',
  }

  # Create a file with content
  file { '/tmp/puppet.info':
    ensure  => 'present',
    content => "This file was created by Puppet on ${facts['hostname']}",
    mode    => '0644',
  }
}

Node-Specific Configuration

node 'web01.example.com' {
  include profile::webserver
}

node 'db01.example.com' {
  include profile::database
}

# Apply to a group of nodes using regex
node /^web\d+\.example\.com$/ {
  include profile::webserver
}

Using Classes and Roles

node default {
  class { 'ntp':
    servers => ['pool.ntp.org'],
  }
  include base::security
}

Apply and Verify

puppet apply site.pp --noop
puppet apply site.pp
puppet agent --test

How to run a Puppet Server and Puppet Agent in Docker containers on the same host for testing and development.

Step 1 — Create a Docker Network

docker network create puppetnetwork
docker network ls

Step 2 — Pull Images

docker pull puppet/puppetserver
docker pull puppet/puppet-agent

Step 3 — Run the Puppet Server

docker run -d --name puppet \
  --network puppetnetwork \
  --hostname puppet \
  -p 8140:8140 \
  puppet/puppetserver

Step 4 — Wait for Server to Start

# Watch logs until CA is ready
docker logs -f puppet
# Look for: "Puppet Server started successfully"

Step 5 — Run the Puppet Agent

docker run -d --name puppet-agent \
  --network puppetnetwork \
  --hostname agent01 \
  -e PUPPETSERVER_HOSTNAME=puppet \
  puppet/puppet-agent

Step 6 — Sign the Agent Certificate

# On the Puppet Server container
docker exec puppet puppetserver ca list
docker exec puppet puppetserver ca sign --certname agent01

Step 7 — Test the Agent

docker exec puppet-agent puppet agent --test

Detailed step-by-step installation of Puppet 6 Server on Ubuntu 20.04 (Focal).

Step 1 — Download and Install Puppet Repository

wget https://apt.puppetlabs.com/puppet6-release-focal.deb
sudo dpkg -i puppet6-release-focal.deb
sudo apt-get update && sudo apt-get upgrade -y

Step 2 — Configure /etc/hosts

sudo nano /etc/hosts
# Add:
127.0.0.1  localhost puppet puppetserver

Step 3 — Verify DNS Resolution

ping puppet
ping puppetserver

Step 4 — Install Puppet Server

sudo apt-get install -y puppetserver

Step 5 — Tune JVM Memory

# Edit /etc/default/puppetserver
# Change -Xms2g -Xmx2g to match available RAM
# For a 1 GB VM:
JAVA_ARGS="-Xms512m -Xmx512m -XX:MaxPermSize=256m"

Step 6 — Start Puppet Server

sudo systemctl start puppetserver
sudo systemctl enable puppetserver
sudo systemctl status puppetserver

Step 7 — Open Firewall Port

sudo ufw allow 8140/tcp

Verify

sudo /opt/puppetlabs/bin/puppetserver ca list

How to regenerate certificates on the Puppet primary server or CA when certificates have expired or the CA needs to be replaced.

When to Regenerate

• Certificates have expired
• The CA was compromised
• Adding DNS alt-names to the server certificate
• Moving the Puppet Server to a new hostname

Regenerate the Primary Server Certificate

# On the Puppet primary server
sudo systemctl stop puppetserver

# Remove the existing server certificate
sudo rm -f /etc/puppetlabs/puppet/ssl/certs/<server-fqdn>.pem
sudo rm -f /etc/puppetlabs/puppet/ssl/private_keys/<server-fqdn>.pem
sudo rm -f /etc/puppetlabs/puppet/ssl/public_keys/<server-fqdn>.pem

# Remove the signed cert from the CA
puppetserver ca clean --certname <server-fqdn>

# Start the server — it will generate a new certificate
sudo systemctl start puppetserver

Regenerate the Entire CA

# Stop the server
sudo systemctl stop puppetserver

# Remove CA data
sudo rm -rf /etc/puppetlabs/puppet/ssl/

# Restart to generate a new CA
sudo systemctl start puppetserver

Warning: Regenerating the CA invalidates all node certificates. All agents must be re-bootstrapped.

Regenerate a Single Agent Certificate

# On the agent node:
sudo rm -rf /etc/puppetlabs/puppet/ssl/

# On the server: clean the old cert
puppetserver ca clean --certname agent.example.com

# Run the agent to generate a new CSR
sudo puppet agent --test

# On the server: sign the new request
puppetserver ca sign --certname agent.example.com

How to fix Puppet agent certificate errors by regenerating the node's SSL certificates.

Error Example

Error: certificate verify failed: unable to get local issuer certificate

Fix on the Agent Node

# Remove the node's SSL directory
sudo rm -rf /etc/puppetlabs/puppet/ssl/

# Re-run the agent — it will generate a new CSR
sudo puppet agent --test --verbose

Sign the New Certificate on the Server

# List pending certificate requests
puppetserver ca list

# Sign the agent's new certificate
puppetserver ca sign --certname <agent-fqdn>

# Or sign all pending
puppetserver ca sign --all

Test the Agent

sudo puppet agent --test

Notes

• Also clean the old cert on the server to avoid conflicts: puppetserver ca clean --certname <agent-fqdn>
• If the server's CA certificate changed, all agents must have their SSL directories wiped and re-registered.