Class: Puppet::Application::Agent

# File 'lib/puppet/application/agent.rb', line 12

def app_defaults
  super.merge({
    :catalog_terminus => :rest,
    :catalog_cache_terminus => :json,
    :node_terminus => :rest,
    :facts_terminus => :facter,
  })
end

#fingerprint ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 411

def fingerprint
  Puppet::Util::Log.newdestination(:console)
  cert_provider = Puppet::X509::CertProvider.new
  client_cert = cert_provider.load_client_cert(Puppet[:certname])
  if client_cert
    puts Puppet::SSL::Digest.new(options[:digest].to_s, client_cert.to_der).to_s
  else
    csr = cert_provider.load_request(Puppet[:certname])
    if csr
      puts Puppet::SSL::Digest.new(options[:digest].to_s, csr.to_der).to_s
    else
      $stderr.puts _("Fingerprint asked but neither the certificate, nor the certificate request have been issued")
      exit(1)
    end
  end
rescue => e
  Puppet.log_exception(e, _("Failed to generate fingerprint: %{message}") % {message: e.message})
  exit(1)
end

#help ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 86

def help
  "\npuppet-agent(8) -- \#{summary}\n========\n\nSYNOPSIS\n--------\nRetrieves the client configuration from the Puppet master and applies it to\nthe local host.\n\nThis service may be run as a daemon, run periodically using cron (or something\nsimilar), or run interactively for testing purposes.\n\n\nUSAGE\n-----\npuppet agent [--certname <NAME>] [-D|--daemonize|--no-daemonize]\n[-d|--debug] [--detailed-exitcodes] [--digest <DIGEST>] [--disable [MESSAGE]] [--enable]\n[--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog|<ABS FILEPATH>|console]\n[--serverport <PORT>] [--noop] [-o|--onetime] [--sourceaddress <IP_ADDRESS>] [-t|--test]\n[-v|--verbose] [-V|--version] [-w|--waitforcert <SECONDS>]\n\n\nDESCRIPTION\n-----------\nThis is the main puppet client. Its job is to retrieve the local\nmachine's configuration from a remote server and apply it. In order to\nsuccessfully communicate with the remote server, the client must have a\ncertificate signed by a certificate authority that the server trusts;\nthe recommended method for this, at the moment, is to run a certificate\nauthority as part of the puppet server (which is the default). The\nclient will connect and request a signed certificate, and will continue\nconnecting until it receives one.\n\nOnce the client has a signed certificate, it will retrieve its\nconfiguration and apply it.\n\n\nUSAGE NOTES\n-----------\n'puppet agent' does its best to find a compromise between interactive\nuse and daemon use. If you run it with no arguments and no configuration, it\ngoes into the background, attempts to get a signed certificate, and retrieves\nand applies its configuration every 30 minutes.\n\nSome flags are meant specifically for interactive use --- in particular,\n'test', 'tags' and 'fingerprint' are useful.\n\n'--test' runs once in the foreground with verbose logging, then exits.\nIt also exits if it can't get a valid catalog. `--test` includes the \n'--detailed-exitcodes' option by default and exits with one of the following \nexit codes:\n\n* 0: The run succeeded with no changes or failures; the system was already in \n   the desired state.\n* 1: The run failed, or wasn't attempted due to another run already in progress.\n* 2: The run succeeded, and some resources were changed.\n* 4: The run succeeded, and some resources failed.\n* 6: The run succeeded, and included both changes and failures.\n\n'--tags' allows you to specify what portions of a configuration you want\nto apply. Puppet elements are tagged with all of the class or definition\nnames that contain them, and you can use the 'tags' flag to specify one\nof these names, causing only configuration elements contained within\nthat class or definition to be applied. This is very useful when you are\ntesting new configurations --- for instance, if you are just starting to\nmanage 'ntpd', you would put all of the new elements into an 'ntpd'\nclass, and call puppet with '--tags ntpd', which would only apply that\nsmall portion of the configuration during your testing, rather than\napplying the whole thing.\n\n'--fingerprint' is a one-time flag. In this mode 'puppet agent' runs\nonce and displays on the console (and in the log) the current certificate\n(or certificate request) fingerprint. Providing the '--digest' option\nallows you to use a different digest algorithm to generate the fingerprint.\nThe main use is to verify that before signing a certificate request on\nthe master, the certificate request the master received is the same as\nthe one the client sent (to prevent against man-in-the-middle attacks\nwhen signing certificates).\n\n'--skip_tags' is a flag used to filter resources. If this is set, then\nonly resources not tagged with the specified tags will be applied.\nValues must be comma-separated.\n\n\nOPTIONS\n-------\n\nNote that any Puppet setting that's valid in the configuration file is also a\nvalid long argument. For example, 'server' is a valid setting, so you can\nspecify '--server <servername>' as an argument. Boolean settings accept a '--no-' \nprefix to turn off a behavior, translating into '--setting' and '--no-setting' \npairs, such as `--daemonize` and `--no-daemonize`.\n\nSee the configuration file documentation at\nhttps://puppet.com/docs/puppet/latest/configuration.html for the\nfull list of acceptable settings. A commented list of all settings can also be\ngenerated by running puppet agent with '--genconfig'.\n\n* --certname:\nSet the certname (unique ID) of the client. The master reads this\nunique identifying string, which is usually set to the node's\nfully-qualified domain name, to determine which configurations the\nnode will receive. Use this option to debug setup problems or\nimplement unusual node identification schemes.\n(This is a Puppet setting, and can go in puppet.conf.)\n\n* --daemonize:\nSend the process into the background. This is the default.\n(This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'\nprefix for boolean settings on the command line.)\n\n* --no-daemonize:\nDo not send the process into the background.\n(This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'\nprefix for boolean settings on the command line.)\n\n* --debug:\nEnable full debugging.\n\n* --detailed-exitcodes:\nProvide extra information about the run via exit codes; works only if '--test'\nor '--onetime' is also specified. If enabled, 'puppet agent' uses the\nfollowing exit codes:\n\n0: The run succeeded with no changes or failures; the system was already in\nthe desired state.\n\n1: The run failed, or wasn't attempted due to another run already in progress.\n\n2: The run succeeded, and some resources were changed.\n\n4: The run succeeded, and some resources failed.\n\n6: The run succeeded, and included both changes and failures.\n\n* --digest:\nChange the certificate fingerprinting digest algorithm. The default is\nSHA256. Valid values depends on the version of OpenSSL installed, but\nwill likely contain MD5, MD2, SHA1 and SHA256.\n\n* --disable:\nDisable working on the local system. This puts a lock file in place,\ncausing 'puppet agent' not to work on the system until the lock file\nis removed. This is useful if you are testing a configuration and do\nnot want the central configuration to override the local state until\neverything is tested and committed.\n\nDisable can also take an optional message that will be reported by the\n'puppet agent' at the next disabled run.\n\n'puppet agent' uses the same lock file while it is running, so no more\nthan one 'puppet agent' process is working at a time.\n\n'puppet agent' exits after executing this.\n\n* --enable:\nEnable working on the local system. This removes any lock file,\ncausing 'puppet agent' to start managing the local system again\nHowever, it continues to use its normal scheduling, so it might\nnot start for another half hour.\n\n'puppet agent' exits after executing this.\n\n*  --evaltrace:\nLogs each resource as it is being evaluated. This allows you to interactively\nsee exactly what is being done. (This is a Puppet setting, and can go in\npuppet.conf. Note the special 'no-' prefix for boolean settings on the command line.)\n\n* --fingerprint:\nDisplay the current certificate or certificate signing request\nfingerprint and then exit. Use the '--digest' option to change the\ndigest algorithm used.\n\n* --help:\nPrint this help message\n\n* --job-id:\nAttach the specified job id to the catalog request and the report used for\nthis agent run. This option only works when '--onetime' is used.  When using\nPuppet Enterprise this flag should not be used as the orchestrator sets the\njob-id for you and it must be unique.\n\n* --logdest:\nWhere to send log messages. Choose between 'syslog' (the POSIX syslog\nservice), 'eventlog' (the Windows Event Log), 'console', or the path to a log\nfile. If debugging or verbosity is enabled, this defaults to 'console'.\nOtherwise, it defaults to 'syslog' on POSIX systems and 'eventlog' on Windows.\nMultiple destinations can be set using a comma separated list \n(eg: `/path/file1,console,/path/file2`)\"\n\nA path ending with '.json' will receive structured output in JSON format. The\nlog file will not have an ending ']' automatically written to it due to the\nappending nature of logging. It must be appended manually to make the content\nvalid JSON.\n\nA path ending with '.jsonl' will receive structured output in JSON Lines\nformat.\n\n* --masterport:\nThe port on which to contact the Puppet Server.\n(This is a Puppet setting, and can go in puppet.conf.\nDeprecated in favor of the 'serverport' setting.)\n\n* --noop:\nUse 'noop' mode where the daemon runs in a no-op or dry-run mode. This\nis useful for seeing what changes Puppet would make without actually\nexecuting the changes.\n(This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'\nprefix for boolean settings on the command line.)\n\n* --onetime:\nRun the configuration once. Runs a single (normally daemonized) Puppet\nrun. Useful for interactively running puppet agent when used in\nconjunction with the --no-daemonize option.\n(This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'\nprefix for boolean settings on the command line.)\n\n* --serverport:\nThe port on which to contact the Puppet Server.\n(This is a Puppet setting, and can go in puppet.conf.)\n\n* --sourceaddress:\nSet the source IP address for transactions. This defaults to automatically selected.\n(This is a Puppet setting, and can go in puppet.conf.)\n\n* --test:\nEnable the most common options used for testing. These are 'onetime',\n'verbose', 'no-daemonize', 'no-usecacheonfailure', 'detailed-exitcodes',\n'no-splay', and 'show_diff'.\n\n* --trace\nPrints stack traces on some errors. (This is a Puppet setting, and can go in\npuppet.conf. Note the special 'no-' prefix for boolean settings on the command line.)\n\n* --verbose:\nTurn on verbose reporting.\n\n* --version:\nPrint the puppet version number and exit.\n\n* --waitforcert:\nThis option only matters for daemons that do not yet have certificates\nand it is enabled by default, with a value of 120 (seconds). This\ncauses 'puppet agent' to connect to the server every 2 minutes and ask\nit to sign a certificate request. This is useful for the initial setup\nof a puppet client. You can turn off waiting for certificates by\nspecifying a time of 0.\n(This is a Puppet setting, and can go in puppet.conf.)\n\n* --write_catalog_summary\nAfter compiling the catalog saves the resource list and classes list to the node\nin the state directory named classes.txt and resources.txt\n(This is a Puppet setting, and can go in puppet.conf.)\n\nEXAMPLE\n-------\n  $ puppet agent --server puppet.domain.com\n\n\nDIAGNOSTICS\n-----------\n\nPuppet agent accepts the following signals:\n\n* SIGHUP:\nRestart the puppet agent daemon.\n* SIGINT and SIGTERM:\nShut down the puppet agent daemon.\n* SIGUSR1:\nImmediately retrieve and apply configurations from the puppet master.\n* SIGUSR2:\nClose file descriptors for log files and reopen them. Used with logrotate.\n\nAUTHOR\n------\nLuke Kanies\n\n\nCOPYRIGHT\n---------\nCopyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License\n\n  HELP\nend\n"

