1PUPPET-AGENT(8)                  Puppet manual                 PUPPET-AGENT(8)
2
3
4

NAME

6       puppet-agent - The puppet agent daemon
7

SYNOPSIS

9       Retrieves  the  client configuration from the Puppet master and applies
10       it to the local host.
11
12       This service may be run as a daemon, run periodically  using  cron  (or
13       something similar), or run interactively for testing purposes.
14

USAGE

16       puppet    agent   [--certname   NAME]   [-D|--daemonize|--no-daemonize]
17       [-d|--debug] [--detailed-exitcodes] [--digest DIGEST] [--disable  [MES‐
18       SAGE]]   [--enable]   [--fingerprint]  [-h|--help]  [-l|--logdest  sys‐
19       log|eventlog|ABS   FILEPATH|console]   [--serverport   PORT]   [--noop]
20       [-o|--onetime]  [--sourceaddress IP_ADDRESS] [-t|--test] [-v|--verbose]
21       [-V|--version] [-w|--waitforcert SECONDS]
22

DESCRIPTION

24       This is the main puppet client. Its job is to retrieve  the  local  ma‐
25       chine´s  configuration  from  a remote server and apply it. In order to
26       successfully communicate with the remote server, the client must have a
27       certificate  signed  by a certificate authority that the server trusts;
28       the recommended method for this, at the moment, is to run a certificate
29       authority  as  part  of  the  puppet server (which is the default). The
30       client will connect and request a signed certificate, and will continue
31       connecting until it receives one.
32
33       Once the client has a signed certificate, it will retrieve its configu‐
34       ration and apply it.
35

USAGE NOTES

37       ´puppet agent´ does its best to find a compromise  between  interactive
38       use  and  daemon use. If you run it with no arguments and no configura‐
39       tion, it goes into the background, attempts to get  a  signed  certifi‐
40       cate, and retrieves and applies its configuration every 30 minutes.
41
42       Some  flags  are meant specifically for interactive use --- in particu‐
43       lar, ´test´, ´tags´ and ´fingerprint´ are useful.
44
45       ´--test´ runs once in the foreground with verbose logging, then  exits.
46       It  also  exits  if  it  can´t get a valid catalog. --test includes the
47       ´--detailed-exitcodes´ option by default and exits with one of the fol‐
48       lowing exit codes:
49
50       •   0:  The  run  succeeded with no changes or failures; the system was
51           already in the desired state.
52
53       •   1: The run failed, or wasn´t attempted due to another  run  already
54           in progress.
55
56       •   2: The run succeeded, and some resources were changed.
57
58       •   4: The run succeeded, and some resources failed.
59
60       •   6: The run succeeded, and included both changes and failures.
61
62
63
64       ´--tags´  allows  you  to  specify what portions of a configuration you
65       want to apply. Puppet elements are tagged with all of the class or def‐
66       inition  names  that  contain  them, and you can use the ´tags´ flag to
67       specify one of these names, causing only  configuration  elements  con‐
68       tained within that class or definition to be applied. This is very use‐
69       ful when you are testing new configurations --- for  instance,  if  you
70       are  just  starting to manage ´ntpd´, you would put all of the new ele‐
71       ments into an ´ntpd´ class, and call puppet with ´--tags  ntpd´,  which
72       would  only  apply  that small portion of the configuration during your
73       testing, rather than applying the whole thing.
74
75       ´--fingerprint´ is a one-time flag. In this mode  ´puppet  agent´  runs
76       once  and displays on the console (and in the log) the current certifi‐
77       cate (or certificate request) fingerprint. Providing the ´--digest´ op‐
78       tion  allows  you  to  use a different digest algorithm to generate the
79       fingerprint. The main use is to verify that before signing  a  certifi‐
80       cate request on the master, the certificate request the master received
81       is  the  same  as  the  one  the  client  sent  (to   prevent   against
82       man-in-the-middle attacks when signing certificates).
83
84       ´--skip_tags´  is a flag used to filter resources. If this is set, then
85       only resources not tagged with the specified tags will be applied. Val‐
86       ues must be comma-separated.
87

