class Puppet::Application::Agent

   # File lib/puppet/application/agent.rb
13 def app_defaults
14   super.merge({
15     :catalog_terminus => :rest,
16     :catalog_cache_terminus => :json,
17     :node_terminus => :rest,
18     :facts_terminus => :facter,
19   })
20 end

    # File lib/puppet/application/agent.rb
412 def fingerprint
413   Puppet::Util::Log.newdestination(:console)
414   cert_provider = Puppet::X509::CertProvider.new
415   client_cert = cert_provider.load_client_cert(Puppet[:certname])
416   if client_cert
417     puts Puppet::SSL::Digest.new(options[:digest].to_s, client_cert.to_der).to_s
418   else
419     csr = cert_provider.load_request(Puppet[:certname])
420     if csr
421       puts Puppet::SSL::Digest.new(options[:digest].to_s, csr.to_der).to_s
422     else
423       $stderr.puts _("Fingerprint asked but neither the certificate, nor the certificate request have been issued")
424       exit(1)
425     end
426   end
427 rescue => e
428   Puppet.log_exception(e, _("Failed to generate fingerprint: %{message}") % {message: e.message})
429   exit(1)
430 end

    # File lib/puppet/application/agent.rb
 87   def help
 88     <<-HELP
 89 
 90 puppet-agent(8) -- #{summary}
 91 ========
 92 
 93 SYNOPSIS
 94 --------
 95 Retrieves the client configuration from the Puppet master and applies it to
 96 the local host.
 97 
 98 This service may be run as a daemon, run periodically using cron (or something
 99 similar), or run interactively for testing purposes.
