1PUPPETCONF(5) Puppet manual PUPPETCONF(5)
2
6
8 • Each of these settings can be specified in puppet.conf or on the
9 command line.
10 • Puppet Enterprise (PE) and open source Puppet share the configura‐
12 tion settings documented here. However, PE defaults differ from
13 open source defaults for some settings, such as node_terminus,
14 storeconfigs, always_retry_plugins, disable18n, environment_timeout
15 (when Code Manager is enabled), and the Puppet Server JRuby max-ac‐
16 tive-instances setting. To verify PE configuration defaults, check
17 the puppet.conf or pe-puppet-server.conf file after installation.
18 • 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 • Settings can be interpolated as $variables in other settings; $en‐
25 vironment is special, in that puppet master will interpolate each
26 agent node´s environment instead of its own.
27 • 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 • 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 • If you use the splay setting, note that the period that it waits
41 changes each time the Puppet agent is restarted.
42 • 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 • The Puppet executables ignores any setting that isn´t relevant to
48 their function.
49 See the configuration guide https://puppet.com/docs/puppet/latest/con‐
53 fig_about_settings.html for more details.
54 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 • Default: $statedir/agent_catalog_run.lock
61 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 • Default: $statedir/agent_disabled.lock
69 allow_duplicate_certs
73 Whether to allow a new certificate request to overwrite an existing
74 certificate request. If true, then the old certificate must be cleaned
75 using puppetserver ca clean, and the new request signed using puppet‐
76 server ca sign.
77 • Default: false
79 allow_pson_serialization
83 Whether when unable to serialize to JSON or other formats, Puppet falls
84 back to PSON. This option affects both puppetserver´s configuration
85 management service responses and when the agent saves its cached cata‐
86 log. This option is useful in preventing the loss of data because rich
87 data cannot be serialized via PSON.
88 • Default: false
90 always_retry_plugins
94 Affects how we cache attempts to load Puppet resource types and fea‐
95 tures. If true, then calls to Puppet.type.<type>? Puppet.feature.<fea‐
96 ture>? will always attempt to load the type or feature (which can be an
97 expensive operation) unless it has already been loaded successfully.
98 This makes it possible for a single agent run to, e.g., install a pack‐
99 age that provides the underlying capabilities for a type or feature,
100 and then later load that type or feature during the same run (even if
101 the type or feature had been tested earlier and had not been avail‐
102 able).
103 If this setting is set to false, then types and features will only be
105 checked once, and if they are not available, the negative result is
106 cached and returned for all subsequent attempts to load the type or
107 feature. This behavior is almost always appropriate for the server, and
108 can result in a significant performance improvement for types and fea‐
109 tures that are checked frequently.
110 • Default: true
112 autoflush
116 Whether log files should always flush to disk.
117 • Default: true
119 autosign
123 Whether (and how) to autosign certificate requests. This setting is
124 only relevant on a Puppet Server acting as a certificate authority
125 (CA).
126 Valid values are true (autosigns all certificate requests; not recom‐
128 mended), false (disables autosigning certificates), or the absolute
129 path to a file.
130 The file specified in this setting may be either a configuration file
132 or a custom policy executable. Puppet will automatically determine what
133 it is: If the Puppet user (see the user setting) can execute the file,
134 it will be treated as a policy executable; otherwise, it will be
135 treated as a config file.
136 If a custom policy executable is configured, the CA Puppet Server will
138 run it every time it receives a CSR. The executable will be passed the
139 subject CN of the request as a command line argument, and the contents
140 of the CSR in PEM format on stdin. It should exit with a status of 0 if
141 the cert should be autosigned and non-zero if the cert should not be
142 autosigned.
143 If a certificate request is not autosigned, it will persist for review.
145 An admin user can use the puppetserver ca sign command to manually sign
146 it, or can delete the request.
147 For info on autosign configuration files, see the guide to Puppet´s
149 config files https://puppet.com/docs/puppet/latest/config_file_au‐
150 tosign.html.
151 • Default: $confdir/autosign.conf
153 basemodulepath
157 The search path for global modules. Should be specified as a list of
158 directories separated by the system path separator character. (The
159 POSIX path separator is ´:´, and the Windows path separator is ´;´.)
160 These are the modules that will be used by all environments. Note that
162 the modules directory of the active environment will have priority over
163 any global directories. For more info, see https://puppet.com/docs/pup‐
164 pet/latest/environments_about.html
165 • Default: $codedir/modules:/usr/share/puppet/modules
167 binder_config
171 The binder configuration file. Puppet reads this file on each request
172 to configure the bindings system. If set to nil (the default), a
173 $confdir/binder_config.yaml is optionally loaded. If it does not ex‐
174 ists, a default configuration is used. If the setting :binding_config
175 is specified, it must reference a valid and existing yaml file.
176 • Default: ``
178 bucketdir
182 Where FileBucket files are stored.
183 • Default: $vardir/bucket
185 ca_fingerprint
189 The expected fingerprint of the CA certificate. If specified, the agent
190 will compare the CA certificate fingerprint that it downloads against
191 this value and reject the CA certificate if the values do not match.
192 This only applies during the first download of the CA certificate.
193 • Default: ``
195 ca_name
199 The name to use the Certificate Authority certificate.
200 • Default: Puppet CA: $certname
202 ca_port
206 The port to use for the certificate authority.
207 • Default: $serverport
209 ca_refresh_interval
213 How often the Puppet agent refreshes its local CA certs. By default the
214 CA certs are refreshed once every 24 hours. If a different duration is
215 specified, then the agent will refresh its CA certs whenever it next
216 runs and the elapsed time since the certs were last refreshed exceeds
217 the duration.
218 In general, the duration should be greater than the runinterval. Set‐
220 ting it to 0 or an equal or lesser value than runinterval, will cause
221 the CA certs to be refreshed on every run.
222 If the agent downloads new CA certs, the agent will use it for subse‐
224 quent network requests. If the refresh request fails or if the CA certs
225 are unchanged on the server, then the agent run will continue using the
226 local CA certs it already has. This setting can be a time interval in
227 seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or years
228 (5y).
229 • Default: 1d
231 ca_server
235 The server to use for certificate authority requests. It´s a separate
236 server because it cannot and does not need to horizontally scale.
237 • Default: $server
239 ca_ttl
243 The default TTL for new certificates. This setting can be a time inter‐
244 val in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
245 years (5y).
246 • Default: 5y
248 cacert
252 The CA certificate.
253 • Default: $cadir/ca_crt.pem
255 cacrl
259 The certificate revocation list (CRL) for the CA.
260 • Default: $cadir/ca_crl.pem
262 cadir
266 The root directory for the certificate authority.
267 • Default: /etc/puppetserver/ca
269 cakey
273 The CA private key.
274 • Default: $cadir/ca_key.pem
276 capub
280 The CA public key.
281 • Default: $cadir/ca_pub.pem
283 catalog_cache_terminus
287 How to store cached catalogs. Valid values are ´json´, ´msgpack´ and
288 ´yaml´. The agent application defaults to ´json´.
289 • Default: ``
291 catalog_terminus
295 Where to get node catalogs. This is useful to change if, for instance,
296 you´d like to pre-compile catalogs and store them in memcached or some
297 other easily-accessed store.
298 • Default: compiler
300 cert_inventory
304 The inventory file. This is a text file to which the CA writes a com‐
305 plete listing of all certificates.
306 • Default: $cadir/inventory.txt
308 certdir
312 The certificate directory.
313 • Default: $ssldir/certs
315 certificate_revocation
319 Whether certificate revocation checking should be enabled, and what
320 level of checking should be performed.
321 When certificate revocation is enabled, Puppet expects the contents of
323 its CRL to be one or more PEM-encoded CRLs concatenated together. When
324 using a cert bundle, CRLs for all CAs in the chain of trust must be in‐
325 cluded in the crl file. The chain should be ordered from least to most
326 authoritative, with the first CRL listed being for the root of the
327 chain and the last being for the leaf CA.
328 When certificate_revocation is set to ´true´ or ´chain´, Puppet ensures
330 that each CA in the chain of trust has not been revoked by its issuing
331 CA.
332 When certificate_revocation is set to ´leaf´, Puppet verifies certs
334 against the issuing CA´s revocation list, but it does not verify the
335 revocation status of the issuing CA or any CA above it within the chain
336 of trust.
337 When certificate_revocation is set to ´false´, Puppet disables all cer‐
339 tificate revocation checking and does not attempt to download the CRL.
340 • Default: chain
342 certname
346 The name to use when handling certificates. When a node requests a cer‐
347 tificate from the CA Puppet Server, it uses the value of the certname
348 setting as its requested Subject CN.
349 This is the name used when managing a node´s permissions in Puppet
351 Server´s auth.conf https://puppet.com/docs/puppetserver/latest/con‐
352 fig_file_auth.html. In most cases, it is also used as the node´s name
353 when matching node definitions https://puppet.com/docs/puppet/lat‐
354 est/lang_node_definitions.html and requesting data from an ENC. (This
355 can be changed with the node_name_value and node_name_fact settings,
356 although you should only do so if you have a compelling reason.)
357 A node´s certname is available in Puppet manifests as $trusted[´cert‐
359 name´]. (See Facts and Built-In Variables https://puppet.com/docs/pup‐
360 pet/latest/lang_facts_and_builtin_vars.html for more details.)
361 • For best compatibility, you should limit the value of certname to
363 only use lowercase letters, numbers, periods, underscores, and
364 dashes. (That is, it should match /A[a-z0-9._-]+Z/.)
365 • The special value ca is reserved, and can´t be used as the certname
367 for a normal node.
368 Note: You must set the certname in the main section of the pup‐
370 pet.conf file. Setting it in a different section causes errors.
371 Defaults to the node´s fully qualified domain name.
375 • Default: the Host´s fully qualified domain name, as determined by
377 Facter
378 ciphers
382 The list of ciphersuites for TLS connections initiated by puppet. The
383 default value is chosen to support TLS 1.0 and up, but can be made more
384 restrictive if needed. The ciphersuites must be specified in OpenSSL
385 format, not IANA.
386 • Default:
388 ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256
389 classfile
393 The file in which puppet agent stores a list of the classes associated
394 with the retrieved configuration. Can be loaded in the separate puppet
395 executable using the --loadclasses option.
396 • Default: $statedir/classes.txt
398 client_datadir
402 The directory in which serialized data is stored on the client.
403 • Default: $vardir/client_data
405 clientbucketdir
409 Where FileBucket files are stored locally.
410 • Default: $vardir/clientbucket
412 clientyamldir
416 The directory in which client-side YAML data is stored.
417 • Default: $vardir/client_yaml
419 code
423 Code to parse directly. This is essentially only used by puppet, and
424 should only be set if you´re writing your own Puppet executable.
425 codedir
427 The main Puppet code directory. The default for this setting is calcu‐
428 lated based on the user. If the process is running as root or the user
429 that Puppet is supposed to run as, it defaults to a system directory,
430 but if it´s running as any other user, it defaults to being in the
431 user´s home directory.
432 • Default: Unix/Linux: /etc/puppet/code -- Windows: C:\Program‐
434 Data\PuppetLabs\code -- Non-root user: ~/.puppetlabs/etc/code
435 color
439 Whether to use colors when logging to the console. Valid values are
440 ansi (equivalent to true), html, and false, which produces no color.
441 • Default: ansi
443 confdir
447 The main Puppet configuration directory. The default for this setting
448 is calculated based on the user. If the process is running as root or
449 the user that Puppet is supposed to run as, it defaults to a system di‐
450 rectory, but if it´s running as any other user, it defaults to being in
451 the user´s home directory.
452 • Default: Unix/Linux: /etc/puppet -- Windows: C:\ProgramData\Puppet‐
454 Labs\puppet\etc -- Non-root user: ~/.puppetlabs/etc/puppet
455 config
459 The configuration file for the current puppet application.
460 • Default: $confdir/${config_file_name}
462 config_file_name
466 The name of the puppet config file.
467 • Default: puppet.conf
469 config_version
473 How to determine the configuration version. By default, it will be the
474 time that the configuration is parsed, but you can provide a shell
475 script to override how the version is determined. The output of this
476 script will be added to every log message in the reports, allowing you
477 to correlate changes on your hosts to the source version on the server.
478 Setting a global value for config_version in puppet.conf is not allowed
480 (but it can be overridden from the commandline). Please set a per-envi‐
481 ronment value in environment.conf instead. For more info, see
482 https://puppet.com/docs/puppet/latest/environments_about.html
483 configprint
485 Prints the value of a specific configuration setting. If the name of a
486 setting is provided for this, then the value is printed and puppet ex‐
487 its. Comma-separate multiple values. For a list of all values, specify
488 ´all´. This setting is deprecated, the ´puppet config´ command replaces
489 this functionality.
490 crl_refresh_interval
492 How often the Puppet agent refreshes its local CRL. By default the CRL
493 is refreshed once every 24 hours. If a different duration is specified,
494 then the agent will refresh its CRL whenever it next runs and the
495 elapsed time since the CRL was last refreshed exceeds the duration.
496 In general, the duration should be greater than the runinterval. Set‐
498 ting it to 0 or an equal or lesser value than runinterval, will cause
499 the CRL to be refreshed on every run.
500 If the agent downloads a new CRL, the agent will use it for subsequent
502 network requests. If the refresh request fails or if the CRL is un‐
503 changed on the server, then the agent run will continue using the local
504 CRL it already has.This setting can be a time interval in seconds (30
505 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
506 • Default: 1d
508 csr_attributes
512 An optional file containing custom attributes to add to certificate
513 signing requests (CSRs). You should ensure that this file does not ex‐
514 ist on your CA Puppet Server; if it does, unwanted certificate exten‐
515 sions may leak into certificates created with the puppetserver ca gen‐
516 erate command.
517 If present, this file must be a YAML hash containing a custom_at‐
519 tributes key and/or an extension_requests key. The value of each key
520 must be a hash, where each key is a valid OID and each value is an ob‐
521 ject that can be cast to a string.
522 Custom attributes can be used by the CA when deciding whether to sign
524 the certificate, but are then discarded. Attribute OIDs can be any OID
525 value except the standard CSR attributes (i.e. attributes described in
526 RFC 2985 section 5.4). This is useful for embedding a pre-shared key
527 for autosigning policy executables (see the autosign setting), often by
528 using the 1.2.840.113549.1.9.7 ("challenge password") OID.
529 Extension requests will be permanently embedded in the final certifi‐
531 cate. Extension OIDs must be in the "ppRegCertExt"
532 (1.3.6.1.4.1.34380.1.1), "ppPrivCertExt" (1.3.6.1.4.1.34380.1.2), or
533 "ppAuthCertExt" (1.3.6.1.4.1.34380.1.3) OID arcs. The ppRegCertExt arc
534 is reserved for four of the most common pieces of data to embed:
535 pp_uuid (.1), pp_instance_id (.2), pp_image_name (.3), and pp_pre‐
536 shared_key (.4) --- in the YAML file, these can be referred to by their
537 short descriptive names instead of their full OID. The ppPrivCertExt
538 arc is unregulated, and can be used for site-specific extensions. The
539 ppAuthCert arc is reserved for two pieces of data to embed: pp_autho‐
540 rization (.1) and pp_auth_role (.13). As with ppRegCertExt, in the YAML
541 file, these can be referred to by their short descriptive name instead
542 of their full OID.
543 • Default: $confdir/csr_attributes.yaml
545 csrdir
549 Where the CA stores certificate requests.
550 • Default: $cadir/requests
552 daemonize
556 Whether to send the process into the background. This defaults to true
557 on POSIX systems, and to false on Windows (where Puppet currently can‐
558 not daemonize).
559 • Default: true
561 data_binding_terminus
565 This setting has been deprecated. Use of any value other than ´hiera´
566 should instead be configured in a version 5 hiera.yaml. Until this set‐
567 ting is removed, it controls which data binding terminus to use for
568 global automatic data binding (across all environments). By default
569 this value is ´hiera´. A value of ´none´ turns off the global binding.
570 • Default: hiera
572 default_file_terminus
576 The default source for files if no server is given in a uri, e.g. pup‐
577 pet:///file. The default of rest causes the file to be retrieved using
578 the server setting. When running apply the default is file_server,
579 causing requests to be filled locally.
580 • Default: rest
582 default_manifest
586 The default main manifest for directory environments. Any environment
587 that doesn´t set the manifest setting in its environment.conf file will
588 use this manifest.
589 This setting´s value can be an absolute or relative path. An absolute
591 path will make all environments default to the same main manifest; a
592 relative path will allow each environment to use its own manifest, and
593 Puppet will resolve the path relative to each environment´s main direc‐
594 tory.
595 In either case, the path can point to a single file or to a directory
597 of manifests to be evaluated in alphabetical order.
598 • Default: ./manifests
600 default_schedules
604 Boolean; whether to generate the default schedule resources. Setting
605 this to false is useful for keeping external report processors clean of
606 skipped schedule resources.
607 • Default: true
609 deviceconfdir
613 The root directory of devices´ $confdir.
614 • Default: $confdir/devices
616 deviceconfig
620 Path to the device config file for puppet device.
621 • Default: $confdir/device.conf
623 devicedir
627 The root directory of devices´ $vardir.
628 • Default: $vardir/devices
630 diff
634 Which diff command to use when printing differences between files. This
635 setting has no default value on Windows, as standard diff is not avail‐
636 able, but Puppet can use many third-party diff tools.
637 • Default: diff
639 diff_args
643 Which arguments to pass to the diff command when printing differences
644 between files. The command to use can be chosen with the diff setting.
645 • Default: -u
647 digest_algorithm
651 Which digest algorithm to use for file resources and the filebucket.
652 Valid values are sha256, sha384, sha512, sha224, md5. Default is
653 sha256.
654 • Default: sha256
656 disable_i18n
660 If true, turns off all translations of Puppet and module log messages,
661 which affects error, warning, and info log messages, as well as any
662 translations in the report and CLI.
663 • Default: true
665 disable_per_environment_manifest
669 Whether to disallow an environment-specific main manifest. When set to
670 true, Puppet will use the manifest specified in the default_manifest
671 setting for all environments. If an environment specifies a different
672 main manifest in its environment.conf file, catalog requests for that
673 environment will fail with an error.
674 This setting requires default_manifest to be set to an absolute path.
676 • Default: false
678 disable_warnings
682 A comma-separated list of warning types to suppress. If large numbers
683 of warnings are making Puppet´s logs too large or difficult to use, you
684 can temporarily silence them with this setting.
685 If you are preparing to upgrade Puppet to a new major version, you
687 should re-enable all warnings for a while.
688 Valid values for this setting are:
690 • deprecations --- disables deprecation warnings.
692 • undefined_variables --- disables warnings about non existing vari‐
694 ables.
695 • undefined_resources --- disables warnings about non existing re‐
697 sources.
698 • Default: []
700 dns_alt_names
704 A comma-separated list of alternate DNS names for Puppet Server. These
705 are extra hostnames (in addition to its certname) that the server is
706 allowed to use when serving agents. Puppet checks this setting when au‐
707 tomatically creating a certificate for Puppet agent or Puppet Server.
708 These can be either IP or DNS, and the type should be specified and
709 followed with a colon. Untyped inputs will default to DNS.
710 In order to handle agent requests at a given hostname (like "puppet.ex‐
712 ample.com"), Puppet Server needs a certificate that proves it´s allowed
713 to use that name; if a server shows a certificate that doesn´t include
714 its hostname, Puppet agents will refuse to trust it. If you use a sin‐
715 gle hostname for Puppet traffic but load-balance it to multiple Puppet
716 Servers, each of those servers needs to include the official hostname
717 in its list of extra names.
718 Note: The list of alternate names is locked in when the server´s cer‐
720 tificate is signed. If you need to change the list later, you can´t
721 just change this setting; you also need to regenerate the certificate.
722 For more information on that process, see the cert regen docs
723 https://puppet.com/docs/puppet/latest/ssl_regenerate_certificates.html.
724 To see all the alternate names your servers are using, log into your CA
726 server and run puppetserver ca list --all, then check the output for
727 (alt names: ...). Most agent nodes should NOT have alternate names; the
728 only certs that should have them are Puppet Server nodes that you want
729 other agents to trust.
730 document_all
732 Whether to document all resources when using puppet doc to generate
733 manifest documentation.
734 • Default: false
736 environment
740 The environment in which Puppet is running. For clients, such as puppet
741 agent, this determines the environment itself, which Puppet uses to
742 find modules and much more. For servers, such as puppet server, this
743 provides the default environment for nodes that Puppet knows nothing
744 about.
745 When defining an environment in the [agent] section, this refers to the
747 environment that the agent requests from the primary server. The envi‐
748 ronment doesn´t have to exist on the local filesystem because the agent
749 fetches it from the primary server. This definition is used when run‐
750 ning puppet agent.
751 When defined in the [user] section, the environment refers to the path
753 that Puppet uses to search for code and modules related to its execu‐
754 tion. This requires the environment to exist locally on the filesystem
755 where puppet is being executed. Puppet subcommands, including puppet
756 module and puppet apply, use this definition.
757 Given that the context and effects vary depending on the config section
759 https://puppet.com/docs/puppet/latest/config_file_main.html#config-sec‐
760 tions in which the environment setting is defined, do not set it glob‐
761 ally.
762 • Default: production
764 environment_data_provider
768 The name of a registered environment data provider used when obtaining
769 environment specific data. The three built in and registered providers
770 are ´none´ (no data), ´function´ (data obtained by calling the function
771 ´environment::data()´) and ´hiera´ (data obtained using a data provider
772 configured using a hiera.yaml file in root of the environment). Other
773 environment data providers may be registered in modules on the module
774 path. For such custom data providers see the respective module documen‐
775 tation. This setting is deprecated.
776 • Default: ``
778 environment_timeout
782 How long the Puppet server should cache data it loads from an environ‐
783 ment.
784 A value of 0 will disable caching. This setting can also be set to un‐
786 limited, which will cache environments until the server is restarted or
787 told to refresh the cache. All other values will result in Puppet
788 server evicting environments that haven´t been used within the last en‐
789 vironment_timeout seconds.
790 You should change this setting once your Puppet deployment is doing
792 non-trivial work. We chose the default value of 0 because it lets new
793 users update their code without any extra steps, but it lowers the per‐
794 formance of your Puppet server. We recommend either:
795 • Setting this to unlimited and explicitly refreshing your Puppet
797 server as part of your code deployment process.
798 • Setting this to a number that will keep your most actively used en‐
800 vironments cached, but allow testing environments to fall out of
801 the cache and reduce memory usage. A value of 3 minutes (3m) is a
802 reasonable value.
803 Once you set environment_timeout to a non-zero value, you need to tell
807 Puppet server to read new code from disk using the environment-cache
808 API endpoint after you deploy new code. See the docs for the Puppet
809 Server administrative API https://puppet.com/docs/puppetserver/lat‐
810 est/admin-api/v1/environment-cache.html.
811 • Default: 0
813 environmentpath
817 A search path for directory environments, as a list of directories sep‐
818 arated by the system path separator character. (The POSIX path separa‐
819 tor is ´:´, and the Windows path separator is ´;´.)
820 This setting must have a value set to enable directory environments.
822 The recommended value is $codedir/environments. For more details, see
823 https://puppet.com/docs/puppet/latest/environments_about.html
824 • Default: $codedir/environments
826 evaltrace
830 Whether each resource should log when it is being evaluated. This al‐
831 lows you to interactively see exactly what is being done.
832 • Default: false
834 exclude_unchanged_resources
838 When set to true, resources that have had no changes after catalog ap‐
839 plication will not have corresponding unchanged resource status updates
840 listed in the report.
841 • Default: true
843 external_nodes
847 The external node classifier (ENC) script to use for node data. Puppet
848 combines this data with the main manifest to produce node catalogs.
849 To enable this setting, set the node_terminus setting to exec.
851 This setting´s value must be the path to an executable command that can
853 produce node information. The command must:
854 • Take the name of a node as a command-line argument.
856 •
858 • classes --- A list of classes, as an array or hash.
860 • environment --- A string.
862 • parameters --- A list of top-scope variables to set, as a hash.
864 • For unknown nodes, exit with a non-zero exit code.
869 Generally, an ENC script makes requests to an external data source.
873 For more info, see the ENC documentation https://puppet.com/docs/pup‐
875 pet/latest/nodes_external.html.
876 • Default: none
878 fact_name_length_soft_limit
882 The soft limit for the length of a fact name.
883 • Default: 2560
885 fact_value_length_soft_limit
889 The soft limit for the length of a fact value.
890 • Default: 4096
892 factpath
896 Where Puppet should look for facts. Multiple directories should be sep‐
897 arated by the system path separator character. (The POSIX path separa‐
898 tor is ´:´, and the Windows path separator is ´;´.)
899 • Default: $vardir/lib/facter:$vardir/facts
901 facts_terminus
905 The node facts terminus.
906 • Default: facter
908 fileserverconfig
912 Where the fileserver configuration is stored.
913 • Default: $confdir/fileserver.conf
915 filetimeout
919 The minimum time to wait between checking for updates in configuration
920 files. This timeout determines how quickly Puppet checks whether a file
921 (such as manifests or puppet.conf) has changed on disk. The default
922 will change in a future release to be ´unlimited´, requiring a reload
923 of the Puppet service to pick up changes to its internal configuration.
924 Currently we do not accept a value of ´unlimited´. To reparse files
925 within an environment in Puppet Server please use the environment_cache
926 endpoint
927 • Default: 15s
929 forge_authorization
933 The authorization key to connect to the Puppet Forge. Leave blank for
934 unauthorized or license based connections
935 • Default: ``
937 freeze_main
941 Freezes the ´main´ class, disallowing any code to be added to it. This
942 essentially means that you can´t have any code outside of a node,
943 class, or definition other than in the site manifest.
944 • Default: false
946 genconfig
950 When true, causes Puppet applications to print an example config file
951 to stdout and exit. The example will include descriptions of each set‐
952 ting, and the current (or default) value of each setting, incorporating
953 any settings overridden on the CLI (with the exception of genconfig it‐
954 self). This setting only makes sense when specified on the command line
955 as --genconfig.
956 • Default: false
958 genmanifest
962 Whether to just print a manifest to stdout and exit. Only makes sense
963 when specified on the command line as --genmanifest. Takes into account
964 arguments specified on the CLI.
965 • Default: false
967 graph
971 Whether to create .dot graph files, which let you visualize the depen‐
972 dency and containment relationships in Puppet´s catalog. You can load
973 and view these files with tools like OmniGraffle http://www.omni‐
974 group.com/applications/omnigraffle/ (OS X) or graphviz
975 http://www.graphviz.org/ (multi-platform).
976 Graph files are created when applying a catalog, so this setting should
978 be used on nodes running puppet agent or puppet apply.
979 The graphdir setting determines where Puppet will save graphs. Note
981 that we don´t save graphs for historical runs; Puppet will replace the
982 previous .dot files with new ones every time it applies a catalog.
983 See your graphing software´s documentation for details on opening .dot
985 files. If you´re using GraphViz´s dot command, you can do a quick PNG
986 render with dot -Tpng <DOT FILE> -o <OUTPUT FILE>.
987 • Default: false
989 graphdir
993 Where to save .dot-format graphs (when the graph setting is enabled).
994 • Default: $statedir/graphs
996 group
1000 The group Puppet Server will run as. Used to ensure the agent side pro‐
1001 cesses (agent, apply, etc) create files and directories readable by
1002 Puppet Server when necessary.
1003 • Default: puppet
1005 hiera_config
1009 The hiera configuration file. Puppet only reads this file on startup,
1010 so you must restart the puppet server every time you edit it.
1011 • Default: $confdir/hiera.yaml. However, for backwards compatibility,
1013 if a file exists at $codedir/hiera.yaml, Puppet uses that instead.
1014 hostcert
1018 Where individual hosts store and look for their certificates.
1019 • Default: $certdir/$certname.pem
1021 hostcert_renewal_interval
1025 When the Puppet agent refreshes its client certificate. By default the
1026 client certificate will refresh 30 days before the certificate expires.
1027 If a different duration is specified, then the agent will refresh its
1028 client certificate whenever it next runs and if the client certificate
1029 expires within the duration specified.
1030 In general, the duration should be greater than the runinterval. Set‐
1032 ting it to 0 will disable automatic renewal.
1033 If the agent downloads a new certificate, the agent will use it for
1035 subsequent network requests. If the refresh request fails, then the
1036 agent run will continue using the certificate it already has. This set‐
1037 ting can be a time interval in seconds (30 or 30s), minutes (30m),
1038 hours (6h), days (2d), or years (5y).
1039 • Default: 30d
1041 hostcrl
1045 Where the host´s certificate revocation list can be found. This is dis‐
1046 tinct from the certificate authority´s CRL.
1047 • Default: $ssldir/crl.pem
1049 hostcsr
1053 Where individual hosts store their certificate request (CSR) while
1054 waiting for the CA to issue their certificate.
1055 • Default: $requestdir/$certname.pem
1057 hostprivkey
1061 Where individual hosts store and look for their private key.
1062 • Default: $privatekeydir/$certname.pem
1064 hostpubkey
1068 Where individual hosts store and look for their public key.
1069 • Default: $publickeydir/$certname.pem
1071 http_connect_timeout
1075 The maximum amount of time to wait when establishing an HTTP connec‐
1076 tion. The default value is 2 minutes. This setting can be a time inter‐
1077 val in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
1078 years (5y).
1079 • Default: 2m
1081 http_debug
1085 Whether to write HTTP request and responses to stderr. This should
1086 never be used in a production environment.
1087 • Default: false
1089 http_extra_headers
1093 The list of extra headers that will be sent with http requests to the
1094 primary server. The header definition consists of a name and a value
1095 separated by a colon.
1096 • Default: []
1098 http_keepalive_timeout
1102 The maximum amount of time a persistent HTTP connection can remain idle
1103 in the connection pool, before it is closed. This timeout should be
1104 shorter than the keepalive timeout used on the HTTP server, e.g. Apache
1105 KeepAliveTimeout directive. This setting can be a time interval in sec‐
1106 onds (30 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1107 • Default: 4s
1109 http_proxy_host
1113 The HTTP proxy host to use for outgoing connections. The proxy will be
1114 bypassed if the server´s hostname matches the NO_PROXY environment
1115 variable or no_proxy setting. Note: You may need to use a FQDN for the
1116 server hostname when using a proxy. Environment variable http_proxy or
1117 HTTP_PROXY will override this value.
1118 • Default: none
1120 http_proxy_password
1124 The password for the user of an authenticated HTTP proxy. Requires the
1125 http_proxy_user setting.
1126 Note that passwords must be valid when used as part of a URL. If a
1128 password contains any characters with special meanings in URLs (as
1129 specified by RFC 3986 section 2.2), they must be URL-encoded. (For ex‐
1130 ample, # would become %23.)
1131 • Default: none
1133 http_proxy_port
1137 The HTTP proxy port to use for outgoing connections
1138 • Default: 3128
1140 http_proxy_user
1144 The user name for an authenticated HTTP proxy. Requires the
1145 http_proxy_host setting.
1146 • Default: none
1148 http_read_timeout
1152 The time to wait for data to be read from an HTTP connection. If noth‐
1153 ing is read after the elapsed interval then the connection will be
1154 closed. The default value is 10 minutes. This setting can be a time in‐
1155 terval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
1156 years (5y).
1157 • Default: 10m
1159 http_user_agent
1163 The HTTP User-Agent string to send when making network requests.
1164 • Default: Puppet/8.3.0 Ruby/3.1.1-p18 (x86_64-linux)
1166 ignore_plugin_errors
1170 Whether the puppet run should ignore errors during pluginsync. If the
1171 setting is false and there are errors during pluginsync, then the agent
1172 will abort the run and submit a report containing information about the
1173 failed run.
1174 • Default: false
1176 ignoremissingtypes
1180 Skip searching for classes and definitions that were missing during a
1181 prior compilation. The list of missing objects is maintained per-envi‐
1182 ronment and persists until the environment is cleared or the primary
1183 server is restarted.
1184 • Default: false
1186 ignoreschedules
1190 Boolean; whether puppet agent should ignore schedules. This is useful
1191 for initial puppet agent runs.
1192 • Default: false
1194 include_legacy_facts
1198 Whether to include legacy facts when requesting a catalog. This option
1199 can be set to false provided all puppet manifests, hiera.yaml and hiera
1200 configuration layers no longer access legacy facts, such as $osfamily,
1201 and instead access structured facts, such as $facts[´os´][´family´].
1202 • Default: false
1204 key_type
1208 The type of private key. Valid values are rsa and ec. Default is rsa.
1209 • Default: rsa
1211 keylength
1215 The bit length of keys.
1216 • Default: 4096
1218 lastrunfile
1222 Where puppet agent stores the last run report summary in yaml format.
1223 • Default: $publicdir/last_run_summary.yaml
1225 lastrunreport
1229 Where Puppet Agent stores the last run report, by default, in yaml for‐
1230 mat. The format of the report can be changed by setting the cache key
1231 of the report terminus in the routes.yaml https://puppet.com/docs/pup‐
1232 pet/latest/config_file_routes.html file. To avoid mismatches between
1233 content and file extension, this setting needs to be manually updated
1234 to reflect the terminus changes.
1235 • Default: $statedir/last_run_report.yaml
1237 ldapattrs
1241 The LDAP attributes to include when querying LDAP for nodes. All re‐
1242 turned attributes are set as variables in the top-level scope. Multiple
1243 values should be comma-separated. The value ´all´ returns all at‐
1244 tributes.
1245 • Default: all
1247 ldapbase
1251 The search base for LDAP searches. It´s impossible to provide a mean‐
1252 ingful default here, although the LDAP libraries might have one already
1253 set. Generally, it should be the ´ou=Hosts´ branch under your main di‐
1254 rectory.
1255 ldapclassattrs
1257 The LDAP attributes to use to define Puppet classes. Values should be
1258 comma-separated.
1259 • Default: puppetclass
1261 ldapparentattr
1265 The attribute to use to define the parent node.
1266 • Default: parentnode
1268 ldappassword
1272 The password to use to connect to LDAP.
1273 ldapport
1275 The LDAP port.
1276 • Default: 389
1278 ldapserver
1282 The LDAP server.
1283 • Default: ldap
1285 ldapssl
1289 Whether SSL should be used when searching for nodes. Defaults to false
1290 because SSL usually requires certificates to be set up on the client
1291 side.
1292 • Default: false
1294 ldapstackedattrs
1298 The LDAP attributes that should be stacked to arrays by adding the val‐
1299 ues in all hierarchy elements of the tree. Values should be comma-sepa‐
1300 rated.
1301 • Default: puppetvar
1303 ldapstring
1307 The search string used to find an LDAP node.
1308 • Default: (&(objectclass=puppetClient)(cn=%s))
1310 ldaptls
1314 Whether TLS should be used when searching for nodes. Defaults to false
1315 because TLS usually requires certificates to be set up on the client
1316 side.
1317 • Default: false
1319 ldapuser
1323 The user to use to connect to LDAP. Must be specified as a full DN.
1324 libdir
1326 An extra search path for Puppet. This is only useful for those files
1327 that Puppet will load on demand, and is only guaranteed to work for
1328 those cases. In fact, the autoload mechanism is responsible for making
1329 sure this directory is in Ruby´s search path
1330 • Default: $vardir/lib
1332 localcacert
1336 Where each client stores the CA certificate.
1337 • Default: $certdir/ca.pem
1339 localedest
1343 Where Puppet should store translation files that it pulls down from the
1344 central server.
1345 • Default: $vardir/locales
1347 localesource
1351 From where to retrieve translation files. The standard Puppet file type
1352 is used for retrieval, so anything that is a valid file source can be
1353 used here.
1354 • Default: puppet:///locales
1356 location_trusted
1360 This will allow sending the name + password and the cookie header to
1361 all hosts that puppet may redirect to. This may or may not introduce a
1362 security breach if puppet redirects you to a site to which you´ll send
1363 your authentication info and cookies.
1364 • Default: false
1366 log_level
1370 Default logging level for messages from Puppet. Allowed values are:
1371 • debug
1373 • info
1375 • notice
1377 • warning
1379 • err
1381 • alert
1383 • emerg
1385 • crit
1387 • Default: notice
1389 logdest
1393 Where to send log messages. Choose between ´syslog´ (the POSIX syslog
1394 service), ´eventlog´ (the Windows Event Log), ´console´, or the path to
1395 a log file. Multiple destinations can be set using a comma separated
1396 list (eg: /path/file1,console,/path/file2)
1397 • Default: ``
1399 logdir
1403 The directory in which to store log files
1404 • Default: Unix/Linux: /var/log/puppet -- Windows: C:\Program‐
1406 Data\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppet‐
1407 labs/var/log
1408 manage_internal_file_permissions
1412 Whether Puppet should manage the owner, group, and mode of files it
1413 uses internally. Note: For Windows agents, the default is false for
1414 versions 4.10.13 and greater, versions 5.5.6 and greater, and versions
1415 6.0 and greater.
1416 • Default: true
1418 manifest
1422 The entry-point manifest for the primary server. This can be one file
1423 or a directory of manifests to be evaluated in alphabetical order. Pup‐
1424 pet manages this path as a directory if one exists or if the path ends
1425 with a / or .
1426 Setting a global value for manifest in puppet.conf is not allowed (but
1428 it can be overridden from the commandline). Please use directory envi‐
1429 ronments instead. If you need to use something other than the environ‐
1430 ment´s manifests directory as the main manifest, you can set manifest
1431 in environment.conf. For more info, see https://puppet.com/docs/pup‐
1432 pet/latest/environments_about.html
1433 • Default: ``
1435 masterport
1439 The default port puppet subcommands use to communicate with Puppet
1440 Server. (eg puppet facts upload, puppet agent). May be overridden by
1441 more specific settings (see ca_port, report_port).
1442 • Default: 8140
1444 max_deprecations
1448 Sets the max number of logged/displayed parser validation deprecation
1449 warnings in case multiple deprecation warnings have been detected. A
1450 value of 0 blocks the logging of deprecation warnings. The count is per
1451 manifest.
1452 • Default: 10
1454 max_errors
1458 Sets the max number of logged/displayed parser validation errors in
1459 case multiple errors have been detected. A value of 0 is the same as a
1460 value of 1; a minimum of one error is always raised. The count is per
1461 manifest.
1462 • Default: 10
1464 max_warnings
1468 Sets the max number of logged/displayed parser validation warnings in
1469 case multiple warnings have been detected. A value of 0 blocks logging
1470 of warnings. The count is per manifest.
1471 • Default: 10
1473 maximum_uid
1477 The maximum allowed UID. Some platforms use negative UIDs but then ship
1478 with tools that do not know how to handle signed ints, so the UIDs show
1479 up as huge numbers that can then not be fed back into the system. This
1480 is a hackish way to fail in a slightly more useful way when that hap‐
1481 pens.
1482 • Default: 4294967290
1484 maxwaitforcert
1488 The maximum amount of time the Puppet agent should wait for its cer‐
1489 tificate request to be signed. A value of unlimited will cause puppet
1490 agent to ask for a signed certificate indefinitely. This setting can be
1491 a time interval in seconds (30 or 30s), minutes (30m), hours (6h), days
1492 (2d), or years (5y).
1493 • Default: unlimited
1495 maxwaitforlock
1499 The maximum amount of time the puppet agent should wait for an already
1500 running puppet agent to finish before starting a new one. This is set
1501 by default to 1 minute. A value of unlimited will cause puppet agent to
1502 wait indefinitely. This setting can be a time interval in seconds (30
1503 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1504 • Default: 1m
1506 merge_dependency_warnings
1510 Whether to merge class-level dependency failure warnings.
1511 When a class has a failed dependency, every resource in the class gen‐
1513 erates a notice level message about the dependency failure, and a warn‐
1514 ing level message about skipping the resource.
1515 If true, all messages caused by a class dependency failure are merged
1517 into one message associated with the class.
1518 • Default: false
1520 mkusers
1524 Whether to create the necessary user and group that puppet agent will
1525 run as.
1526 • Default: false
1528 module_groups
1532 Extra module groups to request from the Puppet Forge. This is an inter‐
1533 nal setting, and users should never change it.
1534 • Default: ``
1536 module_repository
1540 The module repository
1541 • Default: https://forgeapi.puppet.com
1543 module_working_dir
1547 The directory into which module tool data is stored
1548 • Default: $vardir/puppet-module
1550 modulepath
1554 The search path for modules, as a list of directories separated by the
1555 system path separator character. (The POSIX path separator is ´:´, and
1556 the Windows path separator is ´;´.)
1557 Setting a global value for modulepath in puppet.conf is not allowed
1559 (but it can be overridden from the commandline). Please use directory
1560 environments instead. If you need to use something other than the de‐
1561 fault modulepath of <ACTIVE ENVIRONMENT´S MODULES DIR>:$basemodulepath,
1562 you can set modulepath in environment.conf. For more info, see
1563 https://puppet.com/docs/puppet/latest/environments_about.html
1564 name
1566 The name of the application, if we are running as one. The default is
1567 essentially $0 without the path or .rb.
1568 • Default: ``
1570 named_curve
1574 The short name for the EC curve used to generate the EC private key.
1575 Valid values must be one of the curves in
1576 OpenSSL::PKey::EC.builtin_curves. Default is prime256v1.
1577 • Default: prime256v1
1579 no_proxy
1583 List of host or domain names that should not go through
1584 http_proxy_host. Environment variable no_proxy or NO_PROXY will over‐
1585 ride this value. Names can be specified as an FQDN host.example.com,
1586 wildcard *.example.com, dotted domain .example.com, or suffix exam‐
1587 ple.com.
1588 • Default: localhost, 127.0.0.1
1590 node_cache_terminus
1594 How to store cached nodes. Valid values are (none), ´json´, ´msgpack´,
1595 or ´yaml´.
1596 • Default: ``
1598 node_name_fact
1602 The fact name used to determine the node name used for all requests the
1603 agent makes to the primary server. WARNING: This setting is mutually
1604 exclusive with node_name_value. Changing this setting also requires
1605 changes to Puppet Server´s default auth.conf https://pup‐
1606 pet.com/docs/puppetserver/latest/config_file_auth.html.
1607 node_name_value
1609 The explicit value used for the node name for all requests the agent
1610 makes to the primary server. WARNING: This setting is mutually exclu‐
1611 sive with node_name_fact. Changing this setting also requires changes
1612 to Puppet Server´s default auth.conf https://puppet.com/docs/puppet‐
1613 server/latest/config_file_auth.html.
1614 • Default: $certname
1616 node_terminus
1620 Which node data plugin to use when compiling node catalogs.
1621 When Puppet compiles a catalog, it combines two primary sources of
1623 info: the main manifest, and a node data plugin (often called a "node
1624 terminus," for historical reasons). Node data plugins provide three
1625 things for a given node name:
1626 1. A list of classes to add to that node´s catalog (and, optionally,
1628 values for their parameters).
1629 2. Which Puppet environment the node should use.
1631 3. A list of additional top-scope variables to set.
1633 The three main node data plugins are:
1637 • plain --- Returns no data, so that the main manifest controls all
1639 node configuration.
1640 • exec --- Uses an external node classifier (ENC) https://pup‐
1642 pet.com/docs/puppet/latest/nodes_external.html, configured by the
1643 external_nodes setting. This lets you pull a list of Puppet classes
1644 from any external system, using a small glue script to perform the
1645 request and format the result as YAML.
1646 • classifier (formerly console) --- Specific to Puppet Enterprise.
1648 Uses the PE console for node data."
1649 • Default: plain
1651 noop
1655 Whether to apply catalogs in noop mode, which allows Puppet to par‐
1656 tially simulate a normal run. This setting affects puppet agent and
1657 puppet apply.
1658 When running in noop mode, Puppet will check whether each resource is
1660 in sync, like it does when running normally. However, if a resource at‐
1661 tribute is not in the desired state (as declared in the catalog), Pup‐
1662 pet will take no action, and will instead report the changes it would
1663 have made. These simulated changes will appear in the report sent to
1664 the primary Puppet server, or be shown on the console if running puppet
1665 agent or puppet apply in the foreground. The simulated changes will not
1666 send refresh events to any subscribing or notified resources, although
1667 Puppet will log that a refresh event would have been sent.
1668 Important note: The noop metaparameter https://puppet.com/docs/pup‐
1670 pet/latest/metaparameter.html#noop allows you to apply individual re‐
1671 sources in noop mode, and will override the global value of the noop
1672 setting. This means a resource with noop => false will be changed if
1673 necessary, even when running puppet agent with noop = true or --noop.
1674 (Conversely, a resource with noop => true will only be simulated, even
1675 when noop mode is globally disabled.)
1676 • Default: false
1678 number_of_facts_soft_limit
1682 The soft limit for the total number of facts.
1683 • Default: 2048
1685 onetime
1689 Perform one configuration run and exit, rather than spawning a
1690 long-running daemon. This is useful for interactively running puppet
1691 agent, or running puppet agent from cron.
1692 • Default: false
1694 passfile
1698 Where puppet agent stores the password for its private key. Generally
1699 unused.
1700 • Default: $privatedir/password
1702 path
1706 The shell search path. Defaults to whatever is inherited from the par‐
1707 ent process.
1708 This setting can only be set in the [main] section of puppet.conf; it
1710 cannot be set in [server], [agent], or an environment config section.
1711 • Default: none
1713 payload_soft_limit
1717 The soft limit for the size of the payload.
1718 • Default: 16777216
1720 pidfile
1724 The file containing the PID of a running process. This file is intended
1725 to be used by service management frameworks and monitoring systems to
1726 determine if a puppet process is still in the process table.
1727 • Default: $rundir/${run_mode}.pid
1729 plugindest
1733 Where Puppet should store plugins that it pulls down from the central
1734 server.
1735 • Default: $libdir
1737 pluginfactdest
1741 Where Puppet should store external facts that are being handled by plu‐
1742 ginsync
1743 • Default: $vardir/facts.d
1745 pluginfactsource
1749 Where to retrieve external facts for pluginsync
1750 • Default: puppet:///pluginfacts
1752 pluginsignore
1756 What files to ignore when pulling down plugins.
1757 • Default: .svn CVS .git .hg
1759 pluginsource
1763 From where to retrieve plugins. The standard Puppet file type is used
1764 for retrieval, so anything that is a valid file source can be used
1765 here.
1766 • Default: puppet:///plugins
1768 pluginsync
1772 Whether plugins should be synced with the central server. This setting
1773 is deprecated.
1774 • Default: true
1776 postrun_command
1780 A command to run after every agent run. If this command returns a
1781 non-zero return code, the entire Puppet run will be considered to have
1782 failed, even though it might have performed work during the normal run.
1783 preferred_serialization_format
1785 The preferred means of serializing ruby instances for passing over the
1786 wire. This won´t guarantee that all instances will be serialized using
1787 this method, since not all classes can be guaranteed to support this
1788 format, but it will be used for all classes that support it.
1789 • Default: json
1791 preprocess_deferred
1795 Whether puppet should call deferred functions before applying the cata‐
1796 log. If set to true, then all prerequisites needed for the deferred
1797 function must be satisfied prior to puppet running. If set to false,
1798 then deferred functions will follow puppet relationships and ordering.
1799 This allows puppet to install prerequisites needed for a deferred func‐
1800 tion and call the deferred function in the same run.
1801 • Default: false
1803 prerun_command
1807 A command to run before every agent run. If this command returns a
1808 non-zero return code, the entire Puppet run will fail.
1809 preview_outputdir
1811 The directory where catalog previews per node are generated.
1812 • Default: $vardir/preview
1814 priority
1818 The scheduling priority of the process. Valid values are ´high´, ´nor‐
1819 mal´, ´low´, or ´idle´, which are mapped to platform-specific values.
1820 The priority can also be specified as an integer value and will be
1821 passed as is, e.g. -5. Puppet must be running as a privileged user in
1822 order to increase scheduling priority.
1823 • Default: ``
1825 privatedir
1829 Where the client stores private certificate information.
1830 • Default: $ssldir/private
1832 privatekeydir
1836 The private key directory.
1837 • Default: $ssldir/private_keys
1839 profile
1843 Whether to enable experimental performance profiling
1844 • Default: false
1846 publicdir
1850 Where Puppet stores public files.
1851 • Default: Unix/Linux: /var/lib/puppet/public -- Windows: C:\Program‐
1853 Data\PuppetLabs\puppet\public -- Non-root user: ~/.puppet‐
1854 labs/opt/puppet/public
1855 publickeydir
1859 The public key directory.
1860 • Default: $ssldir/public_keys
1862 puppet_trace
1866 Whether to print the Puppet stack trace on some errors. This is a noop
1867 if trace is also set.
1868 • Default: false
1870 puppetdlog
1874 The fallback log file. This is only used when the --logdest option is
1875 not specified AND Puppet is running on an operating system where both
1876 the POSIX syslog service and the Windows Event Log are unavailable.
1877 (Currently, no supported operating systems match that description.)
1878 Despite the name, both puppet agent and puppet server will use this
1880 file as the fallback logging destination.
1881 For control over logging destinations, see the --logdest command line
1883 option in the manual pages for puppet server, puppet agent, and puppet
1884 apply. You can see man pages by running puppet <SUBCOMMAND> --help, or
1885 read them online at https://puppet.com/docs/puppet/latest/man/.
1886 • Default: $logdir/puppetd.log
1888 report
1892 Whether to send reports after every transaction.
1893 • Default: true
1895 report_configured_environmentpath
1899 When versioned_environment_dirs is true Puppet will readlink the envi‐
1900 ronmentpath when constructing the environment´s modulepath. The full
1901 readlinked path is referred to as the "resolved path" and the config‐
1902 ured path potentially containing symlinks is the "configured path".
1903 When reporting where resources come from users may choose between the
1904 configured or resolved path.
1905 When set to false, the resolved paths are reported instead of the con‐
1907 figured paths.
1908 • Default: true
1910 report_include_system_store
1914 Whether the ´http´ report processor should include the system certifi‐
1915 cate store when submitting reports to HTTPS URLs. If false, then the
1916 ´http´ processor will only trust HTTPS report servers whose certifi‐
1917 cates are issued by the puppet CA or one of its intermediate CAs. If
1918 true, the processor will additionally trust CA certificates in the sys‐
1919 tem´s certificate store.
1920 • Default: false
1922 report_port
1926 The port to communicate with the report_server.
1927 • Default: $serverport
1929 report_server
1933 The server to send transaction reports to.
1934 • Default: $server
1936 reportdir
1940 The directory in which to store reports. Each node gets a separate sub‐
1941 directory in this directory. This setting is only used when the store
1942 report processor is enabled (see the reports setting).
1943 • Default: $vardir/reports
1945 reports
1949 The list of report handlers to use. When using multiple report han‐
1950 dlers, their names should be comma-separated, with whitespace allowed.
1951 (For example, reports = http, store.)
1952 This setting is relevant to puppet server and puppet apply. The primary
1954 Puppet server will call these report handlers with the reports it re‐
1955 ceives from agent nodes, and puppet apply will call them with its own
1956 report. (In all cases, the node applying the catalog must have report =
1957 true.)
1958 See the report reference for information on the built-in report han‐
1960 dlers; custom report handlers can also be loaded from modules. (Report
1961 handlers are loaded from the lib directory, at puppet/reports/NAME.rb.)
1962 To turn off reports entirely, set this to none
1964 • Default: store
1966 reporturl
1970 The URL that reports should be forwarded to. This setting is only used
1971 when the http report processor is enabled (see the reports setting).
1972 • Default: http://localhost:3000/reports/upload
1974 requestdir
1978 Where host certificate requests are stored.
1979 • Default: $ssldir/certificate_requests
1981 resourcefile
1985 The file in which puppet agent stores a list of the resources associ‐
1986 ated with the retrieved configuration.
1987 • Default: $statedir/resources.txt
1989 resubmit_facts
1993 Whether to send updated facts after every transaction. By default pup‐
1994 pet only submits facts at the beginning of the transaction before ap‐
1995 plying a catalog. Since puppet can modify the state of the system, the
1996 value of the facts may change after puppet finishes. Therefore, any
1997 facts stored in puppetdb may not be consistent until the agent next
1998 runs, typically in 30 minutes. If this feature is enabled, puppet will
1999 resubmit facts after applying its catalog, ensuring facts for the node
2000 stored in puppetdb are current. However, this will double the fact sub‐
2001 mission load on puppetdb, so it is disabled by default.
2002 • Default: false
2004 rich_data
2008 Enables having extended data in the catalog by storing them as a hash
2009 with the special key __ptype. When enabled, resource containing values
2010 of the data types Binary, Regexp, SemVer, SemVerRange, Timespan and
2011 Timestamp, as well as instances of types derived from Object retain
2012 their data type.
2013 • Default: true
2015 route_file
2019 The YAML file containing indirector route configuration.
2020 • Default: $confdir/routes.yaml
2022 rundir
2026 Where Puppet PID files are kept.
2027 • Default: Unix/Linux: /var/run/puppetlabs -- Windows: C:\Program‐
2029 Data\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppet‐
2030 labs/var/run
2031 runinterval
2035 How often puppet agent applies the catalog. Note that a runinterval of
2036 0 means "run continuously" rather than "never run." This setting can be
2037 a time interval in seconds (30 or 30s), minutes (30m), hours (6h), days
2038 (2d), or years (5y).
2039 • Default: 30m
2041 runtimeout
2045 The maximum amount of time an agent run is allowed to take. A Puppet
2046 agent run that exceeds this timeout will be aborted. A value of 0 dis‐
2047 ables the timeout. Defaults to 1 hour. This setting can be a time in‐
2048 terval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
2049 years (5y).
2050 • Default: 1h
2052 serial
2056 Where the serial number for certificates is stored.
2057 • Default: $cadir/serial
2059 server
2063 The primary Puppet server to which the Puppet agent should connect.
2064 • Default: puppet
2066 server_datadir
2070 The directory in which serialized data is stored, usually in a subdi‐
2071 rectory.
2072 • Default: $vardir/server_data
2074 server_list
2078 The list of primary Puppet servers to which the Puppet agent should
2079 connect, in the order that they will be tried. Each value should be a
2080 fully qualified domain name, followed by an optional ´:´ and port num‐
2081 ber. If a port is omitted, Puppet uses masterport for that host.
2082 • Default: []
2084 serverport
2088 The default port puppet subcommands use to communicate with Puppet
2089 Server. (eg puppet facts upload, puppet agent). May be overridden by
2090 more specific settings (see ca_port, report_port).
2091 • Default: 8140
2093 settings_catalog
2097 Whether to compile and apply the settings catalog
2098 • Default: true
2100 show_diff
2104 Whether to log and report a contextual diff when files are being re‐
2105 placed. This causes partial file contents to pass through Puppet´s nor‐
2106 mal logging and reporting system, so this setting should be used with
2107 caution if you are sending Puppet´s reports to an insecure destination.
2108 This feature currently requires the diff/lcs Ruby library.
2109 • Default: false
2111 signeddir
2115 Where the CA stores signed certificates.
2116 • Default: $cadir/signed
2118 skip_tags
2122 Tags to use to filter resources. If this is set, then only resources
2123 not tagged with the specified tags will be applied. Values must be
2124 comma-separated.
2125 sourceaddress
2127 The address the agent should use to initiate requests.
2128 • Default: ``
2130 splay
2134 Whether to sleep for a random amount of time, ranging from immediately
2135 up to its $splaylimit, before performing its first agent run after a
2136 service restart. After this period, the agent runs periodically on its
2137 $runinterval.
2138 For example, assume a default 30-minute $runinterval, splay set to its
2140 default of false, and an agent starting at :00 past the hour. The agent
2141 would check in every 30 minutes at :01 and :31 past the hour.
2142 With splay enabled, it waits any amount of time up to its $splaylimit
2144 before its first run. For example, it might randomly wait 8 minutes,
2145 then start its first run at :08 past the hour. With the $runinterval at
2146 its default 30 minutes, its next run will be at :38 past the hour.
2147 If you restart an agent´s puppet service with splay enabled, it recal‐
2149 culates its splay period and delays its first agent run after restart‐
2150 ing for this new period. If you simultaneously restart a group of pup‐
2151 pet agents with splay enabled, their checkins to your primary servers
2152 can be distributed more evenly.
2153 • Default: false
2155 splaylimit
2159 The maximum time to delay before an agent´s first run when splay is en‐
2160 abled. Defaults to the agent´s $runinterval. The splay interval is ran‐
2161 dom and recalculated each time the agent is started or restarted. This
2162 setting can be a time interval in seconds (30 or 30s), minutes (30m),
2163 hours (6h), days (2d), or years (5y).
2164 • Default: $runinterval
2166 srv_domain
2170 The domain which will be queried to find the SRV records of servers to
2171 use.
2172 • Default: example.com
2174 ssl_client_header
2178 The header containing an authenticated client´s SSL DN. This header
2179 must be set by the proxy to the authenticated client´s SSL DN (e.g.,
2180 /CN=puppet.puppetlabs.com). Puppet will parse out the Common Name (CN)
2181 from the Distinguished Name (DN) and use the value of the CN field for
2182 authorization.
2183 Note that the name of the HTTP header gets munged by the web server
2185 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2186 verted to underscores, and all letters are uppercased. Thus, to use the
2187 X-Client-DN header, this setting should be HTTP_X_CLIENT_DN.
2188 • Default: HTTP_X_CLIENT_DN
2190 ssl_client_verify_header
2194 The header containing the status message of the client verification.
2195 This header must be set by the proxy to ´SUCCESS´ if the client suc‐
2196 cessfully authenticated, and anything else otherwise.
2197 Note that the name of the HTTP header gets munged by the web server
2199 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2200 verted to underscores, and all letters are uppercased. Thus, to use the
2201 X-Client-Verify header, this setting should be HTTP_X_CLIENT_VERIFY.
2202 • Default: HTTP_X_CLIENT_VERIFY
2204 ssl_lockfile
2208 A lock file to indicate that the ssl bootstrap process is currently in
2209 progress.
2210 • Default: $ssldir/ssl.lock
2212 ssl_trust_store
2216 A file containing CA certificates in PEM format that puppet should
2217 trust when making HTTPS requests. This only applies to https requests
2218 to non-puppet infrastructure, such as retrieving file metadata and con‐
2219 tent from https file sources, puppet module tool and the ´http´ report
2220 processor. This setting is ignored when making requests to puppet://
2221 URLs such as catalog and report requests.
2222 • Default: ``
2224 ssldir
2228 Where SSL certificates are kept.
2229 • Default: $confdir/ssl
2231 statedir
2235 The directory where Puppet state is stored. Generally, this directory
2236 can be removed without causing harm (although it might result in spuri‐
2237 ous service restarts).
2238 • Default: $vardir/state
2240 statefile
2244 Where Puppet agent and Puppet Server store state associated with the
2245 running configuration. In the case of Puppet Server, this file reflects
2246 the state discovered through interacting with clients.
2247 • Default: $statedir/state.yaml
2249 statettl
2253 How long the Puppet agent should cache when a resource was last checked
2254 or synced. This setting can be a time interval in seconds (30 or 30s),
2255 minutes (30m), hours (6h), days (2d), or years (5y). A value of 0 or
2256 unlimited will disable cache pruning.
2257 This setting affects the usage of schedule resources, as the informa‐
2259 tion about when a resource was last checked (and therefore when it
2260 needs to be checked again) is stored in the statefile. The statettl
2261 needs to be large enough to ensure that a resource will not trigger
2262 multiple times during a schedule due to its entry expiring from the
2263 cache.
2264 • Default: 32d
2266 static_catalogs
2270 Whether to compile a static catalog https://puppet.com/docs/puppet/lat‐
2271 est/static_catalogs.html#enabling-or-disabling-static-catalogs, which
2272 occurs only on Puppet Server when the code-id-command and code-con‐
2273 tent-command settings are configured in its puppetserver.conf file.
2274 • Default: true
2276 storeconfigs
2280 Whether to store each client´s configuration, including catalogs,
2281 facts, and related data. This also enables the import and export of re‐
2282 sources in the Puppet language - a mechanism for exchange resources be‐
2283 tween nodes.
2284 By default this uses the ´puppetdb´ backend.
2286 You can adjust the backend using the storeconfigs_backend setting.
2288 • Default: false
2290 storeconfigs_backend
2294 Configure the backend terminus used for StoreConfigs. By default, this
2295 uses the PuppetDB store, which must be installed and configured before
2296 turning on StoreConfigs.
2297 • Default: puppetdb
2299 strict
2303 The strictness level of puppet. Allowed values are:
2304 • off - do not perform extra validation, do not report
2306 • warning - perform extra validation, report as warning
2308 • error - perform extra validation, fail with error (default)
2310 The strictness level is for both language semantics and runtime evalua‐
2314 tion validation. In addition to controlling the behavior with this pri‐
2315 mary server switch some individual warnings may also be controlled by
2316 the disable_warnings setting.
2317 No new validations will be added to a micro (x.y.z) release, but may be
2319 added in minor releases (x.y.0). In major releases it expected that
2320 most (if not all) strictness validation become standard behavior.
2321 • Default: error
2323 strict_environment_mode
2327 Whether the agent specified environment should be considered authorita‐
2328 tive, causing the run to fail if the retrieved catalog does not match
2329 it.
2330 • Default: false
2332 strict_variables
2336 Causes an evaluation error when referencing unknown variables. (This
2337 does not affect referencing variables that are explicitly set to un‐
2338 def).
2339 • Default: true
2341 summarize
2345 Whether to print a transaction summary.
2346 • Default: false
2348 supported_checksum_types
2352 Checksum types supported by this agent for use in file resources of a
2353 static catalog. Values must be comma-separated. Valid types are sha256,
2354 sha256lite, sha384, sha512, sha224, sha1, sha1lite, md5, md5lite,
2355 mtime, ctime. Default is sha256, sha384, sha512, sha224, md5.
2356 • Default: ["sha256", "sha384", "sha512", "sha224", "md5"]
2358 syslogfacility
2362 What syslog facility to use when logging to syslog. Syslog has a fixed
2363 list of valid facilities, and you must choose one of those; you cannot
2364 just make one up.
2365 • Default: daemon
2367 tags
2371 Tags to use to find resources. If this is set, then only resources
2372 tagged with the specified tags will be applied. Values must be
2373 comma-separated.
2374 tasks
2376 Turns on experimental support for tasks and plans in the puppet lan‐
2377 guage. This is for internal API use only. Do not change this setting.
2378 • Default: false
2380 top_level_facts_soft_limit
2384 The soft limit for the number of top level facts.
2385 • Default: 512
2387 trace
2391 Whether to print stack traces on some errors. Will print internal Ruby
2392 stack trace interleaved with Puppet function frames.
2393 • Default: false
2395 transactionstorefile
2399 Transactional storage file for persisting data between transactions for
2400 the purposes of inferring information (such as corrective_change) on
2401 new data received.
2402 • Default: $statedir/transactionstore.yaml
2404 trusted_external_command
2408 The external trusted facts script or directory to use. This setting´s
2409 value can be set to the path to an executable command that can produce
2410 external trusted facts or to a directory containing those executable
2411 commands. The command(s) must:
2412 • Take the name of a node as a command-line argument.
2414 • Return a JSON hash with the external trusted facts for this node.
2416 • For unknown or invalid nodes, exit with a non-zero exit code.
2418 If the setting points to an executable command, then the external
2422 trusted facts will be stored in the ´external´ key of the trusted facts
2423 hash. Otherwise for each executable file in the directory, the external
2424 trusted facts will be stored in the <basename> key of the trusted[´ex‐
2425 ternal´] hash. For example, if the files foo.rb and bar.sh are in the
2426 directory, then trusted[´external´] will be the hash { ´foo´ => <foo.rb
2427 output>, ´bar´ => <bar.sh output> }.
2428 • Default: ``
2430 trusted_oid_mapping_file
2434 File that provides mapping between custom SSL oids and user-friendly
2435 names
2436 • Default: $confdir/custom_trusted_oid_mapping.yaml
2438 use_cached_catalog
2442 Whether to only use the cached catalog rather than compiling a new cat‐
2443 alog on every run. Puppet can be run with this enabled by default and
2444 then selectively disabled when a recompile is desired. Because a Puppet
2445 agent using cached catalogs does not contact the primary server for a
2446 new catalog, it also does not upload facts at the beginning of the Pup‐
2447 pet run.
2448 • Default: false
2450 use_last_environment
2454 Puppet saves both the initial and converged environment in the
2455 last_run_summary file. If they differ, and this setting is set to true,
2456 we will use the last converged environment and skip the node request.
2457 When set to false, we will do the node request and ignore the environ‐
2459 ment data from the last_run_summary file.
2460 • Default: true
2462 use_srv_records
2466 Whether the server will search for SRV records in DNS for the current
2467 domain.
2468 • Default: false
2470 usecacheonfailure
2474 Whether to use the cached configuration when the remote configuration
2475 will not compile. This option is useful for testing new configurations,
2476 where you want to fix the broken configuration rather than reverting to
2477 a known-good one.
2478 • Default: true
2480 user
2484 The user Puppet Server will run as. Used to ensure the agent side pro‐
2485 cesses (agent, apply, etc) create files and directories readable by
2486 Puppet Server when necessary.
2487 • Default: puppet
2489 vardir
2493 Where Puppet stores dynamic and growing data. The default for this set‐
2494 ting is calculated specially, like confdir_.
2495 • Default: Unix/Linux: /var/lib/puppet -- Windows: C:\Program‐
2497 Data\PuppetLabs\puppet\cache -- Non-root user: ~/.puppet‐
2498 labs/opt/puppet/cache
2499 vendormoduledir
2503 The directory containing vendored modules. These modules will be used
2504 by all environments like those in the basemodulepath. The only differ‐
2505 ence is that modules in the basemodulepath are pluginsynced, while ven‐
2506 dored modules are not
2507 • Default: /usr/share/puppet/vendor_modules
2509 versioned_environment_dirs
2513 Whether or not to look for versioned environment directories, symlinked
2514 from $environmentpath/<environment>. This is an experimental feature
2515 and should be used with caution.
2516 • Default: false
2518 waitforcert
2522 How frequently puppet agent should ask for a signed certificate.
2523 When starting for the first time, puppet agent will submit a certifi‐
2525 cate signing request (CSR) to the server named in the ca_server setting
2526 (usually the primary Puppet server); this may be autosigned, or may
2527 need to be approved by a human, depending on the CA server´s configura‐
2528 tion.
2529 Puppet agent cannot apply configurations until its approved certificate
2531 is available. Since the certificate may or may not be available immedi‐
2532 ately, puppet agent will repeatedly try to fetch it at this interval.
2533 You can turn off waiting for certificates by specifying a time of 0, or
2534 a maximum amount of time to wait in the maxwaitforcert setting, in
2535 which case puppet agent will exit if it cannot get a cert. This setting
2536 can be a time interval in seconds (30 or 30s), minutes (30m), hours
2537 (6h), days (2d), or years (5y).
2538 • Default: 2m
2540 waitforlock
2544 How frequently puppet agent should try running when there is an already
2545 ongoing puppet agent instance.
2546 This argument is by default disabled (value set to 0). In this case
2548 puppet agent will immediately exit if it cannot run at that moment.
2549 When a value other than 0 is set, this can also be used in combination
2550 with the maxwaitforlock argument. This setting can be a time interval
2551 in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or years
2552 (5y).
2553 • Default: 0
2555 write_catalog_summary
2559 Whether to write the classfile and resourcefile after applying the cat‐
2560 alog. It is enabled by default, except when running puppet apply.
2561 • Default: true
2563 yamldir
2567 The directory in which YAML data is stored, usually in a subdirectory.
2568 • Default: $vardir/yaml
2570Puppet, Inc. October 2023 PUPPETCONF(5)