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    [--certname    name]    [-D|--daemonize|--no-daemonize]    [-d|--debug]
       [--detailed-exitcodes] [--digest digest] [--disable [message]] [--enable]  [--fingerprint]
       [-h|--help]   [-l|--logdest  syslog|file|console]  [--no-client]  [--noop]  [-o|--onetime]
       [-t|--test] [-v|--verbose] [-V|--version] [-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´.

       --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.

       --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.

       --detailed-exitcodes
              Provide transaction information via exit codes. If this is enabled, an exit code of
              ´2´ means there were changes, an exit code of ´4´ means there were failures  during
              the  transaction,  and  an  exit  code  of  ´6´  means  there were both changes and
              failures.

       --digest
              Change the certificate fingerprinting digest  algorithm.  The  default  is  SHA256.
              Valid  values  depends on the version of OpenSSL installed, but will likely contain
              MD5, MD2, SHA1 and SHA256.

       --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.

              Disable  can  also  take  an  optional message that will be reported by the ´puppet
              agent´ at the next disabled run.

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

       --fingerprint
              Display the current certificate or certificate signing request fingerprint and then
              exit. Use the ´--digest´ option to change the digest algorithm used.

       --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 start  but  not  check
              configuration  unless  it is triggered with puppet kick. This only makes sense when
              puppet agent is being run with listen = true in puppet.conf or was started with the
              --listen option.

       --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.

       --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.

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

       --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.

       SIGUSR2
              Close file descriptors for log files and reopen them. Used with logrotate.

AUTHOR

       Luke Kanies

COPYRIGHT

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