Want to improve your security posture? The 2019 State of DevOps Report tells you how.
Get the report

Installing agents

Open source Puppet 6.10

Expand menu Collapse menu
Open menu Close menu
  1. Install *nix agents
  2. Install Windows agents
    1. Install Windows agents with the .msi package
    2. MSI properties
    3. Upgrading or downgrading between 32-bit and 64-bit Puppet on Windows
  3. Install macOS agents
    1. Install macOS agents from Finder
    2. Install macOS agents from the command line
  4. Adding executables to your PATH
  5. Managing certificate signing requests on the command line
  6. Configuring agents

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

After installing agents, you must sign their certificates. For details, see Managing certificate signing requests on the command line

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
    • 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

Download the .msi package.

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 master.

  1. Run the installer as administrator.
  2. When prompted, provide the hostname of your master, 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_MASTER_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 DefinitionSetting 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

PUPPET_MASTER_SERVER Hostname where the master can be reached. server puppet
PUPPET_CA_SERVER Hostname where the CA master can be reached, if you're using multiple masters and only one of them is acting as the CA. ca_server Value of PUPPET_MASTER_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 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.

This property must be combined with PUPPET_AGENT_ACCOUNT_PASSWORD and PUPPET_AGENT_ACCOUNT_DOMAIN.

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

To install the agent with the master at puppet.acme.com:
msiexec /qn /norestart /i puppet.msi PUPPET_MASTER_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 or from the command line.

Before you begin

Download the appropriate agent tarball.

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.

Install macOS agents from Finder

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

  1. Open the agent package .dmg and click the installer .pkg.
  2. Follow prompts in the installer dialog.

    You must include the master 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.

  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
  6. Configure the agent to connect to the master: /opt/puppetlabs/bin/puppet config set server <MASTER_HOSTNAME>
  7. Configure the agent certname: /opt/puppetlabs/bin/puppet config set certname <AGENT_CERTNAME>

Adding executables to your PATH

To run interactive Puppet commands, you must either add their location to your PATH or execute them using their full path.

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

To add the executable location to your PATH for your current terminal session, 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.

Managing certificate signing requests on the command line

You can view, approve, and reject node requests using the command line.

To view pending node requests on the command line: 
$ sudo puppetserver ca list
To sign a pending request: 
$ sudo puppetserver ca sign <NAME>
To sign pending requests for nodes with DNS altnames: 
$ sudo puppetserver ca sign (<HOSTNAME> or --all) --allow-dns-alt-names

Configuring agents

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

For example, to point the agent at a master called master.example.com, run puppet config set server master.example.com. This command adds the setting server = puppetmaster.example.com to the [main] section of puppet.conf.

To set the certname for the agent, run /opt/puppetlabs/bin/puppet config set certname agent.example.com.

Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.