Module 2: Install Puppet Server and Connect Your First Puppet Agent

TL;DR: To install Puppet and connect your first node, install puppetserver on the primary server, install puppet-agent on the managed node, configure both systems with resolvable hostnames, point the agent at the server in puppet.conf, run puppet agent -t, sign the certificate request with puppetserver ca sign, then run the agent again to retrieve and apply its catalog.

This guide shows how to install Puppet Server, connect a Puppet Agent, sign the first agent certificate, create a test site.pp manifest, and verify a complete Puppet run. It uses the modern Puppet package names and paths while also noting legacy command names you may still see in older tutorials.

In the traditional model of systems administration, every server, database, and network configuration was created and managed by hand, an approach often referred to as “artisan server crafting”. As an infrastructure grows beyond a few machines, this manual process becomes unmanageable, leading to configuration drift and “snowflake servers”—systems that are unique, undocumented, and impossible to replicate. Puppet solves this by allowing you to express your infrastructure as declarative code, treating your servers not as unique “pets” but as “cattle” that can be consistently reproduced and synchronized from a central specification.

The following walkthrough provides a comprehensive, step-by-step guide to installing a Puppet server, enrolling your first agent node, and understanding the underlying communication and execution cycles.

Terminology note: Puppet documentation now commonly uses primary server instead of master, but many engineers and older commands still use “Puppet Master”. This tutorial uses both terms where it helps with search and troubleshooting.

Quick answer: how do you connect a Puppet agent to Puppet Server?

1. Configure DNS or /etc/hosts so the agent can resolve the Puppet Server hostname.
2. Install puppetserver on the primary server and puppet-agent on the node.
3. Set server = puppet.example.com in the agent’s /etc/puppetlabs/puppet/puppet.conf.
4. Run sudo /opt/puppetlabs/bin/puppet agent -t on the agent to create a CSR.
5. Run sudo /opt/puppetlabs/bin/puppetserver ca sign --certname node1.example.com on the server.
6. Run the agent again to download the signed certificate, retrieve its catalog, and apply the manifest.

1. Understanding Puppet agent/server architecture

Before diving into the installation, it is critical to understand the agent/server architecture. In this model, a central Puppet Server or primary server acts as the authoritative source for all configuration code (manifests). The Puppet Agent is software installed on every managed node.

Communication cycle

The interaction between the agent and the server is primarily a series of HTTPS transactions.

1. Fact Collection: The agent runs a tool called Facter to discover details about its hardware, operating system, and network settings.
2. Catalog Request: The agent sends these facts to Puppet Server and requests its “catalog”—a compiled JSON document describing exactly how that specific node should be configured.
3. Compilation: Puppet Server uses the facts and its own manifests to compile the catalog.
4. Application: The agent receives the catalog and makes the necessary changes to the local system to match the desired state.
5. Reporting: The agent sends a report back to the master detailing what changed and if any errors occurred.

2. Preparing the infrastructure

For Puppet to function, the machines must have reliable network connectivity and properly configured hostnames. Puppet relies heavily on SSL certificates, which are tied to the Fully Qualified Domain Name (FQDN) of the machines.

Step 2.1: Set hostnames

On your intended Puppet Server, set a hostname that is easy to resolve. In this tutorial, we will use puppet.example.com for the server and node1.example.com for the agent.

On the Puppet Server:

sudo hostnamectl set-hostname puppet.example.com

On the Agent:

sudo hostnamectl set-hostname node1.example.com

Step 2.2: Configure host resolution

If you do not have a functional internal DNS, you must manually map these addresses in the /etc/hosts file of both machines to ensure they can find each other.

# Example /etc/hosts entry
10.0.0.1   puppet.example.com puppet
10.0.0.2   node1.example.com  node1

3. Installing Puppet Server

The Puppet primary server uses the puppetserver package. Older tutorials may refer to puppetmaster, puppet-master, or Passenger-backed deployments, but modern Puppet Server is a JVM-based service named puppetserver.

Step 3.1: Add the Puppet repository

Puppet provides official repositories for supported Linux distributions. Choose the release package that matches your operating system and codename, then update your package index.

Example pattern on Ubuntu/Debian:

sudo apt-get update
wget https://apt.puppet.com/puppet-release-<codename>.deb
sudo dpkg -i puppet-release-<codename>.deb
sudo apt-get update

Replace <codename> with your distribution codename, such as jammy, focal, or another supported release.

Step 3.2: Install Puppet Server

