Puppet agent on Windows

Puppet agent is the application that manages configurations on your nodes. It requires a Puppet primary server to fetch configuration catalogs.

For more information about invoking the Puppet agent command, see the >puppet agent man page.

Puppet agent's run environment

Puppet agent runs as a specific user, by default LocalSystem, and initiates outbound connections on port 8140.

Ports

By default, Puppet’s HTTPS traffic uses port 8140. Your operating system and firewall must allow Puppet agent to initiate outbound connections on this port.

If you want to use a non-default port, change the serverport setting on all agent nodes, and ensure that you change your Puppet primary server’s port as well.

User

Puppet agent runs as the LocalSystem user, which lets it manage the configuration of the entire system, but prevents it from accessing files on UNC shares.

Puppet agent can also run as a different user. You can change the user in the Service Control Manager (SCM). To start the SCM, click Start -> Run… and then enter Services.msc.

You can also specify a different user when installing Puppet. To do this, install using the CLI and specify the required MSI properties: PUPPET_AGENT_ACCOUNT_USER,PUPPET_AGENT_ACCOUNT_PASSWORD, and PUPPET_AGENT_ACCOUNT_DOMAIN.

Puppet agent’s user can be a local or domain user. If this user isn’t already a local administrator, the Puppet installer adds it to the Administrators group. The installer also grants Logon as Service to the user.

Managing systems with Puppet agent

In a normal Puppet configuration, every node periodically does configuration runs to revert unwanted changes and to pick up recent updates.

On Windows nodes, there are two main ways to do this:

Run Puppet as a service.: The easiest method. The Puppet agent service does configuration runs at a set interval, which can be configured.
Run Puppet agent on demand.: You can also use Bolt or deployMCollective to run on demand on many nodes.

Because the Windows version of the Puppet agent service is much simpler than the *nix version, there’s no real performance to be gained by running Puppet as a scheduled task. If you want scheduled configuration runs, use the Windows service.

Running Puppet agent as a service

The Puppet installer configures Puppet agent to run as a Windows service and starts it. No further action is needed. Puppet agent does configuration runs at a set interval.

Configuring the run interval

The Puppet agent service defaults to doing a configuration run every 30 minutes. If you don’t need frequent configuration runs, a longer run interval lets your Puppet primary servers handle many more agent nodes.

You can configure this with the runinterval setting in puppet.conf:

# C:\ProgramData\PuppetLabs\puppet\etc\puppet.conf
[agent]
  runinterval = 2h

After you change the run interval, the next run happens on the previous schedule, and subsequent runs happen on the new schedule.

Configuring the service start up type

The Puppet agent service defaults to starting automatically. If you want to start it manually or disable it, you can configure this during installation.

To do this, install using the CLI and specify the PUPPET_AGENT_STARTUP_MODE MSI property.

You can also configure this after installation with the Service Control Manager (SCM). To start the SCM, click Start -> Run... and enter Services.msc.

You can also configure agent service with the sc.exe command. To prevent the service from starting on boot, run the following command from the Command Prompt (cmd.exe):

sc config puppet start= demand

Important: The space after start= is mandatory and must be run in cmd.exe. This command won’t work from PowerShell.

To stop and restart the service, run the following commands:

sc stop puppet
sc start puppet

To change the arguments used when triggering a Puppet agent run, add flags to the command:

sc start puppet --debug --logdest eventlog

This example changes the level of detail that gets written to the Event Log.

Running Puppet agent on demand

Some sites prefer to run Puppet agent on demand, and others occasionally need to do an on-demand run.

You can start Puppet agent runs while logged in to the target system, or remotely with Bolt or MCollective.

While logged in to the target system

On Windows, log in as an administrator, and start the configuration run by selecting Start -> Run Puppet Agent. If Windows prompts for User Account Control confirmation, click Yes. The status result of the run is shown in a command prompt window.

Running other Puppet commands

To run other Puppet-related commands, start a command prompt with administrative privileges. You can do so by right-clicking the Command Prompt or Start Command Prompts with Puppet program and clicking Run as administrator. Click Yes if the system asks for UAC confirmation.

Remotely

Open source Puppet users can use Bolt to run tasks and commands on remote systems.

Alternatively, you can install MCollective and the puppet agent plugin to get similar capabilities, but Puppet doesn't provide standalone MCollective packages for Windows.

Important: As of Puppet agent 5.5.4, MCollective is deprecated and will be removed in a future version of Puppet agent. If you use Puppet Enterprise, consider migrating from MCollective to Puppet orchestrator. If you use open source Puppet, migrate MCollective agents and filters using tools like Bolt and the PuppetDB Puppet Query Language.

Disabling and re-enabling Puppet runs

Whether you’re troubleshooting errors, working in a maintenance window, or developing in a sandbox environment, you might need to temporarily disable the Puppet agent from running.

Start a command prompt with Run as administrator.
To disable the agent, run:
```
puppet agent --disable "<MESSAGE>"
```
To enable the agent, run:
```
puppet agent --enable
```

Configuring Puppet agent on Windows

The Puppet agent comes with a default configuration that you might want to change.

Configure Puppet agent with puppet.conf, using the [agent] section, the [main] section, or both. For more information on which settings are relevant to Puppet agent, see important settings.

Logging for Puppet agent on Windows systems

When running as a service, Puppet agent logs messages to the Windows Event Log. You can view its logs by browsing the Event Viewer. Click Control Panel -> System and Security -> Administrative Tools -> Event Viewer.

By default, Puppet logs to the Application event log. However, you can configure Puppet to log to a separate Puppet log instead.

To enable the Puppet log, create the requisite registry key by opening a command prompt and running one of the following commands:

Bash:

reg add HKLM\System\CurrentControlSet\Services\EventLog\Puppet\Puppet /v EventMessageFile /t REG_EXPAND_SZ /d "%SystemRoot%\System32\EventCreate.exe"

PowerShell and the New-EventLog cmdlet:

if ([System.Diagnostics.Eventlog]::SourceExists("puppet")) { Remove-EventLog -Source 'puppet' } & New-EventLog -Source puppet -LogName Puppet

Note that for agents older than 5.5.17 on the 5.5.x stream, 6.4.4 on the 6.4.x stream and 6.8.0 on the primary server stream, use the same Bash command listed above, but the following PowerShell command instead:

if ([System.Diagnostics.Eventlog]::SourceExists("puppet")) { Remove-EventLog -Source 'puppet' } & New-EventLog -Source puppet -LogName Puppet  -MessageResource "%SystemRoot%\System32\EventCreate.exe"

After you add the registry key, you need to reboot your machine for the logging to be redirected.

Note: If you are using an older version of Puppet, double check that you have the most up to date path to EventCreate.exe.

For existing agents, these commands can be placed in an exec resource to configure agents going forward.

Note: Any previously recorded event log messages are not moved; only new messages are recorded in the newly created Puppet log.

You can adjust how verbose the logs are with the log_level setting, which defaults to notice.

When running in the foreground with the --verbose, --debug, or --test options, Puppet agent logs directly to the terminal.

When started with the --logdest <FILE> option, Puppet agent logs to the file specified by <FILE>. Note that there are no file size checks for the --logdest <FILE> option.

Reporting for Puppet agent on Windows systems

In addition to local logging, Puppet agent submits a report to the primary server after each run. This can be disabled by setting report = false in puppet.conf.

Setting Puppet agent CPU priority

When CPU usage is high, lower the priority of the Puppet agent service by using the process priority setting, a cross platform configuration option. Process priority can also be set in the primary server configuration.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.