Installing and configuring agents

You can install agents on *nix, Windows, or macOS.

After you install an agent, you must complete the steps in Configure agents.

Install agents

Install *nix agents

You can install *nix agents using an install script.

Before you begin
Enable the Puppet platform repository.
  1. Install the agent using the command appropriate to your environment.
    • Yum: 
      sudo yum install puppet-agent
    • Apt:
      sudo apt-get install puppet-agent
      Note: The Puppet repository for the APT package management system is: http://apt.puppetlabs.com/
    • Zypper:
      sudo zypper install puppet-agent
  2. Start the Puppet service: 
    sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true

Install Windows agents

You can install Windows agents graphically or from the command line using an .msi package.

Install Windows agents with the .msi package

Use the Windows .msi package if you need to specify agent configuration details during installation, or if you need to install Windows agents locally without internet access.

Before you begin
Install Windows agents with the installer

Use the MSI installer for a more automated installation process. The installer can configure puppet.conf, create CSR attributes, and configure the agent to talk to your primary server.

  1. Run the installer as administrator.
  2. When prompted, provide the hostname of your primary server, for example puppet.
Install Windows agents using msiexec from the command line

Install the MSI manually from the the command line if you need to customize puppet.conf, CSR attributes, or certain agent properties.

On the command line of the node that you want to install the agent on, run the install command: 
msiexec /qn /norestart /i <PACKAGE_NAME>.msi
Tip: You can specify /l*v install.txt to log the progress of the installation to a file.

MSI properties

If you install Windows agents from the command line using the .msi package, you can optionally specify these properties.

Important: If you set a non-default value for PUPPET_SERVER, PUPPET_CA_SERVER, PUPPET_AGENT_CERTNAME, or PUPPET_AGENT_ENVIRONMENT, the installer replaces the existing value in puppet.conf and re-uses the value at upgrade unless you specify a new value. Therefore, if you've customized these properties, don't change the setting directly in puppet.conf; instead, re-run the installer and set a new value at installation.
Property Definition Setting in pe.conf Default
INSTALLDIR Location to install Puppet and its dependencies. n/a

  • 32-bit — C:\Program Files\Puppet Labs\Puppet

  • 64-bit — C:\Program Files \Puppet Labs\Puppet

ENABLE_LONG_PATHS Long filename support. Set to TRUE and set HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled to 1 n/a No value
PUPPET_SERVER Hostname where the primary server can be reached. server puppet
PUPPET_CA_SERVER Hostname where the CA server can be reached, if you're using multiple servers and only one of them is acting as the CA. ca_server Value of PUPPET_SERVER
PUPPET_AGENT_CERTNAME

Node's certificate name, and the name it uses when requesting catalogs.

For best compatibility, limit the value of certname to lowercase letters, numbers, periods, underscores, and dashes.

 certname Value of facter fdqn
PUPPET_AGENT_ENVIRONMENT Node's environment.
Note: If a value for the environment variable already exists in puppet.conf, specifying it during installation does not override that value.
 environment production
PUPPET_AGENT_STARTUP_MODE Whether and how the agent service is allowed to run. Allowed values are:
  • Automatic — Agent starts up when Windows starts and remains running in the background.
  • Manual — Agent can be started in the services console or with net start on the command line.
  • Disabled — Agent is installed but disabled. You must change its startup type in the services console before you can start the service.
n/a Automatic
PUPPET_AGENT_ACCOUNT_USER

Windows user account the agent service uses. This property is useful if the agent needs to access files on UNC shares, because the default LocalService account can't access these network resources.

The user account must already exist, and can be either a local or domain user. The installer allows domain users even if they have not accessed the machine before. The installer grants Logon as Service to the user, and if the user isn't already a local administrator, the installer adds it to the Administrators group.

If you specify PUPPET_AGENT_ACCOUNT_USER, you must also specify PUPPET_AGENT_ACCOUNT_PASSWORD and PUPPET_AGENT_ACCOUNT_DOMAIN unless the node is under a gMSA. For gMSAs, you must specify PUPPET_AGENT_ACCOUNT_USER (the user for the gMSA) and PUPPET_AGENT_ACCOUNT_DOMAIN. Do not specify PUPPET_AGENT_ACCOUNT_PASSWORD.

 n/a LocalSystem
