Puppet agent is the application that manages configurations on your nodes. It requires a Puppet master 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.
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
setting on all agent nodes, and ensure that you change your Puppet master’s port as well.
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’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.
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 master servers handle many more agent nodes.
# 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
You can also configure this after installation with the Service Control Manager (SCM). To start the SCM, click Start -> Run... and enter Services.msc.
sc.execommand. To prevent the service from starting on boot, run the following command from the Command Prompt (
sc config puppet start= demand
start=is mandatory and must be run in cmd.exe. This command won’t work from PowerShell.
sc stop puppet sc start puppet
This example changes the level of detail that gets written to the Event Log.
sc start puppet --debug --logdest eventlog
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.
Open source Puppet users can use Bolt to run tasks and commands on remote systems.
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.
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.
reg add HKLM\System\CurrentControlSet\Services\EventLog\Puppet\Puppet /v EventMessageFile /t REG_EXPAND_SZ /d "C:\Program Files\Puppet Labs\Puppet\puppet\bin\puppetres.dll"
New-EventLogcmdlet to do the same thing:
New-EventLog -Source puppet -LogName Puppet -MessageResource "C:\Program Files\Puppet Labs\Puppet\puppet\bin\puppetres.dll"
You can adjust how verbose the logs are with the
log_level setting, which defaults to
When running in the foreground with the
options, Puppet agent logs directly to the
When started with the
--logdest <FILE> option, Puppet agent logs to the file specified by
Reporting for Puppet agent on Windows systems
In addition to local logging, Puppet agent submits a report to the
Puppet master 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 Puppet master configuration.