class Puppet::Application::Agent

Public Instance Methods

app_defaults() click to toggle source
Calls superclass method Puppet::Application#app_defaults
   # File lib/puppet/application/agent.rb
12 def app_defaults
13   super.merge({
14     :catalog_terminus => :rest,
15     :catalog_cache_terminus => :json,
16     :node_terminus => :rest,
17     :facts_terminus => :facter,
18   })
19 end
fingerprint() click to toggle source
    # File lib/puppet/application/agent.rb
411 def fingerprint
412   Puppet::Util::Log.newdestination(:console)
413   cert_provider = Puppet::X509::CertProvider.new
414   client_cert = cert_provider.load_client_cert(Puppet[:certname])
415   if client_cert
416     puts Puppet::SSL::Digest.new(options[:digest].to_s, client_cert.to_der).to_s
417   else
418     csr = cert_provider.load_request(Puppet[:certname])
419     if csr
420       puts Puppet::SSL::Digest.new(options[:digest].to_s, csr.to_der).to_s
421     else
422       $stderr.puts _("Fingerprint asked but neither the certificate, nor the certificate request have been issued")
423       exit(1)
424     end
425   end
426 rescue => e
427   Puppet.log_exception(e, _("Failed to generate fingerprint: %{message}") % {message: e.message})
428   exit(1)
429 end
help() click to toggle source
    # File lib/puppet/application/agent.rb
 86   def help
 87     <<-HELP
 88 
 89 puppet-agent(8) -- #{summary}
 90 ========
 91 
 92 SYNOPSIS
 93 --------
 94 Retrieves the client configuration from the Puppet master and applies it to
 95 the local host.
 96 
 97 This service may be run as a daemon, run periodically using cron (or something
 98 similar), or run interactively for testing purposes.
 99 
