summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/puppet/face/catalog.rb4
-rw-r--r--lib/puppet/face/certificate.rb3
-rw-r--r--lib/puppet/face/certificate_request.rb27
-rw-r--r--lib/puppet/face/certificate_revocation_list.rb43
-rw-r--r--lib/puppet/face/config.rb4
-rw-r--r--lib/puppet/face/facts.rb3
-rw-r--r--lib/puppet/face/help/action.erb4
-rw-r--r--lib/puppet/face/help/face.erb5
-rw-r--r--lib/puppet/face/node.rb1
-rw-r--r--lib/puppet/face/resource_type.rb1
-rw-r--r--lib/puppet/face/status.rb12
11 files changed, 75 insertions, 32 deletions
diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 9bcaa19c6..10b15d250 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -38,8 +38,8 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do
the source of the catalog can be managed with the `--terminus` option.
EOT
returns <<-'EOT'
- Nothing. When used from the Ruby API, returns a Puppet::Transaction::Report
- object.
+ Nothing. When used from the Ruby API, returns a
+ Puppet::Transaction::Report object.
EOT
examples <<-'EOT'
Apply the locally cached catalog:
diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb
index cb0f61e3b..9a306da37 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -15,7 +15,7 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do
EOT
option "--ca-location LOCATION" do
- summary "The certificate authority to query (local or remote)."
+ summary "Which certificate authority to use (local or remote)."
description <<-'EOT'
Whether to act on the local certificate authority or one provided by a
remote puppet master. Allowed values are 'local' and 'remote.'
@@ -111,4 +111,5 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do
get_action(:search).summary "Invalid for this subcommand."
get_action(:save).summary "Invalid for this subcommand."
+ get_action(:save).description "Invalid for this subcommand."
end
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 12694ba21..774821f12 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -12,30 +12,39 @@ Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do
# Per-action doc overrides
get_action(:destroy).summary "Invalid for this subcommand."
- get_action(:find).summary "Retrieve a single CSR."
- get_action(:find).arguments "<host>"
- get_action(:find).returns <<-'EOT'
+ find = get_action(:find)
+ find.summary "Retrieve a single CSR."
+ find.arguments "<host>"
+ find.returns <<-'EOT'
A single certificate request. When used from the Ruby API, returns a
Puppet::SSL::CertificateRequest object.
RENDERING ISSUES: In most cases, you will want to render this as a string
('--render-as s').
EOT
- get_action(:find).examples <<-'EOT'
+ find.examples <<-'EOT'
Retrieve a single CSR from the puppet master's CA:
$ 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'
+ search = get_action(:search)
+ search.summary "Retrieve all outstanding CSRs."
+ search.arguments "<dummy_text>"
+ search.returns <<-'EOT'
A list of certificate requests; be sure to to render this as a string
('--render-as s'). When used from the Ruby API, returns an array of
Puppet::SSL::CertificateRequest objects.
EOT
- get_action(:search).notes "This action always returns all CSRs, but requires a dummy search key."
- get_action(:search).examples <<-'EOT'
+ search.short_description <<-EOT
+ Retrieves all outstanding certificate signing requests. Due to a known bug,
+ this action requires a dummy search key, the content of which is irrelevant.
+ EOT
+ search.notes <<-EOT
+ Although this action always returns all CSRs, it requires a dummy search
+ key; this is a known bug.
+ EOT
+ search.examples <<-'EOT'
Retrieve all CSRs from the local CA (similar to 'puppet cert list'):
$ puppet certificate_request search x --terminus ca
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index 12ba1f73f..f58368f75 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -10,30 +10,51 @@ Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do
list from the CA.
EOT
- get_action(:find).summary "Retrieve the certificate revocation list."
- get_action(:find).arguments "<dummy_key>"
- get_action(:find).returns <<-'EOT'
- A certificate revocation list. When used from the Ruby API: returns an
+ find = get_action(:find)
+ find.summary "Retrieve the certificate revocation list."
+ find.arguments "<dummy_text>"
+ find.returns <<-'EOT'
+ The certificate revocation list. When used from the Ruby API: returns an
OpenSSL::X509::CRL object.
RENDERING ISSUES: this should usually be rendered as a string
('--render-as s').
EOT
- get_action(:find).examples <<-'EXAMPLES'
+ find.short_description <<-EOT
+ Retrieves the certificate revocation list. Due to a known bug, this action
+ requires a dummy argument, the content of which is irrelevant.
+ EOT
+ find.notes <<-EOT
+ Although this action always returns the CRL from the specified terminus, it
+ requires a dummy argument; this is a known bug.
+ EOT
+ find.examples <<-'EXAMPLES'
Retrieve a copy of the puppet master's 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'
+ destroy = get_action(:destroy)
+ destroy.summary "Delete the certificate revocation list."
+ destroy.arguments "<dummy_text>"
+ destroy.returns "Nothing."
+ destroy.description <<-'EOT'
Deletes the certificate revocation list. This cannot be done over REST, but
- it is possible to delete the locally cached copy or (if run from the CA) the
- CA's own copy of the CRL.
+ it is possible to delete the locally cached copy or the local CA's copy of
+ the CRL.
+ EOT
+ destroy.short_description <<-EOT
+ Deletes the certificate revocation list. This cannot be done over REST, but
+ it is possible to delete the locally cached copy or the local CA's copy of
+ the CRL. Due to a known bug, this action requires a dummy argument, the
+ content of which is irrelevant.
+ EOT
+ destroy.notes <<-EOT
+ Although this action always deletes the CRL from the specified terminus, it
+ requires a dummy argument; this is a known bug.
EOT
get_action(:search).summary "Invalid for this subcommand."
get_action(:save).summary "Invalid for this subcommand."
+ get_action(:save).description "Invalid for this subcommand."
end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index 3fce0ed70..05fc40684 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -10,8 +10,8 @@ Puppet::Face.define(:config, '0.0.1') do
summary "Examine Puppet's current configuration settings."
arguments "(all | <setting> [<setting> ...]"
returns <<-'EOT'
- A single value when called with one config setting, and a list of settings
- and values when called with multiple options or "all."
+ A single value when called with one config setting, and a list of
+ settings and values when called with multiple options or "all."
EOT
description <<-'EOT'
Prints the value of a single configuration option or a list of
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index 99ff14bd9..9d83e3d44 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -25,7 +25,8 @@ Puppet::Indirector::Face.define(:facts, '0.0.1') do
of facts for the requested node. When used from the Ruby API: A
Puppet::Node::Facts object.
- RENDERING ISSUES: Facts cannot currently be rendered as a string.
+ RENDERING ISSUES: Facts cannot currently be rendered as a string; use yaml
+ or json.
EOT
find.notes <<-'EOT'
When using the `facter` terminus, the host argument is ignored.
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index 5242ed218..c84e46cf9 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -46,4 +46,8 @@ undocumented option
end -%>
<% end -%>
+<% if face.respond_to? :indirection -%>
+TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %>
+
+<% end -%>
See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index 870cc547f..255d3d55b 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -75,10 +75,5 @@ end -%>
<% if face.respond_to? :indirection -%>
TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %>
-<% end
- unless face.authors.empty? -%>
-AUTHOR
-<%= face.authors.join("\n").gsub(/^/, ' * ') %>
-
<% end -%>
See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index cd27e0b26..1153ad447 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -13,6 +13,7 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do
get_action(:destroy).summary "Invalid for this subcommand."
get_action(:search).summary "Invalid for this subcommand."
get_action(:save).summary "Invalid for this subcommand."
+ get_action(:save).description "Invalid for this subcommand."
find = get_action(:find)
find.summary "Retrieve a node object."
diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb
index dc6d9de90..3cd28daa3 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -30,6 +30,7 @@ Puppet::Indirector::Face.define(:resource_type, '0.0.1') do
# Action documentation overrides:
get_action(:save).summary = "Invalid for this subcommand."
+ get_action(:save).description "Invalid for this subcommand."
get_action(:destroy).summary = "Invalid for this subcommand."
find = get_action(:find)
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 690c6b371..bdb0c4d26 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -8,11 +8,12 @@ Puppet::Indirector::Face.define(:status, '0.0.1') do
get_action(:destroy).summary "Invalid for this subcommand."
get_action(:save).summary "Invalid for this subcommand."
+ get_action(:save).description "Invalid for this subcommand."
get_action(:search).summary "Invalid for this subcommand."
find = get_action(:find)
find.summary "Check status of puppet master server."
- find.arguments "<dummy_key>"
+ find.arguments "<dummy_text>"
find.returns <<-'EOT'
A "true" response or a low-level connection error. When used from the Ruby
API: returns a Puppet::Status object.
@@ -28,11 +29,20 @@ Puppet::Indirector::Face.define(:status, '0.0.1') do
<--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.short_description <<-EOT
+ Checks whether a Puppet server is properly receiving and processing HTTP
+ requests. Due to a known bug, this action requires a dummy argument, the
+ content of which is irrelevant. This action is only useful when used with
+ '--terminus rest', and will always return true when invoked locally.
+ 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.
+
+ Although this action always returns an unnamed status object, it requires a
+ dummy argument. This is a known bug.
EOT
find.examples <<-'EOT'
Check the status of the configured puppet master:
generated by cgit (git 2.34.1) at 2025-07-15 08:13:49 +0000