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 *nix agents
You can install *nix agents using an install script.
Install the agent using the command appropriate to
sudo yum install puppet-agent
sudo apt-get install puppet-agentNote: The Puppet repository for the APT package management system is: http://apt.puppetlabs.com/
sudo zypper install puppet-agent
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.
Install Windows agents with the installer
Use the MSI installer for a more automated installation process. The installer can
puppet.conf, create CSR attributes, and configure the agent
to talk to your primary server.
- Run the installer as administrator.
- When prompted, provide the hostname of your primary server, for example puppet.
Install Windows agents using
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.
msiexec /qn /norestart /i <PACKAGE_NAME>.msi
/l*v install.txtto log the progress of the installation to a file.
If you install Windows agents from the command line using the .msi package, you can optionally specify these properties.
PUPPET_AGENT_ENVIRONMENT, the installer replaces the existing value in
puppet.confand 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.
||Location to install Puppet and its dependencies.||n/a||
||Long filename support. Set to
||Hostname where the primary server can be reached.||
||Hostname where the CA server can be reached, if you're using multiple servers and only one of them is acting as the CA.||
Node's certificate name, and the name it uses when requesting catalogs.
For best compatibility, limit the value of
|| Node's environment.
Note: If a value for the
||Whether and how the agent service is allowed to
run. Allowed values are:
Windows user account the agent
service uses. This property is useful if the agent needs to
access files on UNC shares, because the default
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
This property must be combined with
||Password for the agent's user account.||n/a||No Value|
||Domain of the agent's user account.||n/a||
||A default MSI property used to control the
behavior of file copies during installation.
Important: If you need to downgrade agents, use
amus as of puppet-agent 1.10.10 and puppet-agent 5.3.4
omus in prior releases
||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.
msiexec /qn /norestart /i puppet.msi PUPPET_SERVER=puppet.acme.com
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.
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
group on your system.
Run the following command to remove the
.shextension from the
mv /opt/puppetlabs/puppet/bin/wrapper.sh /opt/puppetlabs/puppet/bin/wrapper
Run the following commands to relink facter, hiera, and puppet with the newly
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
- In your Mac Preferences, click Security & Privacy, select the Privacy tab, and click Full Disk Access in the left column.
- Click the lock icon, enter your password, and click Unlock.
- Click the + button, then type the ⌘ (Command) + Shift + G shortcut key.
/opt/puppetlabs/bin, then click Go.
- 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.
- Open the agent package .dmg and click the installer .pkg.
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.
- SSH into the node as a root or sudo user.
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.
Change to the directory indicated as the mount point in the previous step, for
Install the agent package:
sudo installer -pkg puppet-agent-installer.pkg -target /
Verify the installation:
Install macOS agents with Homebrew
You can use Homebrew to install the agent on your macOS machine.
brew cask install puppetlabs/puppet/puppet-agent
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 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
Choose from the following options.
Linux: source a script for puppet-agent to install
puppet-agentinstalls. Run the following command:
*nix: Add the Puppet labs bin directory to your PATH
PATHon *nix, run:
Alternatively, you can add this location wherever you configure your
PATH, such as your
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
set PATH=%PATH%;"C:\Program Files\Puppet Labs\Puppet\bin"
$env:PATH += ";C:\Program Files\Puppet Labs\Puppet\bin"
2. Configure 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
set sub-command, which edits puppet.conf automatically, or editing
serversetting, choose from one of the following options:
On the agent node, run:
puppet config set server puppetserver.example.com --section main
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.
server = puppetserver.example.comto the
[main]section of puppet.conf.
Note that there are other optional settings, for example,
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.
To connect the agent to the primary server, run:
puppet ssl bootstrapNote: For Puppet 5 agents, run
puppet agent --testinstead.You will see a message that looks like:
Info: Creating a new RSA SSL key for <agent node>
On the primary server node, sign the certificate:
sudo puppetserver ca sign --certname <name>
On the agent node, run the agent again:
puppet ssl bootstrap