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