1PUPPETCONF(5) Puppet manual PUPPETCONF(5)
2
3
4
6
8 · Each of these settings can be specified in puppet.conf or on the
9 command line.
10
11 · Puppet Enterprise (PE) and open source Puppet share the configura‐
12 tion settings that are documented here. However, PE defaults for
13 some settings differ from the open source Puppet defaults. Some
14 examples of settings that have different PE defaults include dis‐
15 able18n, environment_timeout, always_retry_plugins, and the Puppet
16 Server JRuby max-active-instances setting. To verify PE configura‐
17 tion defaults, check the puppet.conf file after installation.
18
19 · When using boolean settings on the command line, use --setting and
20 --no-setting instead of --setting (true|false). (Using --setting
21 false results in "Error: Could not parse application options: need‐
22 less argument".)
23
24 · Settings can be interpolated as $variables in other settings;
25 $environment is special, in that puppet master will interpolate
26 each agent node´s environment instead of its own.
27
28 · Multiple values should be specified as comma-separated lists; mul‐
29 tiple directories should be separated with the system path separa‐
30 tor (usually a colon).
31
32 · Settings that represent time intervals should be specified in dura‐
33 tion format: an integer immediately followed by one of the units
34 ´y´ (years of 365 days), ´d´ (days), ´h´ (hours), ´m´ (minutes), or
35 ´s´ (seconds). The unit cannot be combined with other units, and
36 defaults to seconds when omitted. Examples are ´3600´ which is
37 equivalent to ´1h´ (one hour), and ´1825d´ which is equivalent to
38 ´5y´ (5 years).
39
40 · If you use the splay setting, note that the period that it waits
41 changes each time the Puppet agent is restarted.
42
43 · Settings that take a single file or directory can optionally set
44 the owner, group, and mode for their value: rundir = $vardir/run {
45 owner = puppet, group = puppet, mode = 644 }
46
47 · The Puppet executables will ignore any setting that isn´t relevant
48 to their function.
49
50
51
52 See the configuration guide https://puppet.com/docs/puppet/latest/con‐
53 fig_about_settings.html for more details.
54
55 agent_catalog_run_lockfile
56 A lock file to indicate that a puppet agent catalog run is currently in
57 progress. The file contains the pid of the process that holds the lock
58 on the catalog run.
59
60 · Default: $statedir/agent_catalog_run.lock
61
62
63
64 agent_disabled_lockfile
65 A lock file to indicate that puppet agent runs have been administra‐
66 tively disabled. File contains a JSON object with state information.
67
68 · Default: $statedir/agent_disabled.lock
69
70
71
72 allow_duplicate_certs
73 Whether to allow a new certificate request to overwrite an existing
74 certificate.
75
76 · Default: false
77
78
79
80 always_retry_plugins
81 Affects how we cache attempts to load Puppet resource types and fea‐
82 tures. If true, then calls to Puppet.type.<type>? Puppet.feature.<fea‐
83 ture>? will always attempt to load the type or feature (which can be an
84 expensive operation) unless it has already been loaded successfully.
85 This makes it possible for a single agent run to, e.g., install a pack‐
86 age that provides the underlying capabilities for a type or feature,
87 and then later load that type or feature during the same run (even if
88 the type or feature had been tested earlier and had not been avail‐
89 able).
90
91 If this setting is set to false, then types and features will only be
92 checked once, and if they are not available, the negative result is
93 cached and returned for all subsequent attempts to load the type or
94 feature. This behavior is almost always appropriate for the server, and
95 can result in a significant performance improvement for types and fea‐
96 tures that are checked frequently.
97
98 · Default: true
99
100
101
102 app_management
103 This setting has no effect and will be removed in a future Puppet ver‐
104 sion.
105
106 · Default: false
107
108
109
110 autoflush
111 Whether log files should always flush to disk.
112
113 · Default: true
114
115
116
117 autosign
118 Whether (and how) to autosign certificate requests. This setting is
119 only relevant on a puppet master acting as a certificate authority
120 (CA).
121
122 Valid values are true (autosigns all certificate requests; not recom‐
123 mended), false (disables autosigning certificates), or the absolute
124 path to a file.
125
126 The file specified in this setting may be either a configuration file
127 or a custom policy executable. Puppet will automatically determine what
128 it is: If the Puppet user (see the user setting) can execute the file,
129 it will be treated as a policy executable; otherwise, it will be
130 treated as a config file.
131
132 If a custom policy executable is configured, the CA puppet master will
133 run it every time it receives a CSR. The executable will be passed the
134 subject CN of the request as a command line argument, and the contents
135 of the CSR in PEM format on stdin. It should exit with a status of 0 if
136 the cert should be autosigned and non-zero if the cert should not be
137 autosigned.
138
139 If a certificate request is not autosigned, it will persist for review.
140 An admin user can use the puppet cert sign command to manually sign it,
141 or can delete the request.
142
143 For info on autosign configuration files, see the guide to Puppet´s
144 config files https://puppet.com/docs/puppet/latest/config_about_set‐
145 tings.html.
146
147 · Default: $confdir/autosign.conf
148
149
150
151 basemodulepath
152 The search path for global modules. Should be specified as a list of
153 directories separated by the system path separator character. (The
154 POSIX path separator is ´:´, and the Windows path separator is ´;´.)
155
156 These are the modules that will be used by all environments. Note that
157 the modules directory of the active environment will have priority over
158 any global directories. For more info, see https://puppet.com/docs/pup‐
159 pet/latest/environments_about.html
160
161 · Default: $codedir/modules:/opt/puppetlabs/puppet/modules
162
163
164
165 bindaddress
166 The address a listening server should bind to.
167
168 · Default: *
169
170
171
172 binder_config
173 The binder configuration file. Puppet reads this file on each request
174 to configure the bindings system. If set to nil (the default), a
175 $confdir/binder_config.yaml is optionally loaded. If it does not
176 exists, a default configuration is used. If the setting :binding_config
177 is specified, it must reference a valid and existing yaml file.
178
179 Default:
180
181
182 bucketdir
183 Where FileBucket files are stored.
184
185 · Default: $vardir/bucket
186
187
188
189 ca
190 Whether the master should function as a certificate authority.
191
192 · Default: true
193
194
195
196 ca_name
197 The name to use the Certificate Authority certificate.
198
199 · Default: Puppet CA: $certname
200
201
202
203 ca_port
204 The port to use for the certificate authority.
205
206 · Default: $masterport
207
208
209
210 ca_server
211 The server to use for certificate authority requests. It´s a separate
212 server because it cannot and does not need to horizontally scale.
213
214 · Default: $server
215
216
217
218 ca_ttl
219 The default TTL for new certificates. This setting can be a time inter‐
220 val in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
221 years (5y).
222
223 · Default: 5y
224
225
226
227 cacert
228 The CA certificate.
229
230 · Default: $cadir/ca_crt.pem
231
232
233
234 cacrl
235 The certificate revocation list (CRL) for the CA. Will be used if
236 present but otherwise ignored.
237
238 · Default: $cadir/ca_crl.pem
239
240
241
242 cadir
243 The root directory for the certificate authority.
244
245 · Default: $ssldir/ca
246
247
248
249 cakey
250 The CA private key.
251
252 · Default: $cadir/ca_key.pem
253
254
255
256 capass
257 Where the CA stores the password for the private key. This setting is
258 deprecated and will be removed in Puppet 6.
259
260 · Default: $caprivatedir/ca.pass
261
262
263
264 caprivatedir
265 Where the CA stores private certificate information. This setting is
266 deprecated and will be removed in Puppet 6.
267
268 · Default: $cadir/private
269
270
271
272 capub
273 The CA public key.
274
275 · Default: $cadir/ca_pub.pem
276
277
278
279 catalog_cache_terminus
280 How to store cached catalogs. Valid values are ´json´, ´msgpack´ and
281 ´yaml´. The agent application defaults to ´json´.
282
283 Default:
284
285
286 catalog_terminus
287 Where to get node catalogs. This is useful to change if, for instance,
288 you´d like to pre-compile catalogs and store them in memcached or some
289 other easily-accessed store.
290
291 · Default: compiler
292
293
294
295 cert_inventory
296 The inventory file. This is a text file to which the CA writes a com‐
297 plete listing of all certificates.
298
299 · Default: $cadir/inventory.txt
300
301
302
303 certdir
304 The certificate directory.
305
306 · Default: $ssldir/certs
307
308
309
310 certificate_revocation
311 Whether certificate revocation checking should be enabled, and what
312 level of checking should be performed.
313
314 When certificate_revocation is set to ´true´ or ´chain´, Puppet will
315 download the CA CRL and will perform revocation checking against each
316 certificate in the chain.
317
318 Puppet is unable to load multiple CRLs, so if certificate_revocation is
319 set to ´chain´ and Puppet attempts to verify a certificate signed by a
320 root CA the behavior is equivalent to the ´leaf´ setting, and if Puppet
321 attempts to verify a certificate signed by an intermediate CA then ver‐
322 ification will fail as Puppet will be unable to load the multiple CRLs
323 required for full chain checking. As such the ´chain´ setting is lim‐
324 ited in functionality and is meant as a stand in pending the implemen‐
325 tation of full chain checking.
326
327 When certificate_revocation is set to ´leaf´, Puppet will download the
328 CA CRL and will verify the leaf certificate against that CRL. CRLs will
329 not be fetched or checked for the rest of the certificates in the
330 chain. If you are using an intermediate CA certificate and want to
331 enable certificate revocation checking, this setting must be set to
332 ´leaf´.
333
334 When certificate_revocation is set to ´false´, Puppet will disable all
335 certificate revocation checking and will not attempt to download the
336 CRL.
337
338 · Default: chain
339
340
341
342 certname
343 The name to use when handling certificates. When a node requests a cer‐
344 tificate from the CA puppet master, it uses the value of the certname
345 setting as its requested Subject CN.
346
347 This is the name used when managing a node´s permissions in auth.conf
348 https://puppet.com/docs/puppet/latest/config_file_auth.html. In most
349 cases, it is also used as the node´s name when matching node defini‐
350 tions https://puppet.com/docs/puppet/latest/lang_node_definitions.html
351 and requesting data from an ENC. (This can be changed with the
352 node_name_value and node_name_fact settings, although you should only
353 do so if you have a compelling reason.)
354
355 A node´s certname is available in Puppet manifests as $trusted[´cert‐
356 name´]. (See Facts and Built-In Variables https://puppet.com/docs/pup‐
357 pet/latest/lang_facts_and_builtin_vars.html for more details.)
358
359 · For best compatibility, you should limit the value of certname to
360 only use lowercase letters, numbers, periods, underscores, and
361 dashes. (That is, it should match /A[a-z0-9._-]+Z/.)
362
363 · The special value ca is reserved, and can´t be used as the certname
364 for a normal node.
365
366
367
368 Defaults to the node´s fully qualified domain name.
369
370 · Default: the Host´s fully qualified domain name, as determined by
371 facter
372
373
374
375 classfile
376 The file in which puppet agent stores a list of the classes associated
377 with the retrieved configuration. Can be loaded in the separate puppet
378 executable using the --loadclasses option.
379
380 · Default: $statedir/classes.txt
381
382
383
384 client_datadir
385 The directory in which serialized data is stored on the client.
386
387 · Default: $vardir/client_data
388
389
390
391 clientbucketdir
392 Where FileBucket files are stored locally.
393
394 · Default: $vardir/clientbucket
395
396
397
398 clientyamldir
399 The directory in which client-side YAML data is stored.
400
401 · Default: $vardir/client_yaml
402
403
404
405 code
406 Code to parse directly. This is essentially only used by puppet, and
407 should only be set if you´re writing your own Puppet executable.
408
409 codedir
410 The main Puppet code directory. The default for this setting is calcu‐
411 lated based on the user. If the process is running as root or the user
412 that Puppet is supposed to run as, it defaults to a system directory,
413 but if it´s running as any other user, it defaults to being in the
414 user´s home directory.
415
416 · Default: Unix/Linux: /etc/puppetlabs/code -- Windows: C:\Program‐
417 Data\PuppetLabs\code -- Non-root user: ~/.puppetlabs/etc/code
418
419
420
421 color
422 Whether to use colors when logging to the console. Valid values are
423 ansi (equivalent to true), html, and false, which produces no color.
424 Defaults to false on Windows, as its console does not support ansi col‐
425 ors.
426
427 · Default: ansi
428
429
430
431 confdir
432 The main Puppet configuration directory. The default for this setting
433 is calculated based on the user. If the process is running as root or
434 the user that Puppet is supposed to run as, it defaults to a system
435 directory, but if it´s running as any other user, it defaults to being
436 in the user´s home directory.
437
438 · Default: Unix/Linux: /etc/puppetlabs/puppet -- Windows: C:\Program‐
439 Data\PuppetLabs\puppet\etc -- Non-root user: ~/.puppetlabs/etc/pup‐
440 pet
441
442
443
444 config
445 The configuration file for the current puppet application.
446
447 · Default: $confdir/${config_file_name}
448
449
450
451 config_file_name
452 The name of the puppet config file.
453
454 · Default: puppet.conf
455
456
457
458 config_version
459 How to determine the configuration version. By default, it will be the
460 time that the configuration is parsed, but you can provide a shell
461 script to override how the version is determined. The output of this
462 script will be added to every log message in the reports, allowing you
463 to correlate changes on your hosts to the source version on the server.
464
465 Setting a global value for config_version in puppet.conf is not allowed
466 (but it can be overridden from the commandline). Please set a per-envi‐
467 ronment value in environment.conf instead. For more info, see
468 https://puppet.com/docs/puppet/latest/environments_about.html
469
470 configprint
471 Prints the value of a specific configuration setting. If the name of a
472 setting is provided for this, then the value is printed and puppet
473 exits. Comma-separate multiple values. For a list of all values, spec‐
474 ify ´all´. This setting is deprecated, the ´puppet config´ command
475 replaces this functionality.
476
477 configtimeout
478 How long the client should wait for the configuration to be retrieved
479 before considering it a failure. This setting is deprecated and has
480 been replaced by http_connect_timeout and http_read_timeout. This set‐
481 ting can be a time interval in seconds (30 or 30s), minutes (30m),
482 hours (6h), days (2d), or years (5y).
483
484 · Default: 2m
485
486
487
488 csr_attributes
489 An optional file containing custom attributes to add to certificate
490 signing requests (CSRs). You should ensure that this file does not
491 exist on your CA puppet master; if it does, unwanted certificate exten‐
492 sions may leak into certificates created with the puppet cert generate
493 command.
494
495 If present, this file must be a YAML hash containing a cus‐
496 tom_attributes key and/or an extension_requests key. The value of each
497 key must be a hash, where each key is a valid OID and each value is an
498 object that can be cast to a string.
499
500 Custom attributes can be used by the CA when deciding whether to sign
501 the certificate, but are then discarded. Attribute OIDs can be any OID
502 value except the standard CSR attributes (i.e. attributes described in
503 RFC 2985 section 5.4). This is useful for embedding a pre-shared key
504 for autosigning policy executables (see the autosign setting), often by
505 using the 1.2.840.113549.1.9.7 ("challenge password") OID.
506
507 Extension requests will be permanently embedded in the final certifi‐
508 cate. Extension OIDs must be in the "ppRegCertExt"
509 (1.3.6.1.4.1.34380.1.1), "ppPrivCertExt" (1.3.6.1.4.1.34380.1.2), or
510 "ppAuthCertExt" (1.3.6.1.4.1.34380.1.3) OID arcs. The ppRegCertExt arc
511 is reserved for four of the most common pieces of data to embed:
512 pp_uuid (.1), pp_instance_id (.2), pp_image_name (.3), and pp_pre‐
513 shared_key (.4) --- in the YAML file, these can be referred to by their
514 short descriptive names instead of their full OID. The ppPrivCertExt
515 arc is unregulated, and can be used for site-specific extensions. The
516 ppAuthCert arc is reserved for two pieces of data to embed: pp_autho‐
517 rization (.1) and pp_auth_role (.13). As with ppRegCertExt, in the YAML
518 file, these can be referred to by their short descriptive name instead
519 of their full OID.
520
521 · Default: $confdir/csr_attributes.yaml
522
523
524
525 csrdir
526 Where the CA stores certificate requests.
527
528 · Default: $cadir/requests
529
530
531
532 daemonize
533 Whether to send the process into the background. This defaults to true
534 on POSIX systems, and to false on Windows (where Puppet currently can‐
535 not daemonize).
536
537 · Default: true
538
539
540
541 data_binding_terminus
542 This setting has been deprecated. Use of any value other than ´hiera´
543 should instead be configured in a version 5 hiera.yaml. Until this set‐
544 ting is removed, it controls which data binding terminus to use for
545 global automatic data binding (across all environments). By default
546 this value is ´hiera´. A value of ´none´ turns off the global binding.
547
548 · Default: hiera
549
550
551
552 default_file_terminus
553 The default source for files if no server is given in a uri, e.g. pup‐
554 pet:///file. The default of rest causes the file to be retrieved using
555 the server setting. When running apply the default is file_server,
556 causing requests to be filled locally.
557
558 · Default: rest
559
560
561
562 default_manifest
563 The default main manifest for directory environments. Any environment
564 that doesn´t set the manifest setting in its environment.conf file will
565 use this manifest.
566
567 This setting´s value can be an absolute or relative path. An absolute
568 path will make all environments default to the same main manifest; a
569 relative path will allow each environment to use its own manifest, and
570 Puppet will resolve the path relative to each environment´s main direc‐
571 tory.
572
573 In either case, the path can point to a single file or to a directory
574 of manifests to be evaluated in alphabetical order.
575
576 · Default: ./manifests
577
578
579
580 default_schedules
581 Boolean; whether to generate the default schedule resources. Setting
582 this to false is useful for keeping external report processors clean of
583 skipped schedule resources.
584
585 · Default: true
586
587
588
589 deviceconfig
590 Path to the device config file for puppet device.
591
592 · Default: $confdir/device.conf
593
594
595
596 devicedir
597 The root directory of devices´ $vardir.
598
599 · Default: $vardir/devices
600
601
602
603 diff
604 Which diff command to use when printing differences between files. This
605 setting has no default value on Windows, as standard diff is not avail‐
606 able, but Puppet can use many third-party diff tools.
607
608 · Default: diff
609
610
611
612 diff_args
613 Which arguments to pass to the diff command when printing differences
614 between files. The command to use can be chosen with the diff setting.
615
616 · Default: -u
617
618
619
620 digest_algorithm
621 Which digest algorithm to use for file resources and the filebucket.
622 Valid values are md5, sha256, sha384, sha512, sha224. Default is md5.
623
624 · Default: md5
625
626
627
628 disable_i18n
629 If true, turns off all translations of Puppet and module log messages,
630 which affects error, warning, and info log messages, as well as any
631 translations in the report and CLI.
632
633 · Default: false
634
635
636
637 disable_per_environment_manifest
638 Whether to disallow an environment-specific main manifest. When set to
639 true, Puppet will use the manifest specified in the default_manifest
640 setting for all environments. If an environment specifies a different
641 main manifest in its environment.conf file, catalog requests for that
642 environment will fail with an error.
643
644 This setting requires default_manifest to be set to an absolute path.
645
646 · Default: false
647
648
649
650 disable_warnings
651 A comma-separated list of warning types to suppress. If large numbers
652 of warnings are making Puppet´s logs too large or difficult to use, you
653 can temporarily silence them with this setting.
654
655 If you are preparing to upgrade Puppet to a new major version, you
656 should re-enable all warnings for a while.
657
658 Valid values for this setting are:
659
660 · deprecations --- disables deprecation warnings.
661
662 · undefined_variables --- disables warnings about non existing vari‐
663 ables.
664
665 · undefined_resources --- disables warnings about non existing
666 resources.
667
668 · Default: []
669
670
671
672 dns_alt_names
673 A comma-separated list of alternate DNS names for Puppet Server. These
674 are extra hostnames (in addition to its certname) that the server is
675 allowed to use when serving agents. Puppet checks this setting when
676 automatically requesting a certificate for Puppet agent or Puppet
677 Server, and when manually generating a certificate with puppet cert
678 generate. These can be either IP or DNS, and the type should be speci‐
679 fied and followed with a colon. Untyped inputs will default to DNS.
680
681 In order to handle agent requests at a given hostname (like "pup‐
682 pet.example.com"), Puppet Server needs a certificate that proves it´s
683 allowed to use that name; if a server shows a certificate that doesn´t
684 include its hostname, Puppet agents will refuse to trust it. If you use
685 a single hostname for Puppet traffic but load-balance it to multiple
686 Puppet Servers, each of those servers needs to include the official
687 hostname in its list of extra names.
688
689 Note: The list of alternate names is locked in when the server´s cer‐
690 tificate is signed. If you need to change the list later, you can´t
691 just change this setting; you also need to:
692
693 · On the server: Stop Puppet Server.
694
695 · On the CA server: Revoke and clean the server´s old certificate.
696 (puppet cert clean <NAME>) (Note puppet cert clean is deprecated
697 and will be replaced with puppetserver ca clean in Puppet 6.)
698
699 · On the server: Delete the old certificate (and any old certificate
700 signing requests) from the ssldir https://puppet.com/docs/pup‐
701 pet/latest/dirs_ssldir.html.
702
703 · On the server: Run puppet agent -t --ca_server <CA HOSTNAME> to
704 request a new certificate
705
706 · On the CA server: Sign the certificate request, explicitly allowing
707 alternate names (puppet cert sign --allow-dns-alt-names <NAME>).
708 (Note puppet cert sign is deprecated and will be replaced with pup‐
709 petserver ca sign in Puppet 6.)
710
711 · On the server: Run puppet agent -t --ca_server <CA HOSTNAME> to
712 retrieve the cert.
713
714 · On the server: Start Puppet Server again.
715
716
717
718 To see all the alternate names your servers are using, log into your CA
719 server and run puppet cert list -a, then check the output for (alt
720 names: ...). Most agent nodes should NOT have alternate names; the only
721 certs that should have them are Puppet Server nodes that you want other
722 agents to trust.
723
724 document_all
725 Whether to document all resources when using puppet doc to generate
726 manifest documentation.
727
728 · Default: false
729
730
731
732 environment
733 The environment in which Puppet is running. For clients, such as puppet
734 agent, this determines the environment itself, which Puppet uses to
735 find modules and much more. For servers, such as puppet master, this
736 provides the default environment for nodes that Puppet knows nothing
737 about.
738
739 When defining an environment in the [agent] section, this refers to the
740 environment that the agent requests from the master. The environment
741 doesn´t have to exist on the local filesystem because the agent fetches
742 it from the master. This definition is used when running puppet agent.
743
744 When defined in the [user] section, the environment refers to the path
745 that Puppet uses to search for code and modules related to its execu‐
746 tion. This requires the environment to exist locally on the filesystem
747 where puppet is being executed. Puppet subcommands, including puppet
748 module and puppet apply, use this definition.
749
750 Given that the context and effects vary depending on the config section
751 https://puppet.com/docs/puppet/latest/config_file_main.html#config-sec‐
752 tions in which the environment setting is defined, do not set it glob‐
753 ally.
754
755 · Default: production
756
757
758
759 environment_data_provider
760 The name of a registered environment data provider used when obtaining
761 environment specific data. The three built in and registered providers
762 are ´none´ (no data), ´function´ (data obtained by calling the function
763 ´environment::data()´) and ´hiera´ (data obtained using a data provider
764 configured using a hiera.yaml file in root of the environment). Other
765 environment data providers may be registered in modules on the module
766 path. For such custom data providers see the respective module documen‐
767 tation. This setting is deprecated.
768
769 Default:
770
771
772 environment_timeout
773 How long the Puppet master should cache data it loads from an environ‐
774 ment. This setting can be a time interval in seconds (30 or 30s), min‐
775 utes (30m), hours (6h), days (2d), or years (5y). A value of 0 will
776 disable caching. This setting can also be set to unlimited, which will
777 cache environments until the master is restarted or told to refresh the
778 cache.
779
780 You should change this setting once your Puppet deployment is doing
781 non-trivial work. We chose the default value of 0 because it lets new
782 users update their code without any extra steps, but it lowers the per‐
783 formance of your Puppet master.
784
785 We recommend setting this to unlimited and explicitly refreshing your
786 Puppet master as part of your code deployment process.
787
788 · With Puppet Server, you should refresh environments by calling the
789 environment-cache API endpoint. See the docs for the Puppet Server
790 administrative API.
791
792 · With a Rack Puppet master, you should restart the web server or the
793 application server. Passenger lets you touch a restart.txt file to
794 refresh an application without restarting Apache; see the Passenger
795 docs for details.
796
797
798
799 We don´t recommend using any value other than 0 or unlimited, since
800 most Puppet masters use a pool of Ruby interpreters which all have
801 their own cache timers. When these timers drift out of sync, agents can
802 be served inconsistent catalogs.
803
804 · Default: 0
805
806
807
808 environmentpath
809 A search path for directory environments, as a list of directories sep‐
810 arated by the system path separator character. (The POSIX path separa‐
811 tor is ´:´, and the Windows path separator is ´;´.)
812
813 This setting must have a value set to enable directory environments.
814 The recommended value is $codedir/environments. For more details, see
815 https://puppet.com/docs/puppet/latest/environments_about.html
816
817 · Default: $codedir/environments
818
819
820
821 evaltrace
822 Whether each resource should log when it is being evaluated. This
823 allows you to interactively see exactly what is being done.
824
825 · Default: false
826
827
828
829 external_nodes
830 The external node classifier (ENC) script to use for node data. Puppet
831 combines this data with the main manifest to produce node catalogs.
832
833 To enable this setting, set the node_terminus setting to exec.
834
835 This setting´s value must be the path to an executable command that can
836 produce node information. The command must:
837
838 · Take the name of a node as a command-line argument.
839
840 ·
841
842 · classes --- A list of classes, as an array or hash.
843
844 · environment --- A string.
845
846 · parameters --- A list of top-scope variables to set, as a hash.
847
848
849
850
851 · For unknown nodes, exit with a non-zero exit code.
852
853
854
855 Generally, an ENC script makes requests to an external data source.
856
857 For more info, see the ENC documentation https://puppet.com/docs/pup‐
858 pet/latest/nodes_external.html.
859
860 · Default: none
861
862
863
864 factpath
865 Where Puppet should look for facts. Multiple directories should be sep‐
866 arated by the system path separator character. (The POSIX path separa‐
867 tor is ´:´, and the Windows path separator is ´;´.)
868
869 · Default: $vardir/lib/facter:$vardir/facts
870
871
872
873 facts_terminus
874 The node facts terminus.
875
876 · Default: facter
877
878
879
880 fileserverconfig
881 Where the fileserver configuration is stored.
882
883 · Default: $confdir/fileserver.conf
884
885
886
887 filetimeout
888 The minimum time to wait between checking for updates in configuration
889 files. This timeout determines how quickly Puppet checks whether a file
890 (such as manifests or templates) has changed on disk. This setting can
891 be a time interval in seconds (30 or 30s), minutes (30m), hours (6h),
892 days (2d), or years (5y).
893
894 · Default: 15s
895
896
897
898 forge_authorization
899 The authorization key to connect to the Puppet Forge. Leave blank for
900 unauthorized or license based connections
901
902 Default:
903
904
905 freeze_main
906 Freezes the ´main´ class, disallowing any code to be added to it. This
907 essentially means that you can´t have any code outside of a node,
908 class, or definition other than in the site manifest.
909
910 · Default: false
911
912
913
914 future_features
915 Whether or not to enable all features currently being developed for
916 future major releases of Puppet. Should be used with caution, as in
917 development features are experimental and can have unexpected effects.
918
919 · Default: false
920
921
922
923 genconfig
924 When true, causes Puppet applications to print an example config file
925 to stdout and exit. The example will include descriptions of each set‐
926 ting, and the current (or default) value of each setting, incorporating
927 any settings overridden on the CLI (with the exception of genconfig
928 itself). This setting only makes sense when specified on the command
929 line as --genconfig.
930
931 · Default: false
932
933
934
935 genmanifest
936 Whether to just print a manifest to stdout and exit. Only makes sense
937 when specified on the command line as --genmanifest. Takes into account
938 arguments specified on the CLI.
939
940 · Default: false
941
942
943
944 graph
945 Whether to create .dot graph files, which let you visualize the depen‐
946 dency and containment relationships in Puppet´s catalog. You can load
947 and view these files with tools like OmniGraffle http://www.omni‐
948 group.com/applications/omnigraffle/ (OS X) or graphviz
949 http://www.graphviz.org/ (multi-platform).
950
951 Graph files are created when applying a catalog, so this setting should
952 be used on nodes running puppet agent or puppet apply.
953
954 The graphdir setting determines where Puppet will save graphs. Note
955 that we don´t save graphs for historical runs; Puppet will replace the
956 previous .dot files with new ones every time it applies a catalog.
957
958 See your graphing software´s documentation for details on opening .dot
959 files. If you´re using GraphViz´s dot command, you can do a quick PNG
960 render with dot -Tpng <DOT FILE> -o <OUTPUT FILE>.
961
962 · Default: false
963
964
965
966 graphdir
967 Where to save .dot-format graphs (when the graph setting is enabled).
968
969 · Default: $statedir/graphs
970
971
972
973 group
974 The group Puppet Server will run as. Used to ensure the agent side pro‐
975 cesses (agent, apply, etc) create files and directories readable by
976 Puppet Server when necessary.
977
978 · Default: puppet
979
980
981
982 hiera_config
983 The hiera configuration file. Puppet only reads this file on startup,
984 so you must restart the puppet master every time you edit it.
985
986 · Default: $confdir/hiera.yaml. However, if a file exists at
987 $codedir/hiera.yaml, Puppet uses that instead.
988
989
990
991 hostcert
992 Where individual hosts store and look for their certificates.
993
994 · Default: $certdir/$certname.pem
995
996
997
998 hostcrl
999 Where the host´s certificate revocation list can be found. This is dis‐
1000 tinct from the certificate authority´s CRL.
1001
1002 · Default: $ssldir/crl.pem
1003
1004
1005
1006 hostcsr
1007 Where individual hosts store and look for their certificate requests.
1008
1009 · Default: $ssldir/csr_$certname.pem
1010
1011
1012
1013 hostprivkey
1014 Where individual hosts store and look for their private key.
1015
1016 · Default: $privatekeydir/$certname.pem
1017
1018
1019
1020 hostpubkey
1021 Where individual hosts store and look for their public key.
1022
1023 · Default: $publickeydir/$certname.pem
1024
1025
1026
1027 http_connect_timeout
1028 The maximum amount of time to wait when establishing an HTTP connec‐
1029 tion. The default value is 2 minutes. This setting can be a time inter‐
1030 val in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
1031 years (5y).
1032
1033 · Default: 2m
1034
1035
1036
1037 http_debug
1038 Whether to write HTTP request and responses to stderr. This should
1039 never be used in a production environment.
1040
1041 · Default: false
1042
1043
1044
1045 http_keepalive_timeout
1046 The maximum amount of time a persistent HTTP connection can remain idle
1047 in the connection pool, before it is closed. This timeout should be
1048 shorter than the keepalive timeout used on the HTTP server, e.g. Apache
1049 KeepAliveTimeout directive. This setting can be a time interval in sec‐
1050 onds (30 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1051
1052 · Default: 4s
1053
1054
1055
1056 http_proxy_host
1057 The HTTP proxy host to use for outgoing connections. The proxy will be
1058 bypassed if the server´s hostname matches the NO_PROXY environment
1059 variable or no_proxy setting. Note: You may need to use a FQDN for the
1060 server hostname when using a proxy. Environment variable http_proxy or
1061 HTTP_PROXY will override this value.
1062
1063 · Default: none
1064
1065
1066
1067 http_proxy_password
1068 The password for the user of an authenticated HTTP proxy. Requires the
1069 http_proxy_user setting.
1070
1071 Note that passwords must be valid when used as part of a URL. If a
1072 password contains any characters with special meanings in URLs (as
1073 specified by RFC 3986 section 2.2), they must be URL-encoded. (For
1074 example, # would become %23.)
1075
1076 · Default: none
1077
1078
1079
1080 http_proxy_port
1081 The HTTP proxy port to use for outgoing connections
1082
1083 · Default: 3128
1084
1085
1086
1087 http_proxy_user
1088 The user name for an authenticated HTTP proxy. Requires the
1089 http_proxy_host setting.
1090
1091 · Default: none
1092
1093
1094
1095 http_read_timeout
1096 The time to wait for one block to be read from an HTTP connection. If
1097 nothing is read after the elapsed interval then the connection will be
1098 closed. The default value is unlimited. This setting can be a time
1099 interval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d),
1100 or years (5y).
1101
1102 Default:
1103
1104
1105 http_user_agent
1106 The HTTP User-Agent string to send when making network requests.
1107
1108 · Default: Puppet/5.5.20 Ruby/2.4.1-p111 (x86_64-linux)
1109
1110
1111
1112 ignorecache
1113 This setting has no effect and will be removed in a future Puppet ver‐
1114 sion.
1115
1116 · Default: false
1117
1118
1119
1120 ignoremissingtypes
1121 Skip searching for classes and definitions that were missing during a
1122 prior compilation. The list of missing objects is maintained per-envi‐
1123 ronment and persists until the environment is cleared or the master is
1124 restarted.
1125
1126 · Default: false
1127
1128
1129
1130 ignoreschedules
1131 Boolean; whether puppet agent should ignore schedules. This is useful
1132 for initial puppet agent runs.
1133
1134 · Default: false
1135
1136
1137
1138 keylength
1139 The bit length of keys.
1140
1141 · Default: 4096
1142
1143
1144
1145 lastrunfile
1146 Where puppet agent stores the last run report summary in yaml format.
1147
1148 · Default: $statedir/last_run_summary.yaml
1149
1150
1151
1152 lastrunreport
1153 Where puppet agent stores the last run report in yaml format.
1154
1155 · Default: $statedir/last_run_report.yaml
1156
1157
1158
1159 ldapattrs
1160 The LDAP attributes to include when querying LDAP for nodes. All
1161 returned attributes are set as variables in the top-level scope. Multi‐
1162 ple values should be comma-separated. The value ´all´ returns all
1163 attributes.
1164
1165 · Default: all
1166
1167
1168
1169 ldapbase
1170 The search base for LDAP searches. It´s impossible to provide a mean‐
1171 ingful default here, although the LDAP libraries might have one already
1172 set. Generally, it should be the ´ou=Hosts´ branch under your main
1173 directory.
1174
1175 ldapclassattrs
1176 The LDAP attributes to use to define Puppet classes. Values should be
1177 comma-separated.
1178
1179 · Default: puppetclass
1180
1181
1182
1183 ldapparentattr
1184 The attribute to use to define the parent node.
1185
1186 · Default: parentnode
1187
1188
1189
1190 ldappassword
1191 The password to use to connect to LDAP.
1192
1193 ldapport
1194 The LDAP port. Only used if node_terminus is set to ldap.
1195
1196 · Default: 389
1197
1198
1199
1200 ldapserver
1201 The LDAP server. Only used if node_terminus is set to ldap.
1202
1203 · Default: ldap
1204
1205
1206
1207 ldapssl
1208 Whether SSL should be used when searching for nodes. Defaults to false
1209 because SSL usually requires certificates to be set up on the client
1210 side.
1211
1212 · Default: false
1213
1214
1215
1216 ldapstackedattrs
1217 The LDAP attributes that should be stacked to arrays by adding the val‐
1218 ues in all hierarchy elements of the tree. Values should be comma-sepa‐
1219 rated.
1220
1221 · Default: puppetvar
1222
1223
1224
1225 ldapstring
1226 The search string used to find an LDAP node.
1227
1228 · Default: (&(objectclass=puppetClient)(cn=%s))
1229
1230
1231
1232 ldaptls
1233 Whether TLS should be used when searching for nodes. Defaults to false
1234 because TLS usually requires certificates to be set up on the client
1235 side.
1236
1237 · Default: false
1238
1239
1240
1241 ldapuser
1242 The user to use to connect to LDAP. Must be specified as a full DN.
1243
1244 libdir
1245 An extra search path for Puppet. This is only useful for those files
1246 that Puppet will load on demand, and is only guaranteed to work for
1247 those cases. In fact, the autoload mechanism is responsible for making
1248 sure this directory is in Ruby´s search path
1249
1250 · Default: $vardir/lib
1251
1252
1253
1254 localcacert
1255 Where each client stores the CA certificate.
1256
1257 · Default: $certdir/ca.pem
1258
1259
1260
1261 localedest
1262 Where Puppet should store translation files that it pulls down from the
1263 central server.
1264
1265 · Default: $vardir/locales
1266
1267
1268
1269 localesource
1270 From where to retrieve translation files. The standard Puppet file type
1271 is used for retrieval, so anything that is a valid file source can be
1272 used here.
1273
1274 · Default: puppet:///locales
1275
1276
1277
1278 log_level
1279 Default logging level for messages from Puppet. Allowed values are:
1280
1281 · debug
1282
1283 · info
1284
1285 · notice
1286
1287 · warning
1288
1289 · err
1290
1291 · alert
1292
1293 · emerg
1294
1295 · crit
1296
1297 · Default: notice
1298
1299
1300
1301 logdest
1302 Where to send log messages. Choose between ´syslog´ (the POSIX syslog
1303 service), ´eventlog´ (the Windows Event Log), ´console´, or the path to
1304 a log file.
1305
1306 Default:
1307
1308
1309 logdir
1310 The directory in which to store log files
1311
1312 · Default: Unix/Linux: /var/log/puppetlabs/puppet -- Windows: C:\Pro‐
1313 gramData\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppet‐
1314 labs/var/log
1315
1316
1317
1318 manage_internal_file_permissions
1319 Whether Puppet should manage the owner, group, and mode of files it
1320 uses internally
1321
1322 · Default: true
1323
1324
1325
1326 manifest
1327 The entry-point manifest for puppet master. This can be one file or a
1328 directory of manifests to be evaluated in alphabetical order. Puppet
1329 manages this path as a directory if one exists or if the path ends with
1330 a / or .
1331
1332 Setting a global value for manifest in puppet.conf is not allowed (but
1333 it can be overridden from the commandline). Please use directory envi‐
1334 ronments instead. If you need to use something other than the environ‐
1335 ment´s manifests directory as the main manifest, you can set manifest
1336 in environment.conf. For more info, see https://puppet.com/docs/pup‐
1337 pet/latest/environments_about.html
1338
1339 Default:
1340
1341
1342 masterhttplog
1343 Where the puppet master web server saves its access log. This is only
1344 used when running a WEBrick puppet master. When puppet master is run‐
1345 ning under a Rack server like Passenger, that web server will have its
1346 own logging behavior.
1347
1348 · Default: $logdir/masterhttp.log
1349
1350
1351
1352 masterport
1353 The default port puppet subcommands use to communicate with Puppet
1354 Server. (eg puppet facts upload, puppet agent). May be overridden by
1355 more specific settings (see ca_port, report_port).
1356
1357 · Default: 8140
1358
1359
1360
1361 max_deprecations
1362 Sets the max number of logged/displayed parser validation deprecation
1363 warnings in case multiple deprecation warnings have been detected. A
1364 value of 0 blocks the logging of deprecation warnings. The count is per
1365 manifest.
1366
1367 · Default: 10
1368
1369
1370
1371 max_errors
1372 Sets the max number of logged/displayed parser validation errors in
1373 case multiple errors have been detected. A value of 0 is the same as a
1374 value of 1; a minimum of one error is always raised. The count is per
1375 manifest.
1376
1377 · Default: 10
1378
1379
1380
1381 max_warnings
1382 Sets the max number of logged/displayed parser validation warnings in
1383 case multiple warnings have been detected. A value of 0 blocks logging
1384 of warnings. The count is per manifest.
1385
1386 · Default: 10
1387
1388
1389
1390 maximum_uid
1391 The maximum allowed UID. Some platforms use negative UIDs but then ship
1392 with tools that do not know how to handle signed ints, so the UIDs show
1393 up as huge numbers that can then not be fed back into the system. This
1394 is a hackish way to fail in a slightly more useful way when that hap‐
1395 pens.
1396
1397 · Default: 4294967290
1398
1399
1400
1401 mkusers
1402 Whether to create the necessary user and group that puppet agent will
1403 run as.
1404
1405 · Default: false
1406
1407
1408
1409 module_groups
1410 Extra module groups to request from the Puppet Forge. This is an inter‐
1411 nal setting, and users should never change it.
1412
1413 Default:
1414
1415
1416 module_repository
1417 The module repository
1418
1419 · Default: https://forgeapi.puppet.com
1420
1421
1422
1423 module_skeleton_dir
1424 The directory which the skeleton for module tool generate is stored.
1425
1426 · Default: $module_working_dir/skeleton
1427
1428
1429
1430 module_working_dir
1431 The directory into which module tool data is stored
1432
1433 · Default: $vardir/puppet-module
1434
1435
1436
1437 modulepath
1438 The search path for modules, as a list of directories separated by the
1439 system path separator character. (The POSIX path separator is ´:´, and
1440 the Windows path separator is ´;´.)
1441
1442 Setting a global value for modulepath in puppet.conf is not allowed
1443 (but it can be overridden from the commandline). Please use directory
1444 environments instead. If you need to use something other than the
1445 default modulepath of <ACTIVE ENVIRONMENT´S MODULES DIR>:$basemod‐
1446 ulepath, you can set modulepath in environment.conf. For more info, see
1447 https://puppet.com/docs/puppet/latest/environments_about.html
1448
1449 name
1450 The name of the application, if we are running as one. The default is
1451 essentially $0 without the path or .rb.
1452
1453 Default:
1454
1455
1456 no_proxy
1457 List of host or domain names that should not go through
1458 http_proxy_host. Environment variable no_proxy or NO_PROXY will over‐
1459 ride this value. Names can be specified as an FQDN host.example.com,
1460 wildcard *.example.com, dotted domain .example.com, or suffix exam‐
1461 ple.com.
1462
1463 · Default: localhost, 127.0.0.1
1464
1465
1466
1467 node_cache_terminus
1468 How to store cached nodes. Valid values are (none), ´json´, ´msgpack´,
1469 ´yaml´ or write only yaml (´write_only_yaml´).
1470
1471 Default:
1472
1473
1474 node_name
1475 How the puppet master determines the client´s identity and sets the
1476 ´hostname´, ´fqdn´ and ´domain´ facts for use in the manifest, in par‐
1477 ticular for determining which ´node´ statement applies to the client.
1478 Possible values are ´cert´ (use the subject´s CN in the client´s cer‐
1479 tificate) and ´facter´ (use the hostname that the client reported in
1480 its facts).
1481
1482 This setting is deprecated, please use explicit fact matching for clas‐
1483 sification.
1484
1485 · Default: cert
1486
1487
1488
1489 node_name_fact
1490 The fact name used to determine the node name used for all requests the
1491 agent makes to the master. WARNING: This setting is mutually exclusive
1492 with node_name_value. Changing this setting also requires changes to
1493 the default auth.conf configuration on the Puppet Master. Please see
1494 http://links.puppet.com/node_name_fact for more information.
1495
1496 node_name_value
1497 The explicit value used for the node name for all requests the agent
1498 makes to the master. WARNING: This setting is mutually exclusive with
1499 node_name_fact. Changing this setting also requires changes to the
1500 default auth.conf configuration on the Puppet Master. Please see
1501 http://links.puppet.com/node_name_value for more information.
1502
1503 · Default: $certname
1504
1505
1506
1507 node_terminus
1508 Which node data plugin to use when compiling node catalogs.
1509
1510 When Puppet compiles a catalog, it combines two primary sources of
1511 info: the main manifest, and a node data plugin (often called a "node
1512 terminus," for historical reasons). Node data plugins provide three
1513 things for a given node name:
1514
1515 1. A list of classes to add to that node´s catalog (and, optionally,
1516 values for their parameters).
1517
1518 2. Which Puppet environment the node should use.
1519
1520 3. A list of additional top-scope variables to set.
1521
1522
1523
1524 The three main node data plugins are:
1525
1526 · plain --- Returns no data, so that the main manifest controls all
1527 node configuration.
1528
1529 · exec --- Uses an external node classifier (ENC) https://pup‐
1530 pet.com/docs/puppet/latest/nodes_external.html, configured by the
1531 external_nodes setting. This lets you pull a list of Puppet classes
1532 from any external system, using a small glue script to perform the
1533 request and format the result as YAML.
1534
1535 · classifier (formerly console) --- Specific to Puppet Enterprise.
1536 Uses the PE console for node data."
1537
1538 · Default: plain
1539
1540
1541
1542 noop
1543 Whether to apply catalogs in noop mode, which allows Puppet to par‐
1544 tially simulate a normal run. This setting affects puppet agent and
1545 puppet apply.
1546
1547 When running in noop mode, Puppet will check whether each resource is
1548 in sync, like it does when running normally. However, if a resource
1549 attribute is not in the desired state (as declared in the catalog),
1550 Puppet will take no action, and will instead report the changes it
1551 would have made. These simulated changes will appear in the report sent
1552 to the puppet master, or be shown on the console if running puppet
1553 agent or puppet apply in the foreground. The simulated changes will not
1554 send refresh events to any subscribing or notified resources, although
1555 Puppet will log that a refresh event would have been sent.
1556
1557 Important note: The noop metaparameter https://puppet.com/docs/pup‐
1558 pet/latest/metaparameter.html#noop allows you to apply individual
1559 resources in noop mode, and will override the global value of the noop
1560 setting. This means a resource with noop => false will be changed if
1561 necessary, even when running puppet agent with noop = true or --noop.
1562 (Conversely, a resource with noop => true will only be simulated, even
1563 when noop mode is globally disabled.)
1564
1565 · Default: false
1566
1567
1568
1569 onetime
1570 Perform one configuration run and exit, rather than spawning a
1571 long-running daemon. This is useful for interactively running puppet
1572 agent, or running puppet agent from cron.
1573
1574 · Default: false
1575
1576
1577
1578 ordering
1579 How unrelated resources should be ordered when applying a catalog.
1580 Allowed values are title-hash, manifest, and random. This setting
1581 affects puppet agent and puppet apply, but not puppet master.
1582
1583 · manifest (the default) will use the order in which the resources
1584 were declared in their manifest files.
1585
1586 · title-hash (the default in 3.x) will order resources randomly, but
1587 will use the same order across runs and across nodes. It is only of
1588 value if you´re migrating from 3.x and have errors running with
1589 manifest.
1590
1591 · random will order resources randomly and change their order with
1592 each run. This can work like a fuzzer for shaking out undeclared
1593 dependencies.
1594
1595
1596
1597 Regardless of this setting´s value, Puppet will always obey explicit
1598 dependencies set with the before/require/notify/subscribe metaparame‐
1599 ters and the ->/~> chaining arrows; this setting only affects the rela‐
1600 tive ordering of unrelated resources.
1601
1602 This setting is deprecated, and will always have a value of manifest in
1603 6.0 and up.
1604
1605 · Default: manifest
1606
1607
1608
1609 passfile
1610 Where puppet agent stores the password for its private key. Generally
1611 unused.
1612
1613 · Default: $privatedir/password
1614
1615
1616
1617 path
1618 The shell search path. Defaults to whatever is inherited from the par‐
1619 ent process.
1620
1621 This setting can only be set in the [main] section of puppet.conf; it
1622 cannot be set in [master], [agent], or an environment config section.
1623
1624 · Default: none
1625
1626
1627
1628 pidfile
1629 The file containing the PID of a running process. This file is intended
1630 to be used by service management frameworks and monitoring systems to
1631 determine if a puppet process is still in the process table.
1632
1633 · Default: $rundir/${run_mode}.pid
1634
1635
1636
1637 plugindest
1638 Where Puppet should store plugins that it pulls down from the central
1639 server.
1640
1641 · Default: $libdir
1642
1643
1644
1645 pluginfactdest
1646 Where Puppet should store external facts that are being handled by plu‐
1647 ginsync
1648
1649 · Default: $vardir/facts.d
1650
1651
1652
1653 pluginfactsource
1654 Where to retrieve external facts for pluginsync
1655
1656 · Default: puppet:///pluginfacts
1657
1658
1659
1660 pluginsignore
1661 What files to ignore when pulling down plugins.
1662
1663 · Default: .svn CVS .git .hg
1664
1665
1666
1667 pluginsource
1668 From where to retrieve plugins. The standard Puppet file type is used
1669 for retrieval, so anything that is a valid file source can be used
1670 here.
1671
1672 · Default: puppet:///plugins
1673
1674
1675
1676 pluginsync
1677 Whether plugins should be synced with the central server. This setting
1678 is deprecated.
1679
1680 · Default: true
1681
1682
1683
1684 postrun_command
1685 A command to run after every agent run. If this command returns a
1686 non-zero return code, the entire Puppet run will be considered to have
1687 failed, even though it might have performed work during the normal run.
1688
1689 preferred_serialization_format
1690 The preferred means of serializing ruby instances for passing over the
1691 wire. This won´t guarantee that all instances will be serialized using
1692 this method, since not all classes can be guaranteed to support this
1693 format, but it will be used for all classes that support it.
1694
1695 · Default: json
1696
1697
1698
1699 prerun_command
1700 A command to run before every agent run. If this command returns a
1701 non-zero return code, the entire Puppet run will fail.
1702
1703 preview_outputdir
1704 The directory where catalog previews per node are generated.
1705
1706 · Default: $vardir/preview
1707
1708
1709
1710 priority
1711 The scheduling priority of the process. Valid values are ´high´, ´nor‐
1712 mal´, ´low´, or ´idle´, which are mapped to platform-specific values.
1713 The priority can also be specified as an integer value and will be
1714 passed as is, e.g. -5. Puppet must be running as a privileged user in
1715 order to increase scheduling priority.
1716
1717 Default:
1718
1719
1720 privatedir
1721 Where the client stores private certificate information.
1722
1723 · Default: $ssldir/private
1724
1725
1726
1727 privatekeydir
1728 The private key directory.
1729
1730 · Default: $ssldir/private_keys
1731
1732
1733
1734 profile
1735 Whether to enable experimental performance profiling
1736
1737 · Default: false
1738
1739
1740
1741 publickeydir
1742 The public key directory.
1743
1744 · Default: $ssldir/public_keys
1745
1746
1747
1748 puppet_trace
1749 Whether to print the Puppet stack trace on some errors. This is a noop
1750 if trace is also set.
1751
1752 · Default: false
1753
1754
1755
1756 puppetdlog
1757 The fallback log file. This is only used when the --logdest option is
1758 not specified AND Puppet is running on an operating system where both
1759 the POSIX syslog service and the Windows Event Log are unavailable.
1760 (Currently, no supported operating systems match that description.)
1761
1762 Despite the name, both puppet agent and puppet master will use this
1763 file as the fallback logging destination.
1764
1765 For control over logging destinations, see the --logdest command line
1766 option in the manual pages for puppet master, puppet agent, and puppet
1767 apply. You can see man pages by running puppet <SUBCOMMAND> --help, or
1768 read them online at https://puppet.com/docs/puppet/latest/man/.
1769
1770 · Default: $logdir/puppetd.log
1771
1772
1773
1774 report
1775 Whether to send reports after every transaction.
1776
1777 · Default: true
1778
1779
1780
1781 report_port
1782 The port to communicate with the report_server.
1783
1784 · Default: $masterport
1785
1786
1787
1788 report_server
1789 The server to send transaction reports to.
1790
1791 · Default: $server
1792
1793
1794
1795 reportdir
1796 The directory in which to store reports. Each node gets a separate sub‐
1797 directory in this directory. This setting is only used when the store
1798 report processor is enabled (see the reports setting).
1799
1800 · Default: $vardir/reports
1801
1802
1803
1804 reports
1805 The list of report handlers to use. When using multiple report han‐
1806 dlers, their names should be comma-separated, with whitespace allowed.
1807 (For example, reports = http, store.)
1808
1809 This setting is relevant to puppet master and puppet apply. The puppet
1810 master will call these report handlers with the reports it receives
1811 from agent nodes, and puppet apply will call them with its own report.
1812 (In all cases, the node applying the catalog must have report = true.)
1813
1814 See the report reference for information on the built-in report han‐
1815 dlers; custom report handlers can also be loaded from modules. (Report
1816 handlers are loaded from the lib directory, at puppet/reports/NAME.rb.)
1817
1818 · Default: store
1819
1820
1821
1822 reporturl
1823 The URL that reports should be forwarded to. This setting is only used
1824 when the http report processor is enabled (see the reports setting).
1825
1826 · Default: http://localhost:3000/reports/upload
1827
1828
1829
1830 requestdir
1831 Where host certificate requests are stored.
1832
1833 · Default: $ssldir/certificate_requests
1834
1835
1836
1837 resourcefile
1838 The file in which puppet agent stores a list of the resources associ‐
1839 ated with the retrieved configuration.
1840
1841 · Default: $statedir/resources.txt
1842
1843
1844
1845 rest_authconfig
1846 The configuration file that defines the rights to the different rest
1847 indirections. This can be used as a fine-grained authorization system
1848 for puppet master. The puppet master command is deprecated and Puppet
1849 Server uses its own auth.conf that must be placed within its configura‐
1850 tion directory.
1851
1852 · Default: $confdir/auth.conf
1853
1854
1855
1856 resubmit_facts
1857 Whether to send updated facts after every transaction.
1858
1859 · Default: false
1860
1861
1862
1863 rich_data
1864 Enables having extended data in the catalog by storing them as a hash
1865 with the special key __pcore_type__. When enabled, resource containing
1866 values of the data types Binary, Regexp, SemVer, SemVerRange, Timespan
1867 and Timestamp, as well as instances of types derived from Object retain
1868 their data type.
1869
1870 · Default: false
1871
1872
1873
1874 route_file
1875 The YAML file containing indirector route configuration.
1876
1877 · Default: $confdir/routes.yaml
1878
1879
1880
1881 rundir
1882 Where Puppet PID files are kept.
1883
1884 · Default: Unix/Linux: /var/run/puppetlabs -- Windows: C:\Program‐
1885 Data\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppet‐
1886 labs/var/run
1887
1888
1889
1890 runinterval
1891 How often puppet agent applies the catalog. Note that a runinterval of
1892 0 means "run continuously" rather than "never run." If you want puppet
1893 agent to never run, you should start it with the --no-client option.
1894 This setting can be a time interval in seconds (30 or 30s), minutes
1895 (30m), hours (6h), days (2d), or years (5y).
1896
1897 · Default: 30m
1898
1899
1900
1901 runtimeout
1902 The maximum amount of time an agent run is allowed to take. A Puppet
1903 agent run that exceeds this timeout will be aborted. Defaults to 0,
1904 which is unlimited. This setting can be a time interval in seconds (30
1905 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1906
1907 · Default: 0
1908
1909
1910
1911 serial
1912 Where the serial number for certificates is stored.
1913
1914 · Default: $cadir/serial
1915
1916
1917
1918 server
1919 The puppet master server to which the puppet agent should connect.
1920
1921 · Default: puppet
1922
1923
1924
1925 server_datadir
1926 The directory in which serialized data is stored, usually in a subdi‐
1927 rectory.
1928
1929 · Default: $vardir/server_data
1930
1931
1932
1933 server_list
1934 The list of puppet master servers to which the puppet agent should con‐
1935 nect, in the order that they will be tried.
1936
1937 · Default: []
1938
1939
1940
1941 show_diff
1942 Whether to log and report a contextual diff when files are being
1943 replaced. This causes partial file contents to pass through Puppet´s
1944 normal logging and reporting system, so this setting should be used
1945 with caution if you are sending Puppet´s reports to an insecure desti‐
1946 nation. This feature currently requires the diff/lcs Ruby library.
1947
1948 · Default: false
1949
1950
1951
1952 signeddir
1953 Where the CA stores signed certificates.
1954
1955 · Default: $cadir/signed
1956
1957
1958
1959 skip_tags
1960 Tags to use to filter resources. If this is set, then only resources
1961 not tagged with the specified tags will be applied. Values must be
1962 comma-separated.
1963
1964 sourceaddress
1965 The address the agent should use to initiate requests.
1966
1967 Default:
1968
1969
1970 splay
1971 Whether to sleep for a random amount of time, ranging from immediately
1972 up to its $splaylimit, before performing its first agent run after a
1973 service restart. After this period, the agent runs periodically on its
1974 $runinterval.
1975
1976 For example, assume a default 30-minute $runinterval, splay set to its
1977 default of false, and an agent starting at :00 past the hour. The agent
1978 would check in every 30 minutes at :01 and :31 past the hour.
1979
1980 With splay enabled, it waits any amount of time up to its $splaylimit
1981 before its first run. For example, it might randomly wait 8 minutes,
1982 then start its first run at :08 past the hour. With the $runinterval at
1983 its default 30 minutes, its next run will be at :38 past the hour.
1984
1985 If you restart an agent´s puppet service with splay enabled, it recal‐
1986 culates its splay period and delays its first agent run after restart‐
1987 ing for this new period. If you simultaneously restart a group of pup‐
1988 pet agents with splay enabled, their checkins to your puppet masters
1989 can be distributed more evenly.
1990
1991 · Default: false
1992
1993
1994
1995 splaylimit
1996 The maximum time to delay before an agent´s first run when splay is
1997 enabled. Defaults to the agent´s $runinterval. The splay interval is
1998 random and recalculated each time the agent is started or restarted.
1999 This setting can be a time interval in seconds (30 or 30s), minutes
2000 (30m), hours (6h), days (2d), or years (5y).
2001
2002 · Default: $runinterval
2003
2004
2005
2006 srv_domain
2007 The domain which will be queried to find the SRV records of servers to
2008 use.
2009
2010 · Default: delivery.puppetlabs.net
2011
2012
2013
2014 ssl_client_ca_auth
2015 Certificate authorities who issue server certificates. SSL servers will
2016 not be considered authentic unless they possess a certificate issued by
2017 an authority listed in this file. If this setting has no value then the
2018 Puppet master´s CA certificate (localcacert) will be used.
2019
2020 Default:
2021
2022
2023 ssl_client_header
2024 The header containing an authenticated client´s SSL DN. This header
2025 must be set by the proxy to the authenticated client´s SSL DN (e.g.,
2026 /CN=puppet.puppetlabs.com). Puppet will parse out the Common Name (CN)
2027 from the Distinguished Name (DN) and use the value of the CN field for
2028 authorization.
2029
2030 Note that the name of the HTTP header gets munged by the web server
2031 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2032 verted to underscores, and all letters are uppercased. Thus, to use the
2033 X-Client-DN header, this setting should be HTTP_X_CLIENT_DN.
2034
2035 · Default: HTTP_X_CLIENT_DN
2036
2037
2038
2039 ssl_client_verify_header
2040 The header containing the status message of the client verification.
2041 This header must be set by the proxy to ´SUCCESS´ if the client suc‐
2042 cessfully authenticated, and anything else otherwise.
2043
2044 Note that the name of the HTTP header gets munged by the web server
2045 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2046 verted to underscores, and all letters are uppercased. Thus, to use the
2047 X-Client-Verify header, this setting should be HTTP_X_CLIENT_VERIFY.
2048
2049 · Default: HTTP_X_CLIENT_VERIFY
2050
2051
2052
2053 ssl_server_ca_auth
2054 Certificate authorities who issue client certificates. SSL clients will
2055 not be considered authentic unless they possess a certificate issued by
2056 an authority listed in this file. If this setting has no value then the
2057 Puppet master´s CA certificate (localcacert) will be used.
2058
2059 Default:
2060
2061
2062 ssldir
2063 Where SSL certificates are kept.
2064
2065 · Default: $confdir/ssl
2066
2067
2068
2069 statedir
2070 The directory where Puppet state is stored. Generally, this directory
2071 can be removed without causing harm (although it might result in spuri‐
2072 ous service restarts).
2073
2074 · Default: $vardir/state
2075
2076
2077
2078 statefile
2079 Where puppet agent and puppet master store state associated with the
2080 running configuration. In the case of puppet master, this file reflects
2081 the state discovered through interacting with clients.
2082
2083 · Default: $statedir/state.yaml
2084
2085
2086
2087 statettl
2088 How long the Puppet agent should cache when a resource was last checked
2089 or synced. This setting can be a time interval in seconds (30 or 30s),
2090 minutes (30m), hours (6h), days (2d), or years (5y). A value of 0 or
2091 unlimited will disable cache pruning.
2092
2093 This setting affects the usage of schedule resources, as the informa‐
2094 tion about when a resource was last checked (and therefore when it
2095 needs to be checked again) is stored in the statefile. The statettl
2096 needs to be large enough to ensure that a resource will not trigger
2097 multiple times during a schedule due to its entry expiring from the
2098 cache.
2099
2100 · Default: 32d
2101
2102
2103
2104 static_catalogs
2105 Whether to compile a static catalog https://puppet.com/docs/puppet/lat‐
2106 est/static_catalogs.html#enabling-or-disabling-static-catalogs, which
2107 occurs only on a Puppet Server master when the code-id-command and
2108 code-content-command settings are configured in its puppetserver.conf
2109 file.
2110
2111 · Default: true
2112
2113
2114
2115 storeconfigs
2116 Whether to store each client´s configuration, including catalogs,
2117 facts, and related data. This also enables the import and export of
2118 resources in the Puppet language - a mechanism for exchange resources
2119 between nodes.
2120
2121 By default this uses the ´puppetdb´ backend.
2122
2123 You can adjust the backend using the storeconfigs_backend setting.
2124
2125 · Default: false
2126
2127
2128
2129 storeconfigs_backend
2130 Configure the backend terminus used for StoreConfigs. By default, this
2131 uses the PuppetDB store, which must be installed and configured before
2132 turning on StoreConfigs.
2133
2134 · Default: puppetdb
2135
2136
2137
2138 strict
2139 The strictness level of puppet. Allowed values are:
2140
2141 · off - do not perform extra validation, do not report
2142
2143 · warning - perform extra validation, report as warning (default)
2144
2145 · error - perform extra validation, fail with error
2146
2147
2148
2149 The strictness level is for both language semantics and runtime evalua‐
2150 tion validation. In addition to controlling the behavior with this mas‐
2151 ter switch some individual warnings may also be controlled by the dis‐
2152 able_warnings setting.
2153
2154 No new validations will be added to a micro (x.y.z) release, but may be
2155 added in minor releases (x.y.0). In major releases it expected that
2156 most (if not all) strictness validation become standard behavior.
2157
2158 · Default: warning
2159
2160
2161
2162 strict_environment_mode
2163 Whether the agent specified environment should be considered authorita‐
2164 tive, causing the run to fail if the retrieved catalog does not match
2165 it.
2166
2167 · Default: false
2168
2169
2170
2171 strict_hostname_checking
2172 Whether to only search for the complete hostname as it is in the cer‐
2173 tificate when searching for node information in the catalogs or to
2174 match dot delimited segments of the cert´s certname and the hostname,
2175 fqdn, and/or domain facts.
2176
2177 This setting is deprecated and will be removed in a future release.
2178
2179 · Default: true
2180
2181
2182
2183 strict_variables
2184 Causes an evaluation error when referencing unknown variables. (This
2185 does not affect referencing variables that are explicitly set to
2186 undef).
2187
2188 · Default: false
2189
2190
2191
2192 summarize
2193 Whether to print a transaction summary.
2194
2195 · Default: false
2196
2197
2198
2199 supported_checksum_types
2200 Checksum types supported by this agent for use in file resources of a
2201 static catalog. Values must be comma-separated. Valid types are md5,
2202 md5lite, sha256, sha256lite, sha384, sha512, sha224, sha1, sha1lite,
2203 mtime, ctime. Default is md5, sha256, sha384, sha512, sha224.
2204
2205 · Default: ["md5", "sha256", "sha384", "sha512", "sha224"]
2206
2207
2208
2209 syslogfacility
2210 What syslog facility to use when logging to syslog. Syslog has a fixed
2211 list of valid facilities, and you must choose one of those; you cannot
2212 just make one up.
2213
2214 · Default: daemon
2215
2216
2217
2218 tags
2219 Tags to use to find resources. If this is set, then only resources
2220 tagged with the specified tags will be applied. Values must be
2221 comma-separated.
2222
2223 tasks
2224 Turns on experimental support for tasks and plans in the puppet lan‐
2225 guage. This is for internal API use only. Do not change this setting.
2226
2227 · Default: false
2228
2229
2230
2231 trace
2232 Whether to print stack traces on some errors. Will print internal Ruby
2233 stack trace interleaved with Puppet function frames.
2234
2235 · Default: false
2236
2237
2238
2239 transactionstorefile
2240 Transactional storage file for persisting data between transactions for
2241 the purposes of infering information (such as corrective_change) on new
2242 data received.
2243
2244 · Default: $statedir/transactionstore.yaml
2245
2246
2247
2248 trusted_oid_mapping_file
2249 File that provides mapping between custom SSL oids and user-friendly
2250 names
2251
2252 · Default: $confdir/custom_trusted_oid_mapping.yaml
2253
2254
2255
2256 trusted_server_facts
2257 The ´trusted_server_facts´ setting is deprecated and has no effect as
2258 the feature this enabled is now always on. The setting will be removed
2259 in a future version of puppet.
2260
2261 · Default: true
2262
2263
2264
2265 use_cached_catalog
2266 Whether to only use the cached catalog rather than compiling a new cat‐
2267 alog on every run. Puppet can be run with this enabled by default and
2268 then selectively disabled when a recompile is desired. Because a Puppet
2269 agent using cached catalogs does not contact the master for a new cata‐
2270 log, it also does not upload facts at the beginning of the Puppet run.
2271
2272 · Default: false
2273
2274
2275
2276 use_srv_records
2277 Whether the server will search for SRV records in DNS for the current
2278 domain.
2279
2280 · Default: false
2281
2282
2283
2284 usecacheonfailure
2285 Whether to use the cached configuration when the remote configuration
2286 will not compile. This option is useful for testing new configurations,
2287 where you want to fix the broken configuration rather than reverting to
2288 a known-good one.
2289
2290 · Default: true
2291
2292
2293
2294 user
2295 The user Puppet Server will run as. Used to ensure the agent side pro‐
2296 cesses (agent, apply, etc) create files and directories readable by
2297 Puppet Server when necessary.
2298
2299 · Default: puppet
2300
2301
2302
2303 vardir
2304 Where Puppet stores dynamic and growing data. The default for this set‐
2305 ting is calculated specially, like confdir_.
2306
2307 · Default: Unix/Linux: /opt/puppetlabs/puppet/cache -- Windows:
2308 C:\ProgramData\PuppetLabs\puppet\cache -- Non-root user: ~/.puppet‐
2309 labs/opt/puppet/cache
2310
2311
2312
2313 waitforcert
2314 How frequently puppet agent should ask for a signed certificate.
2315
2316 When starting for the first time, puppet agent will submit a certifi‐
2317 cate signing request (CSR) to the server named in the ca_server setting
2318 (usually the puppet master); this may be autosigned, or may need to be
2319 approved by a human, depending on the CA server´s configuration.
2320
2321 Puppet agent cannot apply configurations until its approved certificate
2322 is available. Since the certificate may or may not be available immedi‐
2323 ately, puppet agent will repeatedly try to fetch it at this interval.
2324 You can turn off waiting for certificates by specifying a time of 0, in
2325 which case puppet agent will exit if it cannot get a cert. This setting
2326 can be a time interval in seconds (30 or 30s), minutes (30m), hours
2327 (6h), days (2d), or years (5y).
2328
2329 · Default: 2m
2330
2331
2332
2333 yamldir
2334 The directory in which YAML data is stored, usually in a subdirectory.
2335
2336 · Default: $vardir/yaml
2337
2338
2339
2340
2341
2342
2343Puppet, Inc. April 2020 PUPPETCONF(5)