Puppet agent on Windows
Puppet agent is the application that manages configurations on your nodes. It requires a Puppet master server to fetch configuration catalogs from.
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 masterport
setting on all agent
nodes, and ensure that you change your Puppet master’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.
- 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 deploy MCollective to run on demand on many nodes.
Since 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.
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.
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
start=
is mandatory and must be run in
cmd.exe. This command won’t work from PowerShell.sc stop puppet
sc start puppet
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 will be 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.
Disabling and re-enabling Puppet runs
Whether you’re troubleshooting errors, working in a maintenance window, or developing in a sandbox environment, you may need to temporarily disable the Puppet agent from running.
Configuring Puppet agent on Windows
The Puppet agent comes with a default configuration that may not be the most convenient for you.
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 "C:\Program Files\Puppet Labs\Puppet\puppet\bin\puppetres.dll"
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, 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 "C:\Program Files\Puppet Labs\Puppet\puppet\bin\puppetres.dll"
After you add the registry key, you need to reboot your machine for the logging to be redirected.
puppetres.dll
.For existing agents, these commands can be placed in an exec resource to configure agents going forward.
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>
.
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.