sudo apt-get install puppetserver

Step 3.3: Configure puppet.conf

The primary configuration resides in /etc/puppetlabs/puppet/puppet.conf. This file is divided into sections: [main] for global settings, [server] for server settings, and [agent] for agent settings.

Edit /etc/puppetlabs/puppet/puppet.conf:

[main]
    certname = puppet.example.com
    server = puppet.example.com

[server]
    # Location of the site manifest
    manifest = /etc/puppetlabs/code/environments/production/manifests/site.pp

Step 3.4: Initialize the CA and start Puppet Server

Before the server can sign other certificates, it must generate its own Certificate Authority (CA) files.

sudo /opt/puppetlabs/bin/puppetserver ca setup
sudo systemctl enable --now puppetserver
sudo /opt/puppetlabs/bin/puppetserver ca list --all

If you need your server to answer to multiple names (e.g., puppet and puppet.prod.example.com), configure DNS alt names before the first certificate is generated:

sudo /opt/puppetlabs/bin/puppet config set dns_alt_names puppet,puppet.prod.example.com --section server
sudo systemctl restart puppetserver

4. Installing the Puppet Agent node

The agent node only requires the puppet-agent package. It does not need the heavy dependencies of the server.

Step 4.1: Install Puppet Agent

Follow the same repository setup steps as the server, then install the client software:

sudo apt-get install puppet-agent

Step 4.2: Configure the agent

The agent needs to know where to find Puppet Server. You define this in its local puppet.conf.

On the Agent (/etc/puppetlabs/puppet/puppet.conf):

[agent]
    server = puppet.example.com
    report = true

5. The Puppet certificate enrollment workflow

This is the most critical stage of connecting a new node. Because Puppet executes commands as root, it uses a Public Key Infrastructure (PKI) to ensure that the server only gives catalogs to authorized nodes and the agent only accepts instructions from the authorized server.

Step 5.1: Send the agent’s initial certificate request

Run the Puppet agent for the first time in test mode (-t). This triggers the creation of a new local SSL key and sends a Certificate Signing Request (CSR) to Puppet Server.

On the Agent:

sudo /opt/puppetlabs/bin/puppet agent -t

Expected Output:

Info: Creating a new SSL key for node1.example.com Exiting; no certificate found and waitforcert is disabled

Step 5.2: Sign the request on Puppet Server

Puppet Server now has a pending request. The administrator must manually verify and sign it to “enroll” the node into the fleet.

On Puppet Server:

1. List pending requests:

   sudo /opt/puppetlabs/bin/puppetserver ca list
   

2. Sign the specific node:

   sudo /opt/puppetlabs/bin/puppetserver ca sign --certname node1.example.com
   

   Notice: Signed certificate request for node1.example.com

Older Puppet versions used puppet cert list and puppet cert sign; puppetserver ca is the modern CA command family.

Step 5.3: Complete the handshake

Now, return to the agent and run the test again. It will download the signed certificate and proceed to its first configuration run.

On the Agent:

sudo /opt/puppetlabs/bin/puppet agent -t

Info: Caching certificate for node1.example.com Info: Caching catalog for node1.example.com Notice: Finished catalog run in 0.03 seconds

6. Creating your first Puppet manifest

To verify that the connection is truly functional, you should create a simple resource on the server and see it applied to the agent. Puppet uses manifests (files ending in .pp) to store code. The main environment manifest is typically named site.pp.

Step 6.1: Define the site.pp file

On Puppet Server, create the directory structure and the main manifest file.

sudo mkdir -p /etc/puppetlabs/code/environments/production/manifests
sudo vi /etc/puppetlabs/code/environments/production/manifests/site.pp

Add the following code to site.pp:

node 'node1.example.com' {
  file { '/tmp/puppet_test.txt':
    ensure  => file,
    content => "Managed by Puppet - Connection Successful!\n",
    mode    => '0644',
  }

  notify { 'The Puppet Butler has arrived!': }
}

7. The Puppet Agent run cycle in detail

When you trigger a run on the agent, Puppet follows a rigorous, idempotent execution flow. Idempotency means that running the manifest multiple times will result in the same outcome without causing side effects; if the file already exists with the correct content, Puppet will do nothing.

