Installing agents

You can install Puppet Enterprise agents on *nix, Windows, and macOS.

To install FIPS-enabled PE agents, install the appropriate FIPS-enabled agent on a third party supported platform with FIPS mode enabled. You can use FIPS-enabled agents with a non-FIPS enabled primary server.

Agents are typically installed from a package repository hosted on your primary server. The PE package management repository is created during installation of the primary server and serves packages over HTTPS using the same port as the primary server (8140). This means agents don't require any new ports to be open other than the one they already need to communicate with the primary server.

Agent packages can be found on the primary server in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/. This directory contains the platform specific repository file structure for agent packages. For example, if your primary server is running on CentOS 7, in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/, there's a directory el-7-x86_64, which contains the directories with all the packages needed to install an agent.

After installing agents, you must sign their certificates.

Using the install script

The install script installs and configures the agent on target nodes using installation packages from the PE package management repo.

The agent install script performs these actions:

  • Detects the operating system on which it's running, sets up an APT, YUM, or zipper repo that refers back to the primary server, and then pulls down and installs the puppet-agent packages. If the install script can't find agent packages corresponding to the agent's platform, it fails with an error telling you which pe_repo class you need to add to the primary server.

  • Downloads a tarball of plugins from the primary server. This feature is controlled by the settings pe_repo::enable_bulk_pluginsync and pe_repo::enable_windows_bulk_pluginsync, which is set to true (enabled) by default. Depending on how many modules you have installed, bulk plug-in sync can speed agent installation significantly.
    Note: If your primary server runs in a different environment from your agent nodes, you might see some reduced benefit from bulk plug-in sync. The plug-in tarball is created based on the plug-ins running on the primary server agent, which might not match the plug-ins required for agents in a different environment.

  • Creates a basic puppet.conf file.

  • Kicks off a Puppet run.

Automatic downloading of agent installer packages and plugins using the pe_repo class requires an internet connection.
Tip: If your primary server uses a proxy server to access the internet, prior to installation, specify pe_repo::http_proxy_host and pe_repo::http_proxy_port in pe.conf, Hiera, or in the console, in the pe_repo class of the PE Master node group.

You can customize agent installation by providing as flags to the script any number of these options, in any order:

Option Example Result
puppet.conf settings 
main:certname=node1.corp.net
agent:splay=true
agent:environment=development
 The puppet.conf file looks like this: 
[main]
certname = node1.corp.net

[agent]
splay = true
environment = development
CSR attribute settings 
extension_requests:pp_role=webserver
custom_attributes:challengePassword=abc123
 The installer creates a csr_attributes.yaml file before installing with this content: 
---
custom_attributes:
 challengePassword: abc123
extension_requests:
 pp_role: webserver
MSI properties (Windows only) 
-PuppetAgentAccountUser ‘pup_adm’
-PuppetAgentAccountPassword ‘secret’
 The Puppet service runs as pup_adm with a password of secret.
Puppet service status
*nix: 
--puppet-service-ensure stopped
--puppet-service-enable false
Windows 
-PuppetServiceEnsure stopped
-PuppetServiceEnable false
 The Puppet service is stopped and doesn't boot after installation. An initial Puppet run doesn't occur after installation.

puppet.conf settings

You can specify any agent configuration option using the install script. Configuration settings are added to puppet.conf.

These are the most commonly specified agent config options:

  • server

  • certname

  • environment

  • splay

  • splaylimit

  • noop

Tip: On Enterprise Linux systems, if you have a proxy between the agent and the primary server, you can specify http_proxy_host , for example -s agent:http_proxy_host=<PROXY_FQDN>.

See the Configuration Reference for details.

CSR attribute settings

These settings are added to puppet.conf and included in the custom_attributes and extension_requests sections of csr_attributes.yaml.

You can pass as many parameters as needed. Follow the section:key=value pattern and leave one space between parameters.

See the csr_attributes.yaml reference for details.

*nix install script with example agent setup and certificate signing parameters: 
uri='https://primary.example.com:8140/packages/current/install.bash'

curl --insecure "$uri" | sudo bash -s main:certname=<CERTNAME OTHER THAN FQDN> custom_attributes:challengePassword=<PASSWORD_FOR_AUTOSIGNER_SCRIPT> extension_requests:pp_role=<PUPPET NODE ROLE>
Note: If you are unable to run the installation script, or install the MSI package with msiexec, you can set CSR attributes by creating a csr_attributes.yaml file in the Puppet confdir (default C:\ProgramData\PuppetLabs\puppet\etc\csr_attributes.yaml) prior to installing the Puppet agent package.

