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.
Install the agent using the command appropriate to
sudo yum install puppet-agent
sudo apt-get install puppet-agent
sudo zypper install puppet-agent
Start the Puppet
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.
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
- Run the installer as administrator.
- When prompted, provide the hostname of your master, 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||
||Hostname where the master can be reached.||
||Hostname where the CA master can be reached, if you're using multiple masters 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
msiexec /qn /norestart /i puppet.msi PUPPET_MASTER_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 or from the command line.
Download the appropriate agent tarball.
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 whitelist, 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 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.
- 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:
Configure the agent to connect to the master:
/opt/puppetlabs/bin/puppet config set server <MASTER_HOSTNAME>
Configure the agent certname:
/opt/puppetlabs/bin/puppet config set certname <AGENT_CERTNAME>
Adding executables to your
To run interactive Puppet commands, you must either add their location to
execute them using their full path.
The location for Puppet executables
/opt/puppetlabs/bin/, which is not in your
PATH environment variable by default.
PATHfor your current terminal session, run:
Alternatively, you can add this location wherever you configure your
PATH, such as your
Connect the agent to the master
Connect the agent to the master so that it will check in at regular intervals to report its state, retrieve its catalog, and update its configuration if needed.
On the agent node, make an initial connection to the master by doing one of the
You will see a message that looks like:
puppet agent --server <puppetmaster> --waitforcert 60 --test
server = <puppetserver>to the agent's
/etc/puppetlabs/puppet/puppet.conffile and run
puppet agent -t
Info: Creating a new RSA SSL key for <agent node>
On the master node, sign the certificate:
puppetserver ca sign <name>
On the agent node, run the agent:
puppet agent --server <puppetmaster> -t
Managing certificate signing requests on the command line
You can view, approve, and reject node requests using the command line.
$ sudo puppetserver ca list
$ sudo puppetserver ca sign <NAME>
$ sudo puppetserver ca sign (<HOSTNAME> or --all) --allow-dns-alt-names
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
For example, to point the agent at a master called
puppet config set server master.example.com. This command adds the
server = puppetmaster.example.com to the
[main] section of
To set the certname for the agent, run
/opt/puppetlabs/bin/puppet config set