Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Architecture and Setup

Installing Puppet Server and the Agent

Step-by-step plan to install Puppet Server and puppet-agent on Linux, set the server name, start services, open port 8140 and connect your first node.

This lesson walks through a small lab: one machine for the Puppet Server and one or more machines for agents. The commands are for Linux virtual machines you control. Because Puppet cannot run on this site, every command block is read-only; check each against the documentation of your distribution before running it, because package and repository details change over time.

Plan the lab

  • Two VMs: puppet.example.test (server, at least 2 CPU cores and 4 GB RAM, because the server is a Java program) and web1.example.test (agent).
  • Both must resolve each other by name. In a lab, add entries to /etc/hosts on both machines. In production use DNS.
  • Time must be correct on both (use chrony or systemd-timesyncd): certificates are time-sensitive.
  • Port 8140/tcp must be reachable from the agent to the server.
flowchart LR
    W["web1.example.test<br/>puppet-agent"] -->|HTTPS 8140| P["puppet.example.test<br/>puppetserver"]
    DEV["You + Git"] -->|deploy code| P

Installing the server

First add the Puppet repository. The repository package name depends on your distribution and Puppet major version, so take the exact URL from the vendor's download page. On Debian-style systems the pattern is:

Terminal
wget https://apt.puppet.com/puppet8-release-jammy.deb
sudo dpkg -i puppet8-release-jammy.deb
sudo apt-get update
sudo apt-get install -y puppetserver

(jammy is Ubuntu 22.04; substitute your codename.) On Red Hat family: sudo rpm -Uvh the matching puppet8-release package, then sudo dnf install -y puppetserver.

The puppetserver package pulls in puppet-agent, so the server machine also has the agent tools in /opt/puppetlabs/bin.

Memory settings

Puppet Server's heap size is set in /etc/default/puppetserver (Debian) or /etc/sysconfig/puppetserver (Red Hat):

Terminal
JAVA_ARGS="-Xms2g -Xmx2g"

The default is often 2 GB. A rule of thumb: allow around 1 GB of heap per JRuby worker plus headroom, then watch real usage. Too small a heap causes slow runs or out-of-memory errors.

Server name and certificates

Edit /etc/puppetlabs/puppet/puppet.conf on the server:

INI
[main]
server = puppet.example.test

[server]
certname = puppet.example.test

On first start Puppet Server creates its own certificate authority and a certificate for itself, using the certname. Start and enable it:

Terminal
sudo systemctl enable --now puppetserver
sudo systemctl status puppetserver

The first start can take a minute or two while the JVM warms up. Logs are in /var/log/puppetlabs/puppetserver/puppetserver.log. If a firewall runs, open the port:

Terminal
sudo ufw allow 8140/tcp          # Ubuntu
sudo firewall-cmd --permanent --add-port=8140/tcp && sudo firewall-cmd --reload   # Red Hat

Installing the agent

On the agent machine, add the same repository, then install puppet-agent and point it at the server:

Terminal
sudo apt-get install -y puppet-agent
sudo /opt/puppetlabs/bin/puppet config set server puppet.example.test --section main
sudo systemctl enable --now puppet

The puppet config set command edits puppet.conf for you. Start with a manual test run instead of waiting 30 minutes:

Terminal
sudo /opt/puppetlabs/bin/puppet agent --test

The first run will create a private key and a certificate signing request (CSR), submit it to the server and stop with a message that the certificate has not been signed yet. That is expected. Approve it on the server, as the next lesson shows, then run puppet agent --test again to receive the first catalog.

Verifying and troubleshooting

Symptom Likely cause
Connection refused on 8140 Server not started yet (JVM start is slow) or firewall
Could not resolve the server Missing DNS or hosts entry
Certificate errors mentioning dates Clock skew between machines
Server runs out of memory Heap too small for the number of JRuby workers
command not found: puppet Use /opt/puppetlabs/bin/puppet

Useful checks:

Terminal
curl -k https://puppet.example.test:8140/status/v1/simple
/opt/puppetlabs/bin/puppet config print server certname

The first prints running when the server is healthy (the -k skips certificate checks only for this health probe).

A stand-in: preflight checks

Many failed installs come from a skipped prerequisite. This stand-in (Python, not Puppet) models a preflight checklist so you can see the logic.

Python Stand-in: lab preflight checklist

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: pick a JVM heap size

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

That rule of thumb is a starting point only; real sizing comes from monitoring.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which package installs the Puppet Server?

    puppetserver provides the server and depends on puppet-agent.
  2. 2. Why does the agent's first puppet agent --test stop with a certificate message?

    A new agent submits a CSR that the CA must sign first.
  3. 3. Which setting tells the agent where the server is?

    The server setting names the Puppet Server.
  4. 4. Which problem is most associated with certificate errors about dates?

    Certificates have validity periods, so clock skew breaks TLS.

Summary

  • Lab: one server (2+ cores, 4 GB RAM), one or more agents, port 8140 open, names resolve, clocks synced.
  • Install puppetserver on the server and puppet-agent on nodes, from the vendor repository.
  • Set server and certname in puppet.conf; start with systemctl enable --now.
  • Tune the JVM heap for the server.
  • First agent run submits a CSR; signing it is next.

Next: Certificates and Node Authentication