summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--lib/puppet/application/faces.rb50
-rw-r--r--lib/puppet/face/catalog.rb63
-rw-r--r--lib/puppet/face/catalog/select.rb16
-rw-r--r--lib/puppet/face/certificate.rb39
-rw-r--r--lib/puppet/face/certificate_request.rb24
-rw-r--r--lib/puppet/face/certificate_revocation_list.rb22
-rw-r--r--lib/puppet/face/config.rb33
-rw-r--r--lib/puppet/face/facts.rb27
-rw-r--r--lib/puppet/face/file.rb11
-rw-r--r--lib/puppet/face/help/global.erb1
-rw-r--r--lib/puppet/face/key.rb15
-rw-r--r--lib/puppet/face/node.rb19
-rw-r--r--lib/puppet/face/parser.rb6
-rw-r--r--lib/puppet/face/plugin.rb22
-rw-r--r--lib/puppet/face/report.rb26
-rw-r--r--lib/puppet/face/resource.rb15
-rw-r--r--lib/puppet/face/resource_type.rb9
-rw-r--r--lib/puppet/face/secret_agent.rb17
-rw-r--r--lib/puppet/face/status.rb24
-rw-r--r--lib/puppet/indirector/face.rb36
20 files changed, 438 insertions, 37 deletions
diff --git a/lib/puppet/application/faces.rb b/lib/puppet/application/faces.rb
index 3dd3f0312..e7fce66b1 100644
--- a/lib/puppet/application/faces.rb
+++ b/lib/puppet/application/faces.rb
@@ -10,16 +10,54 @@ class Puppet::Application::Faces < Puppet::Application
Puppet::Util::Log.level = :debug
end
- option("--help", "-h") do |arg|
- puts "Usage: puppet faces [actions|terminuses]
-Lists all available faces, and by default includes all available terminuses and actions.
-"
- end
-
option("--verbose", "-v") do
Puppet::Util::Log.level = :info
end
+ def help
+ <<-HELP
+puppet-faces(8) -- List available Faces and actions
+========
+
+SYNOPSIS
+--------
+Lists the available subcommands (with applicable terminuses and/or actions)
+provided by the Puppet Faces API. This information is automatically read
+from the Puppet code present on the system. By default, the output includes
+all terminuses and actions.
+
+USAGE
+-----
+puppet faces [-d|--debug] [-v|--verbose] [actions|terminuses]
+
+OPTIONS
+-------
+Note that any configuration option valid in the configuration file is also
+a valid long 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'.
+
+* --verbose:
+ Sets the log level to "info." This option has no tangible effect at the time
+ of this writing.
+
+* --debug:
+ Sets the log level to "debug." This option has no tangible effect at the time
+ of this writing.
+
+AUTHOR
+------
+Puppet Labs
+
+COPYRIGHT
+---------
+Copyright (c) 2011 Puppet Labs, LLC Licensed under the Apache 2.0 License
+
+ HELP
+ end
+
def list(*arguments)
if arguments.empty?
arguments = %w{terminuses actions}
diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 3e964c7fe..4624313bc 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -5,18 +5,47 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Compile, save, view, and convert catalogs."
-
description <<-EOT
-This face primarily interacts with the compiling subsystem.
-By default, it compiles a catalog using the default manifest and the
-hostname from 'certname', but you can choose to retrieve a catalog from
-the server by specifying '--from rest'. You can also choose to print any
-catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
-with '--format dot'.
+ This face primarily interacts with the compiling subsystem. By default,
+ it compiles a catalog using the default manifest and the hostname from
+ `certname`, but you can choose to retrieve a catalog from the server by
+ specifying `--terminus rest`. You can also choose to print any catalog
+ in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
+ with '--render-as dot'.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `active_record`
+ * `compiler`
+ * `queue`
+ * `rest`
+ * `yaml`
EOT
action(:apply) do
- summary "apply a Puppet::Resource::Catalog object"
+ summary "Apply a Puppet::Resource::Catalog object"
+ description <<-EOT
+ Applies a catalog object retrieved with the `download` action. This
+ action cannot consume a serialized catalog, and is not intended for
+ command-line use."
+ EOT
+ notes <<-EOT
+ This action returns a Puppet::Transaction::Report object.
+ EOT
+ examples <<-EOT
+ From `secret_agent.rb`:
+
+ Puppet::Face[:plugin, '0.0.1'].download
+
+ facts = Puppet::Face[:facts, '0.0.1'].find(certname)
+ catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
+ report = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+
+ Puppet::Face[:report, '0.0.1'].submit(report)
+ EOT
when_invoked do |options|
catalog = Puppet::Face[:catalog, "0.0.1"].find(Puppet[:certname]) or raise "Could not find catalog for #{Puppet[:certname]}"
@@ -42,8 +71,24 @@ with '--format dot'.
end
action(:download) do
- summary "Download the catalog for the certname to the local filesystem."
+ summary "Download this node's catalog from the puppet master server"
+ description <<-EOT
+ Retrieves a catalog from the puppet master. Unlike the `find` action,
+ `download` submits facts to the master as part of the request. This
+ action is not intended for command-line use.
+ EOT
+ notes "This action returns a Puppet::Resource::Catalog object."
+ examples <<-EOT
+ From `secret_agent.rb`:
+
+ Puppet::Face[:plugin, '0.0.1'].download
+
+ facts = Puppet::Face[:facts, '0.0.1'].find(certname)
+ catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
+ report = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+ Puppet::Face[:report, '0.0.1'].submit(report)
+ EOT
when_invoked do |options|
Puppet::Resource::Catalog.indirection.terminus_class = :rest
Puppet::Resource::Catalog.indirection.cache_class = nil
diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb
index a68a8e0f3..a6c97a627 100644
--- a/lib/puppet/face/catalog/select.rb
+++ b/lib/puppet/face/catalog/select.rb
@@ -1,6 +1,22 @@
# Select and show a list of resources of a given type.
Puppet::Face.define(:catalog, '0.0.1') do
action :select do
+ summary "Select and show a list of resources of a given type"
+ description <<-EOT
+ Retrieves a catalog for the specified host and returns an array of
+ resources of the given type. This action is not intended for
+ command-line use.
+ EOT
+ notes <<-NOTES
+ The type name for this action must be given in its capitalized form.
+ That is, calling `catalog select mynode file` will return an empty
+ array, whereas calling it with 'File' will return a list of the node's
+ file resources.
+
+ By default, this action will retrieve a catalog from Puppet's compiler
+ subsystem; you must call the action with `--terminus rest` if you wish
+ to retrieve a catalog from the puppet master.
+ NOTES
when_invoked do |host, type, options|
# REVISIT: Eventually, type should have a default value that triggers
# the non-specific behaviour. For now, though, this will do.
diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb
index 0018c5fd3..ee2b2873f 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -5,16 +5,47 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do
copyright "Puppet Labs", 2011
license "Apache 2 license; see COPYING"
- summary "provide access to the CA for certificate management"
+ summary "Provide access to the CA for certificate management"
+ description <<-EOT
+ This face interacts with a local or remote Puppet certificate
+ authority. Currently, its behavior is not a full superset of puppet
+ cert; specifically, it is unable to mimic puppet cert's "clean" option,
+ and its "generate" action submits a CSR rather than creating a
+ signed certificate.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `ca`
+ * `file`
+ * `rest`
+ EOT
option "--ca-location LOCATION" do
+ summary "The certificate authority to query"
+ description <<-EOT
+ Whether to act on the local certificate authority or one provided by a
+ remote puppet master. Allowed values are 'local' and 'remote.'
+ EOT
+
before_action do |action, args, options|
Puppet::SSL::Host.ca_location = options[:ca_location].to_sym
end
end
action :generate do
- summary "Generate a new Certificate Signing Request for HOST"
+ summary "Generate a new certificate signing request for HOST"
+ description <<-EOT
+ Generates and submits a certificate signing request (CSR) for the
+ provided host identifier. This CSR will then have to be signed by a user
+ with the proper authorization on the certificate authority.
+
+ Puppet agent handles CSR submission automatically. This action is
+ primarily useful for requesting certificates for individual users and
+ external applications.
+ EOT
when_invoked do |name, options|
host = Puppet::SSL::Host.new(name)
@@ -24,7 +55,7 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do
end
action :list do
- summary "List all Certificate Signing Requests"
+ summary "List all certificate signing requests"
when_invoked do |options|
Puppet::SSL::Host.indirection.search("*", {
@@ -34,7 +65,7 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do
end
action :sign do
- summary "Sign a Certificate Signing Request for HOST"
+ summary "Sign a certificate signing request for HOST"
when_invoked do |name, options|
host = Puppet::SSL::Host.new(name)
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 809758423..cc6021517 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -5,4 +5,28 @@ Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Manage certificate requests."
+ description <<-EOT
+ Retrieves and submits certificate signing requests (CSRs). Invoke
+ `search` with an unread key to retrieve all outstanding CSRs, invoke
+ `find` with a node certificate name to retrieve a specific request, and
+ invoke `save` to submit a CSR.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `ca`
+ * `file`
+ * `rest`
+ EOT
+ examples <<-EOT
+ Retrieve all CSRs from the local CA:
+
+ puppet certificate_request search no_key --terminus ca
+
+ Retrieve a single CSR from the puppet master's CA:
+
+ puppet certificate_request find mynode.puppetlabs.lan --terminus rest
+ EOT
end
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index 9913fad4b..2722b20f2 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -5,4 +5,26 @@ Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Manage the list of revoked certificates."
+ description <<-EOT
+ This face is primarily for retrieving the certificate revocation
+ list from the CA. Although it exposes search/save/destroy methods,
+ they shouldn't be used under normal circumstances.
+ EOT
+ notes <<-EOT
+ Although the find action must be given an argument, this argument is
+ never read, and can contain the descriptive text of your choice.
+
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `ca`
+ * `file`
+ * `rest`
+ EOT
+ examples <<-EXAMPLES
+ Retrieve the CRL:
+
+ puppet certificate_revocation_list find crl
+ EXAMPLES
end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index fc685202c..9ca41085e 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -4,9 +4,40 @@ Puppet::Face.define(:config, '0.0.1') do
copyright "Puppet Labs", 2011
license "Apache 2 license; see COPYING"
- summary "Interact with Puppet configuration options."
+ summary "Interact with Puppet configuration options"
action(:print) do
+ summary "Examine Puppet's current configuration options"
+ description <<-EOT
+ Prints the value of a single configuration option or a list of
+ configuration options.
+
+ This action is an alternate interface to the information available with
+ `puppet agent --configprint`.
+ EOT
+ notes <<-EOT
+ The return data of this action varies depending on its arguments. When
+ called with "all," `print` will return a complete list of option names
+ and values. When called with a single configuration option name, it will
+ return the value of that option. When called with a list of
+ configuration option names, it will return the corresponding list of
+ option names and values.
+
+ By default, this action retrieves its configuration information in agent
+ mode. To examine the master's configuration, supply Puppet's global
+ `--mode master` option. To examine configurations from a specific
+ environment, you can use the `--environment` option.
+ EOT
+ examples <<-EOT
+ Get puppet's runfile directory:
+
+ puppet config print rundir
+
+ Get a list of important directories from the master's config:
+
+ puppet config print all --mode master | grep -E "(path|dir)"
+ EOT
+
when_invoked do |*args|
options = args.pop
Puppet.settings[:configprint] = args.join(",")
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index 9add63dd0..ecf4e371e 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -6,9 +6,34 @@ Puppet::Indirector::Face.define(:facts, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Retrieve, store, and view facts."
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `active_record`
+ * `couch`
+ * `facter`
+ * `inventory_active_record`
+ * `memory`
+ * `network_device`
+ * `rest`
+ * `yaml`
+ EOT
action(:upload) do
- summary "upload our facts to the server."
+ summary "Upload our facts to the puppet master."
+ description <<-EOT
+ Retrieves facts for the local system and saves them to the puppet master
+ server. This is essentially a shortcut action: it calls the `find`
+ action with the facter terminus, then passes the returned facts object
+ to the `save` action, which uses the rest terminus.
+ EOT
+ notes <<-EOT
+ This action uses the save action, which requires the puppet master's
+ auth.conf to allow save access to the `facts` REST terminus. See
+ `http://docs.puppetlabs.com/guides/rest_auth_conf.html` for more details.
+ EOT
render_as :yaml
diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb
index 1f2fc9f55..707ceafd4 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -5,6 +5,17 @@ Puppet::Indirector::Face.define(:file, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Retrieve and store files in a filebucket"
+ # TK this needs a description of how to find files in a filebucket, and
+ # some good use cases for retrieving/storing them. I can't write either
+ # of these yet.
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `file`
+ * `rest`
+ EOT
set_indirection_name :file_bucket_file
end
diff --git a/lib/puppet/face/help/global.erb b/lib/puppet/face/help/global.erb
index a19ce1fb0..80c77ad26 100644
--- a/lib/puppet/face/help/global.erb
+++ b/lib/puppet/face/help/global.erb
@@ -16,5 +16,4 @@ Available applications, soon to be ported to Faces:
See 'puppet help <subcommand> <action>' for help on a specific subcommand action.
See 'puppet help <subcommand>' for help on a specific subcommand.
-See 'puppet man <subcommand>' for the full man page.
Puppet v<%= Puppet::PUPPETVERSION %>
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index 148dc06c2..67d775ca4 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -4,11 +4,20 @@ Puppet::Indirector::Face.define(:key, '0.0.1') do
copyright "Puppet Labs", 2011
license "Apache 2 license; see COPYING"
- summary "Create, save, and remove certificate keys."
+ summary "Create, save, and remove certificate keys"
description <<-EOT
-Keys are created for you automatically when certificate
-requests are generated with 'puppet certificate generate'.
+ Keys are created for you automatically when certificate requests are
+ generated with 'puppet certificate generate'. You should not have to use
+ this action directly from the command line.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `ca`
+ * `file`
EOT
end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index c4cf30b98..be38ad388 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -3,9 +3,24 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do
copyright "Puppet Labs", 2011
license "Apache 2 license; see COPYING"
- summary "View and manage nodes"
+ summary "View and manage node definitions"
description <<-EOT
-It defaults to using whatever your node terminus is set as.
+ This face interacts with node objects, which are what Puppet uses to
+ build a catalog. A node object consists of the node's facts,
+ environment, additional top-scope variables, and classes.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `active_record`
+ * `exec`
+ * `ldap`
+ * `memory`
+ * `plain`
+ * `rest`
+ * `yaml`
EOT
end
diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb
index c4c3fb55e..e6a9503dd 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -8,6 +8,12 @@ Puppet::Face.define(:parser, '0.0.1') do
summary "Interact directly with the parser"
action :validate do
+ summary "Validate the syntax of one or more Puppet manifests"
+ description <<-EOT
+ This action validates Puppet DSL syntax without compiling a catalog or
+ syncing any resources. If no manifest files are provided, it will
+ validate the default site manifest.
+ EOT
when_invoked do |*args|
args.pop
files = args
diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 8a2559405..969d42389 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -4,13 +4,29 @@ Puppet::Face.define(:plugin, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Interact with the Puppet plugin system"
+ description <<-EOT
+ This face provides network access to the puppet master's store of
+ plugins. It is intended for use in other faces, rather than for direct
+ command line access.
+ EOT
+ notes <<-EOT
+ The puppet master can serve Ruby code collected from the lib directories
+ of its modules. These plugins can be used on agent nodes to extend
+ Facter and implement custom types and providers.
+ EOT
action :download do
summary "Download plugins from the configured master"
returns <<-EOT
- An array containing the files actually downloaded.
- This will be empty array when everything was in sync.
- EOT
+ An array containing the files actually downloaded. If all files
+ were in sync, this array will be empty.
+ EOT
+ notes "This action modifies files on disk without returning any data."
+ examples <<-EOT
+ Retrieve plugins from the puppet master:
+
+ Puppet::Face[:plugin, '0.0.1'].download
+ EOT
when_invoked do |options|
require 'puppet/configurer/downloader'
diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb
index f5b6d08ff..c8549b14f 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -5,8 +5,34 @@ Puppet::Indirector::Face.define(:report, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Create, display, and submit reports"
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `processor`
+ * `rest`
+ * `yaml`
+ EOT
action(:submit) do
+ summary "Submit a report object to the puppet master"
+ description <<-EOT
+ This action is essentially a shortcut and wrapper for the `save` action
+ with a terminus of `rest`. It also can provide additional details in the
+ event of a report submission failure. It is not intended for use from
+ a command line.
+ EOT
+ examples <<-EOT
+ From secret_agent.rb:
+ Puppet::Face[:plugin, '0.0.1'].download
+
+ facts = Puppet::Face[:facts, '0.0.1'].find(certname)
+ catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
+ report = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+
+ Puppet::Face[:report, '0.0.1'].submit(report)
+ EOT
when_invoked do |report, options|
begin
Puppet::Transaction::Report.indirection.terminus_class = :rest
diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb
index 9ded46c0c..ed6360888 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -5,4 +5,19 @@ Puppet::Indirector::Face.define(:resource, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "Interact directly with resources via the RAL, like ralsh"
+ description <<-EOT
+ This face provides a Ruby API with functionality similar to the puppet
+ resource (née ralsh) command line application. It is not intended to be
+ used from the command line.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `ral`
+ * `rest`
+ EOT
+
+ examples "TK we really need some examples for this one."
end
diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb
index 648cf1191..77ccefa8f 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -5,4 +5,13 @@ Puppet::Indirector::Face.define(:resource_type, '0.0.1') do
license "Apache 2 license; see COPYING"
summary "View resource types, classes, and nodes from all manifests"
+ description "TK I have no idea what this does."
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `parser`
+ * `rest`
+ EOT
end
diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb
index 99208b545..c8c8e6629 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -4,10 +4,23 @@ Puppet::Face.define(:secret_agent, '0.0.1') do
copyright "Puppet Labs", 2011
license "Apache 2 license; see COPYING"
- summary "Provides agent-like behavior, with no plugin downloading or reporting."
+ summary "Provides agent-like behavior, with no plugin downloading or reporting"
+ description <<-EOT
+ This face currently functions as a proof of concept, demonstrating how
+ Faces allows the separation of application logic from Puppet's internal
+ systems; compare the code for puppet agent. It will eventually replace
+ puppet agent entirely, and can provide a template for users who wish to
+ implement agent-like functionality with drastically different
+ application logic.
+ EOT
action(:synchronize) do
- summary "run the secret agent, which makes the catalog and system match..."
+ summary "Retrieve and apply a catalog from the puppet master"
+ description <<-EOT
+ This action mimics the behavior of the puppet agent application. It does
+ not currently daemonize, but can download plugins, submit facts,
+ retrieve and apply a catalog, and submit a report to the puppet master.
+ EOT
when_invoked do |options|
Puppet::Face[:plugin, '0.0.1'].download
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 7ef05fa0e..6a29debdd 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -4,5 +4,27 @@ Puppet::Indirector::Face.define(:status, '0.0.1') do
copyright "Puppet Labs", 2011
license "Apache 2 license; see COPYING"
- summary "View status information"
+ summary "View puppet server status"
+ description <<-EOT
+ This subcommand is only useful for determining whether a puppet master
+ server (or an agent node, if puppet was started with the `--listen`
+ option) is responding to requests.
+
+ Only the `find` action is valid. If the server is responding to
+ requests, `find` will retrieve a status object; if not, the connection
+ will be refused. When invoked with the `local` terminus, `find` will
+ always return true.
+
+ If you wish to query a server other than the master configured in
+ puppet.conf, you must set the `--server` and `--masterport` options on
+ the command line.
+ EOT
+ notes <<-EOT
+ This is an indirector face, which exposes find, search, save, and
+ destroy actions for an indirected subsystem of Puppet. Valid terminuses
+ for this face include:
+
+ * `local`
+ * `rest`
+ EOT
end
diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb
index 0fd44dfea..1371c647e 100644
--- a/lib/puppet/indirector/face.rb
+++ b/lib/puppet/indirector/face.rb
@@ -2,10 +2,23 @@ require 'puppet/face'
class Puppet::Indirector::Face < Puppet::Face
option "--terminus TERMINUS" do
- description %q{
-REVISIT: You can select a terminus, which has some bigger effect
-that we should describe in this file somehow.
-}.strip
+ summary "The indirector terminus to use for this action"
+ description <<-EOT
+Indirector faces expose indirected subsystems of Puppet. These
+subsystems are each able to retrieve and alter a specific type of data
+(with the familiar actions of `find`, `search`, `save`, and `destroy`)
+from an arbitrary number of pluggable backends. In Puppet parlance,
+these backends are called terminuses.
+
+Almost all indirected subsystems have a `rest` terminus that interacts
+with the puppet master's data. Most of them have additional terminuses
+for various local data models, which are in turn used by the indirected
+subsystem on the puppet master whenever it receives a remote request.
+
+The terminus for an action is often determined by context, but
+occasionally needs to be set explicitly. See the "Notes" section of this
+face's manpage for more details.
+ EOT
before_action do |action, args, options|
set_terminus(options[:terminus])
@@ -36,23 +49,38 @@ that we should describe in this file somehow.
end
action :destroy do
+ summary "Delete an object"
when_invoked { |key, options| call_indirection_method(:destroy, key, options) }
end
action :find do
+ summary "Retrieve an object by name"
when_invoked { |key, options| call_indirection_method(:find, key, options) }
end
action :save do
+ summary "Create or modify an object"
+ notes <<-EOT
+ Save actions cannot currently be invoked from the command line, and are
+ for API use only.
+ EOT
when_invoked { |key, options| call_indirection_method(:save, key, options) }
end
action :search do
+ summary "Search for an object"
when_invoked { |key, options| call_indirection_method(:search, key, options) }
end
# Print the configuration for the current terminus class
action :info do
+ summary "Print the default terminus class for this face"
+ description <<-EOT
+ TK So this is per-face, right? No way to tell what the default terminus
+ is per-action, for subsystems that switch to REST for save but query
+ locally for find?
+ EOT
+
when_invoked do |*args|
if t = indirection.terminus_class
puts "Run mode '#{Puppet.run_mode.name}': #{t}"
generated by cgit (git 2.34.1) at 2025-09-19 02:02:39 +0000