#log_config ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 401

def log_config
  #skip also config reading and parsing if debug is not enabled
  return unless Puppet::Util::Log.sendlevel?(:debug)

  Puppet.settings.stringify_settings(:agent, :all).each_pair do |k,v|
    next if k.include?("password") || v.to_s.empty?
    Puppet.debug("Using setting: #{k}=#{v}")
  end
end

#main(daemon) ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 449

def main(daemon)
  Puppet.notice _("Starting Puppet client version %{version}") % { version: Puppet.version }
  daemon.start
end

#onetime(daemon) ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 431

def onetime(daemon)
  begin
    exitstatus = daemon.agent.run({:job_id => options[:job_id], :start_time => options[:start_time], :waitforcert => options[:waitforcert]})
  rescue => detail
    Puppet.log_exception(detail)
  end

  daemon.stop(:exit => false)

  if not exitstatus
    exit(1)
  elsif options[:detailed_exitcodes] then
    exit(exitstatus)
  else
    exit(0)
  end
end

#preinit ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 21

def preinit
  # Do an initial trap, so that cancels don't get a stack trace.
  Signal.trap(:INT) do
    $stderr.puts _("Cancelling startup")
    exit(0)
  end

  {
    :waitforcert => nil,
    :detailed_exitcodes => false,
    :verbose => false,
    :debug => false,
    :setdest => false,
    :enable => false,
    :disable => false,
    :fqdn => nil,
    :serve => [],
    :digest => 'SHA256',
    :graph => true,
    :fingerprint => false,
    :sourceaddress => nil,
    :start_time => Time.now,
  }.each do |opt,val|
    options[opt] = val
  end

  @argv = ARGV.dup