100 
101 
102 USAGE
103 -----
104 puppet agent [--certname <NAME>] [-D|--daemonize|--no-daemonize]
105   [-d|--debug] [--detailed-exitcodes] [--digest <DIGEST>] [--disable [MESSAGE]] [--enable]
106   [--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog|<ABS FILEPATH>|console]
107   [--serverport <PORT>] [--noop] [-o|--onetime] [--sourceaddress <IP_ADDRESS>] [-t|--test]
108   [-v|--verbose] [-V|--version] [-w|--waitforcert <SECONDS>]
109 
110 
111 DESCRIPTION
112 -----------
113 This is the main puppet client. Its job is to retrieve the local
114 machine's configuration from a remote server and apply it. In order to
115 successfully communicate with the remote server, the client must have a
116 certificate signed by a certificate authority that the server trusts;
117 the recommended method for this, at the moment, is to run a certificate
118 authority as part of the puppet server (which is the default). The
119 client will connect and request a signed certificate, and will continue
120 connecting until it receives one.
121 
122 Once the client has a signed certificate, it will retrieve its
123 configuration and apply it.
124 
125 
126 USAGE NOTES
127 -----------
128 'puppet agent' does its best to find a compromise between interactive
129 use and daemon use. If you run it with no arguments and no configuration, it
130 goes into the background, attempts to get a signed certificate, and retrieves
131 and applies its configuration every 30 minutes.
132 
133 Some flags are meant specifically for interactive use --- in particular,
134 'test', 'tags' and 'fingerprint' are useful.
135 
136 '--test' runs once in the foreground with verbose logging, then exits.
137 It also exits if it can't get a valid catalog. `--test` includes the 
138 '--detailed-exitcodes' option by default and exits with one of the following 
139 exit codes:
140 
141 * 0: The run succeeded with no changes or failures; the system was already in 
142      the desired state.
143 * 1: The run failed, or wasn't attempted due to another run already in progress.
144 * 2: The run succeeded, and some resources were changed.
145 * 4: The run succeeded, and some resources failed.
146 * 6: The run succeeded, and included both changes and failures.
147 
148 '--tags' allows you to specify what portions of a configuration you want
149 to apply. Puppet elements are tagged with all of the class or definition
150 names that contain them, and you can use the 'tags' flag to specify one
151 of these names, causing only configuration elements contained within
152 that class or definition to be applied. This is very useful when you are
153 testing new configurations --- for instance, if you are just starting to
154 manage 'ntpd', you would put all of the new elements into an 'ntpd'
155 class, and call puppet with '--tags ntpd', which would only apply that
156 small portion of the configuration during your testing, rather than
157 applying the whole thing.
158 
159 '--fingerprint' is a one-time flag. In this mode 'puppet agent' runs
160 once and displays on the console (and in the log) the current certificate
161 (or certificate request) fingerprint. Providing the '--digest' option
162 allows you to use a different digest algorithm to generate the fingerprint.
163 The main use is to verify that before signing a certificate request on
164 the master, the certificate request the master received is the same as
165 the one the client sent (to prevent against man-in-the-middle attacks
166 when signing certificates).
167 
168 '--skip_tags' is a flag used to filter resources. If this is set, then
169 only resources not tagged with the specified tags will be applied.
170 Values must be comma-separated.
171 
172 
173 OPTIONS
174 -------
175 
176 Note that any Puppet setting that's valid in the configuration file is also a
177 valid long argument. For example, 'server' is a valid setting, so you can
178 specify '--server <servername>' as an argument. Boolean settings accept a '--no-' 
179 prefix to turn off a behavior, translating into '--setting' and '--no-setting' 
180 pairs, such as `--daemonize` and `--no-daemonize`.
181 
182 See the configuration file documentation at
183 https://puppet.com/docs/puppet/latest/configuration.html for the
184 full list of acceptable settings. A commented list of all settings can also be
185 generated by running puppet agent with '--genconfig'.
186 
187 * --certname:
188   Set the certname (unique ID) of the client. The master reads this
189   unique identifying string, which is usually set to the node's
190   fully-qualified domain name, to determine which configurations the
191   node will receive. Use this option to debug setup problems or
192   implement unusual node identification schemes.
193   (This is a Puppet setting, and can go in puppet.conf.)
194 
195 * --daemonize:
196   Send the process into the background. This is the default.
197   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
198   prefix for boolean settings on the command line.)
199 
200 * --no-daemonize:
201   Do not send the process into the background.
202   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
203   prefix for boolean settings on the command line.)
204 
205 * --debug:
206   Enable full debugging.
207 
208 * --detailed-exitcodes:
209   Provide extra information about the run via exit codes; works only if '--test'
210   or '--onetime' is also specified. If enabled, 'puppet agent' uses the
211   following exit codes:
212 
213   0: The run succeeded with no changes or failures; the system was already in
214   the desired state.
215 
216   1: The run failed, or wasn't attempted due to another run already in progress.
217 
218   2: The run succeeded, and some resources were changed.
219 
220   4: The run succeeded, and some resources failed.
221 
222   6: The run succeeded, and included both changes and failures.
223 
224 * --digest:
225   Change the certificate fingerprinting digest algorithm. The default is
226   SHA256. Valid values depends on the version of OpenSSL installed, but
227   will likely contain MD5, MD2, SHA1 and SHA256.
228 
229 * --disable:
230   Disable working on the local system. This puts a lock file in place,
231   causing 'puppet agent' not to work on the system until the lock file
232   is removed. This is useful if you are testing a configuration and do
233   not want the central configuration to override the local state until
234   everything is tested and committed.
235 
236   Disable can also take an optional message that will be reported by the
237   'puppet agent' at the next disabled run.
238 
239   'puppet agent' uses the same lock file while it is running, so no more
240   than one 'puppet agent' process is working at a time.
241 
242   'puppet agent' exits after executing this.
243 
244 * --enable:
245   Enable working on the local system. This removes any lock file,
246   causing 'puppet agent' to start managing the local system again
247   However, it continues to use its normal scheduling, so it might
248   not start for another half hour.
249 
250   'puppet agent' exits after executing this.
251   
252 *  --evaltrace:
253   Logs each resource as it is being evaluated. This allows you to interactively
254   see exactly what is being done. (This is a Puppet setting, and can go in
255   puppet.conf. Note the special 'no-' prefix for boolean settings on the command line.)
256 
257 * --fingerprint:
258   Display the current certificate or certificate signing request
259   fingerprint and then exit. Use the '--digest' option to change the
260   digest algorithm used.
261 
262 * --help:
263   Print this help message
264 
265 * --job-id:
266   Attach the specified job id to the catalog request and the report used for
267   this agent run. This option only works when '--onetime' is used.  When using
268   Puppet Enterprise this flag should not be used as the orchestrator sets the
269   job-id for you and it must be unique.
270 
271 * --logdest:
272   Where to send log messages. Choose between 'syslog' (the POSIX syslog
273   service), 'eventlog' (the Windows Event Log), 'console', or the path to a log
274   file. If debugging or verbosity is enabled, this defaults to 'console'.
275   Otherwise, it defaults to 'syslog' on POSIX systems and 'eventlog' on Windows.
276   Multiple destinations can be set using a comma separated list 
277   (eg: `/path/file1,console,/path/file2`)"
278 
279   A path ending with '.json' will receive structured output in JSON format. The
280   log file will not have an ending ']' automatically written to it due to the
281   appending nature of logging. It must be appended manually to make the content
282   valid JSON.
283 
284   A path ending with '.jsonl' will receive structured output in JSON Lines
285   format.
286 
287 * --masterport:
288   The port on which to contact the Puppet Server.
289   (This is a Puppet setting, and can go in puppet.conf.
290   Deprecated in favor of the 'serverport' setting.)
291 
292 * --noop:
293   Use 'noop' mode where the daemon runs in a no-op or dry-run mode. This
294   is useful for seeing what changes Puppet would make without actually
295   executing the changes.
296   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
297   prefix for boolean settings on the command line.)
298 
299 * --onetime:
300   Run the configuration once. Runs a single (normally daemonized) Puppet
301   run. Useful for interactively running puppet agent when used in
302   conjunction with the --no-daemonize option.
303   (This is a Puppet setting, and can go in puppet.conf. Note the special 'no-'
304   prefix for boolean settings on the command line.)
305 
306 * --serverport:
307   The port on which to contact the Puppet Server.
308   (This is a Puppet setting, and can go in puppet.conf.)
309 
310 * --sourceaddress:
311   Set the source IP address for transactions. This defaults to automatically selected.
312   (This is a Puppet setting, and can go in puppet.conf.)
313 
314 * --test:
315   Enable the most common options used for testing. These are 'onetime',
316   'verbose', 'no-daemonize', 'no-usecacheonfailure', 'detailed-exitcodes',
317   'no-splay', and 'show_diff'.
318   
319 * --trace
320   Prints stack traces on some errors. (This is a Puppet setting, and can go in
321   puppet.conf. Note the special 'no-' prefix for boolean settings on the command line.)
322 
323 * --verbose:
324   Turn on verbose reporting.
325 
326 * --version:
327   Print the puppet version number and exit.
328 
329 * --waitforcert:
330   This option only matters for daemons that do not yet have certificates
331   and it is enabled by default, with a value of 120 (seconds). This
332   causes 'puppet agent' to connect to the server every 2 minutes and ask
333   it to sign a certificate request. This is useful for the initial setup
334   of a puppet client. You can turn off waiting for certificates by
335   specifying a time of 0.
336   (This is a Puppet setting, and can go in puppet.conf.)
337 
338 * --write_catalog_summary
339   After compiling the catalog saves the resource list and classes list to the node
340   in the state directory named classes.txt and resources.txt
341   (This is a Puppet setting, and can go in puppet.conf.)
342 
343 EXAMPLE
344 -------
345     $ puppet agent --server puppet.domain.com
346 
347 
348 DIAGNOSTICS
349 -----------
350 
351 Puppet agent accepts the following signals:
352 
353 * SIGHUP:
354   Restart the puppet agent daemon.
355 * SIGINT and SIGTERM:
356   Shut down the puppet agent daemon.
357 * SIGUSR1:
358   Immediately retrieve and apply configurations from the puppet master.
359 * SIGUSR2:
360   Close file descriptors for log files and reopen them. Used with logrotate.
361 
362 AUTHOR
363 ------
364 Luke Kanies
365 
366 
367 COPYRIGHT
368 ---------
369 Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License
370 
371     HELP
372   end

    # File lib/puppet/application/agent.rb
