Maint: move puppet agent --help

1 files changed, 206 insertions, 0 deletions

diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb
index 2b75505fd..5dc425556 100644
--- a/lib/puppet/application/agent.rb
+++ b/lib/puppet/application/agent.rb
@@ -83,6 +83,212 @@ class Puppet::Application::Agent < Puppet::Application
     @args[:Port] = arg
   end
 
+  def help
+    <<-HELP
+
+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 <host name>] [-l|--logdest syslog|<file>|console]
+      [-o|--onetime] [--serve <handler>] [-t|--test] [--noop]
+      [--digest <digest>] [--fingerprint] [-V|--version]
+      [-v|--verbose] [-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 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 <servername>' 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
+
+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
+
+    HELP
+  end
+
   def run_command
     return fingerprint if options[:fingerprint]
     return onetime if Puppet[:onetime]