Installing Puppet Agent: Linux

Included in Puppet Enterprise 2016.1.

Note: These instructions describe how to install the open source Puppet agent software on Linux distributions for which Puppet provides official packages.

Make sure you’re ready

Before installing Puppet agent on any nodes, complete the pre-install tasks and install Puppet Server on your designated Puppet master.

Note: Puppet 4 changes the locations for many of the most important files and directories. If you’re familiar with Puppet 3 and earlier, read a summary of the changes and refer to the full specification of Puppet directories.

Review system requirements

The agent service requires few resources and runs on many systems. For details, see Puppet’s system requirements.

Install a release package to enable Puppet Collection repositories

For most Linux distributions (including CentOS, Red Hat, Ubuntu, and Debian), you can install official Puppet agent packages directly from Puppet.

Release packages configure your system to download and install appropriate versions of the Puppet packages, including the puppet-agent package. These packages are grouped into a Puppet Collection repository comprised of compatible versions of Puppet tools.

Note: Your distribution’s repositories might provide their own Puppet packages, which often install older versions of the Puppet agent service. To install the latest version of Puppet and receive updates as soon as we release them, use a Puppet Collection repository.

Note: This document covers the Puppet Collection repository of open source Puppet 4-compatible software packages.

Puppet maintains official package repositories for several operating systems and distributions. To make the repositories more predictable, we version them as “Puppet Collections” — each collection has all of the software you need to run a functional Puppet deployment, in versions that are known to work well with each other. Each collection is opt-in, and you must choose one (and on some operating systems, install a package on Puppet-managed systems) to install software and receive updates.

Repository organization

Collection repositories are organized into two tiers that correspond to Puppet Enterprise releases, which are downstream from the collection’s open-source components:

  • Numbered collections, such as Puppet Collection 1 (PC1), are long-lived, stable repositories from which long term support (LTS) Puppet Enterprise releases are built. Numbered collections maintain the same major version of each component package during its lifetime, which delivers bug fixes and minimizes breaking changes, but also introduces fewer new features.
  • The “latest” collection follows every release of Puppet Enterprise, including versions not considered LTS releases, and is updated with new major-version releases that might introduce breaking changes.

Puppet publishes updates for operating systems starting from the time a package is first published for that operating system to a collection repository, and stops updating those packages 30 days after the end of the operating system’s vendor-determined lifespan.

See The Puppet Enterprise Lifecycle for information about phases of the Puppet Support Lifecycle.

About Puppet versions

Puppet’s version numbers use the format X.Y.Z, where:

  • X must increase for major backwards-incompatible changes
  • Y can increase for backwards-compatible new functionality
  • Z can increase for bug fixes

Pinning Puppet package versions

To receive the most up-to-date Puppet software without introducing breaking changes, use the latest collection, pin your infrastructure to known versions, and update the pinned version manually when you’re ready to update. For example, if you’re using the puppetlabs-puppet_agent module to manage the installed puppet-agent package, use this resource to pin it to version 1.7.0:

class { '::puppet_agent':
  collection      => 'latest',
  package_version => '1.7.0',

When puppet-agent 2.0.0 is released, update package_version when you’re ready to upgrade to that version:

class { '::puppet_agent':
  collection      => 'latest',
  package_version => '2.0.0',
Package Contents
puppet-agent Puppet, Facter, Hiera, MCollective, pxp-agent, root certificates, and prerequisites like Ruby and Augeas
puppetserver Puppet Server; depends on puppet-agent
puppetdb PuppetDB
puppetdb-termini Plugins to let Puppet Server talk to PuppetDB

Installing release packages on Yum-based systems

To enable the Puppet Collection 1 repository, first choose the package based on your operating system and version. The packages are located in the repository and named using the following convention:

puppetlabs-release-<COLLECTION>-<OS ABBREVIATION>-<OS VERSION>.noarch.rpm

For instance, the package for Puppet Collection 1 on Red Hat Enterprise Linux 7 (RHEL 7) is puppetlabs-release-pc1-el-7.noarch.rpm.

Next, use the rpm tool as root with the upgrade (-U) flag, and optionally the verbose (-v), and hash (-h) flags:

sudo rpm -Uvh

The rpm tool outputs its progress:

Preparing...                          ################################# [100%]
Updating / installing...
1:puppetlabs-release-pc1-0.9.2-1.el################################# [100%]

Note: To install the release package on Red Hat Enterprise Linux 5, you must download it first. The rpm package manager on RHEL 5 doesn’t support installing packages from a URL.

Installing release packages on Apt-based systems

To enable the Puppet Collection 1 repository, first choose the package based on your operating system and version. The packages are located in the repository and named using the following convention:

puppetlabs-release-<COLLECTION>-<VERSION CODE NAME>.deb

For instance, the release package for Puppet Collection 1 on Debian 7 “Wheezy” is puppetlabs-release-pc1-wheezy.deb. For Ubuntu releases, the code name is the adjective, not the animal.

Next, download the release package and install it as root using the dpkg tool and the install flag (-i):

sudo dpkg -i puppetlabs-release-pc1-wheezy.deb

Finally, run apt-get update after installing the release package to update the apt package lists.

Confirm that you can run Puppet executables

Since version 4, Puppet’s executables are installed to /opt/puppetlabs/bin/, which is not in the default PATH environment variable.

This doesn’t matter for Puppet services — for instance, the service puppet start command works regardless of the PATH — but if you’re running interactive puppet commands, you must either add their location to your PATH or execute them using their full path.

To quickly add this location to your PATH for your current terminal session only, run export PATH=/opt/puppetlabs/bin:$PATH. You can also add this location wherever you configure your PATH, such as your .profile or .bashrc configuration files.

For more information, review the list of files and directories moved in Puppet 4.

Install the puppet-agent package

Use your operating system’s package manager to install the puppet-agent package. After installing the package, do not start the puppet service until you configure critical settings.

For Yum-based systems

On each node, run:

sudo yum install puppet-agent

For Apt-based systems

On each node, run:

sudo apt-get install puppet-agent

Configure critical agent settings

Set the agent’s server setting to your Puppet master’s hostname. The default value is server = puppet, so if your master’s hostname is already puppet, you can skip this step.

See the list of agent-related settings for more configuration options.

Start the puppet service

To start the puppet service, run:

sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true

By default, the service performs a Puppet run every 30 minutes. To manually launch and watch a Puppet run, run:

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

Sign certificates on the CA master

As each agent attempts its first run, it submits a certificate signing request (CSR) to the certificate authority (CA) Puppet master. The CA master must sign these certificates before it can manage the agents.

To do this:

  1. Log into the CA Puppet master.

  2. View outstanding requests by running:

    sudo puppet cert list
  3. Sign a request by running:

    sudo puppet cert sign <NAME>

    Once the Puppet master signs an agent’s certificate, the agent regularly fetches and applies configuration catalogs from the master.

Note: The Puppet documentation includes a detailed description of Puppet’s agent/master communications.

↑ Back to top