PUPPET_AGENT_ACCOUNT_PASSWORD Password for the agent's user account. n/a No Value
PUPPET_AGENT_ACCOUNT_DOMAIN Domain of the agent's user account. n/a .
REINSTALLMODE A default MSI property used to control the behavior of file copies during installation.
Important: If you need to downgrade agents, use REINSTALLMODE=amus when calling msiexec.exe at the command line to prevent removing files that the application needs.
n/a

amus as of puppet-agent 1.10.10 and puppet-agent 5.3.4

omus in prior releases

SKIP_NSSM_REGISTRY_CLEANUP

 Setting to true skips the Non-Sucking Service Manager (NSSM) registry cleanup. This allows you to install in a restrictive User Account Control (UAC) context, or when the installer does not have the necessary permissions to read certain registry keys.
Note: This might cause a restart of DHCP Server or other services.
 n/a No value
To install the agent with the primary server at puppet.acme.com:
msiexec /qn /norestart /i puppet.msi PUPPET_SERVER=puppet.acme.com
To install the agent to a domain user ExampleCorp\bob:
msiexec /qn /norestart /i puppet-<VERSION>.msi PUPPET_AGENT_ACCOUNT_DOMAIN=ExampleCorp PUPPET_AGENT_ACCOUNT_USER=bob PUPPET_AGENT_ACCOUNT_PASSWORD=password

Upgrading or downgrading between 32-bit and 64-bit Puppet on Windows

If necessary, you can upgrade or downgrade between 32-bit and 64-bit Puppet on Windows nodes.

Upgrading to 64-bit

To upgrade from 32-bit to 64-bit Puppet, simply install 64-bit Puppet. You don't need to uninstall the 32-bit version first.

The installer specifically stores information in different areas of the registry to allow rolling back to the 32-bit agent.

Downgrading to 32-bit

If you need to replace a 64-bit version of Puppet with a 32-bit version, you must uninstall Puppet before installing the new package.

You can uninstall Puppet through the Add or Remove Programs interface or from the command line.

To uninstall Puppet from the command line, you must have the original MSI file or know the ProductCode of the installed MSI:

msiexec /qn /norestart /x puppet-agent-1.3.0-x64.msi
msiexec /qn /norestart /x <PRODUCT CODE>

When you uninstall Puppet, the uninstaller removes the Puppet program directory, agent services, and all related registry keys. It leaves the $confdir, $codedir, and $vardir intact, including any SSL keys. To completely remove Puppet from the system, manually delete these directories.

Install macOS agents

You can install macOS agents from Finder, the command line or Homebrew.

Important: For macOS agents, the certname is derived from the name of the machine (such as My-Example-Mac). To prevent installation issues, make sure the name of the node uses lowercases letters. If you don’t want to change your computer’s name, you can enter the agent certname in all lowercase letters when prompted by the installer.

Add full disk access for Puppet on macOS 10.14 and newer

Beginning with macOS 10.14, you must add Puppet to the full disk access list, or allowlist, in order to run Puppet with full permissions and for it to properly manage resources like user and group on your system.

Complete these steps before attempting to install macOS agents.
  1. Run the following command to remove the .sh extension from the wrapper.sh file: 
    mv /opt/puppetlabs/puppet/bin/wrapper.sh /opt/puppetlabs/puppet/bin/wrapper
  2. Run the following commands to relink facter, hiera, and puppet with the newly renamed file: 
    ln -sf /opt/puppetlabs/puppet/bin/wrapper /opt/puppetlabs/bin/facter
    ln -sf /opt/puppetlabs/puppet/bin/wrapper /opt/puppetlabs/bin/hiera
    ln -sf /opt/puppetlabs/puppet/bin/wrapper /opt/puppetlabs/bin/puppet
  3. In your Mac Preferences, click Security & Privacy, select the Privacy tab, and click Full Disk Access in the left column.
  4. Click the lock icon, enter your password, and click Unlock.
  5. Click the + button, then type the ⌘ (Command) + Shift + G shortcut key.
  6. Enter /opt/puppetlabs/bin, then click Go.
  7. Click on the puppet file, then click Open.

Install macOS agents from Finder

You can use Finder to install the agent on your macOS machine.

