[#4196] Move the docs into the source directory structure

Since it is no longer possible to find the running executable from the
call stack, docs have to be kept somewhere in the source tree.
Of course, at this point, we shouldn't be using RDoc::Usage at all.

1 files changed, 128 insertions, 0 deletions

diff --git a/lib/puppet/util/command_line/puppetrun b/lib/puppet/util/command_line/puppetrun
new file mode 100755
index 000000000..ee95c47eb
--- /dev/null
+++ b/lib/puppet/util/command_line/puppetrun
@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+
+#
+# = 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.
+#
+# Expect more documentation on this eventually.
+#
+# = 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://reductivelabs.com/projects/puppet/reference/configref.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 Reductive Labs, LLC
+# Licensed under the GNU Public License
+
+#Puppet::Application[:kick].run