Installing Puppet agent: Linux

This version of Puppet is not included in Puppet Enterprise. The latest version of PE includes Puppet 4.9.

Install the Puppet agent so that your master can communicate with your Linux nodes.

Before you begin: Review the pre-install tasks and installing Puppet Server. If you’re familiar with Puppet 3 and earlier, learn about new locations for many of the files and directories by reading a summary of changes in Puppet 4 or referring to the full specification of Puppet directories.

  1. Install a release package to enable Puppet Collection repositories.

  2. Confirm that you can run Puppet executables.

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

    The executable path 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 the executable 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 details about files and directories moved in Puppet 4.

  3. Install the puppet-agent package on your Puppet agent nodes using the command appropriate to your system:

    • Yum – sudo yum install puppet-agent.
    • Apt – sudo apt-get install puppet-agent.
  4. (Optional) Configure agent settings.

    For example, if your master isn’t reachable at the default address, server = puppet, set the server setting to your Puppet master’s hostname.

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

  5. Start the puppet service: sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true.

  6. (Optional) To see a sample of Puppet agent’s output and verify any changes you may have made to your configuration settings in step 5, manually launch and watch a Puppet run: sudo /opt/puppetlabs/bin/puppet agent --test

  7. Sign certificates on the certificate authority (CA) master.

    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.

    As each Puppet agent runs for the first time, it submits a certificate signing request (CSR) to the CA Puppet master. You must log into that server to check for and sign certificates. After an agent’s certificate is signed, it regularly fetches and applies configuration catalogs from the Puppet master.

About release packages

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.

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.

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.

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

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: 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, as it doesn’t support installing packages from a URL.

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.

↑ Back to top