402 def log_config
403   #skip also config reading and parsing if debug is not enabled
404   return unless Puppet::Util::Log.sendlevel?(:debug)
405 
406   Puppet.settings.stringify_settings(:agent, :all).each_pair do |k,v|
407     next if k.include?("password") || v.to_s.empty?
408     Puppet.debug("Using setting: #{k}=#{v}")
409   end
410 end

    # File lib/puppet/application/agent.rb
450 def main(daemon)
451   Puppet.notice _("Starting Puppet client version %{version}") % { version: Puppet.version }
452   daemon.start
453 end

    # File lib/puppet/application/agent.rb
432 def onetime(daemon)
433   begin
434     exitstatus = daemon.agent.run({:job_id => options[:job_id], :start_time => options[:start_time], :waitforcert => options[:waitforcert]})
435   rescue => detail
436     Puppet.log_exception(detail)
437   end
438 
439   daemon.stop(:exit => false)
440 
441   if not exitstatus
442     exit(1)
443   elsif options[:detailed_exitcodes] then
444     exit(exitstatus)
445   else
446     exit(0)
447   end
448 end

   # File lib/puppet/application/agent.rb
22 def preinit
23   # Do an initial trap, so that cancels don't get a stack trace.
24   Signal.trap(:INT) do
25     $stderr.puts _("Cancelling startup")
26     exit(0)
27   end
28 
29   {
30     :waitforcert => nil,
31     :detailed_exitcodes => false,
32     :verbose => false,
33     :debug => false,
34     :setdest => false,
35     :enable => false,
36     :disable => false,
37     :fqdn => nil,
38     :serve => [],
39     :digest => 'SHA256',
40     :graph => true,
41     :fingerprint => false,
42     :sourceaddress => nil,
43     :start_time => Time.now,
44   }.each do |opt,val|
45     options[opt] = val
46   end
47 
48   @argv = ARGV.dup
49 end

    # File lib/puppet/application/agent.rb
