table of contents
PUPPET-AGENT(8) | Puppet manual | PUPPET-AGENT(8) |
NAME¶
puppet-agent - The puppet agent daemonSYNOPSIS¶
Retrieves the client configuration from the puppet master and applies it to the local host.This service may be run as a daemon, run periodically using cron (or something similar), or run interactively for testing purposes.
USAGE¶
puppet agent [--certname NAME] [-D|--daemonize|--no-daemonize] [-d|--debug] [--detailed-exitcodes] [--digest DIGEST] [--disable [MESSAGE]] [--enable] [--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog|FILE|console] [--masterport PORT] [--noop] [-o|--onetime] [-t|--test] [-v|--verbose] [-V|--version] [-w|--waitforcert SECONDS]DESCRIPTION¶
This is the main puppet client. Its job is to retrieve the local machine´s configuration from a remote server and apply it. In order to successfully communicate with the remote server, the client must have a certificate signed by a certificate authority that the server trusts; the recommended method for this, at the moment, is to run a certificate authority as part of the puppet server (which is the default). The client will connect and request a signed certificate, and will continue connecting until it receives one.Once the client has a signed certificate, it will retrieve its configuration and apply it.
USAGE NOTES¶
´puppet agent´ does its best to find a compromise between interactive use and daemon use. Run with no arguments and no configuration, it will go into the background, attempt to get a signed certificate, and retrieve and apply its configuration every 30 minutes.Some flags are meant specifically for interactive use -- in particular, ´test´, ´tags´ or ´fingerprint´ are useful. ´test´ enables verbose logging, causes the daemon to stay in the foreground, exits if the server´s configuration is invalid (this happens if, for instance, you´ve left a syntax error on the server), and exits after running the configuration once (rather than hanging around as a long-running process).
´tags´ allows you to specify what portions of a configuration you want to apply. Puppet elements are tagged with all of the class or definition names that contain them, and you can use the ´tags´ flag to specify one of these names, causing only configuration elements contained within that class or definition to be applied. This is very useful when you are testing new configurations -- for instance, if you are just starting to manage ´ntpd´, you would put all of the new elements into an ´ntpd´ class, and call puppet with ´--tags ntpd´, which would only apply that small portion of the configuration during your testing, rather than applying the whole thing.
´fingerprint´ is a one-time flag. In this mode ´puppet agent´ will run once and display on the console (and in the log) the current certificate (or certificate request) fingerprint. Providing the ´--digest´ option allows to use a different digest algorithm to generate the fingerprint. The main use is to verify that before signing a certificate request on the master, the certificate request the master received is the same as the one the client sent (to prevent against man-in-the-middle attacks when signing certificates).
OPTIONS¶
Note that any Puppet setting that´s valid in the configuration file is also a valid long argument. For example, ´server´ is a valid setting, so you can specify ´--server servername´ as an argument. Boolean settings translate into ´--setting´ and ´--no-setting´ pairs.See the configuration file documentation at https://docs.puppetlabs.com/references/stable/configuration.html for the full list of acceptable settings. A commented list of all settings can also be generated by running puppet agent with ´--genconfig´.
- --certname
- Set the certname (unique ID) of the client. The master reads this unique identifying string, which is usually set to the node´s fully-qualified domain name, to determine which configurations the node will receive. Use this option to debug setup problems or implement unusual node identification schemes. (This is a Puppet setting, and can go in puppet.conf.)
- --daemonize
- Send the process into the background. This is the default. (This is a Puppet setting, and can go in puppet.conf. Note the special ´no-´ prefix for boolean settings on the command line.)
- --no-daemonize
- Do not send the process into the background. (This is a Puppet setting, and can go in puppet.conf. Note the special ´no-´ prefix for boolean settings on the command line.)
- --debug
- Enable full debugging.
- --detailed-exitcodes
- Provide transaction information via exit codes. If this is enabled, an exit code of ´2´ means there were changes, an exit code of ´4´ means there were failures during the transaction, and an exit code of ´6´ means there were both changes and failures.
- --digest
- Change the certificate fingerprinting digest algorithm. The default is SHA256. Valid values depends on the version of OpenSSL installed, but will likely contain MD5, MD2, SHA1 and SHA256.
- --disable
- Disable working on the local system. This puts a lock file in place, causing ´puppet agent´ not to work on the system until the lock file is removed. This is useful if you are testing a configuration and do not want the central configuration to override the local state until everything is tested and committed.
- Disable can also take an optional message that will be reported by the ´puppet agent´ at the next disabled run.
- ´puppet agent´ uses the same lock file while it is running, so no more than one ´puppet agent´ process is working at a time.
- ´puppet agent´ exits after executing this.
- --enable
- Enable working on the local system. This removes any lock file, causing ´puppet agent´ to start managing the local system again (although it will continue to use its normal scheduling, so it might not start for another half hour).
- ´puppet agent´ exits after executing this.
- --fingerprint
- Display the current certificate or certificate signing request fingerprint and then exit. Use the ´--digest´ option to change the digest algorithm used.
- --help
- Print this help message
- --logdest
- Where to send log messages. Choose between ´syslog´ (the POSIX syslog service), ´eventlog´ (the Windows Event Log), ´console´, or the path to a log file. If debugging or verbosity is enabled, this defaults to ´console´. Otherwise, it defaults to ´syslog´ on POSIX systems and ´eventlog´ on Windows.
- A path ending with ´.json´ will receive structured output in JSON format. The log file will not have an ending ´]´ automatically written to it due to the appending nature of logging. It must be appended manually to make the content valid JSON.
- --masterport
- The port on which to contact the puppet master. (This is a Puppet setting, and can go in puppet.conf.)
- --noop
- Use ´noop´ mode where the daemon runs in a no-op or dry-run mode. This is useful for seeing what changes Puppet will make without actually executing the changes. (This is a Puppet setting, and can go in puppet.conf. Note the special ´no-´ prefix for boolean settings on the command line.)
- --onetime
- Run the configuration once. Runs a single (normally daemonized) Puppet run. Useful for interactively running puppet agent when used in conjunction with the --no-daemonize option. (This is a Puppet setting, and can go in puppet.conf. Note the special ´no-´ prefix for boolean settings on the command line.)
- --test
- Enable the most common options used for testing. These are ´onetime´, ´verbose´, ´ignorecache´, ´no-daemonize´, ´no-usecacheonfailure´, ´detailed-exitcodes´, ´no-splay´, and ´show_diff´.
- --verbose
- Turn on verbose reporting.
- --version
- Print the puppet version number and exit.
- --waitforcert
- This option only matters for daemons that do not yet have certificates and it is enabled by default, with a value of 120 (seconds). This causes ´puppet agent´ to connect to the server every 2 minutes and ask it to sign a certificate request. This is useful for the initial setup of a puppet client. You can turn off waiting for certificates by specifying a time of 0. (This is a Puppet setting, and can go in puppet.conf. Note the special ´no-´ prefix for boolean settings on the command line.)
EXAMPLE¶
$ puppet agent --server puppet.domain.com
DIAGNOSTICS¶
Puppet agent accepts the following signals:- SIGHUP
- Restart the puppet agent daemon.
- SIGINT and SIGTERM
- Shut down the puppet agent daemon.
- SIGUSR1
- Immediately retrieve and apply configurations from the puppet master.
- SIGUSR2
- Close file descriptors for log files and reopen them. Used with logrotate.
AUTHOR¶
Luke KaniesCOPYRIGHT¶
Copyright (c) 2011 Puppet Labs, LLC Licensed under the Apache 2.0 LicenseMay 2015 | Puppet Labs, LLC |