end

#run_command ⇒ `Object`

# File 'lib/puppet/application/agent.rb', line 373

def run_command
  if options[:fingerprint]
    fingerprint
  else
    # It'd be nice to daemonize later, but we have to daemonize before
    # waiting for certificates so that we don't block
    daemon = daemonize_process_when(Puppet[:daemonize])

    # Setup signal traps immediately after daemonization so we clean up the daemon
    daemon.set_signal_traps

    log_config if Puppet[:daemonize]

    # Each application is responsible for pushing loaders onto the context.
    # Use the current environment that has already been established, though
    # it may change later during the configurer run.
    env = Puppet.lookup(:current_environment)
    Puppet.override(current_environment: env,
                    loaders: Puppet::Pops::Loaders.new(env, true)) do
      if Puppet[:onetime]
        onetime(daemon)
      else
        main(daemon)
      end
    end
  end
end

#setup ⇒ `Object`

Raises:

(ArgumentError)

# File 'lib/puppet/application/agent.rb', line 465

def setup
  raise ArgumentError, _("The puppet agent command does not take parameters") unless command_line.args.empty?

  setup_test if options[:test]

  setup_logs

  exit(Puppet.settings.print_configs ? 0 : 1) if Puppet.settings.print_configs?

  Puppet::SSL::Oids.register_puppet_oids

  if options[:fqdn]
    Puppet[:certname] = options[:fqdn]
  end

  Puppet.settings.use :main, :agent, :ssl

  Puppet::Transaction::Report.indirection.terminus_class = :rest
  # we want the last report to be persisted locally
  Puppet::Transaction::Report.indirection.cache_class = :yaml

  if Puppet[:catalog_cache_terminus]
    Puppet::Resource::Catalog.indirection.cache_class = Puppet[:catalog_cache_terminus]
  end

  # In fingerprint mode we don't need to set up the whole agent
  unless options[:fingerprint]
    setup_agent
  end
