Install agents with the install script

You can use the install script for *nix, Windows, and macOS nodes. The install script installs and configures the agent on target nodes using installation packages from the Puppet Enterprise (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 declare on the primary server (in the console at Node Groups > PE Master > Classes).
  • Downloads a plug-in tarball from the primary server. This feature is controlled by the pe_repo::enable_bulk_pluginsync and pe_repo::enable_windows_bulk_pluginsync settings, which are set to true (enabled) by default.
    Note: Depending on how many modules you have installed, bulk plug-in sync can improve agent installation speed. However, if your primary server runs on a different platform than your agent nodes, bulk plug-in sync might be less beneficial. The plug-in tarball is based on the plug-ins running on the primary server's agent, which might not match the plug-ins required for agents on other platforms.
  • Creates a basic puppet.conf file containing the node's configuration settings. This file is stored at /etc/puppetlabs/puppet/puppet.conf.
  • Kicks off a Puppet run.

Use the install script

Before you begin: The agent node must have an internet connection to download the agent installer packages and plug-ins.

If you're installing an agent with a different OS than your primary server, you must declare the corresponding pe_repo class on the primary server, such as pe_repo::platform::el_7_x86_64. Declare these classes in the console at Node Groups > PE Master > Classes.

If your primary server is airgapped or uses a proxy server to access the internet, before installing agents, you must specify pe_repo::http_proxy_host and pe_repo::http_proxy_port in the PE Master node group's pe_repo class. For details, go to Download agent installation packages through a proxy.

  1. In the PE console, go to Nodes > Add nodes > Install agents.
  2. Under Manual installation, copy the command corresponding with your node's OS. You can use the *nix nodes script for *nix and macOS nodes.
  3. Launch the install script by running the command you copied. For Windows nodes, run the command in an administrative PowerShell window.
    Remember: If the install script can't find agent packages corresponding to the agent's OS, it fails with an error telling you which pe_repo::platform class you need to declare on the primary server (at Node Groups > PE Master > Classes).
  4. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  5. Accept the CSR as explained in Managing certificate signing requests.

Customize the install script

If necessary, you can use these options to modify the install script to define specific agent configuration settings, CSR attributes, or MSI properties. You can also control whether the Puppet service is running or enabled after agent installation.

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

puppet.conf settings

You can use the install script to specify agent configuration settings in the node's puppet.conf file, which is generated by the install script.

The Puppet Configuration Reference explains the configuration settings you can specify in puppet.conf and provides tips for successfully defining settings. Some commonly-specified settings include:
  • server
  • certname
  • environment
  • splay
  • splaylimit
  • noop

You can specify an unlimited number of settings in any order. In the install script command, use the section:key=value pattern to define each setting and leave one space between settings. In the *nix install script command, use -s to introduce the assortment of settings.

For example, for an Enterprise Linux system with a proxy between the agent and primary server, you can specify the http_proxy_host setting by adding the following code to the install script command:
-s agent:http_proxy_host=<PROXY_FQDN>
As another example, the following code specifies the splay, certname, and environment settings in the main and agent sections of the puppet.conf file: 
main:certname=node1.company.com \
agent:splay=true \
agent:environment=development
The puppet.conf file resulting from this code contains:
[main]
certname = node1.corp.net

[agent]
splay = true
environment = development
Tip: You can also edit node configuration settings after running the script by editing the puppet.conf file directly (at /etc/puppetlabs/puppet/puppet.conf) or using the puppet config set sub-command.

For example, to point an agent at a primary server called primary.example.com, run puppet config set server primary.example.com. This command adds server = primary.example.com to the [main] section of the node's puppet.conf file.

CSR attribute settings

Certificate signing request attribute settings are added to the node's puppet.conf file and are included in the custom_attributes and extension_requests sections of the csr_attributes.yaml file. The Puppet csr_attributes.yaml: Certificate extensions reference provides details about these settings.

You can specify an unlimited number of settings in any order. In the install script command, use the section:key=value pattern to define each setting and leave one space between settings. In the *nix install script command, use -s to introduce the assortment of settings.

For example, these commands specify agent and certificate signing settings:
-s main:certname=<CERTNAME_OTHER_THAN_FQDN> \
custom_attributes:challengePassword=<PASSWORD_FOR_AUTOSIGNER_SCRIPT> \
extension_requests:pp_role=<PUPPET_NODE_ROLE>
The above code adds the main:certname setting to the puppet.conf file and a csr_attributes.yaml file containing:
---
custom_attributes:
 challengePassword: <PASSWORD_FOR_AUTOSIGNER_SCRIPT>
extension_requests:
 pp_role: <PUPPET_NODE_ROLE>
Tip: If you can't run the install script, you can set CSR attributes by manually creating a csr_attributes.yaml file in the Puppet confdir (at C:\ProgramData\PuppetLabs\puppet\etc\csr_attributes.yaml) prior to installing the Puppet agent package with another agent installation method.

MSI properties (Windows only)

For the Windows install script, 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
For example, adding this code to the Windows install script runs the Puppet service as pup_adm with the defined password:
-PuppetAgentAccountUser ‘pup_adm’ -PuppetAgentAccountPassword ‘<PASSWORD>’ -PuppetAgentAccountDomain '<DOMAIN>'
Important: If you specify PUPPET_AGENT_ACCOUNT_USER, you must also specify PUPPET_AGENT_ACCOUNT_PASSWORD and PUPPET_AGENT_ACCOUNT_DOMAIN unless the node is under a gMSA.

For gMSAs, you must specify PUPPET_AGENT_ACCOUNT_USER (the user for the gMSA) and PUPPET_AGENT_ACCOUNT_DOMAIN. Do not specify PUPPET_AGENT_ACCOUNT_PASSWORD.

If you need to specify additional MSI properties, you might need to Install Windows agents with the .msi package.

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 the Puppet run, or you're using a provisioning system that requires non-default behavior, you can control whether the service is running or enabled.
  • ensure controls whether the Puppet service is running.
    • Accepts values of running or stopped.
    • *nix format: --puppet-service-ensure <VALUE>
    • Windows format: -PuppetServiceEnsure <VALUE>
  • enable controls whether the Puppet service is enabled.
    • Accepts values of true, false, mask, or manual (Windows only).
    • *nix format: --puppet-service-enable <VALUE>
    • Windows format: -PuppetServiceEnable <VALUE>
For example, to stop the Puppet service, ensure it doesn't boot after installation, and prevent a Puppet run from occurring after the agent is installed, include these settings in the *nix install script command: 
-s --puppet-service-ensure stopped --puppet-service-enable false
To do this in the Windows install script command, include:
-PuppetServiceEnsure stopped -PuppetServiceEnable false