- Install *nix agents
- Install Windows agents
- Install macOS agents
Adding executables to your
- Managing certificate signing requests on the command line
- 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.
- Install the agent using the command appropriate to your environment.
sudo yum install puppet-agent
sudo apt-get install puppet-agent
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.
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.
- Run the installer as administrator.
- 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.
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.
|Property||Definition||Setting in ||Default|
| ||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.|| ||Value of |
| || |
Node's certificate name, and the name it uses when requesting catalogs.
For best compatibility, limit the value of
| ||Value of |
| || Node's environment. |
Note: If a value for the
| || |
| ||Whether and how the agent service is allowed to run. Allowed values are: ||n/a|| |
| || |
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 may be 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.
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 example:
- 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 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.
PATHfor your current terminal session, run:
Alternatively, you can add this location wherever you configure your
PATH, such as your
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 setting
server = puppetmaster.example.com to the
[main] section of
To set the certname for the agent, run
/opt/puppetlabs/bin/puppet config set certname agent.example.com.