See Usage notes for curl examples for information about forming curl commands.

Windows install script with example agent setup and certificate signing parameters: 
[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PRIMARY_FQDN>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 main:certname=<certnameOtherThanFQDN> custom_attributes:challengePassword=<passwordForAutosignerScript> extension_requests:pp_role=<puppetNodeRole>

MSI properties (Windows)

For Windows, you can set these MSI properties, with or without additional agent configuration settings.

MSI Property PowerShell flag
INSTALLDIR -InstallDir
PUPPET_AGENT_ACCOUNT_USER -PuppetAgentAccountUser
PUPPET_AGENT_ACCOUNT_PASSWORD -PuppetAgentAccountPassword
PUPPET_AGENT_ACCOUNT_DOMAIN -PuppetAgentAccountDomain
Windows install script with MSI properties and agent configuration settings: 
[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PRIMARY_HOSTNAME>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 -PuppetAgentAccountUser "svcPuppet" -PuppetAgentAccountPassword "s3kr3t_P@ssword" agent:splay=true agent:environment=development

Puppet service status

By default, the install script starts the Puppet agent service and kicks off a Puppet run. If you want to manually trigger a Puppet run, or you're using a provisioning system that requires non-default behavior, you can control whether the service is running and enabled.

Option *nix Windows Values
ensure --puppet-service-ensure <VALUE> -PuppetServiceEnsure <VALUE>

  • running

  • stopped
enable --puppet-service-enable <VALUE> -PuppetServiceEnable <VALUE>

  • true

  • false

  • manual (Windows only)

  • mask
For example:
*nix 
uri='https://<PRIMARY_FQDN>:8140/packages/current/install.bash'

curl --insecure "$uri" | sudo bash -s -- --puppet-service-ensure stopped
Windows 
[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PRIMARY_FQDN>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 -PuppetServiceEnsure stopped

Install *nix agents

You have multiple options for installing *nix agents: from the console, from the command line using PE package management or your own package management, with or without internet access, and more. Chose the installation method that best suits your needs.

Note: You must enable TLSv1 to install agents on these platforms:

  • AIX

  • CentOS 5

  • RHEL 5

  • SLES 11

  • Solaris 10, 11

  • Windows Server 2008 R2

Install agents from the console

You can use the console to leverage tasks that install *nix or Windows agents on target nodes.

Before you begin

Add classes to the PE Master node group for each agent platform used in your environment. For example, pe_repo::platform::el_7_x86_64.

Make sure you have permission to run the appropriate task to install agents on all nodes:

  • *nix targets use the task pe_bootstrap::linux

  • Windows targets use the task pe_bootstrap::windows

For Windows targets, this task requires:
  • Windows 2008 SP2 or newer
  • PowerShell version 3 or higher
  • Microsoft .NET Framework 4.5 or higher
  1. In the console, on the Nodes page, click Add nodes.
  2. Click Install agents.
  3. Select a transport method.
    • SSH for *nix targets
    • WinRM for Windows targets
  4. Enter the target host names and the credentials required to access them. If you use an SSH key, include begin and end tags.
  5. Click Add nodes.
    Tip: Click Installation job started to view the job details for the task.
    Agents are installed on the target nodes and then automatically submit certificate signing requests (CSR) to the primary server. The list of unsigned certificates is updated with new targets.

Install *nix agents with PE package management

PE provides its own package management to help you install agents in your infrastructure.

Note: The <PRIMARY_HOSTNAME> portion of the installer script—as provided in the following example—refers to the FQDN of the primary server. The FQDN must be fully resolvable by the machine on which you're installing or upgrading the agent.
  1. If you're installing an agent with a different OS than the primary server, add the appropriate class for the repo that contains the agent packages.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
    2. On the Classes tab, enter pe_repo and select the repo class from the list of classes.
      Note: The repo classes are listed as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
    3. Click Add class, and commit changes.
    4. Run puppet agent -t to configure the primary server using the newly assigned class.

      The new repo is created in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.

  2. SSH into the node where you want to install the agent, and run the installation command appropriate to your environment.
    • Curl 
      uri='https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash'

curl --insecure "$uri" | sudo bash

      See Usage notes for curl examples for information about forming curl commands.

      Tip: On AIX versions 7.10 and earlier, which don't support the -k option, use --tlsv1 instead. If neither -k or --tlsv1 is supported, you must install using a manually transferred certificate.
    • RHEL 5 and CentOS 5 
      uri='https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash'

curl --insecure --tlsv1 "$uri" | sudo bash
    • wget 
      wget -O - -q --no-check-certificate https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash | sudo bash
    • Solaris 10 
      sudo export PATH=$PATH:/opt/sfw/bin
wget -O - -q --no-check-certificate --secure-protocol=TLSv1 https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash | bash

Install *nix agents with your own package management

If you choose not to use PE package management to install agents, you can use your own package management tools.

Before you begin

Download the appropriate agent tarball.

  1. Add the agent package to your own package management and distribution system.
  2. Configure the package manager on your agent node (YUM, APT) to point to that repo.
  3. Install the agent using the command appropriate to your environment.
    • YUM 
      sudo yum install puppet-agent
    • APT 
      sudo apt-get install puppet-agent

Install *nix agents using a manually transferred certificate

If you choose not to or can't use curl --insecure to trust the primary server during agent installation, you can manually transfer the primary server CA certificate to any machines you want to install agents on, and then run the installation script against that cert.

  1. On the machine that you're installing the agent on, create the directory /etc/puppetlabs/puppet/ssl/certs.
  2. On the primary server, navigate to /etc/puppetlabs/puppet/ssl/certs/ and transfer ca.pem to the certs directory you created on the agent node.
  3. On the agent node, verify file permissions: chmod 444 /etc/puppetlabs/puppet/ssl/certs/ca.pem
  4. Run the installation command, using the --cacert flag to point to the cert: 
    cacert='/etc/puppetlabs/puppet/ssl/certs/ca.pem'
uri='https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash'

curl --cacert "$cacert" "$uri" | sudo bash

    See Usage notes for curl examples for information about forming curl commands.

Install *nix agents without internet access

If you don't have access to the internet beyond your infrastructure, you can download the appropriate agent tarball from an internet-connected system and then install using the package management solution of your choice.

Install *nix agents with PE package management without internet access

Use PE package management to install agents when you don't have internet access beyond your infrastructure.

Before you begin

Download the appropriate agent tarball.

  1. On your primary server, copy the agent tarball to /opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-<AGENT_VERSION>, for example opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-5.5.17/
  2. If you're installing an agent with a different OS than the primary server, add the appropriate class for the repo that contains the agent packages.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
    2. On the Classes tab, enter pe_repo and select the repo class from the list of classes.
      Note: The repo classes are listed as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
    3. Click Add class, and commit changes.
  3. Run Puppet: puppet agent -t
  4. Follow the steps for Install *nix agents with PE package management.

Install *nix agents with your own package management without internet access

Use your own package management to install agents when you don't have internet access beyond your infrastructure.

Before you begin

Download the appropriate agent tarball.

  1. Add the agent package to your own package management and distribution system.
  2. Disable the PE-hosted repo.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
    2. On the Classes tab, find pe_repo class (as well as any class that begins pe_repo::), and click Remove this class.
    3. Commit changes.

Install *nix agents from compilers using your own package management without internet access

If your infrastructure relies on compilers to install agents, you don’t have to copy the agent package to each compiler. Instead, use the console to specify a path to the agent package on your package management server.

Before you begin

Download the appropriate agent tarball.

  1. Add the agent package to your own package management and distribution system.
  2. Set the base_path parameter of the pe_repo class to your package management server.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
    2. On the Classes tab, find the pe_repo class and specify the parameter.
      Parameter Value
      base_path FQDN of your package management server.
    3. Click Add parameter and commit changes.

Install Windows agents

You have multiple options for installing Windows agents: from the console, from a PowerShell window using PE package management, from the command line using an .msi package, and more. Chose the installation method that best suits your needs.

Note: You must enable TLSv1 to install agents on these platforms:

  • AIX

  • CentOS 5

  • RHEL 5

  • SLES 11

  • Solaris 10, 11

  • Windows Server 2008 R2

Install agents from the console

You can use the console to leverage tasks that install *nix or Windows agents on target nodes.

Before you begin

Add classes to the PE Master node group for each agent platform used in your environment. For example, pe_repo::platform::el_7_x86_64.

Make sure you have permission to run the appropriate task to install agents on all nodes:

  • *nix targets use the task pe_bootstrap::linux

  • Windows targets use the task pe_bootstrap::windows

For Windows targets, this task requires:
  • Windows 2008 SP2 or newer
  • PowerShell version 3 or higher
  • Microsoft .NET Framework 4.5 or higher
  1. In the console, on the Nodes page, click Add nodes.
  2. Click Install agents.
  3. Select a transport method.
    • SSH for *nix targets
    • WinRM for Windows targets
  4. Enter the target host names and the credentials required to access them. If you use an SSH key, include begin and end tags.
  5. Click Add nodes.
    Tip: Click Installation job started to view the job details for the task.
    Agents are installed on the target nodes and then automatically submit certificate signing requests (CSR) to the primary server. The list of unsigned certificates is updated with new targets.

Install Windows agents with PE package management

To install a Windows agent with PE package management, you use the pe_repo class to distribute an installation package to agents. You can use this method with or without internet access.

Before you begin
If your primary server doesn't have internet access, download the appropriate agent package and save it on your primary server in the location appropriate for your agent systems:

  • 32-bit systems — /opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-i386-<AGENT_VERSION>/

  • 64-bit systems — /opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-x86_64-<AGENT_VERSION>/

You must use PowerShell 2.0 or later to install Windows agents with PE package management.

Note: The <PRIMARY_HOSTNAME> portion of the installer script—as provided in the following example—refers to the FQDN of the primary server. The FQDN must be fully resolvable by the machine on which you're installing or upgrading the agent.
  1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
  2. On the Classes tab, type pe_repo and select the appropriate repo class from the list of classes.
    • 64-bit (x86_64) — pe_repo::platform::windows_x86_64.
    • 32-bit (i386) — pe_repo::platform::windows_i386.
  3. Click Add class and commit changes.
  4. On the primary server, run Puppet to configure the newly assigned class.

    The new repository is created on the primary server at /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.

  5. On the node, open an administrative PowerShell window, and install: 
    [System.Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; [Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PRIMARY_HOSTNAME>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 -v
    Microsoft Windows Server 2008r2 only: 
    [Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PRIMARY_HOSTNAME>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 -v
Results

After running the installer, you see the following output, which indicates the agent was successfully installed.

Notice: /Service[puppet]/ensure: ensure changed 'stopped' to 'running'
service { 'puppet':
  ensure => 'running',
  enable => 'true',
}

Install Windows agents using a manually transferred certificate

If you need to perform a secure installation on Windows nodes, you can manually transfer the primary server CA certificate to target nodes, and run a specialized installation script against that cert.

  1. Transfer the installation script and the CA certificate from your primary server to the node you're installing.
    File Location on primary server Location on target node
    Installation script (install.ps1) /opt/puppetlabs/server/data/packages/public/ Any accessible local directory.
    CA certificate (ca.pem) /etc/puppetlabs/puppet/ssl/certs/ C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\
  2. Run the installation script, using the -UsePuppetCA flag: .\install.ps1 -UsePuppetCA

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.

Tip: To install on nodes that don't have internet access, save the .msi package to the appropriate location for your system:

  • 32-bit systems — /opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-i386-<AGENT_VERSION>/

  • 64-bit systems — /opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-x86_64-<AGENT_VERSION>/

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 command line if you need to customize puppet.conf, CSR attributes, or certain agent properties.

On the command line of the node 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.
  • You can set CSR attributes by creating a csr_attributes.yaml file in the Puppet confdir (default C:\ProgramData\PuppetLabs\puppet\etc\csr_attributes.yaml) prior to installing the Puppet agent package.

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

PUPPET_SERVER Hostname where the primary server can be reached. server puppet
PUPPET_CA_SERVER Hostname where the CA primary server can be reached, if you're using multiple primary 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.

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

Windows agent installation details

Windows nodes can fetch configurations from a primary server and apply manifests locally, and respond to orchestration commands.

After installing a Windows node, the Start Menu contains a Puppet folder with shortcuts for running the agent manually, running Facter, and opening a command prompt for use with Puppet tools.
Note: You must run Puppet with elevated privileges. Select Run as administrator when opening the command prompt.

The agent runs as a Windows service. By default, the agent fetches and applies configurations every 30 minutes. The agent service can be started and stopped independently using either the service control manager UI or the command line sc.exe utility.

Puppet is automatically added to the machine's PATH environment variable, so you can open any command line and run puppet, facter and the other batch files that are in the bin directory of the Puppet installation. Items necessary for the Puppet environment are also added to the shell, but only for the duration of execution of each of the particular commands.

The installer includes Ruby, gems, and Facter. If you have existing copies of these applications, such as Ruby, they aren't affected by the re-distributed version included with Puppet.

Program directory

Unless overridden during installation, PE and its dependencies are installed in Program Files at \Puppet Labs\Puppet.

You can locate the Program Files directory using the PROGRAMFILES variable or the PROGRAMFILES(X86) variable.

The program directory contains these subdirectories.

Subdirectory Contents
bin scripts for running Puppet and Facter
facter Facter source
hiera Hiera source
misc resources
puppet Puppet source
service code to run the agent as a service
sys Ruby and other tools

Data directory

PE stores settings, manifests, and generated data — such as logs and catalogs — in the data directory. The data directory contains two subdirectories for the various components:

  • etc (the $confdir): Contains configuration files, manifests, certificates, and other important files.
  • var (the $vardir): Contains generated data and logs.

When you run Puppet with elevated privileges as intended, the data directory is located in the COMMON_APPDATA.aspx folder. This folder is typically located at C:\ProgramData\PuppetLabs\. Because the common app data directory is a system folder, it is hidden by default.

If you run Puppet without elevated privileges, it uses a .puppet directory in the current user's home folder as its data directory, which can result in unexpected settings.

Install macOS agents

You can install macOS agents with PE package management, from Finder, or from the command line.

To install macOS agents with PE package management, follow the steps to Install *nix agents with PE package management.

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.

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

macOS agent installation details

macOS agents include core Puppet functionality, plus platform-specific capabilities like package installation, service management with LaunchD, facts inventory with the System Profiler, and directory services integration.

Install non-root agents

Running agents without root privileges can assist teams using PE to work autonomously.

For example, your infrastructure’s platform might be maintained by one team with root privileges while your infrastructure’s applications are managed by a separate team (or teams) with diminished privileges. If the application team wants to be able to manage its part of the infrastructure independently, they can run Puppet without root privileges.

PE is installed with root privileges, so you need a root user to install and configure non-root access to a primary server. The root user who performs this installation can then set up non-root users on the primary server and any nodes running an agent.

Non-root users can perform a reduced set of management tasks, including configuring settings, configuring Facter external facts, running puppet agent --test, and running Puppet with non-privileged cron jobs or a similar scheduling service. Non-root users can also classify nodes by writing or editing manifests in the directories where they have write privileges.

Install non-root *nix agents

Note: Unless specified otherwise, perform these steps as a root user or as sudo.
  1. Install the agent on each node that you want to operate as a non-root user.
  2. Log in to the agent node and add the non-root user: 
    sudo puppet resource user <UNIQUE NON-ROOT USERNAME> ensure=present managehome=true
    Note: Each non-root user must have a unique name.
  3. Set the non-root user password.

    For example, on most *nix systems: passwd <USERNAME>

  4. Stop the puppet service: 
    sudo puppet resource service puppet ensure=stopped enable=false

    By default, the puppet service runs automatically as a root user, so it must be disabled.

  5. Disable the Puppet Execution Protocol agent.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Agent group.
    2. On the Classes tab, select the puppet_enterprise::profile::agent class, specify parameters, click Add parameter, and then commit changes.
      Parameter Value
      pxp_enabled false
  6. Change to the non-root user and generate a certificate signing request: 
    sudo puppet agent -t --certname "<UNIQUE NON-ROOT USERNAME.HOSTNAME>" --server "<PRIMARY_HOSTNAME>"
    Tip: If you wish to use su - <NON-ROOT USERNAME> to switch between accounts, make sure to use the - (-l in some unix variants) argument so that full login privileges are correctly granted. Otherwise you might see permission denied errors when trying to apply a catalog.
  7. On the primary server or in the console, approve the certificate signing request.
  8. On the agent node as the non-root user, set the node's certname and the primary server hostname, and then run Puppet. 
    sudo puppet config set certname <UNIQUE NON-ROOT USERNAME.HOSTNAME> --section agent
    sudo puppet config set server <PRIMARY_HOSTNAME> --section agent
    sudo puppet agent -t
    The configuration specified in the catalog is applied to the node.
    Tip: If you see Facter facts being created in the non-root user’s home directory, you have successfully created a functional non-root agent.
What to do next
To confirm that the non-root agent is correctly configured, verify that:

  • The agent can request certificates and apply the catalog from the primary server when a non-root user runs Puppet: puppet agent -t

  • The agent service is not running: service puppet status

  • Non-root users can collect existing facts by running facter on the agent, and they can define new, external facts.

Install non-root Windows agents

Note: Unless specified otherwise, perform these steps as a root user or as sudo.
  1. Install the agent on each node that you want to operate as a non-root user.
  2. Log in to the agent node and add the non-root user: 
    sudo puppet resource user <UNIQUE NON-ADMIN USERNAME> ensure=present managehome=true password="puppet" groups="Users"
    Note: Each non-root user must have a unique name.
  3. Stop the puppet service: 
    sudo puppet resource service puppet ensure=stopped enable=false

    By default, the puppet service runs automatically as a root user, so it must be disabled.

  4. Change to the non-root user and generate a certificate signing request: 
    puppet agent -t --certname "<UNIQUE NON-ADMIN USERNAME>" --server "<PRIMARY_HOSTNAME>"
    Important: This Puppet run submits a cert request to the primary server and creates a /.puppet directory structure in the non-root user’s home directory. If this directory is not created automatically, you must manually create it before continuing.
  5. As the non-root user, create a configuration file at %USERPROFILE%/.puppet/puppet.conf to specify the agent certname and the hostname of the primary server: 
    [main]
certname = <UNIQUE NON-ADMIN USERNAME.hostname>
server = <PRIMARY_HOSTNAME>
  6. As the non-root user, submit a cert request: puppet agent -t.
  7. On the primary server or in the console, approve the certificate signing request.
    Important: It's possible to sign the root user certificate in order to allow that user to also manage the node. However, this introduces the possibility of unwanted behavior and security issues. For example, if your site.pp has no default node configuration, running the agent as non-admin could lead to unwanted node definitions getting generated using alt hostnames, a potential security issue. If you deploy this scenario, ensure the root and non-root users never try to manage the same resources, have clear-cut node definitions, ensure that classes scope correctly, and so forth.
  8. On the agent node as the non-root user, run Puppet: puppet agent -t.

    The configuration specified in the catalog is applied to the node.

Non-root user functionality

Non-root users can use a subset of functionality. Any operation that requires root privileges, such as installing system packages, can't be managed by a non-root agent.

*nix non-root functionality

On *nix systems, as non-root agent you can enforce these resource types:

  • cron (only non-root cron jobs can be viewed or set)
  • exec (cannot run as another user or group)
  • file (only if the non-root user has read/write privileges)
  • notify
  • schedule
  • ssh_key
  • ssh_authorized_key
  • service
  • augeas
Note: When running a cron job as non-root user, using the -u flag to set a user with root privileges causes the job to fail, resulting in this error message: 
 Notice: /Stage[main]/Main/Node[nonrootuser]/Cron[illegal_action]/ensure: created must be privileged to use -u
You can also inspect these resource types (use puppet resource <resource type>):
  • host
  • mount
  • package

Windows non-root functionality

On Windows systems as non-admin user, you can enforce these types :

  • exec
  • file
Note: A non-root agent on Windows is extremely limited as compared to non-root *nix. While you can use the above resources, you are limited on usage based on what the agent user has access to do (which isn't much). For instance, you can't create a file\directory in C:\Windows unless your user has permission to do so.

You can also inspect these resource types (use puppet resource <resource type>):

  • host
  • package
  • user
  • group
  • service

Managing certificate signing requests

When you install a Puppet agent on a node, the agent automatically submits a certificate signing request (CSR) to the primary server. You must accept this request to bring before the node under PE management can be added your deployment. This allows Puppet to run on the node and enforce your configuration, which in turn adds node information to PuppetDB and makes the node available throughout the console.

You can approve certificate requests from the PE console or the command line. If DNS altnames are set up for agent nodes, you must approve the CSRs on use the command line interface .

Note: Specific user permissions are required to manage certificate requests:
  • To accept or reject CSRs in the console or on the command line, you need the permission Certificate requests: Accept and reject.
  • To manage certificate requests in the console, you also need the permission Console: View.

Managing certificate signing requests in the console

A certificate signing request appears in the console on the Certificates page in the Unsigned certificates tab after you add an agent node to inventory. Accept or reject submitted requests individually or in a batch.

  • To manage requests individually, click Accept or Reject.
  • To manage the entire list of requests, click Accept All or Reject All. Nodes are processed in batches. If you close the browser window or navigate to another website while processing is in progress, only the current batch is processed.

After you accept the certificate signing request, the node appears in the console after the next Puppet run. To make a node available immediately after you approve the request, run Puppet on demand.

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 --certname <NAME>
Note: You can use the Puppet Server CA CLI to sign certificates with altnames or auth extensions by default.

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 primary server called primary.example.com, run puppet config set server primary.example.com. This command adds the setting server = primary.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.