For details about invoking the Puppet agent command, see the puppet agent man page.
This page describes how Puppet agent behaves on *nix systems. For information about Windows, see Puppet Agent on Windows Systems.
Not all operating systems can manage the same resources with Puppet; some resource types are OS-specific, and others may have OS-specific features. See the [resource type reference] for details.
Puppet Agent’s Run Environment
Puppet agent runs as a specific user (usually
root) and initiates outbound connections on port 8140.
By default, Puppet agent runs as
root, which lets it manage the configuration of the entire system.
Puppet agent can also run as a non-root user, as long as it is started by that user. This will restrict the resources that Puppet agent can manage (see below), and requires you to run Puppet agent via a cron job instead of a service.
Resource Types For Non-Root Puppet Agents
When running without root permissions, most of Puppet’s resource providers cannot use
sudo to elevate permissions. This means Puppet can only manage resources that its user can modify without using
Out of the core resource types listed in the [resource type reference], the following are available to non-root agents:
cron(only non-root cron jobs can be viewed or set)
exec(cannot run as another user or group)
file(only if the non-root user has read/write privileges)
service(for services that don’t require root; you can also use the
statusattributes to specify how non-root users should control the service)
If you need to install packages into a directory controlled by a non-root user, you can either use an
exec to unzip a tarball or use a recursive
file resource to copy a directory into place.
By default, Puppet’s HTTPS traffic uses port 8140. Your OS and firewall must allow Puppet agent to initiate outbound connections on this port.
If you want to use a non-default port, you’ll have to change the
masterport setting on all agent nodes, and ensure that you’ve changed your Puppet master’s port as well.
If you are using the deprecated
listen feature, Puppet agent will also need to listen for incoming connections on port 8139. (Configurable with
When running as a service, Puppet agent logs messages to syslog. Your syslog configuration dictates where these messages will be saved, but the default location is
/var/log/messages on Linux,
/var/log/system.log on Mac OS X, and
/var/adm/messages on Solaris.
When running in the foreground with the
--test options, Puppet agent logs directly to the terminal instead of to syslog.
When started with the
--logdest <FILE> option, Puppet agent logs to the file specified by
In Puppet Enterprise, you can browse these reports in the PE console’s node pages, and you can analyze correlated events with the PE event inspector.
Managing Systems With Puppet Agent
In a normal Puppet site, every node should periodically do configuration runs, to revert unwanted changes and to pick up recent updates.
On *nix nodes, there are three main ways to do this:
- Run Puppet agent as a service. The easiest method. The Puppet agent daemon will do configuration runs at a set interval, which can be configured.
- Make a cron job that runs Puppet agent. Requires more manual configuration, but a good choice if you want to reduce the number of persistent processes on your systems. (This was more important in the past, but some versions of Ruby may still have performance and memory use issues with long-lived daemons.)
- Only run Puppet agent on demand. To trigger runs on groups of systems, you can use Puppet Enterprise’s built-in orchestration features. (Open source users can also deploy MCollective.)
Choose whichever one works best for your infrastructure and culture.
Running Puppet Agent as a Service
The Puppet agent command can start a long-lived daemon process, which will do configuration runs at a set interval.
Note: If you are running Puppet agent as a non-root user, you should use a cron job instead.
Starting the Service
The best way to do this is with Puppet agent’s init script / service configuration. If you installed Puppet with packages, they should have included an init script or service configuration for controlling Puppet agent, usually with the service name
puppet (open source) or
pe-puppet (Puppet Enterprise).
In Puppet Enterprise, the agent service is automatically configured and started; you don’t need to manually start it.
In open source Puppet, you can enable the service with:
$ sudo puppet resource service puppet ensure=running enable=true
Alternately, you can run
sudo puppet agent on the command line with no additional options; this will cause Puppet agent to start running and daemonize, but you won’t have an easy interface for restarting or stopping it. To stop the daemon, use the process ID from the agent’s
$ sudo kill $(puppet config print pidfile --section agent)
Configuring the Run Interval
# /etc/puppet/puppet.conf [agent] runinterval = 2h
If you don’t need an aggressive schedule of configuration runs, a longer run interval will let your Puppet master server(s) handle many more agent nodes.
Running Puppet Agent as a Cron Job
onetime setting is set to
true, the Puppet agent command will do one configuration run and then quit. If the
daemonize setting is set to
false, the command will stay in the foreground until the run is finished; if set to
true, it will do the run in the background.
This behavior is good for building a cron job that does configuration runs. You may also want to use the
splaylimit settings to keep the Puppet master from getting overwhelmed, since the system time is probably synchronized on all of your agent nodes.
You can use the Puppet resource command to set up this cron job. Below is an example that runs Puppet once an hour; adjust the path to the Puppet command if you are not using Puppet Enterprise.
$ sudo puppet resource cron puppet-agent ensure=present user=root minute=30 command='/opt/puppet/bin/puppet agent --onetime --no-daemonize --splay --splaylimit 60'
Running Puppet Agent On Demand
Some sites prefer to only run Puppet agent on demand; others use scheduled runs, but occasionally need to do an on-demand run.
Puppet agent runs can be started locally (while logged in to the target system), or remotely via an orchestration tool.
While Logged in to the Target System
If you are currently logged into the machine that needs to run Puppet agent, you can do one of the following:
Run in the foreground, with verbose logging to the terminal:
$ sudo puppet agent --test
Run once in the background:
$ sudo puppet agent --onetime
Note that this won’t notify you when the run is completed.
To run Puppet agent remotely on one machine, you can simply use ssh:
$ ssh [email protected] sudo puppet agent --test
To run remotely on many machines, you will need some form of orchestration or parallel execution tool.
Puppet Enterprise has built-in tools for this. For info, see the Puppet Enterprise manual page on triggering Puppet runs.
For open source Puppet users, the most flexible tool is MCollective, which is somewhat heavyweight to deploy but has many other uses. You’ll need to deploy MCollective and the puppet agent plugin; once everything is ready, see the instructions in the puppet agent plugin’s README for usage details.
Alternately, parallel SSH can be a more lightweight solution for doing Puppet runs. Be sure to limit the number of nodes that run at once, so you don’t overwhelm your Puppet master(s).
Deprecated: Puppet Kick
This version of Puppet still has an older method for remote runs, known as Puppet kick. It is deprecated and you shouldn’t use it, since it requires all of your agent nodes to accept incoming HTTPS connections.
If you’re maintaining a site that already uses Puppet kick, here are the requirements for getting it working when deploying new agent nodes:
Disabling and Re-enabling Puppet Runs
Regardless of how you’re running Puppet agent, you can prevent it from doing any Puppet runs by running
sudo puppet agent --disable "<MESSAGE>". You can re-enable it with
sudo puppet agent --enable.
If Puppet agent attempts to do a configuration run while disabled — either a scheduled run or a manually triggered one — it will log a message like
Notice: Skipping run of Puppet configuration client; administratively disabled (Reason: 'Investigating a problem 5/23/14 -NF'); Use 'puppet agent --enable' to re-enable.