Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Installing Grey arrow pointing right Installing agents Grey arrow pointing right Install Windows agents Grey arrow pointing right

Install Windows agents

Sections

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>/
Client URL (curl) and World Wide Web Get (Wget) commands can be used to download PE repo tarballs from PE’s private repository. These commands modify the standard agent install script for specific platforms or air-gapped environments. These commands modify the standard agent install script for specific platforms or air-gapped environments. If you do not have a specific need for these commands, follow the procedure in Install agents with the install script.

Authentication credentials

Because Puppet Enterprise agent packages are stored in a private repository, you must authenticate to access and download the packages.

Use the string literal license-id as your username and use your PE License ID as the password. You can find your PE License ID in your PE license file or in the PE console by selecting License in the navigation bar.
Note: If your PE License ID is not present in your license, please Contact our sales team.

Authentication procedures

You can use either of the following procedures to authenticate:

  • Create and configure a .netrc file
  • Export credentials to environment variables
Create and configure a .netrc file

A .netrc file is a configuration file used by many command-line tools and programs, including curl, FTP, and Git. The primary purpose of the file is to store login credentials.

Complete the following steps to create and configure a .netrc file:
  1. Create a file named .netrc by running the following commands:
    touch ~/.netrc  
chmod 600 ~/.netrc Copied!
  2. Edit the file to add your credentials, where license-id is a string literal and <PE_License_ID> is your PE License ID: 
    machine artifacts-puppetcore.puppet.com   
  login license-id  
  password <PE_License_ID>Copied!
  3. Run a command with the --netrc option so that the credentials stored in the .netrc  file are used for authentication, as shown in the following example: 
curl --netrc 'https://artifacts-puppetcore.puppet.com/v1/download?version=8.11.0&type=perepo&os_name=el&os_version=9&os_arch=x86_64' -J -OCopied!
Export credentials to environment variables

You can directly curl the endpoints with credentials by completing the following steps:

  1. Export the credentials, where license-id is a string literal and  <PE_License_ID> is your PE License ID: 
    export USERNAME=license-id 
export PASSWORD=<PE_License_ID>Copied!
  2. Call the credentials from the URL, as shown in the following example: 
    curl -u $USERNAME:$PASSWORD 'https://artifacts-puppetcore.puppet.com/v1/download?version=8.11.0&type=perepo&os_name=el&os_version=9&os_arch=x86_64' -J -OCopied!
Request parameters

The following request parameters are accepted by the artifact download endpoint.

Note: To directly copy URLs and download agent and agent repo, see puppet releases.
Name Type Default Example Description
version String None 11 The package version.
os_name String None windows The name of the operating system.
os_version String None 11 The operating system version.
os_arch String None x64 The operating system architecture.
Content disposition

Content disposition is enabled for these packages and can be used while downloading packages to store them with their default name. Use –J –O only with curl. For wget, use the following structure: 

wget --content-disposition <URL>Copied!
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 2022:
    [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
Copied!
    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
Copied!
    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',
}Copied!
  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>.msiCopied!
    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.comCopied!
    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=passwordCopied!
  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.

Was this page helpful?