100 
101 USAGE
102 -----
103 puppet agent [--certname <NAME>] [-D|--daemonize|--no-daemonize]
104   [-d|--debug] [--detailed-exitcodes] [--digest <DIGEST>] [--disable [MESSAGE]] [--enable]
105   [--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog|<ABS FILEPATH>|console]
106   [--serverport <PORT>] [--noop] [-o|--onetime] [--sourceaddress <IP_ADDRESS>] [-t|--test]
107   [-v|--verbose] [-V|--version] [-w|--waitforcert <SECONDS>]
108 
109 
110 DESCRIPTION
111 -----------
112 This is the main puppet client. Its job is to retrieve the local
113 machine's configuration from a remote server and apply it. In order to
114 successfully communicate with the remote server, the client must have a
115 certificate signed by a certificate authority that the server trusts;
116 the recommended method for this, at the moment, is to run a certificate
117 authority as part of the puppet server (which is the default). The
118 client will connect and request a signed certificate, and will continue
119 connecting until it receives one.
120 
121 Once the client has a signed certificate, it will retrieve its
122 configuration and apply it.
123 
124 
125 USAGE NOTES
126 -----------
127 'puppet agent' does its best to find a compromise between interactive
128 use and daemon use. If you run it with no arguments and no configuration, it
129 goes into the background, attempts to get a signed certificate, and retrieves
130 and applies its configuration every 30 minutes.
131 
132 Some flags are meant specifically for interactive use --- in particular,
133 'test', 'tags' and 'fingerprint' are useful.
134 
135 '--test' runs once in the foreground with verbose logging, then exits.
136 It also exits if it can't get a valid catalog. `--test` includes the 
137 '--detailed-exitcodes' option by default and exits with one of the following 
138 exit codes:
139 
140 * 0: The run succeeded with no changes or failures; the system was already in 
141      the desired state.
142 * 1: The run failed, or wasn't attempted due to another run already in progress.
143 * 2: The run succeeded, and some resources were changed.
144 * 4: The run succeeded, and some resources failed.
145 * 6: The run succeeded, and included both changes and failures.
146 
147 '--tags' allows you to specify what portions of a configuration you want
148 to apply. Puppet elements are tagged with all of the class or definition
149 names that contain them, and you can use the 'tags' flag to specify one
150 of these names, causing only configuration elements contained within
151 that class or definition to be applied. This is very useful when you are
152 testing new configurations --- for instance, if you are just starting to
153 manage 'ntpd', you would put all of the new elements into an 'ntpd'
154 class, and call puppet with '--tags ntpd', which would only apply that
155 small portion of the configuration during your testing, rather than
156 applying the whole thing.
157 
158 '--fingerprint' is a one-time flag. In this mode 'puppet agent' runs
159 once and displays on the console (and in the log) the current certificate
160 (or certificate request) fingerprint. Providing the '--digest' option
161 allows to use a different digest algorithm to generate the fingerprint.
162 The main use is to verify that before signing a certificate request on
163 the master, the certificate request the master received is the same as
164 the one the client sent (to prevent against man-in-the-middle attacks
165 when signing certificates).
166 
167 '--skip_tags' is a flag used to filter resources. If this is set, then
168 only resources not tagged with the specified tags will be applied.
169 Values must be comma-separated.
170 
171 
172 OPTIONS
173 -------
174 
175 Note that any Puppet setting that's valid in the configuration file is also a
176 valid long argument. For example, 'server' is a valid setting, so you can
177 specify '--server <servername>' as an argument. Boolean settings accept a '--no-' 
178 prefix to turn off a behavior, translating into '--setting' and '--no-setting' 
179 pairs, such as `--daemonize` and `--no-daemonize`.
180 
181 See the configuration file documentation at
182 https://puppet.com/docs/puppet/latest/configuration.html for the
183 full list of acceptable settings. A commented list of all settings can also be
184 generated by running puppet agent with '--genconfig'.
185 
186 * --certname:
187   Set the certname (unique ID) of the client. The master reads this
188   unique identifying string, which is usually set to the node's
189   fully-qualified domain name, to determine which configurations the
190   node will receive. Use this option to debug setup problems or
191   implement unusual node identification schemes.
192   (This is a Puppet setting, and can go in puppet.conf.)
193 
194 * --daemonize:
195   Send the process into the background. This is the default.
196   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
197   prefix for boolean settings on the command line.)
198 
199 * --no-daemonize:
200   Do not send the process into the background.
201   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
202   prefix for boolean settings on the command line.)
203 
204 * --debug:
205   Enable full debugging.
206 
207 * --detailed-exitcodes:
208   Provide extra information about the run via exit codes; works only if '--test'
209   or '--onetime' is also specified. If enabled, 'puppet agent' uses the
210   following exit codes:
211 
212   0: The run succeeded with no changes or failures; the system was already in
213   the desired state.
214 
215   1: The run failed, or wasn't attempted due to another run already in progress.
216 
217   2: The run succeeded, and some resources were changed.
218 
219   4: The run succeeded, and some resources failed.
220 
221   6: The run succeeded, and included both changes and failures.
222 
223 * --digest:
224   Change the certificate fingerprinting digest algorithm. The default is
225   SHA256. Valid values depends on the version of OpenSSL installed, but
226   will likely contain MD5, MD2, SHA1 and SHA256.
227 
228 * --disable:
229   Disable working on the local system. This puts a lock file in place,
230   causing 'puppet agent' not to work on the system until the lock file
231   is removed. This is useful if you are testing a configuration and do
232   not want the central configuration to override the local state until
233   everything is tested and committed.
234 
235   Disable can also take an optional message that will be reported by the
236   'puppet agent' at the next disabled run.
237 
238   'puppet agent' uses the same lock file while it is running, so no more
239   than one 'puppet agent' process is working at a time.
240 
241   'puppet agent' exits after executing this.
242 
243 * --enable:
244   Enable working on the local system. This removes any lock file,
245   causing 'puppet agent' to start managing the local system again
246   However, it continues to use its normal scheduling, so it might
247   not start for another half hour.
248 
249   'puppet agent' exits after executing this.
250   
251 *  --evaltrace:
252   Logs each resource as it is being evaluated. This allows you to interactively
253   see exactly what is being done. (This is a Puppet setting, and can go in
254   puppet.conf. Note the special 'no-' prefix for boolean settings on the command line.)
255 
256 * --fingerprint:
257   Display the current certificate or certificate signing request
258   fingerprint and then exit. Use the '--digest' option to change the
259   digest algorithm used.
260 
261 * --help:
262   Print this help message
263 
264 * --job-id:
265   Attach the specified job id to the catalog request and the report used for
266   this agent run. This option only works when '--onetime' is used.  When using
267   Puppet Enterprise this flag should not be used as the orchestrator sets the
268   job-id for you and it must be unique.
269 
270 * --logdest:
271   Where to send log messages. Choose between 'syslog' (the POSIX syslog
272   service), 'eventlog' (the Windows Event Log), 'console', or the path to a log
273   file. If debugging or verbosity is enabled, this defaults to 'console'.
274   Otherwise, it defaults to 'syslog' on POSIX systems and 'eventlog' on Windows.
275   Multiple destinations can be set using a comma separated list 
276   (eg: `/path/file1,console,/path/file2`)"
277 
278   A path ending with '.json' will receive structured output in JSON format. The
279   log file will not have an ending ']' automatically written to it due to the
280   appending nature of logging. It must be appended manually to make the content
281   valid JSON.
282 
283   A path ending with '.jsonl' will receive structured output in JSON Lines
284   format.
285 
286 * --masterport:
287   The port on which to contact the Puppet Server.
288   (This is a Puppet setting, and can go in puppet.conf.
289   Deprecated in favor of the 'serverport' setting.)
290 
291 * --noop:
292   Use 'noop' mode where the daemon runs in a no-op or dry-run mode. This
293   is useful for seeing what changes Puppet would make without actually
294   executing the changes.
295   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
296   prefix for boolean settings on the command line.)
297 
298 * --onetime:
299   Run the configuration once. Runs a single (normally daemonized) Puppet
300   run. Useful for interactively running puppet agent when used in
301   conjunction with the --no-daemonize option.
302   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
303   prefix for boolean settings on the command line.)
304 
305 * --serverport:
306   The port on which to contact the Puppet Server.
307   (This is a Puppet setting, and can go in puppet.conf.)
308 
309 * --sourceaddress:
310   Set the source IP address for transactions. This defaults to automatically selected.
311   (This is a Puppet setting, and can go in puppet.conf.)
312 
313 * --test:
314   Enable the most common options used for testing. These are 'onetime',
315   'verbose', 'no-daemonize', 'no-usecacheonfailure', 'detailed-exitcodes',
316   'no-splay', and 'show_diff'.
317   
318 * --trace
319   Prints stack traces on some errors. (This is a Puppet setting, and can go in
320   puppet.conf. Note the special 'no-' prefix for boolean settings on the command line.)
321 
322 * --verbose:
323   Turn on verbose reporting.
324 
325 * --version:
326   Print the puppet version number and exit.
327 
328 * --waitforcert:
329   This option only matters for daemons that do not yet have certificates
330   and it is enabled by default, with a value of 120 (seconds). This
331   causes 'puppet agent' to connect to the server every 2 minutes and ask
332   it to sign a certificate request. This is useful for the initial setup
333   of a puppet client. You can turn off waiting for certificates by
334   specifying a time of 0.
335   (This is a Puppet setting, and can go in puppet.conf.)
336 
337 
338 EXAMPLE
339 -------
340     $ puppet agent --server puppet.domain.com
341 
342 
343 DIAGNOSTICS
344 -----------
345 
346 Puppet agent accepts the following signals:
347 
348 * SIGHUP:
349   Restart the puppet agent daemon.
350 * SIGINT and SIGTERM:
351   Shut down the puppet agent daemon.
352 * SIGUSR1:
353   Immediately retrieve and apply configurations from the puppet master.
354 * SIGUSR2:
355   Close file descriptors for log files and reopen them. Used with logrotate.
356 
357 AUTHOR
358 ------
359 Luke Kanies
360 
361 
362 COPYRIGHT
363 ---------
364 Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License
365 
366     HELP
367   end
log_config() click to toggle source
    # File lib/puppet/application/agent.rb
