Merge branch 'next'

* next: (198 commits)
  (#6722) load all functions before testing...
  Updated CHANGELOG for 2.6.7rc1
  (#5073) Download plugins even if you're filtering on tags
  Fix #5610: Prevent unnecessary RAL lookups
  Revert "Merge branch 'ticket/2.6.x/5605' of git://github.com/stschulte/puppet into 2.6.next"
  (#6723) Fix withenv environment restoration bug
  (#6689) Remove extraneous include of Puppet::Util in InventoryActiveRecord
  Remove extra trailing whitespace from lib/puppet/resource.rb
  (#5428) More fully "stub" Puppet::Resource::Reference for use with storedconfigs
  (#6707) Fix typo in rest_authconfig.rb
  (#6689) Make inventory_active_record terminus search quickly
  (#5479) Test that we auto-require the zone dataset.
  (#5479) Autorequire zfs filesystem when zone dataset is configured
  (#5392) Give a better error when realizing a non-existant resource
  (#2645) Adding a less-stubby test to verify the "system" attribute's behavior
  Update CHANGELOG for 2.6.6
  maint: Remove serialization of InventoryFact values
  maint: Rename InventoryHost to InventoryNode
  (#6441) Add mount fixture for AIX's /etc/filesystems
  Fixed #2645 - Added support for creating system users
  ...

11 files changed, 1237 insertions, 85 deletions

diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb
index 96f33296f..2ee40227e 100644
--- a/lib/puppet/application/agent.rb
+++ b/lib/puppet/application/agent.rb
@@ -9,7 +9,7 @@ class Puppet::Application::Agent < Puppet::Application
 
   def preinit
     # Do an initial trap, so that cancels don't get a stack trace.
-    trap(:INT) do
+    Signal.trap(:INT) do
       $stderr.puts "Cancelling startup"
       exit(0)
     end
@@ -83,6 +83,217 @@ class Puppet::Application::Agent < Puppet::Application
     @args[:Port] = arg
   end
 
+  def help
+    <<-HELP
+
+puppet-agent(8) -- The puppet agent daemon
+========
+
+SYNOPSIS
+--------
+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  [-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 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 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]
@@ -119,7 +330,7 @@ class Puppet::Application::Agent < Puppet::Application
 
     if not report
       exit(1)
-    elsif not Puppet[:noop] and options[:detailed_exitcodes] then
+    elsif options[:detailed_exitcodes] then
       exit(report.exit_status)
     else
       exit(0)
diff --git a/lib/puppet/application/apply.rb b/lib/puppet/application/apply.rb
index e5b4bb5b7..2b7c9f8fb 100644
--- a/lib/puppet/application/apply.rb
+++ b/lib/puppet/application/apply.rb
@@ -26,6 +26,103 @@ class Puppet::Application::Apply < Puppet::Application
     end
   end
 
+  def help
+    <<-HELP
+
+puppet-apply(8) -- Apply Puppet manifests locally
+========
+
+SYNOPSIS
+--------
+Applies a standalone Puppet manifest to the local system.
+
+
+USAGE
+-----
+puppet apply [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose]
+  [-e|--execute] [--detailed-exitcodes] [-l|--logdest <file>]
+  [--apply <catalog>] <file>
+
+
+DESCRIPTION
+-----------
+This is the standalone puppet execution tool; use it to apply
+individual manifests.
+
+When provided with a modulepath, via command line or config file, puppet
+apply can effectively mimic the catalog that would be served by puppet
+master with access to the same modules, although there are some subtle
+differences. When combined with scheduling and an automated system for
+pushing manifests, this can be used to implement a serverless Puppet
+site.
+
+Most users should use 'puppet agent' and 'puppet master' for site-wide
+manifests.
+
+
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument. For example, 'modulepath' is a
+valid configuration parameter, so you can specify '--tags <class>,<tag>'
+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 with
+'--genconfig'.
+
+* --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, and an exit code of '4'
+  means that there were failures during the transaction.
+
+* --help:
+  Print this help message
+
+* --loadclasses:
+  Load any stored classes. 'puppet agent' caches configured classes
+  (usually at /etc/puppet/classes.txt), and setting this option causes
+  all of those classes to be set in your puppet manifest.
+
+* --logdest:
+  Where to send messages. Choose between syslog, the console, and a log
+  file. Defaults to sending messages to the console.
+
+* --execute:
+  Execute a specific piece of Puppet code
+
+* --verbose:
+  Print extra information.
+
+* --apply:
+  Apply a JSON catalog (such as one generated with 'puppet master --compile'). You can
+  either specify a JSON file or pipe in JSON from standard input.
+
+
+EXAMPLE
+-------
+    $ puppet apply -l /tmp/manifest.log manifest.pp
+    $ puppet apply --modulepath=/root/dev/modules -e "include ntpd::server"
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
   def run_command
     if options[:catalog]
       apply
@@ -125,7 +222,7 @@ class Puppet::Application::Apply < Puppet::Application
       configurer = Puppet::Configurer.new
       report = configurer.run(:skip_plugin_download => true, :catalog => catalog)
 
-      exit( Puppet[:noop] ? 0 : options[:detailed_exitcodes] ? report.exit_status : 0 )
+      exit( options[:detailed_exitcodes] ? report.exit_status : 0 )
     rescue => detail
       puts detail.backtrace if Puppet[:trace]
       $stderr.puts detail.message
@@ -143,7 +240,7 @@ class Puppet::Application::Apply < Puppet::Application
     client = nil
     server = nil
 
-    trap(:INT) do
+    Signal.trap(:INT) do
       $stderr.puts "Exiting"
       exit(1)
     end
diff --git a/lib/puppet/application/cert.rb b/lib/puppet/application/cert.rb
index 467b0c859..f02fc893c 100644
--- a/lib/puppet/application/cert.rb
+++ b/lib/puppet/application/cert.rb
@@ -5,17 +5,19 @@ class Puppet::Application::Cert < Puppet::Application
   should_parse_config
   run_mode :master
 
-  attr_accessor :cert_mode, :all, :ca, :digest, :signed
+  attr_accessor :all, :ca, :digest, :signed
 
-  def find_mode(opt)
-    require 'puppet/ssl/certificate_authority'
-    modes = Puppet::SSL::CertificateAuthority::Interface::INTERFACE_METHODS
-    tmp = opt.sub("--", '').to_sym
-    @cert_mode = modes.include?(tmp) ? tmp : nil
+  def subcommand
+    @subcommand
+  end
+  def subcommand=(name)
+    # Handle the nasty, legacy mapping of "clean" to "destroy".
+    sub = name.to_sym
+    @subcommand = (sub == :clean ? :destroy : sub)
   end
 
   option("--clean", "-c") do
-    @cert_mode = :destroy
+    self.subcommand = "destroy"
   end
 
   option("--all", "-a") do
@@ -37,7 +39,7 @@ class Puppet::Application::Cert < Puppet::Application
   require 'puppet/ssl/certificate_authority/interface'
   Puppet::SSL::CertificateAuthority::Interface::INTERFACE_METHODS.reject {|m| m == :destroy }.each do |method|
     option("--#{method}", "-#{method.to_s[0,1]}") do
-      find_mode("--#{method}")
+      self.subcommand = method
     end
   end
 
@@ -45,6 +47,129 @@ class Puppet::Application::Cert < Puppet::Application
     Puppet::Util::Log.level = :info
   end
 
+  def help
+    puts <<-HELP
+
+puppet-cert(8) -- Manage certificates and requests
+========
+
+SYNOPSIS
+--------
+Standalone certificate authority. Capable of generating certificates,
+but mostly used for signing certificate requests from puppet clients.
+
+
+USAGE
+-----
+puppet cert [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose]
+  [-g|--generate] [-l|--list] [-s|--sign] [-r|--revoke] [-p|--print]
+  [-c|--clean] [--verify] [--digest <digest>] [--fingerprint] [host]
+
+
+DESCRIPTION
+-----------
+Because the puppet master service defaults to not signing client
+certificate requests, this script is available for signing outstanding
+requests. It can be used to list outstanding requests and then either
+sign them individually or sign all of them.
+
+
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument. For example, 'ssldir' is a valid
+configuration parameter, so you can specify '--ssldir <directory>' 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 cert with
+'--genconfig'.
+
+* --all:
+  Operate on all items. Currently only makes sense with '--sign',
+  '--clean', or '--list'.
+
+* --digest:
+  Set the digest for fingerprinting (defaults to md5). Valid values
+  depends on your openssl and openssl ruby extension version, but should
+  contain at least md5, sha1, md2, sha256.
+
+* --clean:
+  Remove all files related to a host from puppet cert's storage. This is
+  useful when rebuilding hosts, since new certificate signing requests
+  will only be honored if puppet cert does not have a copy of a signed
+  certificate for that host. The certificate of the host is also
+  revoked. If '--all' is specified then all host certificates, both
+  signed and unsigned, will be removed.
+
+* --debug:
+  Enable full debugging.
+
+* --generate:
+  Generate a certificate for a named client. A certificate/keypair will
+  be generated for each client named on the command line.
+
+* --help:
+  Print this help message
+
+* --list:
+  List outstanding certificate requests. If '--all' is specified, signed
+  certificates are also listed, prefixed by '+', and revoked or invalid
+  certificates are prefixed by '-' (the verification outcome is printed
+  in parenthesis).
+
+* --print:
+  Print the full-text version of a host's certificate.
+
+* --fingerprint:
+  Print the DIGEST (defaults to md5) fingerprint of a host's
+  certificate.
+
+* --revoke:
+  Revoke the certificate of a client. The certificate can be specified
+  either by its serial number, given as a decimal number or a
+  hexadecimal number prefixed by '0x', or by its hostname. The
+  certificate is revoked by adding it to the Certificate Revocation List
+  given by the 'cacrl' config parameter. Note that the puppetmasterd
+  needs to be restarted after revoking certificates.
+
+* --sign:
+  Sign an outstanding certificate request. Unless '--all' is specified,
+  hosts must be listed after all flags.
+
+* --verbose:
+  Enable verbosity.
+
+* --version:
+  Print the puppet version number and exit.
+
+* --verify:
+  Verify the named certificate against the local CA certificate.
+
+
+EXAMPLE
+-------
+    $ puppet cert -l
+    culain.madstop.com
+    $ puppet cert -s culain.madstop.com
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+    exit
+  end
+
   def main
     if @all
       hosts = :all
@@ -54,8 +179,8 @@ class Puppet::Application::Cert < Puppet::Application
       hosts = command_line.args.collect { |h| h.downcase }
     end
     begin
-      @ca.apply(:revoke, :to => hosts) if @cert_mode == :destroy
-      @ca.apply(@cert_mode, :to => hosts, :digest => @digest)
+      @ca.apply(:revoke, :to => hosts) if subcommand == :destroy
+      @ca.apply(subcommand, :to => hosts, :digest => @digest)
     rescue => detail
       puts detail.backtrace if Puppet[:trace]
       puts detail.to_s
@@ -64,11 +189,12 @@ class Puppet::Application::Cert < Puppet::Application
   end
 
   def setup
+    require 'puppet/ssl/certificate_authority'
     exit(Puppet.settings.print_configs ? 0 : 1) if Puppet.settings.print_configs?
 
     Puppet::Util::Log.newdestination :console
 
-    if [:generate, :destroy].include? @cert_mode
+    if [:generate, :destroy].include? subcommand
       Puppet::SSL::Host.ca_location = :local
     else
       Puppet::SSL::Host.ca_location = :only
@@ -82,4 +208,17 @@ class Puppet::Application::Cert < Puppet::Application
       exit(23)
     end
   end
+
+  def parse_options
+    # handle the bareword subcommand pattern.
+    result = super
+    unless self.subcommand then
+      if sub = self.command_line.args.shift then
+        self.subcommand = sub
+      else
+        help
+      end
+    end
+    result
+  end
 end
diff --git a/lib/puppet/application/describe.rb b/lib/puppet/application/describe.rb
index e76b347f6..79643159e 100644
--- a/lib/puppet/application/describe.rb
+++ b/lib/puppet/application/describe.rb
@@ -180,6 +180,60 @@ class Puppet::Application::Describe < Puppet::Application
   option("--list", "-l")
   option("--meta","-m")
 
+  def help
+    <<-HELP
+
+puppet-describe(8) -- Display help about resource types
+========
+
+SYNOPSIS
+--------
+Prints help about Puppet resource types, providers, and metaparameters.
+
+
+USAGE
+-----
+puppet describe [-h|--help] [-s|--short] [-p|--providers] [-l|--list] [-m|--meta]
+
+
+OPTIONS
+-------
+* --help:
+  Print this help text
+
+* --providers:
+  Describe providers in detail for each type
+
+* --list:
+  List all types
+
+* --meta:
+  List all metaparameters
+
+* --short:
+  List only parameters without detail
+
+
+EXAMPLE
+-------
+    $ puppet describe --list
+    $ puppet describe file --providers
+    $ puppet describe user -s -m
+
+
+AUTHOR
+------
+David Lutterkort
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
   def preinit
     options[:parameters] = true
   end
diff --git a/lib/puppet/application/doc.rb b/lib/puppet/application/doc.rb
index aaefd6e75..74811919e 100644
--- a/lib/puppet/application/doc.rb
+++ b/lib/puppet/application/doc.rb
@@ -1,7 +1,6 @@
 require 'puppet/application'
 
 class Puppet::Application::Doc < Puppet::Application
-
   should_not_parse_config
   run_mode :master
 
@@ -50,6 +49,99 @@ class Puppet::Application::Doc < Puppet::Application
     options[:references] << arg.intern
   end
 
+  def help
+    <<-HELP
+
+puppet-doc(8) -- Generate Puppet documentation and references
+========
+
+SYNOPSIS
+--------
+Generates a reference for all Puppet types. Largely meant for internal
+Puppet Labs use.
+
+
+USAGE
+-----
+puppet doc [-a|--all] [-h|--help] [-o|--outputdir <rdoc-outputdir>]
+  [-m|--mode text|pdf|rdoc] [-r|--reference <reference-name>]
+  [--charset <charset>] [<manifest-file>]
+
+
+DESCRIPTION
+-----------
+If mode is not 'rdoc', then this command generates a Markdown document
+describing all installed Puppet types or all allowable arguments to
+puppet executables. It is largely meant for internal use and is used to
+generate the reference document available on the Puppet Labs web site.
+
+In 'rdoc' mode, this command generates an html RDoc hierarchy describing
+the manifests that are in 'manifestdir' and 'modulepath' configuration
+directives. The generated documentation directory is doc by default but
+can be changed with the 'outputdir' option.
+
+If the command is run with the name of a manifest file as an argument,
+puppet doc will output a single manifest's documentation on stdout.
+
+
+OPTIONS
+-------
+* --all:
+  Output the docs for all of the reference types. In 'rdoc'
+  modes, this also outputs documentation for all resources
+
+* --help:
+  Print this help message
+
+* --outputdir:
+  Specifies the directory where to output the rdoc
+  documentation in 'rdoc' mode.
+
+* --mode:
+  Determine the output mode. Valid modes are 'text', 'pdf' and
+  'rdoc'. The 'pdf' mode creates PDF formatted files in the
+  /tmp directory. The default mode is 'text'. In 'rdoc' mode
+  you must provide 'manifests-path'
+
+* --reference:
+  Build a particular reference. Get a list of references by
+  running 'puppet doc --list'.
+
+* --charset:
+  Used only in 'rdoc' mode. It sets the charset used in the
+  html files produced.
+
+
+EXAMPLE
+-------
+    $ puppet doc -r type > /tmp/type_reference.markdown
+
+or
+
+    $ puppet doc --outputdir /tmp/rdoc --mode rdoc /path/to/manifests
+
+or
+
+    $ puppet doc /etc/puppet/manifests/site.pp
+
+or
+
+    $ puppet doc -m pdf -r configuration
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005-2007 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+HELP
+  end
+
   def handle_unknown( opt, arg )
     @unknown_args << {:opt => opt, :arg => arg }
     true
@@ -70,11 +162,6 @@ class Puppet::Application::Doc < Puppet::Application
     files += command_line.args
     Puppet.info "scanning: #{files.inspect}"
 
-          Puppet.settings.setdefaults(
-        "puppetdoc",
-
-      "document_all" => [false, "Document all resources"]
-    )
     Puppet.settings[:document_all] = options[:all] || false
     begin
       require 'puppet/util/rdoc'
diff --git a/lib/puppet/application/filebucket.rb b/lib/puppet/application/filebucket.rb
index 9c3c79bc3..063d97db8 100644
--- a/lib/puppet/application/filebucket.rb
+++ b/lib/puppet/application/filebucket.rb
@@ -12,6 +12,109 @@ class Puppet::Application::Filebucket < Puppet::Application
 
   attr :args
 
+  def help
+    <<-HELP
+
+puppet-filebucket(8) -- Store and retrieve files in a filebucket
+========
+
+SYNOPSIS
+--------
+A stand-alone Puppet filebucket client.
+
+
+USAGE
+-----
+puppet filebucket <mode> [-h|--help] [-V|--version] [-d|--debug]
+  [-v|--verbose] [-l|--local] [-r|--remote] [-s|--server <server>]
+  [-b|--bucket <directory>] <file> <file> ...
+
+Puppet filebucket can operate in three modes, with only one mode per call:
+
+backup:
+  Send one or more files to the specified file bucket. Each sent file is
+  printed with its resulting md5 sum.
+
+get:
+  Return the text associated with an md5 sum. The text is printed to
+  stdout, and only one file can be retrieved at a time.
+
+restore:
+  Given a file path and an md5 sum, store the content associated with
+  the sum into the specified file path. You can specify an entirely new
+  path to this argument; you are not restricted to restoring the content
+  to its original location.
+
+
+DESCRIPTION
+-----------
+This is a stand-alone filebucket client for sending files to a local or
+central filebucket.
+
+Note that 'filebucket' defaults to using a network-based filebucket
+available on the server named 'puppet'. To use this, you'll have to be
+running as a user with valid Puppet certificates. Alternatively, you can
+use your local file bucket by specifying '--local'.
+
+
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument. For example, 'ssldir' is a valid
+configuration parameter, so you can specify '--ssldir <directory>' 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 with
+'--genconfig'.
+
+* --debug:
+  Enable full debugging.
+
+* --help:
+  Print this help message
+
+* --local:
+  Use the local filebucket. This will use the default configuration
+  information.
+
+* --remote:
+  Use a remote filebucket. This will use the default configuration
+  information.
+
+* --server:
+  The server to send the file to, instead of locally.
+
+* --verbose:
+  Print extra information.
+
+* --version:
+  Print version information.
+
+
+EXAMPLE
+-------
+    $ puppet filebucket backup /etc/passwd
+    /etc/passwd: 429b225650b912a2ee067b0a4cf1e949
+    $ puppet filebucket restore /tmp/passwd 429b225650b912a2ee067b0a4cf1e949
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
+
   def run_command
     @args = command_line.args
     command = args.shift
@@ -52,7 +155,7 @@ class Puppet::Application::Filebucket < Puppet::Application
     @client = nil
     @server = nil
 
-    trap(:INT) do
+    Signal.trap(:INT) do
       $stderr.puts "Cancelling"
       exit(1)
     end
diff --git a/lib/puppet/application/inspect.rb b/lib/puppet/application/inspect.rb
index 19324e285..e448cb9e8 100644
--- a/lib/puppet/application/inspect.rb
+++ b/lib/puppet/application/inspect.rb
@@ -19,6 +19,62 @@ class Puppet::Application::Inspect < Puppet::Application
     end
   end
 
+  def help
+    <<-HELP
+
+puppet-inspect(8) -- Send an inspection report
+========
+
+SYNOPSIS
+--------
+
+Prepares and submits an inspection report to the puppet master.
+
+
+USAGE
+-----
+puppet inspect
+
+
+DESCRIPTION
+-----------
+
+This command uses the cached catalog from the previous run of 'puppet
+agent' to determine which attributes of which resources have been
+marked as auditable with the 'audit' metaparameter. It then examines
+the current state of the system, writes the state of the specified
+resource attributes to a report, and submits the report to the puppet
+master.
+
+Puppet inspect does not run as a daemon, and must be run manually or
+from cron.
+
+
+OPTIONS
+-------
+
+Any configuration setting which is valid in the configuration file is
+also a valid long argument, e.g. '--server=master.domain.com'. See the
+configuration file documentation at
+http://docs.puppetlabs.com/references/latest/configuration.html for
+the full list of acceptable settings.
+
+
+AUTHOR
+------
+
+Puppet Labs
+
+
+COPYRIGHT
+---------
+
+Copyright (c) 2011 Puppet Labs, LLC
+Licensed under the GNU General Public License version 2
+
+    HELP
+  end
+
   def setup
     exit(Puppet.settings.print_configs ? 0 : 1) if Puppet.settings.print_configs?
 
@@ -29,7 +85,7 @@ class Puppet::Application::Inspect < Puppet::Application
     Puppet::Util::Log.newdestination(@report)
     Puppet::Util::Log.newdestination(:console) unless options[:logset]
 
-    trap(:INT) do
+    Signal.trap(:INT) do
       $stderr.puts "Exiting"
       exit(1)
     end
@@ -45,79 +101,81 @@ class Puppet::Application::Inspect < Puppet::Application
   end
 
   def run_command
-    retrieval_starttime = Time.now
+    benchmark(:notice, "Finished inspection") do
+      retrieval_starttime = Time.now
 
-    unless catalog = Puppet::Resource::Catalog.indirection.find(Puppet[:certname])
-      raise "Could not find catalog for #{Puppet[:certname]}"
-    end
+      unless catalog = Puppet::Resource::Catalog.indirection.find(Puppet[:certname])
+        raise "Could not find catalog for #{Puppet[:certname]}"
+      end
 
-    @report.configuration_version = catalog.version
+      @report.configuration_version = catalog.version
 
-    inspect_starttime = Time.now
-    @report.add_times("config_retrieval", inspect_starttime - retrieval_starttime)
+      inspect_starttime = Time.now
+      @report.add_times("config_retrieval", inspect_starttime - retrieval_starttime)
 
-    if Puppet[:archive_files]
-      dipper = Puppet::FileBucket::Dipper.new(:Server => Puppet[:archive_file_server])
-    end
+      if Puppet[:archive_files]
+        dipper = Puppet::FileBucket::Dipper.new(:Server => Puppet[:archive_file_server])
+      end
 
-    catalog.to_ral.resources.each do |ral_resource|
-      audited_attributes = ral_resource[:audit]
-      next unless audited_attributes
+      catalog.to_ral.resources.each do |ral_resource|
+        audited_attributes = ral_resource[:audit]
+        next unless audited_attributes
 
-      status = Puppet::Resource::Status.new(ral_resource)
+        status = Puppet::Resource::Status.new(ral_resource)
 
-      begin
-        audited_resource = ral_resource.to_resource
-      rescue StandardError => detail
-        puts detail.backtrace if Puppet[:trace]
-        ral_resource.err "Could not inspect #{ral_resource}; skipping: #{detail}"
-        audited_attributes.each do |name|
-          event = ral_resource.event(
-            :property => name,
-            :status   => "failure",
-            :audited  => true,
-            :message  => "failed to inspect #{name}"
-          )
-          status.add_event(event)
-        end
-      else
-        audited_attributes.each do |name|
-          next if audited_resource[name].nil?
-          # Skip :absent properties of :absent resources. Really, it would be nicer if the RAL returned nil for those, but it doesn't. ~JW
-          if name == :ensure or audited_resource[:ensure] != :absent or audited_resource[name] != :absent
+        begin
+          audited_resource = ral_resource.to_resource
+        rescue StandardError => detail
+          puts detail.backtrace if Puppet[:trace]
+          ral_resource.err "Could not inspect #{ral_resource}; skipping: #{detail}"
+          audited_attributes.each do |name|
             event = ral_resource.event(
-              :previous_value => audited_resource[name],
-              :property       => name,
-              :status         => "audit",
-              :audited        => true,
-              :message        => "inspected value is #{audited_resource[name].inspect}"
-            )
+                                       :property => name,
+                                       :status   => "failure",
+                                       :audited  => true,
+                                       :message  => "failed to inspect #{name}"
+                                       )
             status.add_event(event)
           end
+        else
+          audited_attributes.each do |name|
+            next if audited_resource[name].nil?
+            # Skip :absent properties of :absent resources. Really, it would be nicer if the RAL returned nil for those, but it doesn't. ~JW
+            if name == :ensure or audited_resource[:ensure] != :absent or audited_resource[name] != :absent
+              event = ral_resource.event(
+                                         :previous_value => audited_resource[name],
+                                         :property       => name,
+                                         :status         => "audit",
+                                         :audited        => true,
+                                         :message        => "inspected value is #{audited_resource[name].inspect}"
+                                         )
+              status.add_event(event)
+            end
+          end
         end
-      end
-      if Puppet[:archive_files] and ral_resource.type == :file and audited_attributes.include?(:content)
-        path = ral_resource[:path]
-        if File.readable?(path)
-          begin
-            dipper.backup(path)
-          rescue StandardError => detail
-            Puppet.warning detail
+        if Puppet[:archive_files] and ral_resource.type == :file and audited_attributes.include?(:content)
+          path = ral_resource[:path]
+          if File.readable?(path)
+            begin
+              dipper.backup(path)
+            rescue StandardError => detail
+              Puppet.warning detail
+            end
           end
         end
+        @report.add_resource_status(status)
       end
-      @report.add_resource_status(status)
-    end
 
-    finishtime = Time.now
-    @report.add_times("inspect", finishtime - inspect_starttime)
-    @report.finalize_report
+      finishtime = Time.now
+      @report.add_times("inspect", finishtime - inspect_starttime)
+      @report.finalize_report
 
-    begin
-      Puppet::Transaction::Report.indirection.save(@report)
-    rescue => detail
-      puts detail.backtrace if Puppet[:trace]
-      Puppet.err "Could not send report: #{detail}"
+      begin
+        Puppet::Transaction::Report.indirection.save(@report)
+      rescue => detail
+        puts detail.backtrace if Puppet[:trace]
+        Puppet.err "Could not send report: #{detail}"
+      end
     end
   end
 end
diff --git a/lib/puppet/application/kick.rb b/lib/puppet/application/kick.rb
index 12dad653a..604132818 100644
--- a/lib/puppet/application/kick.rb
+++ b/lib/puppet/application/kick.rb
@@ -37,6 +37,147 @@ class Puppet::Application::Kick < Puppet::Application
     end
   end
 
+  def help
+    <<-HELP
+
+puppet-kick(8) -- Remotely control puppet agent
+========
+
+SYNOPSIS
+--------
+Trigger a puppet agent run on a set of hosts.
+
+
+USAGE
+-----
+puppet kick [-a|--all] [-c|--class <class>] [-d|--debug] [-f|--foreground]
+  [-h|--help] [--host <host>] [--no-fqdn] [--ignoreschedules]
+  [-t|--tag <tag>] [--test] [-p|--ping] <host> [<host> [...]]
+
+
+DESCRIPTION
+-----------
+This script can be used to connect to a set of machines running 'puppet
+agent' and trigger them to run their configurations. The most common
+usage would be to specify a class of hosts and a set of tags, and
+'puppet kick' would look up in LDAP all of the hosts matching that
+class, then connect to each host and trigger a run of all of the objects
+with the specified tags.
+
+If you are not storing your host configurations in LDAP, you can specify
+hosts manually.
+
+You will most likely have to run 'puppet kick' as root to get access to
+the SSL certificates.
+
+'puppet kick' reads 'puppet master''s configuration file, so that it can
+copy things like LDAP settings.
+
+
+USAGE NOTES
+-----------
+'puppet kick' is useless unless 'puppet agent' is listening. See its
+documentation for more information, but the gist is that you must enable
+'listen' on the 'puppet agent' daemon, either using '--listen' on the
+command line or adding 'listen = true' in its config file. In addition,
+you need to set the daemons up to specifically allow connections by
+creating the 'namespaceauth' file, normally at
+'/etc/puppet/namespaceauth.conf'. This file specifies who has access to
+each namespace; if you create the file you must add every namespace you
+want any Puppet daemon to allow -- it is currently global to all Puppet
+daemons.
+
+An example file looks like this:
+
+    [fileserver]
+        allow *.madstop.com
+
+    [puppetmaster]
+        allow *.madstop.com
+
+    [puppetrunner]
+        allow culain.madstop.com
+
+This is what you would install on your Puppet master; non-master hosts
+could leave off the 'fileserver' and 'puppetmaster' namespaces.
+
+
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument. For example, 'ssldir' is a valid
+configuration parameter, so you can specify '--ssldir <directory>' as an
+argument.
+
+See the configuration file documentation at
+http://docs.puppetlabs.com/references/latest/configuration.html for
+the full list of acceptable parameters. A commented list of all
+configuration options can also be generated by running puppet master
+with '--genconfig'.
+
+* --all:
+  Connect to all available hosts. Requires LDAP support at this point.
+
+* --class:
+  Specify a class of machines to which to connect. This only works if
+  you have LDAP configured, at the moment.
+
+* --debug:
+  Enable full debugging.
+
+* --foreground:
+  Run each configuration in the foreground; that is, when connecting to
+  a host, do not return until the host has finished its run. The default
+  is false.
+
+* --help:
+  Print this help message
+
+* --host:
+  A specific host to which to connect. This flag can be specified more
+  than once.
+
+* --ignoreschedules:
+  Whether the client should ignore schedules when running its
+  configuration. This can be used to force the client to perform work it
+  would not normally perform so soon. The default is false.
+
+* --parallel:
+  How parallel to make the connections. Parallelization is provided by
+  forking for each client to which to connect. The default is 1, meaning
+  serial execution.
+
+* --tag:
+  Specify a tag for selecting the objects to apply. Does not work with
+  the --test option.
+
+* --test:
+  Print the hosts you would connect to but do not actually connect. This
+  option requires LDAP support at this point.
+
+* --ping:
+  Do a ICMP echo against the target host. Skip hosts that don't respond
+  to ping.
+
+
+EXAMPLE
+-------
+    $ sudo puppet kick -p 10 -t remotefile -t webserver host1 host2
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
   def run_command
     @hosts += command_line.args
     options[:test] ? test : main
@@ -151,7 +292,7 @@ class Puppet::Application::Kick < Puppet::Application
 
   def preinit
     [:INT, :TERM].each do |signal|
-      trap(signal) do
+      Signal.trap(signal) do
         $stderr.puts "Cancelling"
         exit(1)
       end
@@ -195,7 +336,7 @@ class Puppet::Application::Kick < Puppet::Application
 
     # If we get a signal, then kill all of our children and get out.
     [:INT, :TERM].each do |signal|
-      trap(signal) do
+      Signal.trap(signal) do
         Puppet.notice "Caught #{signal}; shutting down"
         @children.each do |pid, host|
           Process.kill("INT", pid)
diff --git a/lib/puppet/application/master.rb b/lib/puppet/application/master.rb
index 879b66c67..3bfad89f4 100644
--- a/lib/puppet/application/master.rb
+++ b/lib/puppet/application/master.rb
@@ -25,8 +25,94 @@ class Puppet::Application::Master < Puppet::Application
     end
   end
 
+  def help
+    <<-HELP
+
+puppet-master(8) -- The puppet master daemon
+========
+
+SYNOPSIS
+--------
+The central puppet server. Functions as a certificate authority by
+default.
+
+
+USAGE
+-----
+puppet master [-D|--daemonize|--no-daemonize] [-d|--debug] [-h|--help]
+  [-l|--logdest <file>|console|syslog] [-v|--verbose] [-V|--version]
+  [--compile <node-name>]
+
+
+DESCRIPTION
+-----------
+This command starts an instance of puppet master, running as a daemon
+and using Ruby's built-in Webrick webserver. Puppet master can also be
+managed by other application servers; when this is the case, this
+executable is not used.
+
+
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument. For example, 'ssldir' is a valid
+configuration parameter, so you can specify '--ssldir <directory>' 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 master
+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.
+
+* --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.
+
+* --verbose:
+  Enable verbosity.
+
+* --version:
+  Print the puppet version number and exit.
+
+* --compile:
+  Compile a catalogue and output it in JSON from the puppet master. Uses
+  facts contained in the $vardir/yaml/ directory to compile the catalog.
+
+
+EXAMPLE
+-------
+  puppet master
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
   def preinit
-    trap(:INT) do
+    Signal.trap(:INT) do
       $stderr.puts "Cancelling startup"
       exit(0)
     end
diff --git a/lib/puppet/application/queue.rb b/lib/puppet/application/queue.rb
index b9e8ca4ca..de8aea32a 100644
--- a/lib/puppet/application/queue.rb
+++ b/lib/puppet/application/queue.rb
@@ -15,13 +15,13 @@ class Puppet::Application::Queue < Puppet::Application
     # Do an initial trap, so that cancels don't get a stack trace.
 
     # This exits with exit code 1
-    trap(:INT) do
+    Signal.trap(:INT) do
       $stderr.puts "Caught SIGINT; shutting down"
       exit(1)
     end
 
     # This is a normal shutdown, so code 0
-    trap(:TERM) do
+    Signal.trap(:TERM) do
       $stderr.puts "Caught SIGTERM; shutting down"
       exit(0)
     end
@@ -37,6 +37,79 @@ class Puppet::Application::Queue < Puppet::Application
   option("--debug","-d")
   option("--verbose","-v")
 
+  def help
+    <<-HELP
+
+puppet-queue(8) -- Queuing daemon for asynchronous storeconfigs
+========
+
+SYNOPSIS
+--------
+Retrieves serialized storeconfigs records from a queue and processes
+them in order.
+
+
+USAGE
+-----
+puppet queue [-d|--debug] [-v|--verbose]
+
+
+DESCRIPTION
+-----------
+This application runs as a daemon and processes storeconfigs data,
+retrieving the data from a stomp server message queue and writing it to
+a database.
+
+For more information, including instructions for properly setting up
+your puppet master and message queue, see the documentation on setting
+up asynchronous storeconfigs at:
+http://projects.puppetlabs.com/projects/1/wiki/Using_Stored_Configuration
+
+
+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 queue with
+'--genconfig'.
+
+* --debug:
+  Enable full debugging.
+
+* --help:
+  Print this help message
+
+* --verbose:
+  Turn on verbose reporting.
+
+* --version:
+  Print the puppet version number and exit.
+
+
+EXAMPLE
+-------
+    $ puppet queue
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2009 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
   def main
     require 'puppet/indirector/catalog/queue' # provides Puppet::Indirector::Queue.subscribe
     Puppet.notice "Starting puppetqd #{Puppet.version}"
diff --git a/lib/puppet/application/resource.rb b/lib/puppet/application/resource.rb
index c7c1c28be..3995c285b 100644
--- a/lib/puppet/application/resource.rb
+++ b/lib/puppet/application/resource.rb
@@ -35,6 +35,109 @@ class Puppet::Application::Resource < Puppet::Application
     @extra_params << arg.to_sym
   end
 
+  def help
+    <<-HELP
+
+puppet-resource(8) -- The resource abstraction layer shell
+========
+
+SYNOPSIS
+--------
+Uses the Puppet RAL to directly interact with the system.
+
+
+USAGE
+-----
+puppet resource [-h|--help] [-d|--debug] [-v|--verbose] [-e|--edit]
+  [-H|--host <host>] [-p|--param <parameter>] [-t|--types] <type>
+  [<name>] [<attribute>=<value> ...]
+
+
+DESCRIPTION
+-----------
+This command provides simple facilities for converting current system
+state into Puppet code, along with some ability to modify the current
+state using Puppet's RAL.
+
+By default, you must at least provide a type to list, in which case
+puppet resource will tell you everything it knows about all resources of
+that type. You can optionally specify an instance name, and puppet
+resource will only describe that single instance.
+
+If given a type, a name, and a series of <attribute>=<value> pairs,
+puppet resource will modify the state of the specified resource.
+Alternately, if given a type, a name, and the '--edit' flag, puppet
+resource will write its output to a file, open that file in an editor,
+and then apply the saved file as a Puppet transaction.
+
+
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument. For example, 'ssldir' is a valid
+configuration parameter, so you can specify '--ssldir <directory>' 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 with
+'--genconfig'.
+
+* --debug:
+  Enable full debugging.
+
+* --edit:
+  Write the results of the query to a file, open the file in an editor,
+  and read the file back in as an executable Puppet manifest.
+
+* --host:
+  When specified, connect to the resource server on the named host
+  and retrieve the list of resouces of the type specified.
+
+* --help:
+  Print this help message.
+
+* --param:
+  Add more parameters to be outputted from queries.
+
+* --types:
+  List all available types.
+
+* --verbose:
+  Print extra information.
+
+
+EXAMPLE
+-------
+This example uses `puppet resource` to return a Puppet configuration for
+the user `luke`:
+
+    $ puppet resource user luke
+    user { 'luke':
+     home => '/home/luke',
+     uid => '100',
+     ensure => 'present',
+     comment => 'Luke Kanies,,,',
+     gid => '1000',
+     shell => '/bin/bash',
+     groups => ['sysadmin','audio','video','puppet']
+    }
+
+
+AUTHOR
+------
+Luke Kanies
+
+
+COPYRIGHT
+---------
+Copyright (c) 2005-2007 Puppet Labs, LLC Licensed under the GNU Public
+License
+
+    HELP
+  end
+
   def main
     args = command_line.args
     type = args.shift or raise "You must specify the type to display"