puppet 2.6.0 → 2.6.1

data/man/man8/puppetd.8

@@ -1,227 +1,283 @@
-.TH SYNOPSIS  "" "" ""
-.SH NAME
-Synopsis \- 
-.\" Man page generated from reStructeredText.
-.
-.sp
-Retrieve the client configuration from the puppet master and apply it to
-the local host.
-.sp
-Currently must be run out periodically, using cron or something similar.
-.SH USAGE
-.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B puppet agent  [\-D|\-\-daemonize|\-\-no\-daemonize] [\-d|\-\-debug]
-.
-[\-\-detailed\-exitcodes] [\-\-disable] [\-\-enable]
-[\-h|\-\-help] [\-\-fqdn <host name>] [\-l|\-\-logdest syslog|<file>|console]
-[\-o|\-\-onetime] [\-\-serve <handler>] [\-t|\-\-test] [\-\-noop]
-[\-\-digest <digest>] [\-\-fingerprint] [\-V|\-\-version]
-[\-v|\-\-verbose] [\-w|\-\-waitforcert <seconds>]
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.SH DESCRIPTION
-.sp
-This is the main puppet client. Its job is to retrieve the local
-machine\(aqs configuration from a remote server and apply it. In order to
-successfully communicate with the remote server, the client must have a
-certificate signed by a certificate authority that the server trusts;
-the recommended method for this, at the moment, is to run a certificate
-authority as part of the puppet server (which is the default). The
-client will connect and request a signed certificate, and will continue
-connecting until it receives one.
-.sp
-Once the client has a signed certificate, it will retrieve its
-configuration and apply it.
-.SH USAGE NOTES
-.sp
-+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
-and apply its configuration every 30 minutes.
-.sp
-Some flags are meant specifically for interactive use \-\- in particular,
-+test+, +tags+ or +fingerprint+ are useful. +test+ enables verbose
-logging, causes the daemon to stay in the foreground, exits if the
-server\(aqs configuration is invalid (this happens if, for instance, you\(aqve
-left a syntax error on the server), and exits after running the
-configuration once (rather than hanging around as a long\-running
-process).
-.sp
-+tags+ allows you to specify what portions of a configuration you want
-to apply. Puppet elements are tagged with all of the class or definition
-names that contain them, and you can use the +tags+ flag to specify one
-of these names, causing only configuration elements contained within
-that class or definition to be applied. This is very useful when you are
-testing new configurations \-\- for instance, if you are just starting to
-manage +ntpd+, you would put all of the new elements into an +ntpd+
-class, and call puppet with +\-\-tags ntpd+, which would only apply that
-small portion of the configuration during your testing, rather than
-applying the whole thing.
-.sp
-+fingerprint+ is a one\-time flag. In this mode +puppet agent+ will run
-once and display on the console (and in the log) the current certificate
-(or certificate request) fingerprint. Providing the +\-\-digest+ option
-allows to use a different digest algorithm to generate the fingerprint.
-The main use is to verify that before signing a certificate request on
-the master, the certificate request the master received is the same as
-the one the client sent (to prevent against man\-in\-the\-middle attacks
-when signing certificates).
-.SH OPTIONS
-.sp
-Note that any configuration parameter that\(aqs valid in the configuration
-file is also a valid long argument. For example, \(aqserver\(aq is a valid
-configuration parameter, so you can specify \(aq\-\-server <servername>\(aq as
-an argument.
-.sp
-See the configuration file documentation at
-\fI\%http://docs.puppetlabs.com/references/stable/configuration.html\fP for the
-full list of acceptable parameters. A commented list of all
-configuration options can also be generated by running puppet agent with
-\(aq\-\-genconfig\(aq.
-.INDENT 0.0
-.TP
-.B daemonize:          Send the process into the background. This is the
-.
-default.
-.UNINDENT
-.sp
-no\-daemonize:       Do not send the process into the background.
-.sp
-debug:              Enable full debugging.
-.INDENT 0.0
-.TP
-.B 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.
-.TP
-.B detailed\-exitcodes: Provide transaction information via exit codes. If
-.
-this is enabled, an exit code of \(aq2\(aq means there
-were changes, and an exit code of \(aq4\(aq means that
-there were failures during the transaction. This
-option only makes sense in conjunction with
-\-\-onetime.
-.TP
-.B 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.
-.UNINDENT
-.sp
-+puppet agent+ uses the same lock file while it is running, so no more
-than one +puppet agent+ process is working at a time.
-.sp
-+puppet agent+ exits after executing this.
-.INDENT 0.0
-.TP
-.B 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).
-.UNINDENT
-.sp
-+puppet agent+ exits after executing this.
-.INDENT 0.0
-.TP
-.B fqdn:               Set the fully\-qualified domain name of the client.
-.
-This is only used for certificate purposes, but can
-be used to override the discovered hostname. If you
-need to use this flag, it is generally an indication
-of a setup problem.
-.UNINDENT
-.sp
-help:               Print this help message
-.INDENT 0.0
-.TP
-.B 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.
-.TP
-.B 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
-when used in conjunction with \-\-listen.
-.TP
-.B 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.
-.TP
-.B fingerprint:        Display the current certificate or certificate
-.
-signing request fingerprint and then exit. Use the
-+\-\-digest+ option to change the digest algorithm
-used.
-.TP
-.B 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+.
-.TP
-.B test:               Enable the most common options used for testing.
-.
-These are +onetime+, +verbose+, +ignorecache,
-+no\-daemonize+, and +no\-usecacheonfailure+.
-.TP
-.B 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.
-.UNINDENT
-.sp
-verbose:            Turn on verbose reporting.
-.sp
-version:            Print the puppet version number and exit.
-.INDENT 0.0
-.TP
-.B 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.
-.UNINDENT
-.SH EXAMPLE
-.INDENT 0.0
-.INDENT 3.5
-.sp
-puppet agent \-\-server puppet.domain.com
-.UNINDENT
-.UNINDENT
-.SH AUTHOR
-.sp
-Luke Kanies
-.SH COPYRIGHT
-.sp
-Copyright (c) 2005, 2006 Reductive Labs, LLC Licensed under the GNU
-Public License
-.\" Generated by docutils manpage writer.
-.\" 
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
+.TH "PUPPETD" "8" "August 2010" "" ""
+puppet agent [\-D|\-\-daemonize|\-\-no\-daemonize] [\-d|\-\-debug]
+.
+.IP "" 4
+.
+.nf
+
+  [\-\-detailed\-exitcodes] [\-\-disable] [\-\-enable]
+  [\-h|\-\-help] [\-\-fqdn <host name>] [\-l|\-\-logdest syslog|<file>|console]
+  [\-o|\-\-onetime] [\-\-serve <handler>] [\-t|\-\-test] [\-\-noop]
+  [\-\-digest <digest>] [\-\-fingerprint] [\-V|\-\-version]
+  [\-v|\-\-verbose] [\-w|\-\-waitforcert <seconds>]
+.
+.fi
+.
+.IP "" 0
+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 certificate signed by a certificate authority that the server trusts; the recommended method for this, at the moment, is to run a certificate authority as part of the puppet server (which is the default)\. The client will connect and request a signed certificate, and will continue connecting until it receives one\.
+.
+.P
+Once the client has a signed certificate, it will retrieve its configuration and apply it\.+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 and apply its configuration every 30 minutes\.
+.
+.P
+Some flags are meant specifically for interactive use \-\- in particular, +test+, +tags+ or +fingerprint+ are useful\. +test+ enables verbose logging, causes the daemon to stay in the foreground, exits if the server\'s configuration is invalid (this happens if, for instance, you\'ve left a syntax error on the server), and exits after running the configuration once (rather than hanging around as a long\-running process)\.
+.
+.P
++tags+ allows you to specify what portions of a configuration you want to apply\. Puppet elements are tagged with all of the class or definition names that contain them, and you can use the +tags+ flag to specify one of these names, causing only configuration elements contained within that class or definition to be applied\. This is very useful when you are testing new configurations \-\- for instance, if you are just starting to manage +ntpd+, you would put all of the new elements into an +ntpd+ class, and call puppet with +\-\-tags ntpd+, which would only apply that small portion of the configuration during your testing, rather than applying the whole thing\.
+.
+.P
++fingerprint+ is a one\-time flag\. In this mode +puppet agent+ will run once and display on the console (and in the log) the current certificate (or certificate request) fingerprint\. Providing the +\-\-digest+ option allows to use a different digest algorithm to generate the fingerprint\. The main use is to verify that before signing a certificate request on the master, the certificate request the master received is the same as the one the client sent (to prevent against man\-in\-the\-middle attacks when signing certificates)\.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 \fIservername\fR\' as an argument\.
+.
+.P
+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\'\.
+.
+.P
+daemonize: Send the process into the background\. This is the
+.
+.IP "" 4
+.
+.nf
+
+                default\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+no\-daemonize: Do not send the process into the background\.
+.
+.P
+debug: Enable full debugging\.
+.
+.P
+digest: Change the certificate fingerprinting digest
+.
+.IP "" 4
+.
+.nf
+
+                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\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+detailed\-exitcodes: Provide transaction information via exit codes\. If
+.
+.IP "" 4
+.
+.nf
+
+                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\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+disable: Disable working on the local system\. This puts a
+.
+.IP "" 4
+.
+.nf
+
+                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\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
++puppet agent+ uses the same lock file while it is running, so no more than one +puppet agent+ process is working at a time\.
+.
+.P
++puppet agent+ exits after executing this\.
+.
+.P
+enable: Enable working on the local system\. This removes any
+.
+.IP "" 4
+.
+.nf
+
+                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)\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
++puppet agent+ exits after executing this\.
+.
+.P
+fqdn: Set the fully\-qualified domain name of the client\.
+.
+.IP "" 4
+.
+.nf
+
+                This is only used for certificate purposes, but can
+                be used to override the discovered hostname\. If you
+                need to use this flag, it is generally an indication
+                of a setup problem\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+help: Print this help message
+.
+.P
+logdest: Where to send messages\. Choose between syslog, the
+.
+.IP "" 4
+.
+.nf
+
+                console, and a log file\. Defaults to sending
+                messages to syslog, or the console if debugging or
+                verbosity is enabled\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+no\-client: Do not create a config client\. This will cause the
+.
+.IP "" 4
+.
+.nf
+
+                daemon to run without ever checking for its
+                configuration automatically, and only makes sense
+                when used in conjunction with \-\-listen\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+onetime: Run the configuration once\. Runs a single (normally
+.
+.IP "" 4
+.
+.nf
+
+                daemonized) Puppet run\. Useful for interactively
+                running puppet agent when used in conjunction with
+                the \-\-no\-daemonize option\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+fingerprint: Display the current certificate or certificate
+.
+.IP "" 4
+.
+.nf
+
+                signing request fingerprint and then exit\. Use the
+                +\-\-digest+ option to change the digest algorithm
+                used\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+serve: Start another type of server\. By default, +puppet
+.
+.IP "" 4
+.
+.nf
+
+                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+\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+test: Enable the most common options used for testing\.
+.
+.IP "" 4
+.
+.nf
+
+                These are +onetime+, +verbose+, +ignorecache,
+                +no\-daemonize+, and +no\-usecacheonfailure+\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+noop: Use +noop+ mode where the daemon runs in a no\-op or
+.
+.IP "" 4
+.
+.nf
+
+                dry\-run mode\. This is useful for seeing what changes
+                Puppet will make without actually executing the
+                changes\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+verbose: Turn on verbose reporting\.
+.
+.P
+version: Print the puppet version number and exit\.
+.
+.P
+waitforcert: This option only matters for daemons that do not yet
+.
+.IP "" 4
+.
+.nf
+
+                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\.
+.
+.fi
+.
+.IP "" 0
+puppet agent \-\-server puppet\.domain\.comLuke KaniesCopyright (c) 2005, 2006 Reductive Labs, LLC Licensed under the GNU Public License