How to use the command 'puppet agent' (with examples)

The puppet agent command is used to retrieve the client configuration from a Puppet server and apply it to the local host. This allows for centralized management and automation of configuration across multiple machines. The command supports various options to customize its behavior.

Use case 1: Register a node at a Puppet server and apply the received catalog

Code:

puppet agent --test --server puppetserver_fqdn --serverport port --waitforcert poll_time

Motivation: This use case is useful when you want to register a new node (host) with a Puppet server and apply the configuration catalog received from the server. It allows the node to become part of the Puppet infrastructure and benefit from centralized configuration management.

Explanation:

• --test: Runs the agent in test mode, which allows it to apply the received configuration catalog.
• --server puppetserver_fqdn: Specifies the Puppet server’s fully qualified domain name (FQDN) to retrieve the configuration from.
• --serverport port: Specifies the server port on which the Puppet server is running (default is 8140).
• --waitforcert poll_time: Specifies the amount of time in seconds to wait for the certificate to be signed by the Puppet server before timing out.

Example output:

Info: Creating a new SSL certificate request for <node_fqdn>
Info: Certificate Request fingerprint (SHA256): A1:B2:C3:D4:E5:F6:...

Use case 2: Run the agent in the background

Code:

puppet agent

Motivation: Running the agent in the background is useful when you want to daemonize the process and have it automatically run in the background at regular intervals or according to the configured schedule. This ensures that any changes made to the configuration on the Puppet server are applied on the local host.

Explanation: By omitting any additional options, the puppet agent command uses the settings specified in the puppet.conf file. It runs the agent in the background, periodically checking if any changes are available on the Puppet server and applying them to the local host.

Example output: No output is shown unless there are changes to apply.

Use case 3: Run the agent once in the foreground, then exit

Code:

puppet agent --test

Motivation: Running the agent in the foreground with the --test option allows you to manually trigger a single run of the agent and see the output in real-time. This can be helpful for troubleshooting or verifying the configuration on the local host.

Explanation: The --test option runs the agent in foreground test mode, applying the received configuration catalog. When used with puppet agent, it triggers a single run of the agent and prints the output to the console.

Example output:

Info: Using configured environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
...

Use case 4: Run the agent in dry-mode

Code:

puppet agent --test --noop

Motivation: Running the agent in dry-mode, also known as no-op (no operation) mode, allows you to simulate the configuration changes without actually applying them. This can be useful for testing how the configuration changes would affect the system without making any permanent changes.

Explanation: The --noop option tells the agent to run in dry-mode, where it performs a simulated run and displays the changes it would make to the system. It does not apply any modifications to the local host.

Example output:

Notice: Dry-run: Would have triggered 'refresh' (noop)
Notice: Applied catalog in 0.12 seconds

Use case 5: Log every resource being evaluated

Code:

puppet agent --test --evaltrace

Motivation: Enabling the evaluation trace helps in debugging the Puppet configuration and understanding the resource dependency graph. With the evaluation trace, you can see each resource being evaluated by the Puppet agent, even if no changes are being made.

Explanation: The --evaltrace option enables the evaluation trace during the Puppet agent run. It logs detailed debug information about every resource being evaluated and the associated dependencies.

Example output:

Debug: Prefetching package resources for package provider
Debug: Finishing transaction ...
...

Use case 6: Disable the agent

Code:

puppet agent --disable "message"

Motivation: Disabling the agent temporarily prevents it from running and applying any changes to the local host. This can be useful when performing maintenance or troubleshooting activities where you don’t want any automatic configuration changes to occur.

Explanation: The --disable option disables the Puppet agent. It takes an optional message parameter, which is displayed as the reason for disabling the agent. The agent will remain disabled until manually enabled or until the --enable option is used.

Example output:

Notice: Disabling the Puppet agent. Reason: Performing maintenance tasks.

Use case 7: Enable the agent

Code:

puppet agent --enable

Motivation: Enabling the agent allows it to resume normal operation after being disabled. This will initiate the next Puppet run to apply any pending configuration changes on the local host.

Explanation: The --enable option enables the Puppet agent, allowing it to resume running based on the configured schedule or regular intervals. If the agent was previously disabled using the --disable option, this command will enable it again.

Example output:

Notice: Enabling the Puppet agent.

Conclusion:

The puppet agent command provides a flexible way to manage and apply Puppet configuration on a local host. Whether you need to register a new node, run the agent in the background, test the configuration changes, or enable/disable the agent, these examples cover various scenarios to help you effectively use the puppet agent command.