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

 

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