end

#setup_test ⇒ `Object`

Enable all of the most common test options.

# File 'lib/puppet/application/agent.rb', line 455

def setup_test
  Puppet.settings.handlearg("--no-usecacheonfailure")
  Puppet.settings.handlearg("--no-splay")
  Puppet.settings.handlearg("--show_diff")
  Puppet.settings.handlearg("--no-daemonize")
  options[:verbose] = true
  Puppet[:onetime] = true
  options[:detailed_exitcodes] = true
end

#summary ⇒ `Object`



82
83
84

# File 'lib/puppet/application/agent.rb', line 82

def summary
  _("The puppet agent daemon")
end

Class: Puppet::Application::Agent

Constant Summary

Constants inherited from Puppet::Application

Constants included from Util

Constants included from Util::POSIX

Constants included from Util::SymbolicFileMode

Instance Attribute Summary

Attributes inherited from Puppet::Application

Instance Method Summary collapse

Methods inherited from Puppet::Application

Methods included from Util

Methods included from Util::POSIX

Methods included from Util::SymbolicFileMode

Constructor Details

Instance Method Details

#app_defaults ⇒ Object

#fingerprint ⇒ Object

#help ⇒ Object

#log_config ⇒ Object

#main(daemon) ⇒ Object

#onetime(daemon) ⇒ Object

#preinit ⇒ Object

#run_command ⇒ Object

#setup ⇒ Object

#setup_test ⇒ Object

#summary ⇒ Object

#app_defaults ⇒ `Object`

#fingerprint ⇒ `Object`

#help ⇒ `Object`

#log_config ⇒ `Object`

#main(daemon) ⇒ `Object`

#onetime(daemon) ⇒ `Object`

#preinit ⇒ `Object`

#run_command ⇒ `Object`

#setup ⇒ `Object`

#setup_test ⇒ `Object`

#summary ⇒ `Object`