#!/usr/bin/env ruby # == Synopsis # # Retrieve the client configuration from the puppet master and apply # it to the local host. # # Currently must be run out periodically, using cron or something similar. # # = Usage # # puppet agent [-D|--daemonize|--no-daemonize] [-d|--debug] # [--detailed-exitcodes] [--disable] [--enable] # [-h|--help] [--certname ] [-l|--logdest syslog||console] # [-o|--onetime] [--serve ] [-t|--test] [--noop] # [--digest ] [--fingerprint] [-V|--version] # [-v|--verbose] [-w|--waitforcert ] # # = 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 # backgroun, 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 configuration parameter that's valid in the configuration file # is also a valid long argument. For example, 'server' is a valid configuration # parameter, so you can specify '--server ' as an argument. # # See the configuration file documentation at # http://docs.puppetlabs.com/references/stable/configuration.html for # the full list of acceptable parameters. A commented list of all # configuration options can also be generated by running puppet agent with # '--genconfig'. # # daemonize:: # Send the process into the background. This is the default. # # no-daemonize:: # Do not send the process into the background. # # debug:: # Enable full debugging. # # digest:: # Change the certificate fingerprinting digest algorithm. The default is MD5. # Valid values depends on the version of OpenSSL installed, but should always # at least contain MD5, MD2, SHA1 and SHA256. # # detailed-exitcodes:: # Provide transaction information via exit codes. If this is enabled, an # exit code of '2' means there were changes, and an exit code of '4' means # that there were failures during the transaction. This option only makes # sense in conjunction with --onetime. # # 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. # # +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. # # 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. # # help:: # Print this help message # # logdest:: # Where to send messages. Choose between syslog, the console, and a log file. # Defaults to sending messages to syslog, or the console if debugging or # verbosity is enabled. # # no-client:: # Do not create a config client. This will cause the daemon to run # without ever checking for its configuration automatically, and only # makes sense when used in conjunction with --listen. # # 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. # # fingerprint:: # Display the current certificate or certificate signing request fingerprint # and then exit. Use the +--digest+ option to change the digest algorithm used. # # serve:: # Start another type of server. By default, +puppet agent+ will start # a service handler that allows authenticated and authorized remote nodes to # trigger the configuration to be pulled down and applied. You can specify # any handler here that does not require configuration, e.g., filebucket, ca, # or resource. The handlers are in +lib/puppet/network/handler+, and the names # must match exactly, both in the call to +serve+ and in +namespaceauth.conf+. # # test:: # Enable the most common options used for testing. These are +onetime+, # +verbose+, +ignorecache, +no-daemonize+, +no-usecacheonfailure+, # +detailed-exit-codes+, +no-splay+, and +show_diff+. # # 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. # # 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. # # = Example # # puppet agent --server puppet.domain.com # # = Author # # Luke Kanies # # = Copyright # # Copyright (c) 2005, 2006 Puppet Labs, LLC # Licensed under the GNU Public License #Puppet::Application[:agent].run