puppet-agent

Register a node at a Puppet server and apply the received catalog

$ puppet agent --test --server [puppetserver_fqdn] --serverport [port] --waitforcert [poll_time]

$ puppet agent

$ puppet agent --test

$ puppet agent --test --noop

$ puppet agent --test --evaltrace

$ puppet agent --disable "[message]"

$ puppet agent --enable

puppet-agent [options]

Note: The puppet-agent binary is often a wrapper or symlink that executes the puppet command with its agent subcommand (e.g., puppet agent --test). This synopsis refers to the functionality accessible through this entry point.

--test
    Run the agent once in a verbose and reporting mode, suitable for testing and debugging. Equivalent to --onetime --no-daemonize --verbose --waitforcert 10 --no-use_cached_catalog --detailed-exitcodes --no-skip_noop_self_finish.

--onetime
    Run the agent once in the foreground and then exit. Does not daemonize.

--enable
    Enable the Puppet agent service, allowing it to run periodically or start on boot.

--disable
    Disable the Puppet agent service, preventing it from running automatically.

--server <HOST>
    Specify the hostname of the Puppet Master server to connect to.

--waitforcert <SECONDS>
    Wait the specified duration for the Puppet Master to sign the agent's certificate request (CSR).

--noop
    Simulate a run without actually applying any changes to the system. Reports what would have been changed.

--environment <ENV>
    Specify the Puppet environment to request a catalog from.

--verbose
    Log verbosely, showing more information about the agent's operations.

--debug
    Log with debug messages, providing the most detailed output for troubleshooting.

--daemonize
    Run as a background daemon (default behavior if not --onetime).

--no-daemonize
    Do not daemonize; run in the foreground. Often used with --onetime or for interactive debugging.

--fingerprint
    Display the SHA256 fingerprint of the agent's SSL certificate, useful for manual certificate verification.

The puppet-agent is the core client component of the Puppet configuration management system. It's responsible for fetching desired state configurations (called 'catalogs') from a Puppet Master server and applying them to the local system.

The agent ensures that the system's configuration (files, services, packages, users, etc.) matches the definitions in the Puppet manifests. It operates idempotently, meaning it only makes changes when the current state differs from the desired state. It can run continuously as a daemon, regularly checking in with the master, or be invoked for a one-time run (e.g., for testing or manual application).

Communication with the Puppet Master is secured using SSL certificates, ensuring authentication and encryption. The puppet-agent is fundamental for maintaining consistent, compliant, and automated infrastructure across a fleet of managed nodes.

The puppet-agent typically requires root or administrator privileges to apply configurations that modify system state (e.g., installing packages, managing services).

Reliable network connectivity to the Puppet Master is essential for the agent to fetch catalogs and send reports. Issues with network, DNS, or firewalls can prevent the agent from functioning.

Proper management of SSL certificates is critical for secure communication. If certificates are expired, revoked, or untrusted, the agent will fail to communicate with the master.

While Puppet strives for idempotency, custom resources or scripts within manifests that are not carefully written might lead to unintended side effects on repeated runs.

The primary configuration file for the Puppet agent is puppet.conf, typically located in /etc/puppetlabs/puppet/. This file contains settings such as the Puppet Master's hostname, certificate paths, and logging levels. Other configuration files like hiera.yaml might also be used for data lookup.

By default, the puppet-agent logs its operations to syslog (/var/log/syslog or /var/log/messages on Linux, Event Log on Windows) and/or to a dedicated Puppet log file (e.g., /var/log/puppetlabs/puppet/puppet-agent.log). Log levels can be configured via puppet.conf or command-line options like --verbose or --debug.

Puppet was first developed by Luke Kanies in 2005. The agent-master architecture, with the puppet-agent as the client component, has been central to Puppet's design since its early days. Over the years, the agent's capabilities have expanded, including performance optimizations, improved error reporting, and enhanced support for various operating systems and resource types.

Its development has been driven by the evolving needs of large-scale infrastructure automation, moving from simple configuration management to continuous delivery and desired state enforcement.

puppet(8), puppet-server(8), puppet-apply(8), puppet-cert(8), systemctl(1), service(8)