diff options
Diffstat (limited to 'lib/puppet')
27 files changed, 844 insertions, 373 deletions
diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb index 4624313bc..13351540a 100644 --- a/lib/puppet/face/catalog.rb +++ b/lib/puppet/face/catalog.rb @@ -5,46 +5,44 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do license "Apache 2 license; see COPYING" summary "Compile, save, view, and convert catalogs." - description <<-EOT + 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 `--terminus rest`. You can also choose to print any catalog + 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 + + get_action(:destroy).summary "Invalid for this face." + get_action(:search).summary "Query format unknown; potentially invalid for this face." action(:apply) do - 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." + summary "Apply a Puppet::Resource::Catalog object." + description <<-'EOT' + Finds and applies a catalog. This action takes no arguments, but + the source of the catalog can be managed with the --terminus option. EOT - notes <<-EOT - This action returns a Puppet::Transaction::Report object. + returns <<-'EOT' + A Puppet::Transaction::Report object. EOT - examples <<-EOT - From `secret_agent.rb`: + examples <<-'EOT' + Apply the locally cached catalog: - Puppet::Face[:plugin, '0.0.1'].download + $ puppet catalog apply --terminus yaml + + Retrieve a catalog from the master and apply it, in one step: - 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 catalog apply --terminus rest - Puppet::Face[:report, '0.0.1'].submit(report) + From `secret_agent.rb` (API example): + + # ... + Puppet::Face[:catalog, '0.0.1'].download + # (Termini are singletons; catalog.download has a side effect of + # setting the catalog terminus to yaml) + report = Puppet::Face[:catalog, '0.0.1'].apply + # ... EOT when_invoked do |options| @@ -71,23 +69,33 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do end action(:download) do - 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. + summary "Download this node's catalog from the puppet master server." + description <<-'EOT' + Retrieves a catalog from the puppet master and saves it to the + local yaml cache. The saved catalog can be used in subsequent + catalog actions by specifying '--terminus rest'. + + This action always contacts the puppet master and will ignore + alternate termini. + EOT + returns "Nothing." + notes <<-'EOT' + As termini are singletons, this action has a side effect of + exporting Puppet::Resource::Catalog.indirection.terminus_class = + yaml to the calling context when used with the Ruby Faces API. The + terminus must be explicitly re-set for subsequent catalog actions. EOT - notes "This action returns a Puppet::Resource::Catalog object." - examples <<-EOT - From `secret_agent.rb`: + examples <<-'EOT' + Retrieve and store a catalog: - Puppet::Face[:plugin, '0.0.1'].download + $ puppet catalog 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) + From `secret_agent.rb` (API example): - Puppet::Face[:report, '0.0.1'].submit(report) + Puppet::Face[:plugin, '0.0.1'].download + Puppet::Face[:facts, '0.0.1'].upload + Puppet::Face[:catalog, '0.0.1'].download + # ... EOT when_invoked do |options| Puppet::Resource::Catalog.indirection.terminus_class = :rest diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb index a6c97a627..d86963e75 100644 --- a/lib/puppet/face/catalog/select.rb +++ b/lib/puppet/face/catalog/select.rb @@ -2,21 +2,28 @@ 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 + arguments "<host> <resource_type>" + returns <<-'EOT' + An array of resource objects excised from a catalog. When used at + the command line, returns a list of resource references (Type[title]). + EOT + 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. + resources of the given type. 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. - + notes <<-'NOTES' 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. + + FORMATTING ISSUES: This action cannot currently render useful yaml; + instead, it returns an entire catalog. Use json instead. NOTES + examples <<-'EOT' + Ask the puppet master for a list of managed file resources for a node: + + $ puppet catalog select --terminus rest somenode.magpie.lan file + EOT 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 859946623..cab8817e3 100644 --- a/lib/puppet/face/certificate.rb +++ b/lib/puppet/face/certificate.rb @@ -6,26 +6,17 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do license "Apache 2 license; see COPYING" summary "Provide access to the CA for certificate management" - description <<-EOT + 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, + 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 + 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 @@ -36,16 +27,23 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do end action :generate do - summary "Generate a new certificate signing request for HOST" - description <<-EOT + summary "Generate a new certificate signing request for HOST." + arguments "<host>" + returns "Nothing." + 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 + specified host. 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 + Puppet agent usually handles CSR submission automatically. This action is primarily useful for requesting certificates for individual users and external applications. EOT + examples <<-'EOT' + Request a certificate for "somenode" from the site's CA: + + $ puppet certificate generate somenode.puppetlabs.lan --ca-location remote + EOT when_invoked do |name, options| host = Puppet::SSL::Host.new(name) @@ -55,7 +53,11 @@ 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." + returns <<-'EOT' + An array of CSR object #inspect strings. This output is currently messy, + but does contain the names of nodes requesting certificates. + EOT when_invoked do |options| Puppet::SSL::Host.indirection.search("*", { @@ -65,7 +67,17 @@ 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." + arguments "<host>" + returns <<-'EOT' + A string that appears to be an x509 certificate, but is actually + not. Retrieve certificates using the `find` action. + EOT + examples <<-'EOT' + Sign somenode.puppetlabs.lan's certificate: + + $ puppet certificate sign somenode.puppetlabs.lan --ca-location remote + EOT when_invoked do |name, options| host = Puppet::SSL::Host.new(name) @@ -73,4 +85,27 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do Puppet::SSL::Host.indirection.save(host) end end + + # Indirector action doc overrides + find = get_action(:find) + find.summary "Retrieve a certificate" + find.arguments "<host>" + find.returns <<-'EOT' + An x509 SSL certificate. You will usually want to render this as a + string ('--render-as s'). + + Note that this action has a side effect of caching a copy of the + certificate in Puppet's `ssldir`. + EOT + + destroy = get_action(:destroy) + destroy.summary "Delete a local certificate." + destroy.arguments "<host>" + destroy.returns "Nothing." + destroy.description <<-'EOT' + Deletes a certificate. This action currently only works with a local CA. + EOT + + get_action(:search).summary "Invalid for this face." + get_action(:save).summary "Invalid for this face." end diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb index cc6021517..29cf7dc78 100644 --- a/lib/puppet/face/certificate_request.rb +++ b/lib/puppet/face/certificate_request.rb @@ -5,28 +5,41 @@ Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do license "Apache 2 license; see COPYING" summary "Manage certificate requests." - description <<-EOT + description <<-'EOT' Retrieves and submits certificate signing requests (CSRs). Invoke - `search` with an unread key to retrieve all outstanding CSRs, invoke + `search` with a dummy 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 + # Per-action doc overrides + get_action(:destroy).summary "Invalid for this face." + get_action(:find).summary "Retrieve a single CSR." + get_action(:find).arguments "<host>" + get_action(:find).returns <<-'EOT' + A single certificate request. In most cases, you will want to render + this as a string ('--render-as s'). + EOT + get_action(:find).examples <<-'EOT' Retrieve a single CSR from the puppet master's CA: - puppet certificate_request find mynode.puppetlabs.lan --terminus rest + $ puppet certificate_request find somenode.puppetlabs.lan --terminus rest + EOT + + get_action(:search).summary "Retrieve all outstanding CSRs." + get_action(:search).arguments "<dummy_key>" + get_action(:search).returns <<-'EOT' + An array of certificate request objects. In most cases, you will + want to render this as a string ('--render-as s'). EOT + get_action(:search).notes "This action always returns all CSRs, but requires a dummy search key." + get_action(:search).examples <<-'EOT' + Retrieve all CSRs from the local CA: + + $ puppet certificate_request search x --terminus ca + EOT + + get_action(:save).summary "Submit a certificate signing request." + get_action(:save).arguments "<x509_CSR>" end diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb index 2722b20f2..0525a601f 100644 --- a/lib/puppet/face/certificate_revocation_list.rb +++ b/lib/puppet/face/certificate_revocation_list.rb @@ -5,26 +5,35 @@ 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 + 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` + get_action(:find).summary "Retrieve the certificate revocation list." + get_action(:find).arguments "<dummy_key>" + get_action(:find).returns <<-'EOT' + A certificate revocation list. You will usually want to render this + as a string ('--render-as s'). EOT - examples <<-EXAMPLES - Retrieve the CRL: + get_action(:find).examples <<-'EXAMPLES' + Retrieve a copy of the puppet master's CRL: - puppet certificate_revocation_list find crl + $ puppet certificate_revocation_list find crl --terminus rest EXAMPLES + + get_action(:destroy).summary "Delete the certificate revocation list." + get_action(:destroy).arguments "<dummy_key>" + get_action(:destroy).returns "Nothing." + get_action(:destroy).description <<-'EOT' + Deletes the certificate revocation list. This cannot be done over + REST, but it is possible to both delete the locally cached copy of + the CA's CRL and delete the CA's own copy (if running on the CA + machine and invoked with '--terminus ca'). Needless to say, don't do + this unless you know what you're up to. + EOT + + get_action(:search).summary "Invalid for this face." + get_action(:save).summary "Invalid for this face." end diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb index 9ca41085e..6e5bff071 100644 --- a/lib/puppet/face/config.rb +++ b/lib/puppet/face/config.rb @@ -4,38 +4,37 @@ 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's configuration options." action(:print) do - summary "Examine Puppet's current configuration options" - description <<-EOT + summary "Examine Puppet's current configuration options." + arguments "(all | <option> [<option> ...]" + returns <<-'EOT' + When called with one option: a single value. + + When called with "all" or multiple options: a list of options and + their values. + EOT + 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`. + `puppet <subcommand> --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. + notes <<-'EOT' + By default, this action reads the configuration in agent mode. + Use the '--mode' and '--environment' flags to examine other + configuration domains. EOT - examples <<-EOT + examples <<-'EOT' Get puppet's runfile directory: - puppet config print rundir + $ 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)" + $ puppet config print all --mode master | grep -E "(path|dir)" EOT when_invoked do |*args| diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb index ecf4e371e..05028a435 100644 --- a/lib/puppet/face/facts.rb +++ b/lib/puppet/face/facts.rb @@ -5,34 +5,59 @@ Puppet::Indirector::Face.define(:facts, '0.0.1') do copyright "Puppet Labs", 2011 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` + summary "Retrieve and store facts." + description <<-'EOT' + This face manages facts, the collections of normalized system + information used by Puppet. It can read facts directly from the + local system (using the default `facter` terminus), look up facts + reported by other systems, and submit facts to the puppet master. + + When used with the `rest` terminus, this face is essentially a + front-end to the inventory service REST API. See the inventory + service documentation for more detail. + EOT + + find = get_action(:find) + find.summary "Retrieve a host's facts." + find.arguments "<host>" + find.returns "A Puppet::Node::Facts object." + find.notes <<-'EOT' + When using the `facter` terminus, the host argument is essentially ignored. + EOT + find.examples <<-'EOT' + Get facts from the local system: + + $ puppet facts find x + + Ask the puppet master for facts for an arbitrary node: + + $ puppet facts find somenode.puppetlabs.lan --terminus rest + + Query a DB-backed inventory directly (bypassing the REST API): + + $ puppet facts find somenode.puppetlabs.lan --terminus inventory_active_record --mode master EOT + get_action(:destroy).summary "Invalid for this face." + get_action(:search).summary "Query format unknown; potentially invalid for this face." + action(:upload) do - 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. + summary "Upload local facts to the puppet master." + description <<-'EOT' + Reads facts from the local system using the facter terminus, then + saves the returned facts using the rest terminus. + EOT + returns "Nothing." + notes <<-'EOT' + This action requires that the puppet master's `auth.conf` file + allow save access to the `facts` REST terminus. Puppet agent does + not use this facility, and it is turned off by default. See + <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details. 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. + examples <<-'EOT' + Upload facts: + + $ puppet facts upload EOT render_as :yaml diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb index 707ceafd4..1cf9bc7f3 100644 --- a/lib/puppet/face/file.rb +++ b/lib/puppet/face/file.rb @@ -5,17 +5,43 @@ 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` + description <<-'EOT' + This face interacts with objects stored in a local or remote + filebucket. File objects are accessed by their MD5 sum; see the + examples for the relevant syntax. EOT + notes <<-'EOT' + To retrieve the unmunged contents of a file, you must call find with + --render-as s. Rendering as yaml will return a hash of metadata + about the file, including its contents. + + This face does not interact with the `clientbucketdir` (the default + local filebucket for puppet agent); it interacts with the primary + "master"-type filebucket located in the `bucketdir`. If you wish to + interact with puppet agent's default filebucket, you'll need to set + the <--bucketdir> option appropriately when invoking actions. + EOT + + file = get_action(:find) + file.summary "Retrieve a file from the filebucket." + file.arguments "md5/<md5sum>" + file.returns <<-'EOT' + The file object with the specified checksum. + + RENDERING ISSUES: Rendering as a string returns the contents of the + file object; rendering as yaml returns a hash of metadata about said + file, including but not limited to its contents. Rendering as json + is currently broken, and returns a hash containing only the contents + of the file. + EOT + file.examples <<-'EOT' + Retrieve the contents of a file: + + $ puppet file find md5/9aedba7f413c97dc65895b1cd9421f2c --render-as s + EOT + + get_action(:search).summary "Invalid for this face." + get_action(:destroy).summary "Invalid for this face." set_indirection_name :file_bucket_file end diff --git a/lib/puppet/face/file/download.rb b/lib/puppet/face/file/download.rb index f5413d493..8a300fbf1 100644 --- a/lib/puppet/face/file/download.rb +++ b/lib/puppet/face/file/download.rb @@ -1,6 +1,24 @@ # Download a specified file into the local filebucket. Puppet::Face.define(:file, '0.0.1') do action :download do |*args| + summary "Download a file into the local filebucket." + arguments "( {md5}<checksum> | puppet:///... )" + returns "Nothing" + description <<-EOT + Downloads a file from the puppet master's filebucket and + duplicates it in the local filebucket. This action's checksum + syntax differs from `find`'s, and it can accept a <puppet:///> URL. + EOT + examples <<-'EOT' + Download a file by URL: + + $ puppet file download puppet:///modules/editors/vim/.vimrc + + Download a file by MD5 sum: + + $ puppet file download {md5}8f798d4e754db0ac89186bbaeaf0af18 + EOT + when_invoked do |sum, options| if sum =~ /^puppet:\/\// # it's a puppet url require 'puppet/file_serving' diff --git a/lib/puppet/face/file/store.rb b/lib/puppet/face/file/store.rb index 4c9523b6c..97dbd86b4 100644 --- a/lib/puppet/face/file/store.rb +++ b/lib/puppet/face/file/store.rb @@ -1,6 +1,15 @@ # Store a specified file in our filebucket. Puppet::Face.define(:file, '0.0.1') do action :store do |*args| + summary "Store a file in the local filebucket." + arguments "<file>" + returns "Nothing." + examples <<-EOT + Store a file: + + $ puppet file store /root/.bashrc + EOT + when_invoked do |path, options| file = Puppet::FileBucket::File.new(File.read(path)) diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb index aef917447..9376adf04 100644 --- a/lib/puppet/face/help.rb +++ b/lib/puppet/face/help.rb @@ -7,13 +7,20 @@ Puppet::Face.define(:help, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Displays help about puppet subcommands" + summary "Display Puppet help." action(:help) do summary "Display help about faces and their actions." + arguments "[<face>] [<action>]" + returns "Short help text for the specified face or action." + examples <<-'EOT' + Get help for an action: + + $ puppet help + EOT option "--version VERSION" do - summary "which version of the interface to show help for" + summary "The version of the face for which to show help." end default @@ -88,7 +95,7 @@ Puppet::Face.define(:help, '0.0.1') do def erb(name) template = (Pathname(__FILE__).dirname + "help" + name) - erb = ERB.new(template.read, nil, '%') + erb = ERB.new(template.read, nil, '-') erb.filename = template.to_s return erb end diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb index c26958a35..c788f34fd 100644 --- a/lib/puppet/face/help/action.erb +++ b/lib/puppet/face/help/action.erb @@ -1,48 +1,57 @@ -puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %>(1) -- <%= action.summary || face.summary %> -<%= '=' * (_erbout.length - 1) %> +<%= action.summary || face.summary || "unknown face..." %> -% if action.synopsis -SYNOPSIS --------- +<% if action.synopsis -%> +USAGE: <%= action.synopsis %> -<%= action.synopsis %> +<% end -%> +<% if action.short_description -%> +<%= action.short_description.strip %> -% end -% if action.description -DESCRIPTION ------------ -<%= action.description %> +<% end -%> +<% if action.returns -%> +RETURNS: <%= action.returns.strip %> -%end -% unless action.options.empty? -OPTIONS -------- -% action.options.sort.each do |name| -% option = action.get_option name -<%= " " + option.optparse.join(" |" ) %> +<% end -%> +OPTIONS: +<%# Remove these options once we can introspect them normally. -%> + --mode MODE - The run mode to use (`user`, `agent`, or + `master`). + --render-as FORMAT - The rendering format to use. + --verbose - Whether to log verbosely. + --debug - Whether to log debug information. +<% unless action.options.empty? + optionroom = 30 + summaryroom = 80 - 5 - optionroom + action.options.sort.each do |name| + option = action.get_option name -%> +<%= " " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%> +<% if !(option.summary) -%> +unknown option... +<% elsif option.summary.length <= summaryroom -%> <%= option.summary %> -<%= option.description %> +<% + else + words = option.summary.split + wrapped = [''] + i = 0 + words.each do |word| + if wrapped[i].length + word.length <= summaryroom + wrapped[i] << word + ' ' + else + i += 1 + wrapped[i] = word + ' ' + end + end +-%> +<%= wrapped.shift.strip %> +<% wrapped.each do |line| -%> +<%= (' ' * (optionroom + 5) ) + line.strip %> +<% end + end + end -%> +<% end -%> -% end -% end -% if action.examples -EXAMPLES --------- +<% if action.examples -%> +EXAMPLES: <%= action.examples %> -% end -% if action.notes -NOTES ------ -<%= action.notes %> - -% end -% unless action.authors.empty? -AUTHOR ------- -<%= action.authors.map {|x| " * " + x } .join("\n") %> - -%end -COPYRIGHT AND LICENSE ---------------------- -<%= action.copyright %> -<%= action.license %> +<% end -%> diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb index b249981de..2a0f0181c 100644 --- a/lib/puppet/face/help/face.erb +++ b/lib/puppet/face/help/face.erb @@ -1,48 +1,91 @@ -NAME - <%= face.name %> -- <%= face.summary || "unknown face..." %> +<%= face.summary || "unknown face..." %> -% if face.synopsis -SYNOPSIS -<%= face.synopsis.gsub(/^/, ' ') %> +<% if face.synopsis -%> +USAGE: <%= face.synopsis %> -% end -% if face.description -DESCRIPTION -<%= face.description.chomp.gsub(/^/, ' ') %> +<% end -%> +<% if face.short_description -%> +<%= face.short_description %> -%end -% unless face.options.empty? -OPTIONS -% face.options.sort.each do |name| -% option = face.get_option name -<%= " " + option.optparse.join(" |" ) %> +<% end -%> +OPTIONS: +<%# Remove these options once we can introspect them normally. -%> + --mode MODE - The run mode to use (`user`, `agent`, or + `master`). + --render-as FORMAT - The rendering format to use. + --verbose - Whether to log verbosely. + --debug - Whether to log debug information. +<% unless face.options.empty? + optionroom = 30 + summaryroom = 80 - 5 - optionroom + face.options.sort.each do |name| + option = face.get_option name -%> +<%= " " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%> +<% if !(option.summary) -%> +unknown option... +<% elsif option.summary.length <= summaryroom -%> <%= option.summary %> -<%= option.description %> +<% + else + words = option.summary.split + wrapped = [''] + i = 0 + words.each do |word| + if wrapped[i].length + word.length <= summaryroom + wrapped[i] << word + ' ' + else + i += 1 + wrapped[i] = word + ' ' + end + end +-%> +<%= wrapped.shift.strip %> +<% wrapped.each do |line| -%> +<%= (' ' * (optionroom + 5) ) + line.strip %> +<% end + end + end -%> +<% end -%> -% end -% end -ACTIONS -% padding = face.actions.map{|x| x.to_s.length}.max + 2 -% face.actions.each do |actionname| -% action = face.get_action(actionname) - <%= action.name.to_s.ljust(padding) %> <%= action.summary %> -% end +ACTIONS: +<% padding = face.actions.map{|x| x.to_s.length}.max + 2 + summaryroom = 80 - (padding + 4) + face.actions.each do |actionname| + action = face.get_action(actionname) -%> + <%= action.name.to_s.ljust(padding) + ' ' -%> +<% if !(action.summary) -%> +unknown action... +<% elsif action.summary.length <= summaryroom -%> +<%= action.summary %> +<% else + words = action.summary.split + wrapped = [''] + i = 0 + words.each do |word| + if wrapped[i].length + word.length <= summaryroom + wrapped[i] << word + ' ' + else + i += 1 + wrapped[i] = word + ' ' + end + end +-%> +<%= wrapped.shift.strip %> +<% wrapped.each do |line| -%> +<%= (' ' * (padding + 4) ) + line.strip %> +<% end + end +end -%> -% if face.examples -EXAMPLES -<%= face.examples %> -% end -% if face.notes -NOTES -<%= face.notes %> +<% if face.respond_to? :indirection -%> +TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %> -% end -% unless face.authors.empty? +<% end + unless face.authors.empty? -%> AUTHOR <%= face.authors.join("\n").gsub(/^/, ' * ') %> -%end -COPYRIGHT AND LICENSE +<% end -%> +COPYRIGHT AND LICENSE: <%= face.copyright.gsub(/^/, ' ') %> <%= face.license.gsub(/^/, ' ') %> - diff --git a/lib/puppet/face/help/global.erb b/lib/puppet/face/help/global.erb index 80c77ad26..c5a9ec9e0 100644 --- a/lib/puppet/face/help/global.erb +++ b/lib/puppet/face/help/global.erb @@ -1,18 +1,18 @@ Usage: puppet <subcommand> [options] <action> [options] Available subcommands, from Puppet Faces: -% Puppet::Face.faces.sort.each do |name| -% face = Puppet::Face[name, :current] +<% Puppet::Face.faces.sort.each do |name| + face = Puppet::Face[name, :current] -%> <%= face.name.to_s.ljust(16) %> <%= face.summary %> -% end +<% end -%> -% unless legacy_applications.empty? then # great victory when this is true! +<% unless legacy_applications.empty? then # great victory when this is true! -%> Available applications, soon to be ported to Faces: -% legacy_applications.each do |appname| -% summary = horribly_extract_summary_from appname +<% legacy_applications.each do |appname| + summary = horribly_extract_summary_from appname -%> <%= appname.to_s.ljust(16) %> <%= summary %> -% end -% end +<% end + end -%> See 'puppet help <subcommand> <action>' for help on a specific subcommand action. See 'puppet help <subcommand>' for help on a specific subcommand. diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb new file mode 100644 index 000000000..899d0166c --- /dev/null +++ b/lib/puppet/face/help/man.erb @@ -0,0 +1,133 @@ +puppet-<%= face.name %>(8) -- <%= face.summary || "Unknown face." %> +<%= '=' * (_erbout.length - 1) %> + +<% if face.synopsis -%> +SYNOPSIS +-------- +<%= face.synopsis %> + +<% end + if face.description -%> +DESCRIPTION +----------- +<%= face.description.strip %> + +<% end -%> +OPTIONS +------- +Note that any configuration parameter that's valid in the configuration +file is also a valid long argument, although it may or may not be +relevant to the present action. 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 with +`--genconfig`. + +* --mode MODE: + The run mode to use for the current action. Valid modes are `user`, `agent`, + and `master`. +* --render-as FORMAT: + The format in which to render output. The most common formats are `json`, + `s` (string), and `yaml`, but other options such as `dot` are + sometimes available. +* --verbose: + Whether to log verbosely. +* --debug: + Whether to log debug information. +<% unless face.options.empty? + face.options.sort.each do |name| + option = face.get_option name -%> +<%= "* " + option.optparse.join(" | " ) %>: +<%= option.description.gsub(/^/, ' ') || ' ' + option.summary %> +<% end + end -%> + +ACTIONS +------- +<% face.actions.each do |actionname| + action = face.get_action(actionname) -%> +* `<%= action.name.to_s %>` - <%= action.summary %>: +<% if action.synopsis -%> + `SYNOPSIS` + + <%= action.synopsis %> + +<% end -%> +<% if action.description -%> + `DESCRIPTION` + +<%= action.description.gsub(/^/, ' ') %> +<% end + unique_options = action.options - face.options + unless unique_options.empty? -%> + `OPTIONS` + +<% unique_options.sort.each do |name| + option = action.get_option name + text = option.description || option.summary -%> + <%= '<' + option.optparse.join("> | <") + '>' %> - +<%= text.gsub(/^/, ' ') %> +<% end -%> + +<% end -%> +<% if action.returns -%> + `RETURNS` + +<%= action.returns.gsub(/^/, ' ') %> + +<% end + if action.notes -%> + `NOTES` + +<%= action.notes.gsub(/^/, ' ') %> + +<% end + end + if face.examples or face.actions.any? {|actionname| face.get_action(actionname).examples} -%> +EXAMPLES +-------- +<% end + if face.examples -%> +<%= face.examples %> + +<% end + face.actions.each do |actionname| + action = face.get_action(actionname) + if action.examples -%> +`<%= action.name.to_s %>` + +<%= action.examples.strip %> +<% end + end -%> + +<% if face.notes or face.respond_to? :indirection -%> +NOTES +----- +<% if face.notes -%> +<%= face.notes.strip %> + +<% end # notes +if face.respond_to? :indirection -%> +This is an indirector face, which exposes `find`, `search`, `save`, and +`destroy` actions for an indirected subsystem of Puppet. Valid termini +for this face include: + +* `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>` + +<% end # indirection + end # notes or indirection + unless face.authors.empty? -%> +AUTHOR +------ +<%= face.authors.join("\n").gsub(/^/, ' * ') %> + +<% end -%> +COPYRIGHT AND LICENSE +--------------------- +<%= face.copyright %> +<%= face.license %> + diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb index 67d775ca4..54c4975c5 100644 --- a/lib/puppet/face/key.rb +++ b/lib/puppet/face/key.rb @@ -4,20 +4,12 @@ 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" - - description <<-EOT - 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` + summary "Create, save, and remove certificate keys." + description <<-'EOT' + Manages certificate private keys. Keys are created for you + automatically when certificate requests are generated with 'puppet + certificate generate', and it should not be necessary to use this action + directly. EOT end diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb index be38ad388..d244127a4 100644 --- a/lib/puppet/face/node.rb +++ b/lib/puppet/face/node.rb @@ -3,24 +3,35 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "View and manage node definitions" - - description <<-EOT - This face interacts with node objects, which are what Puppet uses to + summary "View and manage node definitions." + description <<-'EOT' + This face interacts with node objects, which are used by Puppet to build a catalog. A node object consists of the node's facts, - environment, additional top-scope variables, and classes. + environment, node parameters (exposed in the parser as 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` + get_action(:destroy).summary "Invalid for this face." + get_action(:search).summary "Invalid for this face." + get_action(:save).summary "Invalid for this face." + + find = get_action(:find) + find.summary "Retrieve a node object." + find.arguments "<host>" + find.returns <<-'EOT' + A Puppet::Node object. + + RENDERING ISSUES: Rendering as string and json are currently broken; + node objects can only be rendered as yaml. + EOT + find.examples <<-'EOT' + Retrieve an "empty" (no classes, fact and bulit-in parameters only, + and an environment of "production") node: + + $ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml + + Retrieve a node using the puppet master's configured ENC: + + $ puppet node find somenode.puppetlabs.lan --terminus exec --mode master --render-as yaml EOT end diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb index e6a9503dd..8dd3efb75 100644 --- a/lib/puppet/face/parser.rb +++ b/lib/puppet/face/parser.rb @@ -5,11 +5,13 @@ Puppet::Face.define(:parser, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Interact directly with the parser" + summary "Interact directly with the parser." action :validate do - summary "Validate the syntax of one or more Puppet manifests" - description <<-EOT + summary "Validate the syntax of one or more Puppet manifests." + arguments "[<manifest>] [<manifest> ...]" + returns "Nothing, or the first syntax error encountered." + 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. diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb index 969d42389..541468d39 100644 --- a/lib/puppet/face/plugin.rb +++ b/lib/puppet/face/plugin.rb @@ -3,29 +3,36 @@ Puppet::Face.define(:plugin, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Interact with the Puppet plugin system" - description <<-EOT + 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. + plugins. EOT - notes <<-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. If all files - were in sync, this array will be empty. + summary "Download plugins from the puppet master." + description <<-'EOT' + Downloads plugins from the configured puppet master. Any plugins + downloaded in this way will be used in all subsequent Puppet activity. EOT - notes "This action modifies files on disk without returning any data." - examples <<-EOT + returns <<-'EOT' + A display-formatted list of the files downloaded. If all plugin + files were in sync, this list will be empty. + EOT + notes "This action modifies files on disk." + examples <<-'EOT' Retrieve plugins from the puppet master: - Puppet::Face[:plugin, '0.0.1'].download + $ puppet plugin download + + Retrieve plugins from the puppet master (API example): + + $ Puppet::Face[:plugin, '0.0.1'].download EOT when_invoked do |options| diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb index c8549b14f..1345d6359 100644 --- a/lib/puppet/face/report.rb +++ b/lib/puppet/face/report.rb @@ -5,33 +5,42 @@ 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` + get_action(:find).summary "Invalid for this face." + get_action(:search).summary "Invalid for this face." + get_action(:destroy).summary "Invalid for this face." + save = get_action(:save) + save.summary "Submit a report." + save.arguments "<report>" + save.returns "Nothing." + save.examples <<-'EOT' + From the implementation of `puppet report submit` (API example): + + begin + Puppet::Transaction::Report.indirection.terminus_class = :rest + Puppet::Face[:report, "0.0.1"].save(report) + Puppet.notice "Uploaded report for #{report.name}" + rescue => detail + puts detail.backtrace if Puppet[:trace] + Puppet.err "Could not send report: #{detail}" + end EOT action(:submit) do summary "Submit a report object to the puppet master" - description <<-EOT + 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 + with the `rest` terminus, which provides additional details in the event of a report submission failure. It is not intended for use from a command line. EOT - examples <<-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) + # ... + report = Puppet::Face[:catalog, '0.0.1'].apply Puppet::Face[:report, '0.0.1'].submit(report) + return report EOT when_invoked do |report, options| begin diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb index 87e587624..59f628675 100644 --- a/lib/puppet/face/resource.rb +++ b/lib/puppet/face/resource.rb @@ -5,19 +5,47 @@ 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 + description <<-'EOT' This face provides a Ruby API with functionality similar to the puppet resource (originally 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` + get_action(:destroy).summary "Invalid for this face." + + search = get_action(:search) + search.summary "Get all resources of a single type." + search.arguments "<resource_type>" + search.returns "An array of resource objects." + search.examples <<-'EOT' + Get a list of all user resources (API example): + + all_users = Puppet::Face[:resource, '0.0.1'].search("user") + EOT + + find = get_action(:find) + find.summary "Get a single resource." + find.arguments "<type>/<title>" + find.returns "A resource object." + find.examples <<-'EOT' + Print information about a user on this system (API example): + + puts Puppet::Face[:resource, '0.0.1'].find("user/luke").to_pson EOT - examples "TK we really need some examples for this one." + save = get_action(:save) + save.summary "Create a new resource." + save.arguments "<resource_object>" + save.returns "The same resource object passed." + save.examples <<-'EOT' + Create a new file resource (API example): + + my_resource = Puppet::Resource.new( + :file, + "/tmp/demonstration", + :parameters => {:ensure => :present, :content => "some\nthing\n"} + ) + + Puppet::Face[:resource, '0.0.1'].save(my_resource) + EOT end diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb index 77ccefa8f..9d7639fc5 100644 --- a/lib/puppet/face/resource_type.rb +++ b/lib/puppet/face/resource_type.rb @@ -4,14 +4,67 @@ Puppet::Indirector::Face.define(:resource_type, '0.0.1') do copyright "Puppet Labs", 2011 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` + summary "View classes, defined resource types, and nodes from all manifests" + description <<-'EOT' + This face reads information about the resource collections (classes, + nodes, and defined types) available in Puppet's site manifest and + modules. + + It will eventually be extended to examine native resource types. + EOT + + # Action documentation overrides: + get_action(:save).summary = "Invalid for this face." + get_action(:destroy).summary = "Invalid for this face." + + find = get_action(:find) + find.summary "Retrieve info about a resource collection." + find.arguments "<collection_name>" + find.returns <<-'EOT' + A hash of info about one resource collection. This hash will include the + following four keys: + + * `file` (a string) + * `name` (a string) + * `type` (<hostclass>, <definition>, or <node>) + * `line` (an integer) + + It may also include the following keys: + + * `parent` (<name_of_resource_collection>) + * `arguments` (a hash of parameters and default values) + * `doc` (a string) + + RENDERING ISSUES: yaml and string output for this indirection are + currently unusable; use json instead. + EOT + find.examples <<-'EOT' + Retrieve info about a specific locally-defined class: + + $ puppet resource_type find ntp::disabled + + Retrieve info from the puppet master about a specific class: + + $ puppet resource_type find ntp --terminus rest + EOT + + search = get_action(:search) + search.summary "Search for collections matching a regular expression." + search.arguments "<regular_expression>" + search.returns <<-'EOT' + An array of resource collection info hashes. (See "RETURNS" under `find`.) + + RENDERING ISSUES: yaml and string output for this indirection are + currently unusable; use json instead. EOT + search.examples <<-'EOT' + Retrieve all classes, nodes, and defined types: + + $ puppet resource_type search '.*' + + Search for classes related to Nagios: + + $ puppet resource_type search nagios + EOT + end diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb index c8c8e6629..105850cd3 100644 --- a/lib/puppet/face/secret_agent.rb +++ b/lib/puppet/face/secret_agent.rb @@ -4,22 +4,36 @@ 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" - 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. + summary "Mimics puppet agent." + 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 actual 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 + non-standard application logic. EOT action(:synchronize) do - 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. + summary "Run secret_agent once." + arguments "[-v | --verbose] [-d | --debug]" # Remove this once options are introspectible + description <<-'EOT' + This action mimics a single run 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 + returns "A Puppet::Transaction::Report object." + examples <<-'EOT' + Trigger a Puppet run with the configured puppet master: + + $ puppet secret_agent + EOT + notes <<-'EOT' + This action requires that the puppet master's `auth.conf` file + allow save access to the `facts` REST terminus. Puppet agent does + not use this facility, and it is turned off by default. See + <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details. EOT when_invoked do |options| diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb index 6a29debdd..4ae24e81b 100644 --- a/lib/puppet/face/status.rb +++ b/lib/puppet/face/status.rb @@ -4,27 +4,36 @@ Puppet::Indirector::Face.define(:status, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - 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. + summary "View puppet server status." - 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. + get_action(:destroy).summary "Invalid for this face." + get_action(:save).summary "Invalid for this face." + get_action(:search).summary "Invalid for this face." - 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. + find = get_action(:find) + find.summary "Check status of puppet master server." + find.arguments "<dummy_key>" + find.returns "A Puppet::Status object, or a low-level connection error." + find.description <<-'EOT' + Checks whether a Puppet server is properly receiving and processing + REST requests. This action is only useful when used with '--terminus + rest'; when invoked with the `local` terminus, `find` will always + return true. + + This action will query the configured puppet master. To query other + servers, including puppet agent nodes started with the --listen + option, you can set set the global --server and --masterport options + on the command line; note that agent nodes listen on port 8139. + EOT + find.notes <<-'EOT' + This action requires that the server's `auth.conf` file allow find + access to the `status` REST terminus. Puppet agent does not use this + facility, and it is turned off by default. See + <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details. 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: + find.examples <<-'EOT' + Check the status of the configured puppet master: - * `local` - * `rest` + $ puppet status find x --terminus rest EOT end diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb index 1371c647e..f6c36e31d 100644 --- a/lib/puppet/indirector/face.rb +++ b/lib/puppet/indirector/face.rb @@ -2,22 +2,22 @@ require 'puppet/face' class Puppet::Indirector::Face < Puppet::Face option "--terminus TERMINUS" do - summary "The indirector terminus to use for this action" + 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. + 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| @@ -49,36 +49,39 @@ face's manpage for more details. end action :destroy do - summary "Delete an object" + summary "Delete an object." + arguments "<key>" when_invoked { |key, options| call_indirection_method(:destroy, key, options) } end action :find do - summary "Retrieve an object by name" + summary "Retrieve an object by name." + arguments "<key>" 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. + summary "Create or overwrite an object." + arguments "<object>" + description <<-EOT + Create or overwrite an object. 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" + summary "Search for an object or retrieve multiple objects." + arguments "<query>" 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" + 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? + Prints the default terminus class for this face. Note that + different run modes may have different default terminuses. EOT when_invoked do |*args| diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb index 3c377a49f..748888c2e 100644 --- a/lib/puppet/interface/action.rb +++ b/lib/puppet/interface/action.rb @@ -46,6 +46,7 @@ class Puppet::Interface::Action ######################################################################## # Documentation... attr_doc :returns + attr_doc :arguments def synopsis output = PrettyPrint.format do |s| s.text("puppet #{@face.name}") @@ -67,6 +68,7 @@ class Puppet::Interface::Action end end end + s.text(" #{arguments}") if arguments end end diff --git a/lib/puppet/interface/documentation.rb b/lib/puppet/interface/documentation.rb index 48e9a8b1a..aedcc1c24 100644 --- a/lib/puppet/interface/documentation.rb +++ b/lib/puppet/interface/documentation.rb @@ -78,7 +78,7 @@ class Puppet::Interface return nil if @description.nil? lines = @description.split("\n") grab = [5, lines.index('') || 5].min - @short_description = lines[0, grab].join("\n") + @short_description = lines[0, grab].join("\n") + ' [...]' end @short_description end |