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 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 · 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;
25 $environment is special, in that puppet master will interpolate
26 each 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 will ignore any setting that isn´t relevant
48 to 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.
75 · Default: false
77 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 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 · Default: true
99 app_management
103 This setting has no effect and will be removed in a future Puppet ver‐
104 sion.
105 · Default: false
107 autoflush
111 Whether log files should always flush to disk.
112 · Default: true
114 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 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 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 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 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 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 · Default: $confdir/autosign.conf
148 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 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 · Default: $codedir/modules:/opt/puppetlabs/puppet/modules
162 bindaddress
166 The address a listening server should bind to.
167 · Default: *
169 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 Default:
180 bucketdir
183 Where FileBucket files are stored.
184 · Default: $vardir/bucket
186 ca
190 Whether the master should function as a certificate authority.
191 · Default: true
193 ca_name
197 The name to use the Certificate Authority certificate.
198 · Default: Puppet CA: $certname
200 ca_port
204 The port to use for the certificate authority.
205 · Default: $masterport
207 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 · Default: $server
215 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 · Default: 5y
224 cacert
228 The CA certificate.
229 · Default: $cadir/ca_crt.pem
231 cacrl
235 The certificate revocation list (CRL) for the CA. Will be used if
236 present but otherwise ignored.
237 · Default: $cadir/ca_crl.pem
239 cadir
243 The root directory for the certificate authority.
244 · Default: $ssldir/ca
246 cakey
250 The CA private key.
251 · Default: $cadir/ca_key.pem
253 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 · Default: $caprivatedir/ca.pass
261 caprivatedir
265 Where the CA stores private certificate information. This setting is
266 deprecated and will be removed in Puppet 6.
267 · Default: $cadir/private
269 capub
273 The CA public key.
274 · Default: $cadir/ca_pub.pem
276 catalog_cache_terminus
280 How to store cached catalogs. Valid values are ´json´, ´msgpack´ and
281 ´yaml´. The agent application defaults to ´json´.
282 Default:
284 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 · Default: compiler
292 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 · Default: $cadir/inventory.txt
300 certdir
304 The certificate directory.
305 · Default: $ssldir/certs
307 certificate_revocation
311 Whether certificate revocation checking should be enabled, and what
312 level of checking should be performed.
313 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 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 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 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 · Default: chain
339 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 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 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 · 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 · The special value ca is reserved, and can´t be used as the certname
364 for a normal node.
365 Defaults to the node´s fully qualified domain name.
369 · Default: the Host´s fully qualified domain name, as determined by
371 facter
372 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 · Default: $statedir/classes.txt
381 client_datadir
385 The directory in which serialized data is stored on the client.
386 · Default: $vardir/client_data
388 clientbucketdir
392 Where FileBucket files are stored locally.
393 · Default: $vardir/clientbucket
395 clientyamldir
399 The directory in which client-side YAML data is stored.
400 · Default: $vardir/client_yaml
402 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 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 · Default: Unix/Linux: /etc/puppetlabs/code -- Windows: C:\Program‐
417 Data\PuppetLabs\code -- Non-root user: ~/.puppetlabs/etc/code
418 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 · Default: ansi
428 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 · Default: Unix/Linux: /etc/puppetlabs/puppet -- Windows: C:\Program‐
439 Data\PuppetLabs\puppet\etc -- Non-root user: ~/.puppetlabs/etc/pup‐
440 pet
441 config
445 The configuration file for the current puppet application.
446 · Default: $confdir/${config_file_name}
448 config_file_name
452 The name of the puppet config file.
453 · Default: puppet.conf
455 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 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 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 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 · Default: 2m
485 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 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 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 Extension requests will be permanently embedded in the final certifi‐
508 cate. Extension OIDs must be in the "ppRegCertExt"
509 (1.3.6.1.4.1.34380.1.1), "ppPrivCertExt" (1.3.6.1.4.1.34380.1.2), or
510 "ppAuthCertExt" (1.3.6.1.4.1.34380.1.3) OID arcs. The ppRegCertExt arc
511 is reserved for four of the most common pieces of data to embed:
512 pp_uuid (.1), pp_instance_id (.2), pp_image_name (.3), and pp_pre‐
513 shared_key (.4) --- in the YAML file, these can be referred to by their
514 short descriptive names instead of their full OID. The ppPrivCertExt
515 arc is unregulated, and can be used for site-specific extensions. The
516 ppAuthCert arc is reserved for two pieces of data to embed: pp_autho‐
517 rization (.1) and pp_auth_role (.13). As with ppRegCertExt, in the YAML
518 file, these can be referred to by their short descriptive name instead
519 of their full OID.
520 · Default: $confdir/csr_attributes.yaml
522 csrdir
526 Where the CA stores certificate requests.
527 · Default: $cadir/requests
529 daemonize
533 Whether to send the process into the background. This defaults to true
534 on POSIX systems, and to false on Windows (where Puppet currently can‐
535 not daemonize).
536 · Default: true
538 data_binding_terminus
542 This setting has been deprecated. Use of any value other than ´hiera´
543 should instead be configured in a version 5 hiera.yaml. Until this set‐
544 ting is removed, it controls which data binding terminus to use for
545 global automatic data binding (across all environments). By default
546 this value is ´hiera´. A value of ´none´ turns off the global binding.
547 · Default: hiera
549 default_file_terminus
553 The default source for files if no server is given in a uri, e.g. pup‐
554 pet:///file. The default of rest causes the file to be retrieved using
555 the server setting. When running apply the default is file_server,
556 causing requests to be filled locally.
557 · Default: rest
559 default_manifest
563 The default main manifest for directory environments. Any environment
564 that doesn´t set the manifest setting in its environment.conf file will
565 use this manifest.
566 This setting´s value can be an absolute or relative path. An absolute
568 path will make all environments default to the same main manifest; a
569 relative path will allow each environment to use its own manifest, and
570 Puppet will resolve the path relative to each environment´s main direc‐
571 tory.
572 In either case, the path can point to a single file or to a directory
574 of manifests to be evaluated in alphabetical order.
575 · Default: ./manifests
577 default_schedules
581 Boolean; whether to generate the default schedule resources. Setting
582 this to false is useful for keeping external report processors clean of
583 skipped schedule resources.
584 · Default: true
586 deviceconfig
590 Path to the device config file for puppet device.
591 · Default: $confdir/device.conf
593 devicedir
597 The root directory of devices´ $vardir.
598 · Default: $vardir/devices
600 diff
604 Which diff command to use when printing differences between files. This
605 setting has no default value on Windows, as standard diff is not avail‐
606 able, but Puppet can use many third-party diff tools.
607 · Default: diff
609 diff_args
613 Which arguments to pass to the diff command when printing differences
614 between files. The command to use can be chosen with the diff setting.
615 · Default: -u
617 digest_algorithm
621 Which digest algorithm to use for file resources and the filebucket.
622 Valid values are md5, sha256, sha384, sha512, sha224. Default is md5.
623 · Default: md5
625 disable_i18n
629 If true, turns off all translations of Puppet and module log messages,
630 which affects error, warning, and info log messages, as well as any
631 translations in the report and CLI.
632 · Default: false
634 disable_per_environment_manifest
638 Whether to disallow an environment-specific main manifest. When set to
639 true, Puppet will use the manifest specified in the default_manifest
640 setting for all environments. If an environment specifies a different
641 main manifest in its environment.conf file, catalog requests for that
642 environment will fail with an error.
643 This setting requires default_manifest to be set to an absolute path.
645 · Default: false
647 disable_warnings
651 A comma-separated list of warning types to suppress. If large numbers
652 of warnings are making Puppet´s logs too large or difficult to use, you
653 can temporarily silence them with this setting.
654 If you are preparing to upgrade Puppet to a new major version, you
656 should re-enable all warnings for a while.
657 Valid values for this setting are:
659 · deprecations --- disables deprecation warnings.
661 · undefined_variables --- disables warnings about non existing vari‐
663 ables.
664 · undefined_resources --- disables warnings about non existing
666 resources.
667 · Default: []
669 dns_alt_names
673 A comma-separated list of alternate DNS names for Puppet Server. These
674 are extra hostnames (in addition to its certname) that the server is
675 allowed to use when serving agents. Puppet checks this setting when
676 automatically requesting a certificate for Puppet agent or Puppet
677 Server, and when manually generating a certificate with puppet cert
678 generate. These can be either IP or DNS, and the type should be speci‐
679 fied and followed with a colon. Untyped inputs will default to DNS.
680 In order to handle agent requests at a given hostname (like "pup‐
682 pet.example.com"), Puppet Server needs a certificate that proves it´s
683 allowed to use that name; if a server shows a certificate that doesn´t
684 include its hostname, Puppet agents will refuse to trust it. If you use
685 a single hostname for Puppet traffic but load-balance it to multiple
686 Puppet Servers, each of those servers needs to include the official
687 hostname in its list of extra names.
688 Note: The list of alternate names is locked in when the server´s cer‐
690 tificate is signed. If you need to change the list later, you can´t
691 just change this setting; you also need to:
692 · On the server: Stop Puppet Server.
694 · On the CA server: Revoke and clean the server´s old certificate.
696 (puppet cert clean <NAME>) (Note puppet cert clean is deprecated
697 and will be replaced with puppetserver ca clean in Puppet 6.)
698 · On the server: Delete the old certificate (and any old certificate
700 signing requests) from the ssldir https://puppet.com/docs/pup‐
701 pet/latest/dirs_ssldir.html.
702 · On the server: Run puppet agent -t --ca_server <CA HOSTNAME> to
704 request a new certificate
705 · On the CA server: Sign the certificate request, explicitly allowing
707 alternate names (puppet cert sign --allow-dns-alt-names <NAME>).
708 (Note puppet cert sign is deprecated and will be replaced with pup‐
709 petserver ca sign in Puppet 6.)
710 · On the server: Run puppet agent -t --ca_server <CA HOSTNAME> to
712 retrieve the cert.
713 · On the server: Start Puppet Server again.
715 To see all the alternate names your servers are using, log into your CA
719 server and run puppet cert list -a, then check the output for (alt
720 names: ...). Most agent nodes should NOT have alternate names; the only
721 certs that should have them are Puppet Server nodes that you want other
722 agents to trust.
723 document_all
725 Whether to document all resources when using puppet doc to generate
726 manifest documentation.
727 · Default: false
729 environment
733 The environment in which Puppet is running. For clients, such as puppet
734 agent, this determines the environment itself, which Puppet uses to
735 find modules and much more. For servers, such as puppet master, this
736 provides the default environment for nodes that Puppet knows nothing
737 about.
738 When defining an environment in the [agent] section, this refers to the
740 environment that the agent requests from the master. The environment
741 doesn´t have to exist on the local filesystem because the agent fetches
742 it from the master. This definition is used when running puppet agent.
743 When defined in the [user] section, the environment refers to the path
745 that Puppet uses to search for code and modules related to its execu‐
746 tion. This requires the environment to exist locally on the filesystem
747 where puppet is being executed. Puppet subcommands, including puppet
748 module and puppet apply, use this definition.
749 Given that the context and effects vary depending on the config section
751 https://puppet.com/docs/puppet/latest/config_file_main.html#config-sec‐
752 tions in which the environment setting is defined, do not set it glob‐
753 ally.
754 · Default: production
756 environment_data_provider
760 The name of a registered environment data provider used when obtaining
761 environment specific data. The three built in and registered providers
762 are ´none´ (no data), ´function´ (data obtained by calling the function
763 ´environment::data()´) and ´hiera´ (data obtained using a data provider
764 configured using a hiera.yaml file in root of the environment). Other
765 environment data providers may be registered in modules on the module
766 path. For such custom data providers see the respective module documen‐
767 tation. This setting is deprecated.
768 Default:
770 environment_timeout
773 How long the Puppet master should cache data it loads from an environ‐
774 ment. This setting can be a time interval in seconds (30 or 30s), min‐
775 utes (30m), hours (6h), days (2d), or years (5y). A value of 0 will
776 disable caching. This setting can also be set to unlimited, which will
777 cache environments until the master is restarted or told to refresh the
778 cache.
779 You should change this setting once your Puppet deployment is doing
781 non-trivial work. We chose the default value of 0 because it lets new
782 users update their code without any extra steps, but it lowers the per‐
783 formance of your Puppet master.
784 We recommend setting this to unlimited and explicitly refreshing your
786 Puppet master as part of your code deployment process.
787 · With Puppet Server, you should refresh environments by calling the
789 environment-cache API endpoint. See the docs for the Puppet Server
790 administrative API.
791 · With a Rack Puppet master, you should restart the web server or the
793 application server. Passenger lets you touch a restart.txt file to
794 refresh an application without restarting Apache; see the Passenger
795 docs for details.
796 We don´t recommend using any value other than 0 or unlimited, since
800 most Puppet masters use a pool of Ruby interpreters which all have
801 their own cache timers. When these timers drift out of sync, agents can
802 be served inconsistent catalogs.
803 · Default: 0
805 environmentpath
809 A search path for directory environments, as a list of directories sep‐
810 arated by the system path separator character. (The POSIX path separa‐
811 tor is ´:´, and the Windows path separator is ´;´.)
812 This setting must have a value set to enable directory environments.
814 The recommended value is $codedir/environments. For more details, see
815 https://puppet.com/docs/puppet/latest/environments_about.html
816 · Default: $codedir/environments
818 evaltrace
822 Whether each resource should log when it is being evaluated. This
823 allows you to interactively see exactly what is being done.
824 · Default: false
826 external_nodes
830 The external node classifier (ENC) script to use for node data. Puppet
831 combines this data with the main manifest to produce node catalogs.
832 To enable this setting, set the node_terminus setting to exec.
834 This setting´s value must be the path to an executable command that can
836 produce node information. The command must:
837 · Take the name of a node as a command-line argument.
839 ·
841 · classes --- A list of classes, as an array or hash.
843 · environment --- A string.
845 · parameters --- A list of top-scope variables to set, as a hash.
847 · For unknown nodes, exit with a non-zero exit code.
852 Generally, an ENC script makes requests to an external data source.
856 For more info, see the ENC documentation https://puppet.com/docs/pup‐
858 pet/latest/nodes_external.html.
859 · Default: none
861 factpath
865 Where Puppet should look for facts. Multiple directories should be sep‐
866 arated by the system path separator character. (The POSIX path separa‐
867 tor is ´:´, and the Windows path separator is ´;´.)
868 · Default: $vardir/lib/facter:$vardir/facts
870 facts_terminus
874 The node facts terminus.
875 · Default: facter
877 fileserverconfig
881 Where the fileserver configuration is stored.
882 · Default: $confdir/fileserver.conf
884 filetimeout
888 The minimum time to wait between checking for updates in configuration
889 files. This timeout determines how quickly Puppet checks whether a file
890 (such as manifests or templates) has changed on disk. This setting can
891 be a time interval in seconds (30 or 30s), minutes (30m), hours (6h),
892 days (2d), or years (5y).
893 · Default: 15s
895 forge_authorization
899 The authorization key to connect to the Puppet Forge. Leave blank for
900 unauthorized or license based connections
901 Default:
903 freeze_main
906 Freezes the ´main´ class, disallowing any code to be added to it. This
907 essentially means that you can´t have any code outside of a node,
908 class, or definition other than in the site manifest.
909 · Default: false
911 future_features
915 Whether or not to enable all features currently being developed for
916 future major releases of Puppet. Should be used with caution, as in
917 development features are experimental and can have unexpected effects.
918 · Default: false
920 genconfig
924 When true, causes Puppet applications to print an example config file
925 to stdout and exit. The example will include descriptions of each set‐
926 ting, and the current (or default) value of each setting, incorporating
927 any settings overridden on the CLI (with the exception of genconfig
928 itself). This setting only makes sense when specified on the command
929 line as --genconfig.
930 · Default: false
932 genmanifest
936 Whether to just print a manifest to stdout and exit. Only makes sense
937 when specified on the command line as --genmanifest. Takes into account
938 arguments specified on the CLI.
939 · Default: false
941 graph
945 Whether to create .dot graph files, which let you visualize the depen‐
946 dency and containment relationships in Puppet´s catalog. You can load
947 and view these files with tools like OmniGraffle http://www.omni‐
948 group.com/applications/omnigraffle/ (OS X) or graphviz
949 http://www.graphviz.org/ (multi-platform).
950 Graph files are created when applying a catalog, so this setting should
952 be used on nodes running puppet agent or puppet apply.
953 The graphdir setting determines where Puppet will save graphs. Note
955 that we don´t save graphs for historical runs; Puppet will replace the
956 previous .dot files with new ones every time it applies a catalog.
957 See your graphing software´s documentation for details on opening .dot
959 files. If you´re using GraphViz´s dot command, you can do a quick PNG
960 render with dot -Tpng <DOT FILE> -o <OUTPUT FILE>.
961 · Default: false
963 graphdir
967 Where to save .dot-format graphs (when the graph setting is enabled).
968 · Default: $statedir/graphs
970 group
974 The group Puppet Server will run as. Used to ensure the agent side pro‐
975 cesses (agent, apply, etc) create files and directories readable by
976 Puppet Server when necessary.
977 · Default: puppet
979 hiera_config
983 The hiera configuration file. Puppet only reads this file on startup,
984 so you must restart the puppet master every time you edit it.
985 · Default: $confdir/hiera.yaml. However, if a file exists at
987 $codedir/hiera.yaml, Puppet uses that instead.
988 hostcert
992 Where individual hosts store and look for their certificates.
993 · Default: $certdir/$certname.pem
995 hostcrl
999 Where the host´s certificate revocation list can be found. This is dis‐
1000 tinct from the certificate authority´s CRL.
1001 · Default: $ssldir/crl.pem
1003 hostcsr
1007 Where individual hosts store and look for their certificate requests.
1008 · Default: $ssldir/csr_$certname.pem
1010 hostprivkey
1014 Where individual hosts store and look for their private key.
1015 · Default: $privatekeydir/$certname.pem
1017 hostpubkey
1021 Where individual hosts store and look for their public key.
1022 · Default: $publickeydir/$certname.pem
1024 http_connect_timeout
1028 The maximum amount of time to wait when establishing an HTTP connec‐
1029 tion. The default value is 2 minutes. This setting can be a time inter‐
1030 val in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
1031 years (5y).
1032 · Default: 2m
1034 http_debug
1038 Whether to write HTTP request and responses to stderr. This should
1039 never be used in a production environment.
1040 · Default: false
1042 http_keepalive_timeout
1046 The maximum amount of time a persistent HTTP connection can remain idle
1047 in the connection pool, before it is closed. This timeout should be
1048 shorter than the keepalive timeout used on the HTTP server, e.g. Apache
1049 KeepAliveTimeout directive. This setting can be a time interval in sec‐
1050 onds (30 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1051 · Default: 4s
1053 http_proxy_host
1057 The HTTP proxy host to use for outgoing connections. The proxy will be
1058 bypassed if the server´s hostname matches the NO_PROXY environment
1059 variable or no_proxy setting. Note: You may need to use a FQDN for the
1060 server hostname when using a proxy. Environment variable http_proxy or
1061 HTTP_PROXY will override this value.
1062 · Default: none
1064 http_proxy_password
1068 The password for the user of an authenticated HTTP proxy. Requires the
1069 http_proxy_user setting.
1070 Note that passwords must be valid when used as part of a URL. If a
1072 password contains any characters with special meanings in URLs (as
1073 specified by RFC 3986 section 2.2), they must be URL-encoded. (For
1074 example, # would become %23.)
1075 · Default: none
1077 http_proxy_port
1081 The HTTP proxy port to use for outgoing connections
1082 · Default: 3128
1084 http_proxy_user
1088 The user name for an authenticated HTTP proxy. Requires the
1089 http_proxy_host setting.
1090 · Default: none
1092 http_read_timeout
1096 The time to wait for one block to be read from an HTTP connection. If
1097 nothing is read after the elapsed interval then the connection will be
1098 closed. The default value is unlimited. This setting can be a time
1099 interval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d),
1100 or years (5y).
1101 Default:
1103 http_user_agent
1106 The HTTP User-Agent string to send when making network requests.
1107 · Default: Puppet/5.5.20 Ruby/2.4.1-p111 (x86_64-linux)
1109 ignorecache
1113 This setting has no effect and will be removed in a future Puppet ver‐
1114 sion.
1115 · Default: false
1117 ignoremissingtypes
1121 Skip searching for classes and definitions that were missing during a
1122 prior compilation. The list of missing objects is maintained per-envi‐
1123 ronment and persists until the environment is cleared or the master is
1124 restarted.
1125 · Default: false
1127 ignoreschedules
1131 Boolean; whether puppet agent should ignore schedules. This is useful
1132 for initial puppet agent runs.
1133 · Default: false
1135 keylength
1139 The bit length of keys.
1140 · Default: 4096
1142 lastrunfile
1146 Where puppet agent stores the last run report summary in yaml format.
1147 · Default: $statedir/last_run_summary.yaml
1149 lastrunreport
1153 Where puppet agent stores the last run report in yaml format.
1154 · Default: $statedir/last_run_report.yaml
1156 ldapattrs
1160 The LDAP attributes to include when querying LDAP for nodes. All
1161 returned attributes are set as variables in the top-level scope. Multi‐
1162 ple values should be comma-separated. The value ´all´ returns all
1163 attributes.
1164 · Default: all
1166 ldapbase
1170 The search base for LDAP searches. It´s impossible to provide a mean‐
1171 ingful default here, although the LDAP libraries might have one already
1172 set. Generally, it should be the ´ou=Hosts´ branch under your main
1173 directory.
1174 ldapclassattrs
1176 The LDAP attributes to use to define Puppet classes. Values should be
1177 comma-separated.
1178 · Default: puppetclass
1180 ldapparentattr
1184 The attribute to use to define the parent node.
1185 · Default: parentnode
1187 ldappassword
1191 The password to use to connect to LDAP.
1192 ldapport
1194 The LDAP port. Only used if node_terminus is set to ldap.
1195 · Default: 389
1197 ldapserver
1201 The LDAP server. Only used if node_terminus is set to ldap.
1202 · Default: ldap
1204 ldapssl
1208 Whether SSL should be used when searching for nodes. Defaults to false
1209 because SSL usually requires certificates to be set up on the client
1210 side.
1211 · Default: false
1213 ldapstackedattrs
1217 The LDAP attributes that should be stacked to arrays by adding the val‐
1218 ues in all hierarchy elements of the tree. Values should be comma-sepa‐
1219 rated.
1220 · Default: puppetvar
1222 ldapstring
1226 The search string used to find an LDAP node.
1227 · Default: (&(objectclass=puppetClient)(cn=%s))
1229 ldaptls
1233 Whether TLS should be used when searching for nodes. Defaults to false
1234 because TLS usually requires certificates to be set up on the client
1235 side.
1236 · Default: false
1238 ldapuser
1242 The user to use to connect to LDAP. Must be specified as a full DN.
1243 libdir
1245 An extra search path for Puppet. This is only useful for those files
1246 that Puppet will load on demand, and is only guaranteed to work for
1247 those cases. In fact, the autoload mechanism is responsible for making
1248 sure this directory is in Ruby´s search path
1249 · Default: $vardir/lib
1251 localcacert
1255 Where each client stores the CA certificate.
1256 · Default: $certdir/ca.pem
1258 localedest
1262 Where Puppet should store translation files that it pulls down from the
1263 central server.
1264 · Default: $vardir/locales
1266 localesource
1270 From where to retrieve translation files. The standard Puppet file type
1271 is used for retrieval, so anything that is a valid file source can be
1272 used here.
1273 · Default: puppet:///locales
1275 log_level
1279 Default logging level for messages from Puppet. Allowed values are:
1280 · debug
1282 · info
1284 · notice
1286 · warning
1288 · err
1290 · alert
1292 · emerg
1294 · crit
1296 · Default: notice
1298 logdest
1302 Where to send log messages. Choose between ´syslog´ (the POSIX syslog
1303 service), ´eventlog´ (the Windows Event Log), ´console´, or the path to
1304 a log file.
1305 Default:
1307 logdir
1310 The directory in which to store log files
1311 · Default: Unix/Linux: /var/log/puppetlabs/puppet -- Windows: C:\Pro‐
1313 gramData\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppet‐
1314 labs/var/log
1315 manage_internal_file_permissions
1319 Whether Puppet should manage the owner, group, and mode of files it
1320 uses internally
1321 · Default: true
1323 manifest
1327 The entry-point manifest for puppet master. This can be one file or a
1328 directory of manifests to be evaluated in alphabetical order. Puppet
1329 manages this path as a directory if one exists or if the path ends with
1330 a / or .
1331 Setting a global value for manifest in puppet.conf is not allowed (but
1333 it can be overridden from the commandline). Please use directory envi‐
1334 ronments instead. If you need to use something other than the environ‐
1335 ment´s manifests directory as the main manifest, you can set manifest
1336 in environment.conf. For more info, see https://puppet.com/docs/pup‐
1337 pet/latest/environments_about.html
1338 Default:
1340 masterhttplog
1343 Where the puppet master web server saves its access log. This is only
1344 used when running a WEBrick puppet master. When puppet master is run‐
1345 ning under a Rack server like Passenger, that web server will have its
1346 own logging behavior.
1347 · Default: $logdir/masterhttp.log
1349 masterport
1353 The default port puppet subcommands use to communicate with Puppet
1354 Server. (eg puppet facts upload, puppet agent). May be overridden by
1355 more specific settings (see ca_port, report_port).
1356 · Default: 8140
1358 max_deprecations
1362 Sets the max number of logged/displayed parser validation deprecation
1363 warnings in case multiple deprecation warnings have been detected. A
1364 value of 0 blocks the logging of deprecation warnings. The count is per
1365 manifest.
1366 · Default: 10
1368 max_errors
1372 Sets the max number of logged/displayed parser validation errors in
1373 case multiple errors have been detected. A value of 0 is the same as a
1374 value of 1; a minimum of one error is always raised. The count is per
1375 manifest.
1376 · Default: 10
1378 max_warnings
1382 Sets the max number of logged/displayed parser validation warnings in
1383 case multiple warnings have been detected. A value of 0 blocks logging
1384 of warnings. The count is per manifest.
1385 · Default: 10
1387 maximum_uid
1391 The maximum allowed UID. Some platforms use negative UIDs but then ship
1392 with tools that do not know how to handle signed ints, so the UIDs show
1393 up as huge numbers that can then not be fed back into the system. This
1394 is a hackish way to fail in a slightly more useful way when that hap‐
1395 pens.
1396 · Default: 4294967290
1398 mkusers
1402 Whether to create the necessary user and group that puppet agent will
1403 run as.
1404 · Default: false
1406 module_groups
1410 Extra module groups to request from the Puppet Forge. This is an inter‐
1411 nal setting, and users should never change it.
1412 Default:
1414 module_repository
1417 The module repository
1418 · Default: https://forgeapi.puppet.com
1420 module_skeleton_dir
1424 The directory which the skeleton for module tool generate is stored.
1425 · Default: $module_working_dir/skeleton
1427 module_working_dir
1431 The directory into which module tool data is stored
1432 · Default: $vardir/puppet-module
1434 modulepath
1438 The search path for modules, as a list of directories separated by the
1439 system path separator character. (The POSIX path separator is ´:´, and
1440 the Windows path separator is ´;´.)
1441 Setting a global value for modulepath in puppet.conf is not allowed
1443 (but it can be overridden from the commandline). Please use directory
1444 environments instead. If you need to use something other than the
1445 default modulepath of <ACTIVE ENVIRONMENT´S MODULES DIR>:$basemod‐
1446 ulepath, you can set modulepath in environment.conf. For more info, see
1447 https://puppet.com/docs/puppet/latest/environments_about.html
1448 name
1450 The name of the application, if we are running as one. The default is
1451 essentially $0 without the path or .rb.
1452 Default:
1454 no_proxy
1457 List of host or domain names that should not go through
1458 http_proxy_host. Environment variable no_proxy or NO_PROXY will over‐
1459 ride this value. Names can be specified as an FQDN host.example.com,
1460 wildcard *.example.com, dotted domain .example.com, or suffix exam‐
1461 ple.com.
1462 · Default: localhost, 127.0.0.1
1464 node_cache_terminus
1468 How to store cached nodes. Valid values are (none), ´json´, ´msgpack´,
1469 ´yaml´ or write only yaml (´write_only_yaml´).
1470 Default:
1472 node_name
1475 How the puppet master determines the client´s identity and sets the
1476 ´hostname´, ´fqdn´ and ´domain´ facts for use in the manifest, in par‐
1477 ticular for determining which ´node´ statement applies to the client.
1478 Possible values are ´cert´ (use the subject´s CN in the client´s cer‐
1479 tificate) and ´facter´ (use the hostname that the client reported in
1480 its facts).
1481 This setting is deprecated, please use explicit fact matching for clas‐
1483 sification.
1484 · Default: cert
1486 node_name_fact
1490 The fact name used to determine the node name used for all requests the
1491 agent makes to the master. WARNING: This setting is mutually exclusive
1492 with node_name_value. Changing this setting also requires changes to
1493 the default auth.conf configuration on the Puppet Master. Please see
1494 http://links.puppet.com/node_name_fact for more information.
1495 node_name_value
1497 The explicit value used for the node name for all requests the agent
1498 makes to the master. WARNING: This setting is mutually exclusive with
1499 node_name_fact. Changing this setting also requires changes to the
1500 default auth.conf configuration on the Puppet Master. Please see
1501 http://links.puppet.com/node_name_value for more information.
1502 · Default: $certname
1504 node_terminus
1508 Which node data plugin to use when compiling node catalogs.
1509 When Puppet compiles a catalog, it combines two primary sources of
1511 info: the main manifest, and a node data plugin (often called a "node
1512 terminus," for historical reasons). Node data plugins provide three
1513 things for a given node name:
1514 1. A list of classes to add to that node´s catalog (and, optionally,
1516 values for their parameters).
1517 2. Which Puppet environment the node should use.
1519 3. A list of additional top-scope variables to set.
1521 The three main node data plugins are:
1525 · plain --- Returns no data, so that the main manifest controls all
1527 node configuration.
1528 · exec --- Uses an external node classifier (ENC) https://pup‐
1530 pet.com/docs/puppet/latest/nodes_external.html, configured by the
1531 external_nodes setting. This lets you pull a list of Puppet classes
1532 from any external system, using a small glue script to perform the
1533 request and format the result as YAML.
1534 · classifier (formerly console) --- Specific to Puppet Enterprise.
1536 Uses the PE console for node data."
1537 · Default: plain
1539 noop
1543 Whether to apply catalogs in noop mode, which allows Puppet to par‐
1544 tially simulate a normal run. This setting affects puppet agent and
1545 puppet apply.
1546 When running in noop mode, Puppet will check whether each resource is
1548 in sync, like it does when running normally. However, if a resource
1549 attribute is not in the desired state (as declared in the catalog),
1550 Puppet will take no action, and will instead report the changes it
1551 would have made. These simulated changes will appear in the report sent
1552 to the puppet master, or be shown on the console if running puppet
1553 agent or puppet apply in the foreground. The simulated changes will not
1554 send refresh events to any subscribing or notified resources, although
1555 Puppet will log that a refresh event would have been sent.
1556 Important note: The noop metaparameter https://puppet.com/docs/pup‐
1558 pet/latest/metaparameter.html#noop allows you to apply individual
1559 resources in noop mode, and will override the global value of the noop
1560 setting. This means a resource with noop => false will be changed if
1561 necessary, even when running puppet agent with noop = true or --noop.
1562 (Conversely, a resource with noop => true will only be simulated, even
1563 when noop mode is globally disabled.)
1564 · Default: false
1566 onetime
1570 Perform one configuration run and exit, rather than spawning a
1571 long-running daemon. This is useful for interactively running puppet
1572 agent, or running puppet agent from cron.
1573 · Default: false
1575 ordering
1579 How unrelated resources should be ordered when applying a catalog.
1580 Allowed values are title-hash, manifest, and random. This setting
1581 affects puppet agent and puppet apply, but not puppet master.
1582 · manifest (the default) will use the order in which the resources
1584 were declared in their manifest files.
1585 · title-hash (the default in 3.x) will order resources randomly, but
1587 will use the same order across runs and across nodes. It is only of
1588 value if you´re migrating from 3.x and have errors running with
1589 manifest.
1590 · random will order resources randomly and change their order with
1592 each run. This can work like a fuzzer for shaking out undeclared
1593 dependencies.
1594 Regardless of this setting´s value, Puppet will always obey explicit
1598 dependencies set with the before/require/notify/subscribe metaparame‐
1599 ters and the ->/~> chaining arrows; this setting only affects the rela‐
1600 tive ordering of unrelated resources.
1601 This setting is deprecated, and will always have a value of manifest in
1603 6.0 and up.
1604 · Default: manifest
1606 passfile
1610 Where puppet agent stores the password for its private key. Generally
1611 unused.
1612 · Default: $privatedir/password
1614 path
1618 The shell search path. Defaults to whatever is inherited from the par‐
1619 ent process.
1620 This setting can only be set in the [main] section of puppet.conf; it
1622 cannot be set in [master], [agent], or an environment config section.
1623 · Default: none
1625 pidfile
1629 The file containing the PID of a running process. This file is intended
1630 to be used by service management frameworks and monitoring systems to
1631 determine if a puppet process is still in the process table.
1632 · Default: $rundir/${run_mode}.pid
1634 plugindest
1638 Where Puppet should store plugins that it pulls down from the central
1639 server.
1640 · Default: $libdir
1642 pluginfactdest
1646 Where Puppet should store external facts that are being handled by plu‐
1647 ginsync
1648 · Default: $vardir/facts.d
1650 pluginfactsource
1654 Where to retrieve external facts for pluginsync
1655 · Default: puppet:///pluginfacts
1657 pluginsignore
1661 What files to ignore when pulling down plugins.
1662 · Default: .svn CVS .git .hg
1664 pluginsource
1668 From where to retrieve plugins. The standard Puppet file type is used
1669 for retrieval, so anything that is a valid file source can be used
1670 here.
1671 · Default: puppet:///plugins
1673 pluginsync
1677 Whether plugins should be synced with the central server. This setting
1678 is deprecated.
1679 · Default: true
1681 postrun_command
1685 A command to run after every agent run. If this command returns a
1686 non-zero return code, the entire Puppet run will be considered to have
1687 failed, even though it might have performed work during the normal run.
1688 preferred_serialization_format
1690 The preferred means of serializing ruby instances for passing over the
1691 wire. This won´t guarantee that all instances will be serialized using
1692 this method, since not all classes can be guaranteed to support this
1693 format, but it will be used for all classes that support it.
1694 · Default: json
1696 prerun_command
1700 A command to run before every agent run. If this command returns a
1701 non-zero return code, the entire Puppet run will fail.
1702 preview_outputdir
1704 The directory where catalog previews per node are generated.
1705 · Default: $vardir/preview
1707 priority
1711 The scheduling priority of the process. Valid values are ´high´, ´nor‐
1712 mal´, ´low´, or ´idle´, which are mapped to platform-specific values.
1713 The priority can also be specified as an integer value and will be
1714 passed as is, e.g. -5. Puppet must be running as a privileged user in
1715 order to increase scheduling priority.
1716 Default:
1718 privatedir
1721 Where the client stores private certificate information.
1722 · Default: $ssldir/private
1724 privatekeydir
1728 The private key directory.
1729 · Default: $ssldir/private_keys
1731 profile
1735 Whether to enable experimental performance profiling
1736 · Default: false
1738 publickeydir
1742 The public key directory.
1743 · Default: $ssldir/public_keys
1745 puppet_trace
1749 Whether to print the Puppet stack trace on some errors. This is a noop
1750 if trace is also set.
1751 · Default: false
1753 puppetdlog
1757 The fallback log file. This is only used when the --logdest option is
1758 not specified AND Puppet is running on an operating system where both
1759 the POSIX syslog service and the Windows Event Log are unavailable.
1760 (Currently, no supported operating systems match that description.)
1761 Despite the name, both puppet agent and puppet master will use this
1763 file as the fallback logging destination.
1764 For control over logging destinations, see the --logdest command line
1766 option in the manual pages for puppet master, puppet agent, and puppet
1767 apply. You can see man pages by running puppet <SUBCOMMAND> --help, or
1768 read them online at https://puppet.com/docs/puppet/latest/man/.
1769 · Default: $logdir/puppetd.log
1771 report
1775 Whether to send reports after every transaction.
1776 · Default: true
1778 report_port
1782 The port to communicate with the report_server.
1783 · Default: $masterport
1785 report_server
1789 The server to send transaction reports to.
1790 · Default: $server
1792 reportdir
1796 The directory in which to store reports. Each node gets a separate sub‐
1797 directory in this directory. This setting is only used when the store
1798 report processor is enabled (see the reports setting).
1799 · Default: $vardir/reports
1801 reports
1805 The list of report handlers to use. When using multiple report han‐
1806 dlers, their names should be comma-separated, with whitespace allowed.
1807 (For example, reports = http, store.)
1808 This setting is relevant to puppet master and puppet apply. The puppet
1810 master will call these report handlers with the reports it receives
1811 from agent nodes, and puppet apply will call them with its own report.
1812 (In all cases, the node applying the catalog must have report = true.)
1813 See the report reference for information on the built-in report han‐
1815 dlers; custom report handlers can also be loaded from modules. (Report
1816 handlers are loaded from the lib directory, at puppet/reports/NAME.rb.)
1817 · Default: store
1819 reporturl
1823 The URL that reports should be forwarded to. This setting is only used
1824 when the http report processor is enabled (see the reports setting).
1825 · Default: http://localhost:3000/reports/upload
1827 requestdir
1831 Where host certificate requests are stored.
1832 · Default: $ssldir/certificate_requests
1834 resourcefile
1838 The file in which puppet agent stores a list of the resources associ‐
1839 ated with the retrieved configuration.
1840 · Default: $statedir/resources.txt
1842 rest_authconfig
1846 The configuration file that defines the rights to the different rest
1847 indirections. This can be used as a fine-grained authorization system
1848 for puppet master. The puppet master command is deprecated and Puppet
1849 Server uses its own auth.conf that must be placed within its configura‐
1850 tion directory.
1851 · Default: $confdir/auth.conf
1853 resubmit_facts
1857 Whether to send updated facts after every transaction.
1858 · Default: false
1860 rich_data
1864 Enables having extended data in the catalog by storing them as a hash
1865 with the special key __pcore_type__. When enabled, resource containing
1866 values of the data types Binary, Regexp, SemVer, SemVerRange, Timespan
1867 and Timestamp, as well as instances of types derived from Object retain
1868 their data type.
1869 · Default: false
1871 route_file
1875 The YAML file containing indirector route configuration.
1876 · Default: $confdir/routes.yaml
1878 rundir
1882 Where Puppet PID files are kept.
1883 · Default: Unix/Linux: /var/run/puppetlabs -- Windows: C:\Program‐
1885 Data\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppet‐
1886 labs/var/run
1887 runinterval
1891 How often puppet agent applies the catalog. Note that a runinterval of
1892 0 means "run continuously" rather than "never run." If you want puppet
1893 agent to never run, you should start it with the --no-client option.
1894 This setting can be a time interval in seconds (30 or 30s), minutes
1895 (30m), hours (6h), days (2d), or years (5y).
1896 · Default: 30m
1898 runtimeout
1902 The maximum amount of time an agent run is allowed to take. A Puppet
1903 agent run that exceeds this timeout will be aborted. Defaults to 0,
1904 which is unlimited. This setting can be a time interval in seconds (30
1905 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1906 · Default: 0
1908 serial
1912 Where the serial number for certificates is stored.
1913 · Default: $cadir/serial
1915 server
1919 The puppet master server to which the puppet agent should connect.
1920 · Default: puppet
1922 server_datadir
1926 The directory in which serialized data is stored, usually in a subdi‐
1927 rectory.
1928 · Default: $vardir/server_data
1930 server_list
1934 The list of puppet master servers to which the puppet agent should con‐
1935 nect, in the order that they will be tried.
1936 · Default: []
1938 show_diff
1942 Whether to log and report a contextual diff when files are being
1943 replaced. This causes partial file contents to pass through Puppet´s
1944 normal logging and reporting system, so this setting should be used
1945 with caution if you are sending Puppet´s reports to an insecure desti‐
1946 nation. This feature currently requires the diff/lcs Ruby library.
1947 · Default: false
1949 signeddir
1953 Where the CA stores signed certificates.
1954 · Default: $cadir/signed
1956 skip_tags
1960 Tags to use to filter resources. If this is set, then only resources
1961 not tagged with the specified tags will be applied. Values must be
1962 comma-separated.
1963 sourceaddress
1965 The address the agent should use to initiate requests.
1966 Default:
1968 splay
1971 Whether to sleep for a random amount of time, ranging from immediately
1972 up to its $splaylimit, before performing its first agent run after a
1973 service restart. After this period, the agent runs periodically on its
1974 $runinterval.
1975 For example, assume a default 30-minute $runinterval, splay set to its
1977 default of false, and an agent starting at :00 past the hour. The agent
1978 would check in every 30 minutes at :01 and :31 past the hour.
1979 With splay enabled, it waits any amount of time up to its $splaylimit
1981 before its first run. For example, it might randomly wait 8 minutes,
1982 then start its first run at :08 past the hour. With the $runinterval at
1983 its default 30 minutes, its next run will be at :38 past the hour.
1984 If you restart an agent´s puppet service with splay enabled, it recal‐
1986 culates its splay period and delays its first agent run after restart‐
1987 ing for this new period. If you simultaneously restart a group of pup‐
1988 pet agents with splay enabled, their checkins to your puppet masters
1989 can be distributed more evenly.
1990 · Default: false
1992 splaylimit
1996 The maximum time to delay before an agent´s first run when splay is
1997 enabled. Defaults to the agent´s $runinterval. The splay interval is
1998 random and recalculated each time the agent is started or restarted.
1999 This setting can be a time interval in seconds (30 or 30s), minutes
2000 (30m), hours (6h), days (2d), or years (5y).
2001 · Default: $runinterval
2003 srv_domain
2007 The domain which will be queried to find the SRV records of servers to
2008 use.
2009 · Default: delivery.puppetlabs.net
2011 ssl_client_ca_auth
2015 Certificate authorities who issue server certificates. SSL servers will
2016 not be considered authentic unless they possess a certificate issued by
2017 an authority listed in this file. If this setting has no value then the
2018 Puppet master´s CA certificate (localcacert) will be used.
2019 Default:
2021 ssl_client_header
2024 The header containing an authenticated client´s SSL DN. This header
2025 must be set by the proxy to the authenticated client´s SSL DN (e.g.,
2026 /CN=puppet.puppetlabs.com). Puppet will parse out the Common Name (CN)
2027 from the Distinguished Name (DN) and use the value of the CN field for
2028 authorization.
2029 Note that the name of the HTTP header gets munged by the web server
2031 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2032 verted to underscores, and all letters are uppercased. Thus, to use the
2033 X-Client-DN header, this setting should be HTTP_X_CLIENT_DN.
2034 · Default: HTTP_X_CLIENT_DN
2036 ssl_client_verify_header
2040 The header containing the status message of the client verification.
2041 This header must be set by the proxy to ´SUCCESS´ if the client suc‐
2042 cessfully authenticated, and anything else otherwise.
2043 Note that the name of the HTTP header gets munged by the web server
2045 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2046 verted to underscores, and all letters are uppercased. Thus, to use the
2047 X-Client-Verify header, this setting should be HTTP_X_CLIENT_VERIFY.
2048 · Default: HTTP_X_CLIENT_VERIFY
2050 ssl_server_ca_auth
2054 Certificate authorities who issue client certificates. SSL clients will
2055 not be considered authentic unless they possess a certificate issued by
2056 an authority listed in this file. If this setting has no value then the
2057 Puppet master´s CA certificate (localcacert) will be used.
2058 Default:
2060 ssldir
2063 Where SSL certificates are kept.
2064 · Default: $confdir/ssl
2066 statedir
2070 The directory where Puppet state is stored. Generally, this directory
2071 can be removed without causing harm (although it might result in spuri‐
2072 ous service restarts).
2073 · Default: $vardir/state
2075 statefile
2079 Where puppet agent and puppet master store state associated with the
2080 running configuration. In the case of puppet master, this file reflects
2081 the state discovered through interacting with clients.
2082 · Default: $statedir/state.yaml
2084 statettl
2088 How long the Puppet agent should cache when a resource was last checked
2089 or synced. This setting can be a time interval in seconds (30 or 30s),
2090 minutes (30m), hours (6h), days (2d), or years (5y). A value of 0 or
2091 unlimited will disable cache pruning.
2092 This setting affects the usage of schedule resources, as the informa‐
2094 tion about when a resource was last checked (and therefore when it
2095 needs to be checked again) is stored in the statefile. The statettl
2096 needs to be large enough to ensure that a resource will not trigger
2097 multiple times during a schedule due to its entry expiring from the
2098 cache.
2099 · Default: 32d
2101 static_catalogs
2105 Whether to compile a static catalog https://puppet.com/docs/puppet/lat‐
2106 est/static_catalogs.html#enabling-or-disabling-static-catalogs, which
2107 occurs only on a Puppet Server master when the code-id-command and
2108 code-content-command settings are configured in its puppetserver.conf
2109 file.
2110 · Default: true
2112 storeconfigs
2116 Whether to store each client´s configuration, including catalogs,
2117 facts, and related data. This also enables the import and export of
2118 resources in the Puppet language - a mechanism for exchange resources
2119 between nodes.
2120 By default this uses the ´puppetdb´ backend.
2122 You can adjust the backend using the storeconfigs_backend setting.
2124 · Default: false
2126 storeconfigs_backend
2130 Configure the backend terminus used for StoreConfigs. By default, this
2131 uses the PuppetDB store, which must be installed and configured before
2132 turning on StoreConfigs.
2133 · Default: puppetdb
2135 strict
2139 The strictness level of puppet. Allowed values are:
2140 · off - do not perform extra validation, do not report
2142 · warning - perform extra validation, report as warning (default)
2144 · error - perform extra validation, fail with error
2146 The strictness level is for both language semantics and runtime evalua‐
2150 tion validation. In addition to controlling the behavior with this mas‐
2151 ter switch some individual warnings may also be controlled by the dis‐
2152 able_warnings setting.
2153 No new validations will be added to a micro (x.y.z) release, but may be
2155 added in minor releases (x.y.0). In major releases it expected that
2156 most (if not all) strictness validation become standard behavior.
2157 · Default: warning
2159 strict_environment_mode
2163 Whether the agent specified environment should be considered authorita‐
2164 tive, causing the run to fail if the retrieved catalog does not match
2165 it.
2166 · Default: false
2168 strict_hostname_checking
2172 Whether to only search for the complete hostname as it is in the cer‐
2173 tificate when searching for node information in the catalogs or to
2174 match dot delimited segments of the cert´s certname and the hostname,
2175 fqdn, and/or domain facts.
2176 This setting is deprecated and will be removed in a future release.
2178 · Default: true
2180 strict_variables
2184 Causes an evaluation error when referencing unknown variables. (This
2185 does not affect referencing variables that are explicitly set to
2186 undef).
2187 · Default: false
2189 summarize
2193 Whether to print a transaction summary.
2194 · Default: false
2196 supported_checksum_types
2200 Checksum types supported by this agent for use in file resources of a
2201 static catalog. Values must be comma-separated. Valid types are md5,
2202 md5lite, sha256, sha256lite, sha384, sha512, sha224, sha1, sha1lite,
2203 mtime, ctime. Default is md5, sha256, sha384, sha512, sha224.
2204 · Default: ["md5", "sha256", "sha384", "sha512", "sha224"]
2206 syslogfacility
2210 What syslog facility to use when logging to syslog. Syslog has a fixed
2211 list of valid facilities, and you must choose one of those; you cannot
2212 just make one up.
2213 · Default: daemon
2215 tags
2219 Tags to use to find resources. If this is set, then only resources
2220 tagged with the specified tags will be applied. Values must be
2221 comma-separated.
2222 tasks
2224 Turns on experimental support for tasks and plans in the puppet lan‐
2225 guage. This is for internal API use only. Do not change this setting.
2226 · Default: false
2228 trace
2232 Whether to print stack traces on some errors. Will print internal Ruby
2233 stack trace interleaved with Puppet function frames.
2234 · Default: false
2236 transactionstorefile
2240 Transactional storage file for persisting data between transactions for
2241 the purposes of infering information (such as corrective_change) on new
2242 data received.
2243 · Default: $statedir/transactionstore.yaml
2245 trusted_oid_mapping_file
2249 File that provides mapping between custom SSL oids and user-friendly
2250 names
2251 · Default: $confdir/custom_trusted_oid_mapping.yaml
2253 trusted_server_facts
2257 The ´trusted_server_facts´ setting is deprecated and has no effect as
2258 the feature this enabled is now always on. The setting will be removed
2259 in a future version of puppet.
2260 · Default: true
2262 use_cached_catalog
2266 Whether to only use the cached catalog rather than compiling a new cat‐
2267 alog on every run. Puppet can be run with this enabled by default and
2268 then selectively disabled when a recompile is desired. Because a Puppet
2269 agent using cached catalogs does not contact the master for a new cata‐
2270 log, it also does not upload facts at the beginning of the Puppet run.
2271 · Default: false
2273 use_srv_records
2277 Whether the server will search for SRV records in DNS for the current
2278 domain.
2279 · Default: false
2281 usecacheonfailure
2285 Whether to use the cached configuration when the remote configuration
2286 will not compile. This option is useful for testing new configurations,
2287 where you want to fix the broken configuration rather than reverting to
2288 a known-good one.
2289 · Default: true
2291 user
2295 The user Puppet Server will run as. Used to ensure the agent side pro‐
2296 cesses (agent, apply, etc) create files and directories readable by
2297 Puppet Server when necessary.
2298 · Default: puppet
2300 vardir
2304 Where Puppet stores dynamic and growing data. The default for this set‐
2305 ting is calculated specially, like confdir_.
2306 · Default: Unix/Linux: /opt/puppetlabs/puppet/cache -- Windows:
2308 C:\ProgramData\PuppetLabs\puppet\cache -- Non-root user: ~/.puppet‐
2309 labs/opt/puppet/cache
2310 waitforcert
2314 How frequently puppet agent should ask for a signed certificate.
2315 When starting for the first time, puppet agent will submit a certifi‐
2317 cate signing request (CSR) to the server named in the ca_server setting
2318 (usually the puppet master); this may be autosigned, or may need to be
2319 approved by a human, depending on the CA server´s configuration.
2320 Puppet agent cannot apply configurations until its approved certificate
2322 is available. Since the certificate may or may not be available immedi‐
2323 ately, puppet agent will repeatedly try to fetch it at this interval.
2324 You can turn off waiting for certificates by specifying a time of 0, in
2325 which case puppet agent will exit if it cannot get a cert. This setting
2326 can be a time interval in seconds (30 or 30s), minutes (30m), hours
2327 (6h), days (2d), or years (5y).
2328 · Default: 2m
2330 yamldir
2334 The directory in which YAML data is stored, usually in a subdirectory.
2335 · Default: $vardir/yaml
2337Puppet, Inc. April 2020 PUPPETCONF(5)