Puppet agent on *nix systems
Puppet agent is the application that manages the configurations on your nodes. It requires a Puppet primary server to fetch configuration catalogs from.
Depending on your infrastructure and needs, you can manage systems with Puppet agent as a service, as a cron job, or on demand.
For more information about running the puppet agent
command, see the puppet agent man page.
Puppet agent's run environment
Puppet agent runs as a specific user, (usually root
) and initiates outbound connections on port
8140.
Ports
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, you have to change the serverport setting on all agent nodes, and ensure that you change your primary Puppet server’s port as well.
User
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. However, this restricts the resources that Puppet agent can manage, and requires you to run Puppet agent as a cron job instead of a service.
If you need to install packages into a directory
controlled by a non-root user, use an exec
to unzip a tarball or use a
recursive file
resource to copy a directory into place.
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 sudo
.
Resource type | Details |
---|---|
augeas
|
|
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. |
notify
|
|
schedule
|
|
service
|
For services that don’t require root.
You can also use the start , stop ,
and status attributes to specify
how non-root users can control the service. |
ssh_authorized_key
|
|
ssh_key
|
Manage systems with Puppet agent
In a standard Puppet configuration, each node periodically does configuration runs to revert unwanted changes and to pick up recent updates.
- Run Puppet agent as a service.
- The easiest method. The Puppet agent daemon does 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.
- Only run Puppet agent on demand.
- You can also deploy MCollective to run on demand on many nodes.
Choose whichever one works best for your infrastructure and culture.
Run Puppet agent as a service
The puppet agent
command can start a long-lived daemon process that does
configuration runs at a set interval.
Run Puppet agent as a cron job
Run Puppet agent as a cron job when running as a non-root user.
If the
onetime
setting is set to true
, the Puppet agent
command does one configuration run and then quits. If the daemonize
setting is set
to false
,
the command stays in the foreground until the run is finished. If set
to true
, it
does the run in the background.
This behavior is good for
building a cron job that does configuration runs. You can use the splay
and splaylimit
settings to keep the primaryPuppet server from getting overwhelmed, because the
system time is probably synchronized across all of your agent nodes.
puppet resource
command:
sudo puppet resource cron puppet-agent ensure=present user=root minute=30 command='/opt/puppetlabs/bin/puppet agent --onetime --no-daemonize --splay --splaylimit 60'
The
above example runs Puppet one time every
hour. Run Puppet agent on demand
Some sites prefer to run Puppet agent on-demand, and others use scheduled runs along with the occasional on-demand run.
You can start Puppet agent runs while logged in to the target system, or remotely with Bolt or MCollective.
ssh ops@magpie.example.com sudo puppet agent --test
To run remotely on multiple machines, you need some form of orchestration or parallel execution tool, such as Bolt or MCollective with the puppet agent plugin.
Disable and re-enable 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.
Configuring Puppet agent
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 information on settings
relevant to Puppet agent, see important settings.
Logging for Puppet agent on *nix systems
When running as a service, Puppet agent
logs messages to syslog. Your syslog configuration determines where
these messages are saved, but the default location is /var/log/messages
on Linux, and /var/log/system.log
on Mac OS X.
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 instead of to syslog.
When started with the --logdest
<FILE>
option, Puppet agent logs to the file
specified by <FILE>
.
Reporting for Puppet agent on *nix systems
In addition to local logging, Puppet agent
submits a report to the primary Puppet server after each run.
This can be disabled by setting report =
false
in puppet.conf.)