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