diff options
Diffstat (limited to 'man/man8/puppetd.8')
| -rw-r--r-- | man/man8/puppetd.8 | 508 |
1 files changed, 282 insertions, 226 deletions
diff --git a/man/man8/puppetd.8 b/man/man8/puppetd.8 index 090c3342d..32aede791 100644 --- a/man/man8/puppetd.8 +++ b/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 |