[Pkg-puppet-devel] [SCM] Puppet packaging for Debian branch, experimental, updated. debian/2.6.8-1-844-g7ec39d5
nfagerlund
nick.fagerlund at gmail.com
Tue May 10 08:04:40 UTC 2011
The following commit has been merged in the experimental branch:
commit 489b065b9e25b8dcb389ae63b73ba0c696f0ead5
Author: nfagerlund <nick.fagerlund at gmail.com>
Date: Wed Feb 16 10:26:22 2011 -0800
(#1204) Reformat help text for puppet doc and puppet agent.
Markdown changes for compatibility with Ronn, in the interest of
better manpages.
diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb
index fa1ec58..fa06aae 100644
--- a/lib/puppet/application/agent.rb
+++ b/lib/puppet/application/agent.rb
@@ -86,26 +86,30 @@ class Puppet::Application::Agent < Puppet::Application
def help
<<-HELP
-SYNOPSIS
+puppet-agent(8) -- The puppet agent daemon
========
-Retrieve the client configuration from the puppet master and apply it to
+
+SYNOPSIS
+--------
+Retrieves the client configuration from the puppet master and applies it to
the local host.
-Currently must be run out periodically, using cron or something similar.
+This service may be run as a daemon, run periodically using cron (or something
+similar), or run interactively for testing purposes.
USAGE
-=====
- puppet agent [-D|--daemonize|--no-daemonize] [-d|--debug]
- [--detailed-exitcodes] [--disable] [--enable]
- [-h|--help] [--certname <host name>] [-l|--logdest syslog|<file>|console]
- [-o|--onetime] [--serve <handler>] [-t|--test] [--noop]
- [--digest <digest>] [--fingerprint] [-V|--version]
- [-v|--verbose] [-w|--waitforcert <seconds>]
+-----
+puppet agent [-D|--daemonize|--no-daemonize] [-d|--debug]
+ [--detailed-exitcodes] [--disable] [--enable] [-h|--help]
+ [--certname <host name>] [-l|--logdest syslog|<file>|console]
+ [-o|--onetime] [--serve <handler>] [-t|--test] [--noop]
+ [--digest <digest>] [--fingerprint] [-V|--version]
+ [-v|--verbose] [-w|--waitforcert <seconds>]
DESCRIPTION
-===========
+-----------
This is the main puppet client. Its job is to retrieve the local
machine's configuration from a remote server and apply it. In order to
successfully communicate with the remote server, the client must have a
@@ -120,10 +124,10 @@ configuration and apply it.
USAGE NOTES
-===========
+-----------
'puppet agent' does its best to find a compromise between interactive
use and daemon use. Run with no arguments and no configuration, it will
-go into the backgroun, attempt to get a signed certificate, and retrieve
+go into the background, attempt to get a signed certificate, and retrieve
and apply its configuration every 30 minutes.
Some flags are meant specifically for interactive use -- in particular,
@@ -156,7 +160,7 @@ when signing certificates).
OPTIONS
-=======
+-------
Note that any configuration parameter that's valid in the configuration
file is also a valid long argument. For example, 'server' is a valid
configuration parameter, so you can specify '--server <servername>' as
@@ -168,121 +172,122 @@ full list of acceptable parameters. A commented list of all
configuration options can also be generated by running puppet agent with
'--genconfig'.
-daemonize: Send the process into the background. This is the
- default.
-
-no-daemonize: Do not send the process into the background.
-
-debug: Enable full debugging.
-
-digest: Change the certificate fingerprinting digest
- algorithm. The default is MD5. Valid values depends
- on the version of OpenSSL installed, but should
- always at least contain MD5, MD2, SHA1 and SHA256.
-
-detailed-exitcodes: Provide transaction information via exit codes. If
- this is enabled, an exit code of '2' means there
- were changes, and an exit code of '4' means that
- there were failures during the transaction. This
- option only makes sense in conjunction with
- --onetime.
-
-disable: Disable working on the local system. This puts a
- lock file in place, causing 'puppet agent' not to
- work on the system until the lock file is removed.
- This is useful if you are testing a configuration
- and do not want the central configuration to
- override the local state until everything is tested
- and committed.
-
-'puppet agent' uses the same lock file while it is running, so no more
-than one 'puppet agent' process is working at a time.
-
-'puppet agent' exits after executing this.
-
-enable: Enable working on the local system. This removes any
- lock file, causing 'puppet agent' to start managing
- the local system again (although it will continue to
- use its normal scheduling, so it might not start for
- another half hour).
-
-'puppet agent' exits after executing this.
-
-certname: Set the certname (unique ID) of the client. The
- master reads this unique identifying string, which
- is usually set to the node's fully-qualified domain
- name, to determine which configurations the node
- will receive. Use this option to debug setup
- problems or implement unusual node identification
- schemes.
-
-help: Print this help message
-
-logdest: Where to send messages. Choose between syslog, the
- console, and a log file. Defaults to sending
- messages to syslog, or the console if debugging or
- verbosity is enabled.
-
-no-client: Do not create a config client. This will cause the
- daemon to run without ever checking for its
- configuration automatically, and only makes sense
-
-onetime: Run the configuration once. Runs a single (normally
- daemonized) Puppet run. Useful for interactively
- running puppet agent when used in conjunction with
- the --no-daemonize option.
-
-fingerprint: Display the current certificate or certificate
- signing request fingerprint and then exit. Use the
- '--digest' option to change the digest algorithm
- used.
-
-serve: Start another type of server. By default, 'puppet
- agent' will start a service handler that allows
- authenticated and authorized remote nodes to trigger
- the configuration to be pulled down and applied. You
- can specify any handler here that does not require
- configuration, e.g., filebucket, ca, or resource.
- The handlers are in 'lib/puppet/network/handler',
- and the names must match exactly, both in the call
- to 'serve' and in 'namespaceauth.conf'.
-
-test: Enable the most common options used for testing.
- These are 'onetime', 'verbose', 'ignorecache',
- 'no-daemonize', 'no-usecacheonfailure',
- 'detailed-exit-codes', 'no-splay', and 'show_diff'.
-
-noop: Use 'noop' mode where the daemon runs in a no-op or
- dry-run mode. This is useful for seeing what changes
- Puppet will make without actually executing the
- changes.
-
-verbose: Turn on verbose reporting.
-
-version: Print the puppet version number and exit.
-
-waitforcert: This option only matters for daemons that do not yet
- have certificates and it is enabled by default, with
- a value of 120 (seconds). This causes 'puppet agent'
- to connect to the server every 2 minutes and ask it
- to sign a certificate request. This is useful for
- the initial setup of a puppet client. You can turn
- off waiting for certificates by specifying a time of
- 0.
+* --daemonize:
+ Send the process into the background. This is the default.
+
+* --no-daemonize:
+ Do not send the process into the background.
+
+* --debug:
+ Enable full debugging.
+
+* --digest:
+ Change the certificate fingerprinting digest algorithm. The default is
+ MD5. Valid values depends on the version of OpenSSL installed, but
+ should always at least contain MD5, MD2, SHA1 and SHA256.
+
+* --detailed-exitcodes:
+ Provide transaction information via exit codes. If this is enabled, an
+ exit code of '2' means there were changes, and an exit code of '4'
+ means that there were failures during the transaction. This option
+ only makes sense in conjunction with --onetime.
+
+* --disable:
+ Disable working on the local system. This puts a lock file in place,
+ causing 'puppet agent' not to work on the system until the lock file
+ is removed. This is useful if you are testing a configuration and do
+ not want the central configuration to override the local state until
+ everything is tested and committed.
+
+ 'puppet agent' uses the same lock file while it is running, so no more
+ than one 'puppet agent' process is working at a time.
+
+ 'puppet agent' exits after executing this.
+
+* --enable:
+ Enable working on the local system. This removes any lock file,
+ causing 'puppet agent' to start managing the local system again
+ (although it will continue to use its normal scheduling, so it might
+ not start for another half hour).
+
+ 'puppet agent' exits after executing this.
+
+* --certname:
+ Set the certname (unique ID) of the client. The master reads this
+ unique identifying string, which is usually set to the node's
+ fully-qualified domain name, to determine which configurations the
+ node will receive. Use this option to debug setup problems or
+ implement unusual node identification schemes.
+
+* --help:
+ Print this help message
+
+* --logdest:
+ Where to send messages. Choose between syslog, the console, and a log
+ file. Defaults to sending messages to syslog, or the console if
+ debugging or verbosity is enabled.
+
+* --no-client:
+ Do not create a config client. This will cause the daemon to run
+ without ever checking for its configuration automatically, and only
+ makes sense
+
+* --onetime:
+ Run the configuration once. Runs a single (normally daemonized) Puppet
+ run. Useful for interactively running puppet agent when used in
+ conjunction with the --no-daemonize option.
+
+* --fingerprint:
+ Display the current certificate or certificate signing request
+ fingerprint and then exit. Use the '--digest' option to change the
+ digest algorithm used.
+
+* --serve:
+ Start another type of server. By default, 'puppet agent' will start a
+ service handler that allows authenticated and authorized remote nodes
+ to trigger the configuration to be pulled down and applied. You can
+ specify any handler here that does not require configuration, e.g.,
+ filebucket, ca, or resource. The handlers are in
+ 'lib/puppet/network/handler', and the names must match exactly, both
+ in the call to 'serve' and in 'namespaceauth.conf'.
+
+* --test:
+ Enable the most common options used for testing. These are 'onetime',
+ 'verbose', 'ignorecache', 'no-daemonize', 'no-usecacheonfailure',
+ 'detailed-exit-codes', 'no-splay', and 'show_diff'.
+
+* --noop:
+ Use 'noop' mode where the daemon runs in a no-op or dry-run mode. This
+ is useful for seeing what changes Puppet will make without actually
+ executing the changes.
+
+* --verbose:
+ Turn on verbose reporting.
+
+* --version:
+ Print the puppet version number and exit.
+
+* --waitforcert:
+ This option only matters for daemons that do not yet have certificates
+ and it is enabled by default, with a value of 120 (seconds). This
+ causes 'puppet agent' to connect to the server every 2 minutes and ask
+ it to sign a certificate request. This is useful for the initial setup
+ of a puppet client. You can turn off waiting for certificates by
+ specifying a time of 0.
EXAMPLE
-=======
- puppet agent --server puppet.domain.com
+-------
+ $ puppet agent --server puppet.domain.com
AUTHOR
-======
+------
Luke Kanies
COPYRIGHT
-=========
+---------
Copyright (c) 2005, 2006 Puppet Labs, LLC Licensed under the GNU Public
License
diff --git a/lib/puppet/application/doc.rb b/lib/puppet/application/doc.rb
index c7f270c..3bfe416 100644
--- a/lib/puppet/application/doc.rb
+++ b/lib/puppet/application/doc.rb
@@ -53,20 +53,24 @@ class Puppet::Application::Doc < Puppet::Application
def help
<<-HELP
-SYNOPSIS
+puppet-doc(8) -- Generate Puppet documentation and references
========
-Generate a reference for all Puppet types. Largely meant for internal
+
+SYNOPSIS
+--------
+Generates a reference for all Puppet types. Largely meant for internal
Puppet Labs use.
USAGE
-=====
- puppet doc [-a|--all] [-h|--help] [-o|--outputdir <rdoc outputdir>] [-m|--mode <text|pdf|rdoc>]
- [-r|--reference <[type]|configuration|..>] [--charset CHARSET] [manifest-file]
+-----
+puppet doc [-a|--all] [-h|--help] [-o|--outputdir <rdoc-outputdir>]
+ [-m|--mode text|pdf|rdoc] [-r|--reference <reference-name>]
+ [--charset <charset>] [<manifest-file>]
DESCRIPTION
-===========
+-----------
If mode is not 'rdoc', then this command generates a Markdown document
describing all installed Puppet types or all allowable arguments to
puppet executables. It is largely meant for internal use and is used to
@@ -77,57 +81,62 @@ the manifests that are in 'manifestdir' and 'modulepath' configuration
directives. The generated documentation directory is doc by default but
can be changed with the 'outputdir' option.
-If the command is started with 'manifest-file' command-line arguments,
-puppet doc generate a single manifest documentation that is output on
-stdout.
+If the command is run with the name of a manifest file as an argument,
+puppet doc will output a single manifest's documentation on stdout.
OPTIONS
-=======
-all: Output the docs for all of the reference types. In 'rdoc'
- modes, this also outputs documentation for all resources
+-------
+* --all:
+ Output the docs for all of the reference types. In 'rdoc'
+ modes, this also outputs documentation for all resources
-help: Print this help message
+* --help:
+ Print this help message
-outputdir: Specifies the directory where to output the rdoc
- documentation in 'rdoc' mode.
+* --outputdir:
+ Specifies the directory where to output the rdoc
+ documentation in 'rdoc' mode.
-mode: Determine the output mode. Valid modes are 'text', 'pdf' and
- 'rdoc'. The 'pdf' mode creates PDF formatted files in the
- /tmp directory. The default mode is 'text'. In 'rdoc' mode
- you must provide 'manifests-path'
+* --mode:
+ Determine the output mode. Valid modes are 'text', 'pdf' and
+ 'rdoc'. The 'pdf' mode creates PDF formatted files in the
+ /tmp directory. The default mode is 'text'. In 'rdoc' mode
+ you must provide 'manifests-path'
-reference: Build a particular reference. Get a list of references by
- running 'puppet doc --list'.
+* --reference:
+ Build a particular reference. Get a list of references by
+ running 'puppet doc --list'.
-charset: Used only in 'rdoc' mode. It sets the charset used in the
- html files produced.
+* --charset:
+ Used only in 'rdoc' mode. It sets the charset used in the
+ html files produced.
EXAMPLE
-=======
- $ puppet doc -r type > /tmp/type_reference.markdown
+-------
+ $ puppet doc -r type > /tmp/type_reference.markdown
or
- $ puppet doc --outputdir /tmp/rdoc --mode rdoc /path/to/manifests
+ $ puppet doc --outputdir /tmp/rdoc --mode rdoc /path/to/manifests
or
- $ puppet doc /etc/puppet/manifests/site.pp
+ $ puppet doc /etc/puppet/manifests/site.pp
or
- $ puppet doc -m pdf -r configuration
+ $ puppet doc -m pdf -r configuration
AUTHOR
-======
+------
Luke Kanies
COPYRIGHT
-=========
+---------
Copyright (c) 2005-2007 Puppet Labs, LLC Licensed under the GNU Public
License
--
Puppet packaging for Debian
More information about the Pkg-puppet-devel
mailing list