401 def log_config
402   #skip also config reading and parsing if debug is not enabled
403   return unless Puppet::Util::Log.sendlevel?(:debug)
404 
405   Puppet.settings.stringify_settings(:agent, :all).each_pair do |k,v|
406     next if k.include?("password") || v.to_s.empty?
407     Puppet.debug("Using setting: #{k}=#{v}")
408   end
409 end
main(daemon) click to toggle source
    # File lib/puppet/application/agent.rb
449 def main(daemon)
450   Puppet.notice _("Starting Puppet client version %{version}") % { version: Puppet.version }
451   daemon.start
452 end
onetime(daemon) click to toggle source
    # File lib/puppet/application/agent.rb
431 def onetime(daemon)
432   begin
433     exitstatus = daemon.agent.run({:job_id => options[:job_id], :start_time => options[:start_time]})
434   rescue => detail
435     Puppet.log_exception(detail)
436   end
437 
438   daemon.stop(:exit => false)
439 
440   if not exitstatus
441     exit(1)
442   elsif options[:detailed_exitcodes] then
443     exit(exitstatus)
444   else
445     exit(0)
446   end
447 end
preinit() click to toggle source
   # File lib/puppet/application/agent.rb
21 def preinit
22   # Do an initial trap, so that cancels don't get a stack trace.
23   Signal.trap(:INT) do
24     $stderr.puts _("Cancelling startup")
25     exit(0)
26   end
27 
28   {
29     :waitforcert => nil,
30     :detailed_exitcodes => false,
31     :verbose => false,
32     :debug => false,
33     :setdest => false,
34     :enable => false,
35     :disable => false,
36     :fqdn => nil,
37     :serve => [],
38     :digest => 'SHA256',
39     :graph => true,
40     :fingerprint => false,
41     :sourceaddress => nil,
42     :start_time => Time.now,
43   }.each do |opt,val|
44     options[opt] = val
45   end
46 
47   @argv = ARGV.dup
48 end
run_command() click to toggle source
    # File lib/puppet/application/agent.rb