1. Pluginsync: Before anything else, Puppet synchronizes any custom Ruby plugins, facts, or types from the server’s modules to the agent’s local cache.
2. Facter Run: The agent gathers local facts (OS version, IP, etc.) and sends them to the server.
3. Compilation & Catalog Delivery: Puppet Server evaluates the site.pp file. It sees the node 'node1.example.com' block, matches it to the incoming request, and compiles a catalog.
4. Transaction: The agent walks through the catalog. For the file resource:
   • It checks if /tmp/puppet_test.txt exists.
   • It compares the local checksum to the desired content checksum.
   • If they differ, it overwrites the file.
5. Post-checks & Reporting: The agent records the result (Success/Failure/Skipped) and sends a report back to Puppet Server.

8. Verifying a successful Puppet Agent connection

To verify the installation, run the agent again and inspect the system.

On the Agent:

sudo /opt/puppetlabs/bin/puppet agent -t

Successful Output Log:

Notice: /Stage[main]//Node[node1.example.com]/File[/tmp/puppet_test.txt]/ensure: created Notice: The Puppet Butler has arrived! Notice: Finished catalog run in 0.12 seconds

System Check:

cat /tmp/puppet_test.txt

Managed by Puppet - Connection Successful!

9. Advanced verification and troubleshooting

If the connection fails, diagnose the two most common buckets of Puppet setup errors: connectivity and catalog failures.

Bucket 1: Connectivity and certificates

• Port Check: Ensure Puppet Server is listening on port 8140. Use netcat or telnet to verify the server is reachable.

  nc -z -v puppet.example.com 8140
  

• SSL Verification: If you see “SSL certificate verify failed,” it often means the system clocks are out of sync. Puppet requires time synchronization (via NTP) to validate certificates.
• Manual cert find: You can test the REST API manually with wget or curl to try downloading the CA certificate from the server.

Bucket 2: Catalog failures

• Syntax Check: Validate your code on Puppet Server before running the agent:

  /opt/puppetlabs/bin/puppet parser validate /etc/puppetlabs/code/environments/production/manifests/site.pp
  

• Dry-run Mode (--noop): Run the agent with the --noop flag. This will show you what Puppet would do without actually making changes to the system.
• Debug Mode: Use the --debug flag for verbose output of every step Puppet takes.
• Reviewing the Catalog: On the agent, you can inspect the actual JSON catalog delivered by Puppet Server in /opt/puppetlabs/puppet/cache/client_data/catalog/.

10. Post-enrollment best practices

Once your first agent is connected, the sources recommend transitioning toward a more modular and professional workflow.

• Implement Modules: Move resources out of site.pp and into Modules. For example, create an nginx module with an init.pp class.
• Use the Package-File-Service Pattern: This is the foundational pattern for Puppet automation: ensure the package is installed, the file (config) is deployed, and the service is running and listening for changes.
• Version Control with Git: Do not edit manifests directly on the production server. Store your manifests in a Git repository. Use a deployment workflow to promote tested code into the server’s environment directory.
• Standardize with Roles and Profiles: For scaling, use the Roles and Profiles design pattern. Profiles bundle lower-level modules into usable tech-stack components, while Roles define the business purpose of the machine (e.g., “Web Server” or “Database”).

Frequently asked questions

What package installs Puppet Server?

Use the puppetserver package on the primary server. Use puppet-agent on managed nodes.

Which port does Puppet Agent use to reach Puppet Server?

Puppet Agent connects to Puppet Server over TCP port 8140. Firewalls, security groups, and host firewalls must allow the agent to reach the server on that port.

Where is puppet.conf located?

Modern Puppet packages store the main configuration file at /etc/puppetlabs/puppet/puppet.conf. Older tutorials may reference /etc/puppet/puppet.conf.

What command signs a Puppet Agent certificate?

On Puppet Server, use sudo /opt/puppetlabs/bin/puppetserver ca sign --certname node1.example.com. Older versions used sudo puppet cert sign node1.example.com.

How do I test a Puppet Agent run?

Run sudo /opt/puppetlabs/bin/puppet agent -t on the agent node. Add --noop to preview changes without applying them, or --debug for detailed troubleshooting output.

Official Puppet references

For current platform support and package-specific details, check Puppet’s official documentation for installing Puppet, installing Puppet Server, installing Puppet Agent, and certificate authority and SSL behavior.

By following this detailed walkthrough, you have moved from manual “artisan” management to an automated, scalable infrastructure. Your Puppet manifests now serve as live documentation that is guaranteed to be up-to-date and executable, ensuring your servers remain consistent across their entire lifecycle.

Back to Getting started with Puppet: a beginner to production tutorial series index