#!/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