OPTIONS

89       Note  that any Puppet setting that´s valid in the configuration file is
90       also a valid long argument. For example, ´server´ is a  valid  setting,
91       so  you  can specify ´--server servername´ as an argument. Boolean set‐
92       tings accept a ´--no-´ prefix to turn off a behavior, translating  into
93       ´--setting´ and ´--no-setting´ pairs, such as --daemonize and --no-dae‐
94       monize.
95
96       See   the   configuration   file    documentation    at    https://pup
97       pet.com/docs/puppet/latest/configuration.html  for the full list of ac‐
98       ceptable settings. A commented list of all settings can also be  gener‐
99       ated by running puppet agent with ´--genconfig´.
100
101       •   --certname:  Set the certname (unique ID) of the client. The master
102           reads this unique identifying string, which is usually set  to  the
103           node´s  fully-qualified  domain name, to determine which configura‐
104           tions the node will receive. Use this option to debug  setup  prob‐
105           lems  or  implement unusual node identification schemes. (This is a
106           Puppet setting, and can go in puppet.conf.)
107
108       •   --daemonize: Send the process into the background. This is the  de‐
109           fault.  (This  is a Puppet setting, and can go in puppet.conf. Note
110           the special ´no-´ prefix for boolean settings on the command line.)
111
112       •   --no-daemonize: Do not send the process into the background.  (This
113           is  a  Puppet  setting, and can go in puppet.conf. Note the special
114           ´no-´ prefix for boolean settings on the command line.)
115
116       •   --debug: Enable full debugging.
117
118       •   --detailed-exitcodes: Provide extra information about the  run  via
119           exit  codes;  works  only if ´--test´ or ´--onetime´ is also speci‐
120           fied. If enabled, ´puppet agent´ uses the following exit codes:
121
122           0: The run succeeded with no changes or failures;  the  system  was
123           already in the desired state.
124
125           1:  The  run failed, or wasn´t attempted due to another run already
126           in progress.
127
128           2: The run succeeded, and some resources were changed.
129
130           4: The run succeeded, and some resources failed.
131
132           6: The run succeeded, and included both changes and failures.
133
134       •   --digest: Change the certificate fingerprinting  digest  algorithm.
135           The  default  is  SHA256.  Valid  values  depends on the version of
136           OpenSSL installed, but will  likely  contain  MD5,  MD2,  SHA1  and
137           SHA256.
138
139       •   --disable:  Disable  working  on the local system. This puts a lock
140           file in place, causing ´puppet agent´ not to work on the system un‐
141           til  the  lock file is removed. This is useful if you are testing a
142           configuration and do not want the central configuration to override
143           the local state until everything is tested and committed.
144
145           Disable  can also take an optional message that will be reported by
146           the ´puppet agent´ at the next disabled run.
147
148           ´puppet agent´ uses the same lock file while it is running,  so  no
149           more than one ´puppet agent´ process is working at a time.
150
151           ´puppet agent´ exits after executing this.
152
153       •   --enable: Enable working on the local system. This removes any lock
154           file, causing ´puppet agent´ to start  managing  the  local  system
155           again  However,  it  continues  to use its normal scheduling, so it
156           might not start for another half hour.
157
158           ´puppet agent´ exits after executing this.
159
160       •   --evaltrace: Logs each resource as it is being evaluated. This  al‐
161           lows  you to interactively see exactly what is being done. (This is
162           a Puppet setting, and can go in puppet.conf. Note the special ´no-´
163           prefix for boolean settings on the command line.)
164
165       •   --fingerprint: Display the current certificate or certificate sign‐
166           ing request fingerprint and then exit. Use the ´--digest´ option to
167           change the digest algorithm used.
168
169       •   --help: Print this help message
170
171       •   --job-id:  Attach  the  specified job id to the catalog request and
172           the report used for this agent run. This  option  only  works  when
173           ´--onetime´  is used. When using Puppet Enterprise this flag should
174           not be used as the orchestrator sets the job-id for you and it must
175           be unique.
176
177       •   --logdest: Where to send log messages. Choose between ´syslog´ (the
178           POSIX syslog service), ´eventlog´ (the Windows  Event  Log),  ´con‐
179           sole´,  or the path to a log file. If debugging or verbosity is en‐
180           abled, this defaults to ´console´. Otherwise, it defaults to  ´sys‐
181           log´  on POSIX systems and ´eventlog´ on Windows. Multiple destina‐
182           tions can be set using a comma separated list (eg: /path/file1,con‐
183           sole,/path/file2)"
184
185           A  path  ending with ´.json´ will receive structured output in JSON
186           format. The log file will not  have  an  ending  ´]´  automatically
187           written  to  it  due to the appending nature of logging. It must be
188           appended manually to make the content valid JSON.
189
190           A path ending with ´.jsonl´ will receive structured output in  JSON
191           Lines format.
192
193       •   --masterport: The port on which to contact the Puppet Server. (This
194           is a Puppet setting, and can go in puppet.conf. Deprecated in favor
195           of the ´serverport´ setting.)
196
197       •   --noop: Use ´noop´ mode where the daemon runs in a no-op or dry-run
198           mode. This is useful for seeing  what  changes  Puppet  would  make
199           without  actually executing the changes. (This is a Puppet setting,
200           and can go in puppet.conf. Note the special ´no-´ prefix for  bool‐
201           ean settings on the command line.)
202
203       •   --onetime: Run the configuration once. Runs a single (normally dae‐
204           monized) Puppet run. Useful for interactively running puppet  agent
205           when used in conjunction with the --no-daemonize option. (This is a
206           Puppet setting, and can go in puppet.conf. Note the  special  ´no-´
207           prefix for boolean settings on the command line.)
208
209       •   --serverport: The port on which to contact the Puppet Server. (This
210           is a Puppet setting, and can go in puppet.conf.)
211
212       •   --sourceaddress: Set the source IP address for  transactions.  This
213           defaults  to automatically selected. (This is a Puppet setting, and
214           can go in puppet.conf.)
215
216       •   --test: Enable the most common options used for testing. These  are
217           ´onetime´,  ´verbose´, ´no-daemonize´, ´no-usecacheonfailure´, ´de‐
218           tailed-exitcodes´, ´no-splay´, and ´show_diff´.
219
220       •   --trace Prints stack traces on some errors. (This is a Puppet  set‐
221           ting,  and can go in puppet.conf. Note the special ´no-´ prefix for
222           boolean settings on the command line.)
223
224       •   --verbose: Turn on verbose reporting.
225
226       •   --version: Print the puppet version number and exit.
227
228       •   --waitforcert: This option only matters for daemons that do not yet
229           have certificates and it is enabled by default, with a value of 120
230           (seconds). This causes ´puppet agent´ to connect to the server  ev‐
231           ery  2  minutes  and  ask it to sign a certificate request. This is
232           useful for the initial setup of a puppet client. You can  turn  off
233           waiting for certificates by specifying a time of 0. (This is a Pup‐
234           pet setting, and can go in puppet.conf.)
235
236       •   --write_catalog_summary After compiling the catalog saves  the  re‐
237           source  list  and  classes  list to the node in the state directory
238           named classes.txt and resources.txt (This is a Puppet setting,  and
239           can go in puppet.conf.)
240
241
242

EXAMPLE

244       $ puppet agent --server puppet.domain.com
245

DIAGNOSTICS

247       Puppet agent accepts the following signals:
248
249       SIGHUP Restart the puppet agent daemon.
250
251       SIGINT and SIGTERM
252              Shut down the puppet agent daemon.
253
254       SIGUSR1
255              Immediately  retrieve  and  apply configurations from the puppet
256              master.
257
258       SIGUSR2
259              Close file descriptors for log files and reopen them. Used  with
260              logrotate.
261

AUTHOR

263       Luke Kanies
264
266       Copyright  (c)  2011 Puppet Inc., LLC Licensed under the Apache 2.0 Li‐
267       cense
268
269
270
271Puppet, Inc.                     October 2022                  PUPPET-AGENT(8)
Impressum