Before you begin
Download the appropriate agent tarball.
  1. Open the agent package .dmg and click the installer .pkg.
  2. Follow prompts in the installer dialog.
    You must include the primary server hostname and the agent certname.

Install macOS agents from the command line

You can use the command line to install the agent on a macOS machine.

Before you begin
Download the appropriate agent tarball.
  1. SSH into the node as a root or sudo user.
  2. Mount the disk image: sudo hdiutil mount <DMGFILE>

    A line appears ending with /Volumes/puppet-agent-VERSION. This directory location is the mount point for the virtual volume created from the disk image.

  3. Change to the directory indicated as the mount point in the previous step, for example: cd /Volumes/puppet-agent-VERSION
  4. Install the agent package: sudo installer -pkg puppet-agent-installer.pkg -target /
  5. Verify the installation: /opt/puppetlabs/bin/puppet --version

Install macOS agents with Homebrew

You can use Homebrew to install the agent on your macOS machine.

Before you begin
Install Homebrew.
Install the latest version of the Puppet agent: 
brew cask install puppetlabs/puppet/puppet-agent

Configure agents

Once you have installed your agents, you must complete the following three configuration steps.

1. Configure your PATH to access Puppet commands

Puppet's command line interface (CLI) consists of a single Puppet command with many subcommands, for example puppet --help.

Puppet commands are located in the bin directory — /opt/puppetlabs/bin/ on *nix and C:\Program Files\Puppet Labs\puppet\bin on Windows. The bin directory is not in your PATH environment variable by default. To have access to the Puppet commands, you must add the bin directory to your PATH.

Choose from the following options.

Linux: source a script for puppet-agent to install

If you are on Linux, you can source a script that puppet-agent installs. Run the following command:
source /etc/profile.d/puppet-agent.sh

*nix: Add the Puppet labs bin directory to your PATH

To add the bin directory to your PATH on *nix, run: 
export PATH=/opt/puppetlabs/bin:$PATH
Alternatively, you can add this location wherever you configure your PATH, such as your .profile or .bashrc configuration files.

Windows: Add the Puppet labs bin directory to your PATH

To run Puppet commands on Windows, start a command prompt with administrative privileges. You can do so by right-clicking the Start Command Prompts with Puppet program and clicking Run as administrator. Click Yes if the system asks for UAC confirmation.

The Puppet agent .msi adds the Puppet bin directory to the system path automatically. If you are not using the Start Command Prompts, you may need to manually add the bin directory to your PATH using one of the following commands:

For cmd.exe, run:
set PATH=%PATH%;"C:\Program Files\Puppet Labs\Puppet\bin"
For PowerShell, run:
 $env:PATH += ";C:\Program Files\Puppet Labs\Puppet\bin"

2. Configure the server setting

The server is setting, which allows you to connect the agent to the primary Puppet server, is the only mandatory setting.

You can add configuration to agents by using the puppet config set sub-command, which edits puppet.conf automatically, or editing /etc/puppetlabs/puppet/puppet.conf directly.

To configure the server setting, choose from one of the following options:
  • On the agent node, run:
    puppet config set server puppetserver.example.com --section main

  • Manually edit /etc/puppetlabs/puppet/puppet.conf or C:\ProgramData\PuppetLabs\puppet\etc\puppet.conf.

    Note that the location on Windows depends on whether you are running with administrative privileges. If you are not, it will be in home directory, not system location.

Results
This command adds the setting server = puppetserver.example.com to the [main] section of puppet.conf.

Note that there are other optional settings, for example, serverport, ca_server, ca_port, report_server, report_port, which you might need for more complicated Puppet deployments, such as when using a CA server and multiple compilers.

3. Connect the agent to the primary server and sign the certificate

Once you had added the server, you must connect the Puppet agent to the primary server so that it will check in at regular intervals to report its state, retrieve its catalog, and update its configuration if needed.

  1. To connect the agent to the primary server, run: 
    puppet ssl bootstrap
    Note: For Puppet 5 agents, run puppet agent --test instead.
    You will see a message that looks like:
    Info: Creating a new RSA SSL key for <agent node>
  2. On the primary server node, sign the certificate: 
    sudo puppetserver ca sign --certname <name>
  3. On the agent node, run the agent again: 
    puppet ssl bootstrap