369 def run_command
370   if options[:fingerprint]
371     fingerprint
372   else
373     # It'd be nice to daemonize later, but we have to daemonize before
374     # waiting for certificates so that we don't block
375     daemon = daemonize_process_when(Puppet[:daemonize])
376 
377     # Setup signal traps immediately after daemonization so we clean up the daemon
378     daemon.set_signal_traps
379 
380     log_config if Puppet[:daemonize]
381 
382     # run ssl state machine, waiting if needed
383     ssl_context = wait_for_certificates
384 
385     # Each application is responsible for pushing loaders onto the context.
386     # Use the current environment that has already been established, though
387     # it may change later during the configurer run.
388     env = Puppet.lookup(:current_environment)
389     Puppet.override(ssl_context: ssl_context,
390                     current_environment: env,
391                     loaders: Puppet::Pops::Loaders.new(env, true)) do
392       if Puppet[:onetime]
393         onetime(daemon)
394       else
395         main(daemon)
396       end
397     end
398   end
399 end
setup() click to toggle source
    # File lib/puppet/application/agent.rb
465 def setup
466   raise ArgumentError, _("The puppet agent command does not take parameters") unless command_line.args.empty?
467 
468   setup_test if options[:test]
469 
470   setup_logs
471 
472   exit(Puppet.settings.print_configs ? 0 : 1) if Puppet.settings.print_configs?
473 
474   Puppet::SSL::Oids.register_puppet_oids
475 
476   if options[:fqdn]
477     Puppet[:certname] = options[:fqdn]
478   end
479 
480   Puppet.settings.use :main, :agent, :ssl
481 
482   Puppet::Transaction::Report.indirection.terminus_class = :rest
483   # we want the last report to be persisted locally
484   Puppet::Transaction::Report.indirection.cache_class = :yaml
485 
486   if Puppet[:catalog_cache_terminus]
487     Puppet::Resource::Catalog.indirection.cache_class = Puppet[:catalog_cache_terminus]
488   end
489 
490   # In fingerprint mode we don't need to set up the whole agent
491   unless options[:fingerprint]
492     setup_agent
493   end
494 end
setup_test() click to toggle source

Enable all of the most common test options.

    # File lib/puppet/application/agent.rb
455 def setup_test
456   Puppet.settings.handlearg("--no-usecacheonfailure")
457   Puppet.settings.handlearg("--no-splay")
458   Puppet.settings.handlearg("--show_diff")
459   Puppet.settings.handlearg("--no-daemonize")
460   options[:verbose] = true
461   Puppet[:onetime] = true
462   options[:detailed_exitcodes] = true
463 end
summary() click to toggle source
   # File lib/puppet/application/agent.rb
82 def summary
83   _("The puppet agent daemon")
84 end

Private Instance Methods

daemonize_process_when(should_daemonize) click to toggle source
    # File lib/puppet/application/agent.rb
515 def daemonize_process_when(should_daemonize)
516   daemon = Puppet::Daemon.new(@agent, Puppet::Util::Pidlock.new(Puppet[:pidfile]))
517   daemon.argv = @argv
518 
519   daemon.daemonize if should_daemonize
520 
521   daemon
522 end
enable_disable_client(agent) click to toggle source
    # File lib/puppet/application/agent.rb
498 def enable_disable_client(agent)
499   if options[:enable]
500     agent.enable
501   elsif options[:disable]
502     agent.disable(options[:disable_message] || 'reason not specified')
503   end
504   exit(0)
505 end
setup_agent() click to toggle source
    # File lib/puppet/application/agent.rb
507 def setup_agent
508   agent = Puppet::Agent.new(Puppet::Configurer, (not(Puppet[:onetime])))
509 
510   enable_disable_client(agent) if options[:enable] or options[:disable]
511 
512   @agent = agent
513 end
wait_for_certificates() click to toggle source
    # File lib/puppet/application/agent.rb
524 def wait_for_certificates
525   waitforcert = options[:waitforcert] || (Puppet[:onetime] ? 0 : Puppet[:waitforcert])
526   sm = Puppet::SSL::StateMachine.new(waitforcert: waitforcert)
527   sm.ensure_client_certificate
528 end