diff options
| -rw-r--r-- | lib/puppet/application/agent.rb | 206 | ||||
| -rwxr-xr-x | lib/puppet/util/command_line/puppetd | 188 |
2 files changed, 206 insertions, 188 deletions
diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb index 2b75505fd..5dc425556 100644 --- a/lib/puppet/application/agent.rb +++ b/lib/puppet/application/agent.rb @@ -83,6 +83,212 @@ class Puppet::Application::Agent < Puppet::Application @args[:Port] = arg end + def help + <<-HELP + +SYNOPSIS +======== +Retrieve the client configuration from the puppet master and apply it to +the local host. + +Currently must be run out periodically, using cron or something similar. + + +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>] + + +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 +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. + +Once the client has a signed certificate, it will retrieve its +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 +and apply its configuration every 30 minutes. + +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). + +'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. + +'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). + + +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 +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 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. + + +EXAMPLE +======= + puppet agent --server puppet.domain.com + + +AUTHOR +====== +Luke Kanies + + +COPYRIGHT +========= +Copyright (c) 2005, 2006 Puppet Labs, LLC Licensed under the GNU Public +License + + HELP + end + def run_command return fingerprint if options[:fingerprint] return onetime if Puppet[:onetime] diff --git a/lib/puppet/util/command_line/puppetd b/lib/puppet/util/command_line/puppetd deleted file mode 100755 index 71b28429b..000000000 --- a/lib/puppet/util/command_line/puppetd +++ /dev/null @@ -1,188 +0,0 @@ -#!/usr/bin/env ruby - -# == Synopsis -# -# Retrieve the client configuration from the puppet master and apply -# it to the local host. -# -# Currently must be run out periodically, using cron or something similar. -# -# = 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>] -# -# = 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 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. -# -# Once the client has a signed certificate, it will retrieve its 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 and apply its -# configuration every 30 minutes. -# -# 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). -# -# +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. -# -# +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). -# -# -# = 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 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 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 when used in conjunction with --listen. -# -# 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 -# -# = Author -# -# Luke Kanies -# -# = Copyright -# -# Copyright (c) 2005, 2006 Puppet Labs, LLC -# Licensed under the GNU Public License - -#Puppet::Application[:agent].run |