Installing Puppet agent: Linux

Make sure you’re ready

Before installing Puppet on any agent nodes, make sure you’ve read the pre-install tasks and installed Puppet Server.

Note: Puppet 4 changed 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 supported versions and requirements

Most Linux systems (including CentOS, Redhat, Ubuntu, and Debian) have official Puppet agent packages. For a complete list of supported platforms, view the system requirements page.

Install a release package to enable Puppet Collection repositories

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

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

• For Puppet 3.8 open source packages, see its repository documentation.
• For Puppet Enterprise installation tarballs, see its installation documentation.

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 yum.puppetlabs.com 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 https://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm

The rpm tool outputs its progress:

Retrieving https://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm
Preparing...                          ################################# [100%]
Updating / installing...
1:puppetlabs-release-pc1-0.9.2-1.el################################# [100%]

Note: We only provide the puppet-agent package for recent versions of Puppet on RHEL 5, and to install it you must first download the package as rpm 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 apt.puppetlabs.com 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):

wget https://apt.puppetlabs.com/puppetlabs-release-pc1-wheezy.deb
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 you can run Puppet executables

The new location for Puppet’s executables is /opt/puppetlabs/bin/, which is not in your PATH environment variable by default.

This doesn’t matter for Puppet services — for instance, service puppet start 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, use the command 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, see our page about files and directories moved in Puppet 4.

Install the puppet-agent package

For Yum-based systems

On your Puppet agent nodes, run sudo yum install puppet-agent.

For Apt-based systems

On your Puppet agent nodes, run sudo apt-get install puppet-agent.

Do not start the puppet service yet.

Configure critical agent settings

You probably want to set the server setting to your Puppet master’s hostname. The default value is server = puppet, so if your master is reachable at that address, you can skip this.

For other settings you might want to change, see the list of agent-related settings.

Start the puppet service

To start the Puppet service, run sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true.

To manually launch and watch a Puppet run, run sudo /opt/puppetlabs/bin/puppet agent --test.

Sign certificates on the CA master

As each Puppet agent runs for the first time, it submits a certificate signing request (CSR) to the certificate authority (CA) Puppet master. You must log into that server to check for and sign certificates. On the Puppet master:

1. Run sudo /opt/puppetlabs/bin/puppet cert list to see any outstanding requests.
2. Run sudo /opt/puppetlabs/bin/puppet cert sign <NAME> to sign a request.

After an agent’s certificate is signed, it regularly fetches and applies configuration catalogs from the Puppet master.