374 def run_command
375   if options[:fingerprint]
376     fingerprint
377   else
378     # It'd be nice to daemonize later, but we have to daemonize before
379     # waiting for certificates so that we don't block
380     daemon = daemonize_process_when(Puppet[:daemonize])
381 
382     # Setup signal traps immediately after daemonization so we clean up the daemon
383     daemon.set_signal_traps
384 
385     log_config if Puppet[:daemonize]
386 
387     # Each application is responsible for pushing loaders onto the context.
388     # Use the current environment that has already been established, though
389     # it may change later during the configurer run.
390     env = Puppet.lookup(:current_environment)
391     Puppet.override(current_environment: env,
392                     loaders: Puppet::Pops::Loaders.new(env, true)) do
393       if Puppet[:onetime]
394         onetime(daemon)
395       else
396         main(daemon)
397       end
398     end
399   end
400 end

    # File lib/puppet/application/agent.rb
466 def setup
467   raise ArgumentError, _("The puppet agent command does not take parameters") unless command_line.args.empty?
468 
469   setup_test if options[:test]
470 
471   setup_logs
472 
473   exit(Puppet.settings.print_configs ? 0 : 1) if Puppet.settings.print_configs?
474 
475   Puppet::SSL::Oids.register_puppet_oids
476 
477   if options[:fqdn]
478     Puppet[:certname] = options[:fqdn]
479   end
480 
481   Puppet.settings.use :main, :agent, :ssl
482 
483   Puppet::Transaction::Report.indirection.terminus_class = :rest
484   # we want the last report to be persisted locally
485   Puppet::Transaction::Report.indirection.cache_class = :yaml
486 
487   if Puppet[:catalog_cache_terminus]
488     Puppet::Resource::Catalog.indirection.cache_class = Puppet[:catalog_cache_terminus]
489   end
490 
491   # In fingerprint mode we don't need to set up the whole agent
492   unless options[:fingerprint]
493     setup_agent
494   end
495 end

    # File lib/puppet/application/agent.rb
456 def setup_test
457   Puppet.settings.handlearg("--no-usecacheonfailure")
458   Puppet.settings.handlearg("--no-splay")
459   Puppet.settings.handlearg("--show_diff")
460   Puppet.settings.handlearg("--no-daemonize")
461   options[:verbose] = true
462   Puppet[:onetime] = true
463   options[:detailed_exitcodes] = true
464 end

   # File lib/puppet/application/agent.rb
83 def summary
84   _("The puppet agent daemon")
85 end

    # File lib/puppet/application/agent.rb
516 def daemonize_process_when(should_daemonize)
517   daemon = Puppet::Daemon.new(@agent, Puppet::Util::Pidlock.new(Puppet[:pidfile]))
518   daemon.argv = @argv
519 
520   daemon.daemonize if should_daemonize
521 
522   daemon
523 end

    # File lib/puppet/application/agent.rb
499 def enable_disable_client(agent)
500   if options[:enable]
501     agent.enable
502   elsif options[:disable]
503     agent.disable(options[:disable_message] || 'reason not specified')
504   end
505   exit(0)
506 end

    # File lib/puppet/application/agent.rb
508 def setup_agent
509   agent = Puppet::Agent.new(Puppet::Configurer, (not(Puppet[:onetime])))
510 
511   enable_disable_client(agent) if options[:enable] or options[:disable]
512 
513   @agent = agent
514 end