Install Windows agents

There are many ways you can install agents on Windows nodes, including PowerShell scripts, the Puppet Enterprise (PE) console, the MSI installer, and the msiexec command.

We recommend you Install agents with the install script or Install agents from the console whenever possible, and we've described other cases here for your reference. For non-root agents, refer to Install non-root Windows agents.

Install Windows agents with PE package management

Puppet Enterprise (PE) provides its own package management to help you install agents on Windows nodes. 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 tarball and save it to the appropriate agent package directory on your primary server.
  • For 32-bit systems, save the tarball at \opt\puppetlabs\server\data\packages\public\<PE_VERSION>\windows-i386-<AGENT_VERSION>\
  • For 64-bit systems, save the tarball at \opt\puppetlabs\server\data\packages\public\<PE_VERSION>\windows-x86_64-<AGENT_VERSION>\
These commands modify the standard agent install script for specific platforms or airgapped environments. If you do not have a specific need for these commands, we recommend you Install agents with the install script.
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. On the agent node, open an administrative PowerShell window, and run the appropriate agent install script command:
    For Microsoft Windows Server 2008r2: 
    [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
    For all other Windows platforms:
    [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
    After running the install script, the following output indicates the agent was installed successfully:
    Notice: /Service[puppet]/ensure: ensure changed 'stopped' to 'running'
service { 'puppet':
  ensure => 'running',
  enable => 'true',
}
  2. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  3. Accept the CSR as explained in Managing certificate signing requests.

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 any Windows machines you want to install agents on, and then run a variation of the agent install script against that cert.

  1. Transfer the CA certificate:
    1. On the machine where you want to install the agent, create this directory: C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\'
    2. On the primary server, navigate to: \etc\puppetlabs\puppet\ssl\certs\
    3. Copy ca.pem to the certs directory you created on the agent node.
  2. Transfer the agent install script:
    1. On the primary server, navigate to: \opt\puppetlabs\server\data\packages\public\
    2. Copy install.ps1 to any accessible local directory on the agent node.
  3. In an administrative PowerShell window, run the install script with the -UsePuppetCA flag: .\install.ps1 -UsePuppetCA
  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.

Install Windows agents with the .msi package

You can use the Windows MSI installer or the msiexec command to install the agent .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 appropriate agent .msi package.
To install agents on Windows nodes without internet access, save the .msi package to the appropriate agent package directory:
  • For 32-bit systems, save the package at \opt\puppetlabs\server\data\packages\public\<PE_VERSION>\windows-i386-<AGENT_VERSION>\
  • For 64-bit systems, save the package at \opt\puppetlabs\server\data\packages\public\<PE_VERSION>\windows-x86_64-<AGENT_VERSION>\

Install Windows agents with the MSI installer

Use the MSI installer for an automated installation process. The installer can configure puppet.conf, configure CSR attributes, and connect the agent to your primary server.

  1. Run the MSI installer as administrator.
  2. When prompted, provide your primary server's hostname, for example puppet.company.com.
  3. Once the agent is installed, you must accept the node's CSR as explained in Managing certificate signing requests.

Install Windows agents using msiexec from the command line

You can install the .msi package manually from the command line if you need to customize puppet.conf, CSR attributes, or certain agent properties.

If you Install agents with the install script (with PowerShell), you can Customize the install script by specifying CSR attribute settings and some MSI properties. The msiexec command does not require PowerShell and allows you to specify more MSI properties.

  1. Identify the MSI properties you want to include in the msiexec command and prepare the syntax for those properties.
  2. If you need to set CSR attributes, create 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.
    Customize the install script explains how to specify CSR attribute settings.
  3. To log installation progress to an install.txt log file, include /l*v install.txt in your msiexec command.
  4. On the command line of the node where you want to install the agent, run your msiexec command.
    The basic command is:
    msiexec /qn /norestart /i <PACKAGE_NAME>.msi
    Your command likely includes additional arguments, such as /l*v, PUPPET_AGENT_CERTNAME, or any other valid MSI properties. For example, this msiexec command installs the agent with a primary server located at puppet.acme.com:
    msiexec /qn /norestart /i <PACKAGE_NAME>.msi PUPPET_SERVER=puppet.acme.com
    This msiexec command installs the agent to a domain user account called bob on the ExampleCorp domain with the account password of password:
    msiexec /qn /norestart /i <PACKAGE_NAME>.msi PUPPET_AGENT_ACCOUNT_DOMAIN=ExampleCorp PUPPET_AGENT_ACCOUNT_USER=bob PUPPET_AGENT_ACCOUNT_PASSWORD=password
  5. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  6. Accept the CSR as explained in Managing certificate signing requests.

MSI properties

You can use these MSI properties if you install Windows agents with the msiexec command.

Important: The following MSI properties define puppet.conf settings:
  • PUPPET_SERVER corresponds with server
  • PUPPET_CA_SERVER corresponds with ca_server
  • PUPPET_AGENT_CERTNAME corresponds with certname
  • PUPPET_AGENT_ENVIRONMENT corresponds with environment

If you use msiexec to specify a non-default value for these properties, the installer replaces the default value in puppet.conf and re-uses your specified value at upgrade. Therefore, if you need to change these properties after setting them with msiexec, don't change them directly in puppet.conf; instead, you need to re-run the installer and set a new value.

Customize the install script provides more details on puppet.conf settings.

Property Definition Default value
INSTALLDIR Location to install Puppet and its dependencies.

For 32-bit systems: C:\Program Files\Puppet Labs\Puppet

For 64-bit systems: C:\Program Files \Puppet Labs\Puppet
PUPPET_SERVER Hostname where the primary server can be reached. 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. Value of PUPPET_SERVER
PUPPET_AGENT_CERTNAME The agent node's certificate name and the name it uses when requesting catalogs.
Important: Only use lowercase letters, numbers, periods, underscores, and dashes.
 Value of facter fdqn
PUPPET_AGENT_ENVIRONMENT The agent node's environment.
Important: If the node already has a puppet.conf file containing a value for the environment variable, specifying it during installation doesn't override that value.
 production
PUPPET_AGENT_STARTUP_MODE Whether and how the agent service is allowed to run. Allowed values are:
  • Automatic: The agent service when Windows starts and remains running in the background.
  • Manual: The agent service can be started in the services console or with net start on the command line.
  • Disabled: The agent service is installed but disabled. You must change its startup type in the services console before you can start the service.
 Automatic
PUPPET_AGENT_ACCOUNT_USER

The Windows user account the agent service uses.

Use this property when 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.
  • Grants Logon as Service to the user.
  • Add the user to the Administrators group, if the user isn't already a local administrator.
Important: If you specify this property, you must also specify PUPPET_AGENT_ACCOUNT_PASSWORD and PUPPET_AGENT_ACCOUNT_DOMAIN unless the node is under a gMSA.

For gMSAs, you must also specify PUPPET_AGENT_ACCOUNT_DOMAIN, but do not specify PUPPET_AGENT_ACCOUNT_PASSWORD.

 LocalSystem
PUPPET_AGENT_ACCOUNT_PASSWORD Password for the agent's user account.

Do not specify this property for nodes running under gMSAs.

 No value
PUPPET_AGENT_ACCOUNT_DOMAIN Domain of the agent's user account. .
REINSTALLMODE A default MSI property that controls file copy behavior during installation.
Important: If you need to downgrade agents, use REINSTALLMODE=amus when calling msiexec.exe at the command line to prevent removing required files.

From puppet-agent version 1.10.10 and 5.3.4: amus

Prior releases: omus

About Windows agents

Windows nodes can fetch configurations from the 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 to use Puppet tools.
Remember: 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 Puppet installation's bin directory. Items necessary for the Puppet environment are also added to the shell, but only for the duration of each command's execution.

The installer includes Ruby, 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 files 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 files 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:
  • 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, the data directory is located in the COMMON_APPDATA.aspx directory. This direcotry is typically located at C:\ProgramData\PuppetLabs\. Because the COMMAN_APPDATA.aspx 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 directory as its data directory, which can result in unexpected settings. We recommend always running Puppet with elevated privileges, unless otherwise specified for specific scenarios.