Puppet Master-Agent Setup: Manage Servers from One Place

— ny_wk

Managing a handful of servers by hand is fine. Managing hundreds is a nightmare of drift, typos, and "wait, did I configure that box?" Puppet fixes that: an open-source configuration management tool where you define the desired state once on a master, and every agent server enforces it. Here's how the master-agent model works and how to set it up.

How Puppet's model works

Puppet is a master-agent system. The master holds your configuration (written as "manifests"), and each managed server runs a Puppet agent that periodically checks in, pulls its assigned config, and makes the machine match it. You describe what the system should look like; Puppet figures out how to get there and keeps it that way.

Before you start

• Two or more servers (one master, one or more agents).
• Root privileges.
• Correct hostnames/FQDNs and time sync — Puppet uses certificates, and clock skew or unresolved names break the SSL handshake. Set /etc/hosts entries and an NTP service on every node.

Step 1 — Prepare both servers

Set the FQDN on master and agents, add host entries so they resolve each other, and enable NTP so their clocks match. This prep prevents the most common Puppet failures.

Step 2 — Install and configure the master

Add the Puppet repository, install the Puppet server package, point it at its hostname, and start the service. The master listens (default port 8140) for agents to connect.

Step 3 — Install and configure the agent

On each agent, install the Puppet agent package, set the server value to your master's FQDN in puppet.conf, and start the agent. On first run it sends a certificate signing request to the master.

Step 4 — Sign the certificate

On the master, list pending requests and sign the agent's cert (puppetserver ca sign --certname <agent>). Until you sign it, the agent can't receive config — this is Puppet's trust handshake.

Step 5 — Write your first manifest

Manifests declare resources. A simple one ensures a package is installed and a service is running:

package { 'httpd': ensure => installed } service { 'httpd': ensure => running, enable => true }

Assign it to nodes, and on the next check-in every agent enforces it.

Key takeaways

• Puppet = define desired state on a master; agents pull and enforce it automatically.
• Get hostnames/FQDN, host entries, and NTP time sync right first — certificates depend on it.
• Agents send a cert request; you sign it on the master to establish trust.
• Manifests declare resources (packages, services, files); agents converge to them on each run.

Frequently asked questions

Why does Puppet need time sync and FQDNs?

It uses SSL certificates between master and agents — clock skew or unresolved hostnames break the handshake.

What's a manifest?

A file (.pp) declaring the desired state as resources — packages, services, files, users — that agents enforce.

How often do agents apply config?

By default every 30 minutes, and you can trigger a run manually with puppet agent -t.

Does Puppet work on Windows?

Yes — it manages Unix-like systems and Windows from the same master.

Set up the trust, write a manifest, and one master quietly keeps a whole fleet in the exact state you declared — no more configuration drift.