Provided by: puppet_2.7.11-1ubuntu2_all bug

NAME

       puppet-agent - The puppet agent daemon

SYNOPSIS

       Retrieves  the  client  configuration  from  the puppet master and applies it to the local
       host.

       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]

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 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, ´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

DIAGNOSTICS

       Puppet agent accepts the following signals:

       SIGHUP Restart the puppet agent daemon.

       SIGINT and SIGTERM
              Shut down the puppet agent daemon.

       SIGUSR1
              Immediately retrieve and apply configurations from the puppet master.

AUTHOR

       Luke Kanies

COPYRIGHT

       Copyright (c) 2011 Puppet Labs, LLC Licensed under the Apache 2.0 License