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) or "ppPrivCertExt" (1.3.6.1.4.1.34380.1.2) OID
510 arcs. The ppRegCertExt arc is reserved for four of the most common
511 pieces of data to embed: pp_uuid (.1), pp_instance_id (.2),
512 pp_image_name (.3), and pp_preshared_key (.4) --- in the YAML file,
513 these can be referred to by their short descriptive names instead of
514 their full OID. The ppPrivCertExt arc is unregulated, and can be used
515 for site-specific extensions.
516 · Default: $confdir/csr_attributes.yaml
518 csrdir
522 Where the CA stores certificate requests.
523 · Default: $cadir/requests
525 daemonize
529 Whether to send the process into the background. This defaults to true
530 on POSIX systems, and to false on Windows (where Puppet currently can‐
531 not daemonize).
532 · Default: true
534 data_binding_terminus
538 This setting has been deprecated. Use of any value other than ´hiera´
539 should instead be configured in a version 5 hiera.yaml. Until this set‐
540 ting is removed, it controls which data binding terminus to use for
541 global automatic data binding (across all environments). By default
542 this value is ´hiera´. A value of ´none´ turns off the global binding.
543 · Default: hiera
545 default_file_terminus
549 The default source for files if no server is given in a uri, e.g. pup‐
550 pet:///file. The default of rest causes the file to be retrieved using
551 the server setting. When running apply the default is file_server,
552 causing requests to be filled locally.
553 · Default: rest
555 default_manifest
559 The default main manifest for directory environments. Any environment
560 that doesn´t set the manifest setting in its environment.conf file will
561 use this manifest.
562 This setting´s value can be an absolute or relative path. An absolute
564 path will make all environments default to the same main manifest; a
565 relative path will allow each environment to use its own manifest, and
566 Puppet will resolve the path relative to each environment´s main direc‐
567 tory.
568 In either case, the path can point to a single file or to a directory
570 of manifests to be evaluated in alphabetical order.
571 · Default: ./manifests
573 default_schedules
577 Boolean; whether to generate the default schedule resources. Setting
578 this to false is useful for keeping external report processors clean of
579 skipped schedule resources.
580 · Default: true
582 deviceconfig
586 Path to the device config file for puppet device.
587 · Default: $confdir/device.conf
589 devicedir
593 The root directory of devices´ $vardir.
594 · Default: $vardir/devices
596 diff
600 Which diff command to use when printing differences between files. This
601 setting has no default value on Windows, as standard diff is not avail‐
602 able, but Puppet can use many third-party diff tools.
603 · Default: diff
605 diff_args
609 Which arguments to pass to the diff command when printing differences
610 between files. The command to use can be chosen with the diff setting.
611 · Default: -u
613 digest_algorithm
617 Which digest algorithm to use for file resources and the filebucket.
618 Valid values are md5, sha256, sha384, sha512, sha224. Default is md5.
619 · Default: md5
621 disable_i18n
625 If true, turns off all translations of Puppet and module log messages,
626 which affects error, warning, and info log messages, as well as any
627 translations in the report and CLI.
628 · Default: false
630 disable_per_environment_manifest
634 Whether to disallow an environment-specific main manifest. When set to
635 true, Puppet will use the manifest specified in the default_manifest
636 setting for all environments. If an environment specifies a different
637 main manifest in its environment.conf file, catalog requests for that
638 environment will fail with an error.
639 This setting requires default_manifest to be set to an absolute path.
641 · Default: false
643 disable_warnings
647 A comma-separated list of warning types to suppress. If large numbers
648 of warnings are making Puppet´s logs too large or difficult to use, you
649 can temporarily silence them with this setting.
650 If you are preparing to upgrade Puppet to a new major version, you
652 should re-enable all warnings for a while.
653 Valid values for this setting are:
655 · deprecations --- disables deprecation warnings.
657 · undefined_variables --- disables warnings about non existing vari‐
659 ables.
660 · undefined_resources --- disables warnings about non existing
662 resources.
663 · Default: []
665 dns_alt_names
669 A comma-separated list of alternate DNS names for Puppet Server. These
670 are extra hostnames (in addition to its certname) that the server is
671 allowed to use when serving agents. Puppet checks this setting when
672 automatically requesting a certificate for Puppet agent or Puppet
673 Server, and when manually generating a certificate with puppet cert
674 generate. These can be either IP or DNS, and the type should be speci‐
675 fied and followed with a colon. Untyped inputs will default to DNS.
676 In order to handle agent requests at a given hostname (like "pup‐
678 pet.example.com"), Puppet Server needs a certificate that proves it´s
679 allowed to use that name; if a server shows a certificate that doesn´t
680 include its hostname, Puppet agents will refuse to trust it. If you use
681 a single hostname for Puppet traffic but load-balance it to multiple
682 Puppet Servers, each of those servers needs to include the official
683 hostname in its list of extra names.
684 Note: The list of alternate names is locked in when the server´s cer‐
686 tificate is signed. If you need to change the list later, you can´t
687 just change this setting; you also need to:
688 · On the server: Stop Puppet Server.
690 · On the CA server: Revoke and clean the server´s old certificate.
692 (puppet cert clean <NAME>) (Note puppet cert clean is deprecated
693 and will be replaced with puppetserver ca clean in Puppet 6.)
694 · On the server: Delete the old certificate (and any old certificate
696 signing requests) from the ssldir https://puppet.com/docs/pup‐
697 pet/latest/dirs_ssldir.html.
698 · On the server: Run puppet agent -t --ca_server <CA HOSTNAME> to
700 request a new certificate
701 · On the CA server: Sign the certificate request, explicitly allowing
703 alternate names (puppet cert sign --allow-dns-alt-names <NAME>).
704 (Note puppet cert sign is deprecated and will be replaced with pup‐
705 petserver ca sign in Puppet 6.)
706 · On the server: Run puppet agent -t --ca_server <CA HOSTNAME> to
708 retrieve the cert.
709 · On the server: Start Puppet Server again.
711 To see all the alternate names your servers are using, log into your CA
715 server and run puppet cert list -a, then check the output for (alt
716 names: ...). Most agent nodes should NOT have alternate names; the only
717 certs that should have them are Puppet Server nodes that you want other
718 agents to trust.
719 document_all
721 Whether to document all resources when using puppet doc to generate
722 manifest documentation.
723 · Default: false
725 environment
729 The environment in which Puppet is running. For clients, such as puppet
730 agent, this determines the environment itself, which Puppet uses to
731 find modules and much more. For servers, such as puppet master, this
732 provides the default environment for nodes that Puppet knows nothing
733 about.
734 When defining an environment in the [agent] section, this refers to the
736 environment that the agent requests from the master. The environment
737 doesn´t have to exist on the local filesystem because the agent fetches
738 it from the master. This definition is used when running puppet agent.
739 When defined in the [user] section, the environment refers to the path
741 that Puppet uses to search for code and modules related to its execu‐
742 tion. This requires the environment to exist locally on the filesystem
743 where puppet is being executed. Puppet subcommands, including puppet
744 module and puppet apply, use this definition.
745 Given that the context and effects vary depending on the config section
747 https://puppet.com/docs/puppet/latest/config_file_main.html#config-sec‐
748 tions in which the environment setting is defined, do not set it glob‐
749 ally.
750 · Default: production
752 environment_data_provider
756 The name of a registered environment data provider used when obtaining
757 environment specific data. The three built in and registered providers
758 are ´none´ (no data), ´function´ (data obtained by calling the function
759 ´environment::data()´) and ´hiera´ (data obtained using a data provider
760 configured using a hiera.yaml file in root of the environment). Other
761 environment data providers may be registered in modules on the module
762 path. For such custom data providers see the respective module documen‐
763 tation. This setting is deprecated.
764 Default:
766 environment_timeout
769 How long the Puppet master should cache data it loads from an environ‐
770 ment. This setting can be a time interval in seconds (30 or 30s), min‐
771 utes (30m), hours (6h), days (2d), or years (5y). A value of 0 will
772 disable caching. This setting can also be set to unlimited, which will
773 cache environments until the master is restarted or told to refresh the
774 cache.
775 You should change this setting once your Puppet deployment is doing
777 non-trivial work. We chose the default value of 0 because it lets new
778 users update their code without any extra steps, but it lowers the per‐
779 formance of your Puppet master.
780 We recommend setting this to unlimited and explicitly refreshing your
782 Puppet master as part of your code deployment process.
783 · With Puppet Server, you should refresh environments by calling the
785 environment-cache API endpoint. See the docs for the Puppet Server
786 administrative API.
787 · With a Rack Puppet master, you should restart the web server or the
789 application server. Passenger lets you touch a restart.txt file to
790 refresh an application without restarting Apache; see the Passenger
791 docs for details.
792 We don´t recommend using any value other than 0 or unlimited, since
796 most Puppet masters use a pool of Ruby interpreters which all have
797 their own cache timers. When these timers drift out of sync, agents can
798 be served inconsistent catalogs.
799 · Default: 0
801 environmentpath
805 A search path for directory environments, as a list of directories sep‐
806 arated by the system path separator character. (The POSIX path separa‐
807 tor is ´:´, and the Windows path separator is ´;´.)
808 This setting must have a value set to enable directory environments.
810 The recommended value is $codedir/environments. For more details, see
811 https://puppet.com/docs/puppet/latest/environments_about.html
812 · Default: $codedir/environments
814 evaltrace
818 Whether each resource should log when it is being evaluated. This
819 allows you to interactively see exactly what is being done.
820 · Default: false
822 external_nodes
826 The external node classifier (ENC) script to use for node data. Puppet
827 combines this data with the main manifest to produce node catalogs.
828 To enable this setting, set the node_terminus setting to exec.
830 This setting´s value must be the path to an executable command that can
832 produce node information. The command must:
833 · Take the name of a node as a command-line argument.
835 ·
837 · classes --- A list of classes, as an array or hash.
839 · environment --- A string.
841 · parameters --- A list of top-scope variables to set, as a hash.
843 · For unknown nodes, exit with a non-zero exit code.
848 Generally, an ENC script makes requests to an external data source.
852 For more info, see the ENC documentation https://puppet.com/docs/pup‐
854 pet/latest/nodes_external.html.
855 · Default: none
857 factpath
861 Where Puppet should look for facts. Multiple directories should be sep‐
862 arated by the system path separator character. (The POSIX path separa‐
863 tor is ´:´, and the Windows path separator is ´;´.)
864 · Default: $vardir/lib/facter:$vardir/facts
866 facts_terminus
870 The node facts terminus.
871 · Default: facter
873 fileserverconfig
877 Where the fileserver configuration is stored.
878 · Default: $confdir/fileserver.conf
880 filetimeout
884 The minimum time to wait between checking for updates in configuration
885 files. This timeout determines how quickly Puppet checks whether a file
886 (such as manifests or templates) has changed on disk. This setting can
887 be a time interval in seconds (30 or 30s), minutes (30m), hours (6h),
888 days (2d), or years (5y).
889 · Default: 15s
891 forge_authorization
895 The authorization key to connect to the Puppet Forge. Leave blank for
896 unauthorized or license based connections
897 Default:
899 freeze_main
902 Freezes the ´main´ class, disallowing any code to be added to it. This
903 essentially means that you can´t have any code outside of a node,
904 class, or definition other than in the site manifest.
905 · Default: false
907 future_features
911 Whether or not to enable all features currently being developed for
912 future major releases of Puppet. Should be used with caution, as in
913 development features are experimental and can have unexpected effects.
914 · Default: false
916 genconfig
920 When true, causes Puppet applications to print an example config file
921 to stdout and exit. The example will include descriptions of each set‐
922 ting, and the current (or default) value of each setting, incorporating
923 any settings overridden on the CLI (with the exception of genconfig
924 itself). This setting only makes sense when specified on the command
925 line as --genconfig.
926 · Default: false
928 genmanifest
932 Whether to just print a manifest to stdout and exit. Only makes sense
933 when specified on the command line as --genmanifest. Takes into account
934 arguments specified on the CLI.
935 · Default: false
937 graph
941 Whether to create .dot graph files, which let you visualize the depen‐
942 dency and containment relationships in Puppet´s catalog. You can load
943 and view these files with tools like OmniGraffle http://www.omni‐
944 group.com/applications/omnigraffle/ (OS X) or graphviz
945 http://www.graphviz.org/ (multi-platform).
946 Graph files are created when applying a catalog, so this setting should
948 be used on nodes running puppet agent or puppet apply.
949 The graphdir setting determines where Puppet will save graphs. Note
951 that we don´t save graphs for historical runs; Puppet will replace the
952 previous .dot files with new ones every time it applies a catalog.
953 See your graphing software´s documentation for details on opening .dot
955 files. If you´re using GraphViz´s dot command, you can do a quick PNG
956 render with dot -Tpng <DOT FILE> -o <OUTPUT FILE>.
957 · Default: false
959 graphdir
963 Where to save .dot-format graphs (when the graph setting is enabled).
964 · Default: $statedir/graphs
966 group
970 The group Puppet Server will run as. Used to ensure the agent side pro‐
971 cesses (agent, apply, etc) create files and directories readable by
972 Puppet Server when necessary.
973 · Default: puppet
975 hiera_config
979 The hiera configuration file. Puppet only reads this file on startup,
980 so you must restart the puppet master every time you edit it.
981 · Default: $confdir/hiera.yaml. However, if a file exists at
983 $codedir/hiera.yaml, Puppet uses that instead.
984 hostcert
988 Where individual hosts store and look for their certificates.
989 · Default: $certdir/$certname.pem
991 hostcrl
995 Where the host´s certificate revocation list can be found. This is dis‐
996 tinct from the certificate authority´s CRL.
997 · Default: $ssldir/crl.pem
999 hostcsr
1003 Where individual hosts store and look for their certificate requests.
1004 · Default: $ssldir/csr_$certname.pem
1006 hostprivkey
1010 Where individual hosts store and look for their private key.
1011 · Default: $privatekeydir/$certname.pem
1013 hostpubkey
1017 Where individual hosts store and look for their public key.
1018 · Default: $publickeydir/$certname.pem
1020 http_connect_timeout
1024 The maximum amount of time to wait when establishing an HTTP connec‐
1025 tion. The default value is 2 minutes. This setting can be a time inter‐
1026 val in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or
1027 years (5y).
1028 · Default: 2m
1030 http_debug
1034 Whether to write HTTP request and responses to stderr. This should
1035 never be used in a production environment.
1036 · Default: false
1038 http_keepalive_timeout
1042 The maximum amount of time a persistent HTTP connection can remain idle
1043 in the connection pool, before it is closed. This timeout should be
1044 shorter than the keepalive timeout used on the HTTP server, e.g. Apache
1045 KeepAliveTimeout directive. This setting can be a time interval in sec‐
1046 onds (30 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1047 · Default: 4s
1049 http_proxy_host
1053 The HTTP proxy host to use for outgoing connections. The proxy will be
1054 bypassed if the server´s hostname matches the NO_PROXY environment
1055 variable or no_proxy setting. Note: You may need to use a FQDN for the
1056 server hostname when using a proxy. Environment variable http_proxy or
1057 HTTP_PROXY will override this value.
1058 · Default: none
1060 http_proxy_password
1064 The password for the user of an authenticated HTTP proxy. Requires the
1065 http_proxy_user setting.
1066 Note that passwords must be valid when used as part of a URL. If a
1068 password contains any characters with special meanings in URLs (as
1069 specified by RFC 3986 section 2.2), they must be URL-encoded. (For
1070 example, # would become %23.)
1071 · Default: none
1073 http_proxy_port
1077 The HTTP proxy port to use for outgoing connections
1078 · Default: 3128
1080 http_proxy_user
1084 The user name for an authenticated HTTP proxy. Requires the
1085 http_proxy_host setting.
1086 · Default: none
1088 http_read_timeout
1092 The time to wait for one block to be read from an HTTP connection. If
1093 nothing is read after the elapsed interval then the connection will be
1094 closed. The default value is unlimited. This setting can be a time
1095 interval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d),
1096 or years (5y).
1097 Default:
1099 http_user_agent
1102 The HTTP User-Agent string to send when making network requests.
1103 · Default: Puppet/5.5.18 Ruby/2.4.1-p111 (x86_64-linux)
1105 ignorecache
1109 This setting has no effect and will be removed in a future Puppet ver‐
1110 sion.
1111 · Default: false
1113 ignoremissingtypes
1117 Skip searching for classes and definitions that were missing during a
1118 prior compilation. The list of missing objects is maintained per-envi‐
1119 ronment and persists until the environment is cleared or the master is
1120 restarted.
1121 · Default: false
1123 ignoreschedules
1127 Boolean; whether puppet agent should ignore schedules. This is useful
1128 for initial puppet agent runs.
1129 · Default: false
1131 keylength
1135 The bit length of keys.
1136 · Default: 4096
1138 lastrunfile
1142 Where puppet agent stores the last run report summary in yaml format.
1143 · Default: $statedir/last_run_summary.yaml
1145 lastrunreport
1149 Where puppet agent stores the last run report in yaml format.
1150 · Default: $statedir/last_run_report.yaml
1152 ldapattrs
1156 The LDAP attributes to include when querying LDAP for nodes. All
1157 returned attributes are set as variables in the top-level scope. Multi‐
1158 ple values should be comma-separated. The value ´all´ returns all
1159 attributes.
1160 · Default: all
1162 ldapbase
1166 The search base for LDAP searches. It´s impossible to provide a mean‐
1167 ingful default here, although the LDAP libraries might have one already
1168 set. Generally, it should be the ´ou=Hosts´ branch under your main
1169 directory.
1170 ldapclassattrs
1172 The LDAP attributes to use to define Puppet classes. Values should be
1173 comma-separated.
1174 · Default: puppetclass
1176 ldapparentattr
1180 The attribute to use to define the parent node.
1181 · Default: parentnode
1183 ldappassword
1187 The password to use to connect to LDAP.
1188 ldapport
1190 The LDAP port. Only used if node_terminus is set to ldap.
1191 · Default: 389
1193 ldapserver
1197 The LDAP server. Only used if node_terminus is set to ldap.
1198 · Default: ldap
1200 ldapssl
1204 Whether SSL should be used when searching for nodes. Defaults to false
1205 because SSL usually requires certificates to be set up on the client
1206 side.
1207 · Default: false
1209 ldapstackedattrs
1213 The LDAP attributes that should be stacked to arrays by adding the val‐
1214 ues in all hierarchy elements of the tree. Values should be comma-sepa‐
1215 rated.
1216 · Default: puppetvar
1218 ldapstring
1222 The search string used to find an LDAP node.
1223 · Default: (&(objectclass=puppetClient)(cn=%s))
1225 ldaptls
1229 Whether TLS should be used when searching for nodes. Defaults to false
1230 because TLS usually requires certificates to be set up on the client
1231 side.
1232 · Default: false
1234 ldapuser
1238 The user to use to connect to LDAP. Must be specified as a full DN.
1239 libdir
1241 An extra search path for Puppet. This is only useful for those files
1242 that Puppet will load on demand, and is only guaranteed to work for
1243 those cases. In fact, the autoload mechanism is responsible for making
1244 sure this directory is in Ruby´s search path
1245 · Default: $vardir/lib
1247 localcacert
1251 Where each client stores the CA certificate.
1252 · Default: $certdir/ca.pem
1254 localedest
1258 Where Puppet should store translation files that it pulls down from the
1259 central server.
1260 · Default: $vardir/locales
1262 localesource
1266 From where to retrieve translation files. The standard Puppet file type
1267 is used for retrieval, so anything that is a valid file source can be
1268 used here.
1269 · Default: puppet:///locales
1271 log_level
1275 Default logging level for messages from Puppet. Allowed values are:
1276 · debug
1278 · info
1280 · notice
1282 · warning
1284 · err
1286 · alert
1288 · emerg
1290 · crit
1292 · Default: notice
1294 logdest
1298 Where to send log messages. Choose between ´syslog´ (the POSIX syslog
1299 service), ´eventlog´ (the Windows Event Log), ´console´, or the path to
1300 a log file.
1301 Default:
1303 logdir
1306 The directory in which to store log files
1307 · Default: Unix/Linux: /var/log/puppetlabs/puppet -- Windows: C:\Pro‐
1309 gramData\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppet‐
1310 labs/var/log
1311 manage_internal_file_permissions
1315 Whether Puppet should manage the owner, group, and mode of files it
1316 uses internally
1317 · Default: true
1319 manifest
1323 The entry-point manifest for puppet master. This can be one file or a
1324 directory of manifests to be evaluated in alphabetical order. Puppet
1325 manages this path as a directory if one exists or if the path ends with
1326 a / or .
1327 Setting a global value for manifest in puppet.conf is not allowed (but
1329 it can be overridden from the commandline). Please use directory envi‐
1330 ronments instead. If you need to use something other than the environ‐
1331 ment´s manifests directory as the main manifest, you can set manifest
1332 in environment.conf. For more info, see https://puppet.com/docs/pup‐
1333 pet/latest/environments_about.html
1334 Default:
1336 masterhttplog
1339 Where the puppet master web server saves its access log. This is only
1340 used when running a WEBrick puppet master. When puppet master is run‐
1341 ning under a Rack server like Passenger, that web server will have its
1342 own logging behavior.
1343 · Default: $logdir/masterhttp.log
1345 masterport
1349 The default port puppet subcommands use to communicate with Puppet
1350 Server. (eg puppet facts upload, puppet agent). May be overridden by
1351 more specific settings (see ca_port, report_port).
1352 · Default: 8140
1354 max_deprecations
1358 Sets the max number of logged/displayed parser validation deprecation
1359 warnings in case multiple deprecation warnings have been detected. A
1360 value of 0 blocks the logging of deprecation warnings. The count is per
1361 manifest.
1362 · Default: 10
1364 max_errors
1368 Sets the max number of logged/displayed parser validation errors in
1369 case multiple errors have been detected. A value of 0 is the same as a
1370 value of 1; a minimum of one error is always raised. The count is per
1371 manifest.
1372 · Default: 10
1374 max_warnings
1378 Sets the max number of logged/displayed parser validation warnings in
1379 case multiple warnings have been detected. A value of 0 blocks logging
1380 of warnings. The count is per manifest.
1381 · Default: 10
1383 maximum_uid
1387 The maximum allowed UID. Some platforms use negative UIDs but then ship
1388 with tools that do not know how to handle signed ints, so the UIDs show
1389 up as huge numbers that can then not be fed back into the system. This
1390 is a hackish way to fail in a slightly more useful way when that hap‐
1391 pens.
1392 · Default: 4294967290
1394 mkusers
1398 Whether to create the necessary user and group that puppet agent will
1399 run as.
1400 · Default: false
1402 module_groups
1406 Extra module groups to request from the Puppet Forge. This is an inter‐
1407 nal setting, and users should never change it.
1408 Default:
1410 module_repository
1413 The module repository
1414 · Default: https://forgeapi.puppet.com
1416 module_skeleton_dir
1420 The directory which the skeleton for module tool generate is stored.
1421 · Default: $module_working_dir/skeleton
1423 module_working_dir
1427 The directory into which module tool data is stored
1428 · Default: $vardir/puppet-module
1430 modulepath
1434 The search path for modules, as a list of directories separated by the
1435 system path separator character. (The POSIX path separator is ´:´, and
1436 the Windows path separator is ´;´.)
1437 Setting a global value for modulepath in puppet.conf is not allowed
1439 (but it can be overridden from the commandline). Please use directory
1440 environments instead. If you need to use something other than the
1441 default modulepath of <ACTIVE ENVIRONMENT´S MODULES DIR>:$basemod‐
1442 ulepath, you can set modulepath in environment.conf. For more info, see
1443 https://puppet.com/docs/puppet/latest/environments_about.html
1444 name
1446 The name of the application, if we are running as one. The default is
1447 essentially $0 without the path or .rb.
1448 Default:
1450 no_proxy
1453 List of host or domain names that should not go through
1454 http_proxy_host. Environment variable no_proxy or NO_PROXY will over‐
1455 ride this value. Names can be specified as an FQDN host.example.com,
1456 wildcard *.example.com, dotted domain .example.com, or suffix exam‐
1457 ple.com.
1458 · Default: localhost, 127.0.0.1
1460 node_cache_terminus
1464 How to store cached nodes. Valid values are (none), ´json´, ´msgpack´,
1465 ´yaml´ or write only yaml (´write_only_yaml´).
1466 Default:
1468 node_name
1471 How the puppet master determines the client´s identity and sets the
1472 ´hostname´, ´fqdn´ and ´domain´ facts for use in the manifest, in par‐
1473 ticular for determining which ´node´ statement applies to the client.
1474 Possible values are ´cert´ (use the subject´s CN in the client´s cer‐
1475 tificate) and ´facter´ (use the hostname that the client reported in
1476 its facts)
1477 · Default: cert
1479 node_name_fact
1483 The fact name used to determine the node name used for all requests the
1484 agent makes to the master. WARNING: This setting is mutually exclusive
1485 with node_name_value. Changing this setting also requires changes to
1486 the default auth.conf configuration on the Puppet Master. Please see
1487 http://links.puppet.com/node_name_fact for more information.
1488 node_name_value
1490 The explicit value used for the node name for all requests the agent
1491 makes to the master. WARNING: This setting is mutually exclusive with
1492 node_name_fact. Changing this setting also requires changes to the
1493 default auth.conf configuration on the Puppet Master. Please see
1494 http://links.puppet.com/node_name_value for more information.
1495 · Default: $certname
1497 node_terminus
1501 Which node data plugin to use when compiling node catalogs.
1502 When Puppet compiles a catalog, it combines two primary sources of
1504 info: the main manifest, and a node data plugin (often called a "node
1505 terminus," for historical reasons). Node data plugins provide three
1506 things for a given node name:
1507 1. A list of classes to add to that node´s catalog (and, optionally,
1509 values for their parameters).
1510 2. Which Puppet environment the node should use.
1512 3. A list of additional top-scope variables to set.
1514 The three main node data plugins are:
1518 · plain --- Returns no data, so that the main manifest controls all
1520 node configuration.
1521 · exec --- Uses an external node classifier (ENC) https://pup‐
1523 pet.com/docs/puppet/latest/nodes_external.html, configured by the
1524 external_nodes setting. This lets you pull a list of Puppet classes
1525 from any external system, using a small glue script to perform the
1526 request and format the result as YAML.
1527 · classifier (formerly console) --- Specific to Puppet Enterprise.
1529 Uses the PE console for node data."
1530 · Default: plain
1532 noop
1536 Whether to apply catalogs in noop mode, which allows Puppet to par‐
1537 tially simulate a normal run. This setting affects puppet agent and
1538 puppet apply.
1539 When running in noop mode, Puppet will check whether each resource is
1541 in sync, like it does when running normally. However, if a resource
1542 attribute is not in the desired state (as declared in the catalog),
1543 Puppet will take no action, and will instead report the changes it
1544 would have made. These simulated changes will appear in the report sent
1545 to the puppet master, or be shown on the console if running puppet
1546 agent or puppet apply in the foreground. The simulated changes will not
1547 send refresh events to any subscribing or notified resources, although
1548 Puppet will log that a refresh event would have been sent.
1549 Important note: The noop metaparameter https://puppet.com/docs/pup‐
1551 pet/latest/metaparameter.html#noop allows you to apply individual
1552 resources in noop mode, and will override the global value of the noop
1553 setting. This means a resource with noop => false will be changed if
1554 necessary, even when running puppet agent with noop = true or --noop.
1555 (Conversely, a resource with noop => true will only be simulated, even
1556 when noop mode is globally disabled.)
1557 · Default: false
1559 onetime
1563 Perform one configuration run and exit, rather than spawning a
1564 long-running daemon. This is useful for interactively running puppet
1565 agent, or running puppet agent from cron.
1566 · Default: false
1568 ordering
1572 How unrelated resources should be ordered when applying a catalog.
1573 Allowed values are title-hash, manifest, and random. This setting
1574 affects puppet agent and puppet apply, but not puppet master.
1575 · manifest (the default) will use the order in which the resources
1577 were declared in their manifest files.
1578 · title-hash (the default in 3.x) will order resources randomly, but
1580 will use the same order across runs and across nodes. It is only of
1581 value if you´re migrating from 3.x and have errors running with
1582 manifest.
1583 · random will order resources randomly and change their order with
1585 each run. This can work like a fuzzer for shaking out undeclared
1586 dependencies.
1587 Regardless of this setting´s value, Puppet will always obey explicit
1591 dependencies set with the before/require/notify/subscribe metaparame‐
1592 ters and the ->/~> chaining arrows; this setting only affects the rela‐
1593 tive ordering of unrelated resources.
1594 This setting is deprecated, and will always have a value of manifest in
1596 6.0 and up.
1597 · Default: manifest
1599 passfile
1603 Where puppet agent stores the password for its private key. Generally
1604 unused.
1605 · Default: $privatedir/password
1607 path
1611 The shell search path. Defaults to whatever is inherited from the par‐
1612 ent process.
1613 This setting can only be set in the [main] section of puppet.conf; it
1615 cannot be set in [master], [agent], or an environment config section.
1616 · Default: none
1618 pidfile
1622 The file containing the PID of a running process. This file is intended
1623 to be used by service management frameworks and monitoring systems to
1624 determine if a puppet process is still in the process table.
1625 · Default: $rundir/${run_mode}.pid
1627 plugindest
1631 Where Puppet should store plugins that it pulls down from the central
1632 server.
1633 · Default: $libdir
1635 pluginfactdest
1639 Where Puppet should store external facts that are being handled by plu‐
1640 ginsync
1641 · Default: $vardir/facts.d
1643 pluginfactsource
1647 Where to retrieve external facts for pluginsync
1648 · Default: puppet:///pluginfacts
1650 pluginsignore
1654 What files to ignore when pulling down plugins.
1655 · Default: .svn CVS .git .hg
1657 pluginsource
1661 From where to retrieve plugins. The standard Puppet file type is used
1662 for retrieval, so anything that is a valid file source can be used
1663 here.
1664 · Default: puppet:///plugins
1666 pluginsync
1670 Whether plugins should be synced with the central server. This setting
1671 is deprecated.
1672 · Default: true
1674 postrun_command
1678 A command to run after every agent run. If this command returns a
1679 non-zero return code, the entire Puppet run will be considered to have
1680 failed, even though it might have performed work during the normal run.
1681 preferred_serialization_format
1683 The preferred means of serializing ruby instances for passing over the
1684 wire. This won´t guarantee that all instances will be serialized using
1685 this method, since not all classes can be guaranteed to support this
1686 format, but it will be used for all classes that support it.
1687 · Default: json
1689 prerun_command
1693 A command to run before every agent run. If this command returns a
1694 non-zero return code, the entire Puppet run will fail.
1695 preview_outputdir
1697 The directory where catalog previews per node are generated.
1698 · Default: $vardir/preview
1700 priority
1704 The scheduling priority of the process. Valid values are ´high´, ´nor‐
1705 mal´, ´low´, or ´idle´, which are mapped to platform-specific values.
1706 The priority can also be specified as an integer value and will be
1707 passed as is, e.g. -5. Puppet must be running as a privileged user in
1708 order to increase scheduling priority.
1709 Default:
1711 privatedir
1714 Where the client stores private certificate information.
1715 · Default: $ssldir/private
1717 privatekeydir
1721 The private key directory.
1722 · Default: $ssldir/private_keys
1724 profile
1728 Whether to enable experimental performance profiling
1729 · Default: false
1731 publickeydir
1735 The public key directory.
1736 · Default: $ssldir/public_keys
1738 puppet_trace
1742 Whether to print the Puppet stack trace on some errors. This is a noop
1743 if trace is also set.
1744 · Default: false
1746 puppetdlog
1750 The fallback log file. This is only used when the --logdest option is
1751 not specified AND Puppet is running on an operating system where both
1752 the POSIX syslog service and the Windows Event Log are unavailable.
1753 (Currently, no supported operating systems match that description.)
1754 Despite the name, both puppet agent and puppet master will use this
1756 file as the fallback logging destination.
1757 For control over logging destinations, see the --logdest command line
1759 option in the manual pages for puppet master, puppet agent, and puppet
1760 apply. You can see man pages by running puppet <SUBCOMMAND> --help, or
1761 read them online at https://puppet.com/docs/puppet/latest/man/.
1762 · Default: $logdir/puppetd.log
1764 report
1768 Whether to send reports after every transaction.
1769 · Default: true
1771 report_port
1775 The port to communicate with the report_server.
1776 · Default: $masterport
1778 report_server
1782 The server to send transaction reports to.
1783 · Default: $server
1785 reportdir
1789 The directory in which to store reports. Each node gets a separate sub‐
1790 directory in this directory. This setting is only used when the store
1791 report processor is enabled (see the reports setting).
1792 · Default: $vardir/reports
1794 reports
1798 The list of report handlers to use. When using multiple report han‐
1799 dlers, their names should be comma-separated, with whitespace allowed.
1800 (For example, reports = http, store.)
1801 This setting is relevant to puppet master and puppet apply. The puppet
1803 master will call these report handlers with the reports it receives
1804 from agent nodes, and puppet apply will call them with its own report.
1805 (In all cases, the node applying the catalog must have report = true.)
1806 See the report reference for information on the built-in report han‐
1808 dlers; custom report handlers can also be loaded from modules. (Report
1809 handlers are loaded from the lib directory, at puppet/reports/NAME.rb.)
1810 · Default: store
1812 reporturl
1816 The URL that reports should be forwarded to. This setting is only used
1817 when the http report processor is enabled (see the reports setting).
1818 · Default: http://localhost:3000/reports/upload
1820 requestdir
1824 Where host certificate requests are stored.
1825 · Default: $ssldir/certificate_requests
1827 resourcefile
1831 The file in which puppet agent stores a list of the resources associ‐
1832 ated with the retrieved configuration.
1833 · Default: $statedir/resources.txt
1835 rest_authconfig
1839 The configuration file that defines the rights to the different rest
1840 indirections. This can be used as a fine-grained authorization system
1841 for puppet master. The puppet master command is deprecated and Puppet
1842 Server uses its own auth.conf that must be placed within its configura‐
1843 tion directory.
1844 · Default: $confdir/auth.conf
1846 resubmit_facts
1850 Whether to send updated facts after every transaction.
1851 · Default: false
1853 rich_data
1857 Enables having extended data in the catalog by storing them as a hash
1858 with the special key __pcore_type__. When enabled, resource containing
1859 values of the data types Binary, Regexp, SemVer, SemVerRange, Timespan
1860 and Timestamp, as well as instances of types derived from Object retain
1861 their data type.
1862 · Default: false
1864 route_file
1868 The YAML file containing indirector route configuration.
1869 · Default: $confdir/routes.yaml
1871 rundir
1875 Where Puppet PID files are kept.
1876 · Default: Unix/Linux: /var/run/puppetlabs -- Windows: C:\Program‐
1878 Data\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppet‐
1879 labs/var/run
1880 runinterval
1884 How often puppet agent applies the catalog. Note that a runinterval of
1885 0 means "run continuously" rather than "never run." If you want puppet
1886 agent to never run, you should start it with the --no-client option.
1887 This setting can be a time interval in seconds (30 or 30s), minutes
1888 (30m), hours (6h), days (2d), or years (5y).
1889 · Default: 30m
1891 runtimeout
1895 The maximum amount of time an agent run is allowed to take. A Puppet
1896 agent run that exceeds this timeout will be aborted. Defaults to 0,
1897 which is unlimited. This setting can be a time interval in seconds (30
1898 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1899 · Default: 0
1901 serial
1905 Where the serial number for certificates is stored.
1906 · Default: $cadir/serial
1908 server
1912 The puppet master server to which the puppet agent should connect.
1913 · Default: puppet
1915 server_datadir
1919 The directory in which serialized data is stored, usually in a subdi‐
1920 rectory.
1921 · Default: $vardir/server_data
1923 server_list
1927 The list of puppet master servers to which the puppet agent should con‐
1928 nect, in the order that they will be tried.
1929 · Default: []
1931 show_diff
1935 Whether to log and report a contextual diff when files are being
1936 replaced. This causes partial file contents to pass through Puppet´s
1937 normal logging and reporting system, so this setting should be used
1938 with caution if you are sending Puppet´s reports to an insecure desti‐
1939 nation. This feature currently requires the diff/lcs Ruby library.
1940 · Default: false
1942 signeddir
1946 Where the CA stores signed certificates.
1947 · Default: $cadir/signed
1949 skip_tags
1953 Tags to use to filter resources. If this is set, then only resources
1954 not tagged with the specified tags will be applied. Values must be
1955 comma-separated.
1956 sourceaddress
1958 The address the agent should use to initiate requests.
1959 Default:
1961 splay
1964 Whether to sleep for a random amount of time, ranging from immediately
1965 up to its $splaylimit, before performing its first agent run after a
1966 service restart. After this period, the agent runs periodically on its
1967 $runinterval.
1968 For example, assume a default 30-minute $runinterval, splay set to its
1970 default of false, and an agent starting at :00 past the hour. The agent
1971 would check in every 30 minutes at :01 and :31 past the hour.
1972 With splay enabled, it waits any amount of time up to its $splaylimit
1974 before its first run. For example, it might randomly wait 8 minutes,
1975 then start its first run at :08 past the hour. With the $runinterval at
1976 its default 30 minutes, its next run will be at :38 past the hour.
1977 If you restart an agent´s puppet service with splay enabled, it recal‐
1979 culates its splay period and delays its first agent run after restart‐
1980 ing for this new period. If you simultaneously restart a group of pup‐
1981 pet agents with splay enabled, their checkins to your puppet masters
1982 can be distributed more evenly.
1983 · Default: false
1985 splaylimit
1989 The maximum time to delay before an agent´s first run when splay is
1990 enabled. Defaults to the agent´s $runinterval. The splay interval is
1991 random and recalculated each time the agent is started or restarted.
1992 This setting can be a time interval in seconds (30 or 30s), minutes
1993 (30m), hours (6h), days (2d), or years (5y).
1994 · Default: $runinterval
1996 srv_domain
2000 The domain which will be queried to find the SRV records of servers to
2001 use.
2002 · Default: delivery.puppetlabs.net
2004 ssl_client_ca_auth
2008 Certificate authorities who issue server certificates. SSL servers will
2009 not be considered authentic unless they possess a certificate issued by
2010 an authority listed in this file. If this setting has no value then the
2011 Puppet master´s CA certificate (localcacert) will be used.
2012 Default:
2014 ssl_client_header
2017 The header containing an authenticated client´s SSL DN. This header
2018 must be set by the proxy to the authenticated client´s SSL DN (e.g.,
2019 /CN=puppet.puppetlabs.com). Puppet will parse out the Common Name (CN)
2020 from the Distinguished Name (DN) and use the value of the CN field for
2021 authorization.
2022 Note that the name of the HTTP header gets munged by the web server
2024 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2025 verted to underscores, and all letters are uppercased. Thus, to use the
2026 X-Client-DN header, this setting should be HTTP_X_CLIENT_DN.
2027 · Default: HTTP_X_CLIENT_DN
2029 ssl_client_verify_header
2033 The header containing the status message of the client verification.
2034 This header must be set by the proxy to ´SUCCESS´ if the client suc‐
2035 cessfully authenticated, and anything else otherwise.
2036 Note that the name of the HTTP header gets munged by the web server
2038 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2039 verted to underscores, and all letters are uppercased. Thus, to use the
2040 X-Client-Verify header, this setting should be HTTP_X_CLIENT_VERIFY.
2041 · Default: HTTP_X_CLIENT_VERIFY
2043 ssl_server_ca_auth
2047 Certificate authorities who issue client certificates. SSL clients will
2048 not be considered authentic unless they possess a certificate issued by
2049 an authority listed in this file. If this setting has no value then the
2050 Puppet master´s CA certificate (localcacert) will be used.
2051 Default:
2053 ssldir
2056 Where SSL certificates are kept.
2057 · Default: $confdir/ssl
2059 statedir
2063 The directory where Puppet state is stored. Generally, this directory
2064 can be removed without causing harm (although it might result in spuri‐
2065 ous service restarts).
2066 · Default: $vardir/state
2068 statefile
2072 Where puppet agent and puppet master store state associated with the
2073 running configuration. In the case of puppet master, this file reflects
2074 the state discovered through interacting with clients.
2075 · Default: $statedir/state.yaml
2077 statettl
2081 How long the Puppet agent should cache when a resource was last checked
2082 or synced. This setting can be a time interval in seconds (30 or 30s),
2083 minutes (30m), hours (6h), days (2d), or years (5y). A value of 0 or
2084 unlimited will disable cache pruning.
2085 This setting affects the usage of schedule resources, as the informa‐
2087 tion about when a resource was last checked (and therefore when it
2088 needs to be checked again) is stored in the statefile. The statettl
2089 needs to be large enough to ensure that a resource will not trigger
2090 multiple times during a schedule due to its entry expiring from the
2091 cache.
2092 · Default: 32d
2094 static_catalogs
2098 Whether to compile a static catalog https://puppet.com/docs/puppet/lat‐
2099 est/static_catalogs.html#enabling-or-disabling-static-catalogs, which
2100 occurs only on a Puppet Server master when the code-id-command and
2101 code-content-command settings are configured in its puppetserver.conf
2102 file.
2103 · Default: true
2105 storeconfigs
2109 Whether to store each client´s configuration, including catalogs,
2110 facts, and related data. This also enables the import and export of
2111 resources in the Puppet language - a mechanism for exchange resources
2112 between nodes.
2113 By default this uses the ´puppetdb´ backend.
2115 You can adjust the backend using the storeconfigs_backend setting.
2117 · Default: false
2119 storeconfigs_backend
2123 Configure the backend terminus used for StoreConfigs. By default, this
2124 uses the PuppetDB store, which must be installed and configured before
2125 turning on StoreConfigs.
2126 · Default: puppetdb
2128 strict
2132 The strictness level of puppet. Allowed values are:
2133 · off - do not perform extra validation, do not report
2135 · warning - perform extra validation, report as warning (default)
2137 · error - perform extra validation, fail with error
2139 The strictness level is for both language semantics and runtime evalua‐
2143 tion validation. In addition to controlling the behavior with this mas‐
2144 ter switch some individual warnings may also be controlled by the dis‐
2145 able_warnings setting.
2146 No new validations will be added to a micro (x.y.z) release, but may be
2148 added in minor releases (x.y.0). In major releases it expected that
2149 most (if not all) strictness validation become standard behavior.
2150 · Default: warning
2152 strict_environment_mode
2156 Whether the agent specified environment should be considered authorita‐
2157 tive, causing the run to fail if the retrieved catalog does not match
2158 it.
2159 · Default: false
2161 strict_hostname_checking
2165 Whether to only search for the complete hostname as it is in the cer‐
2166 tificate when searching for node information in the catalogs.
2167 · Default: false
2169 strict_variables
2173 Causes an evaluation error when referencing unknown variables. (This
2174 does not affect referencing variables that are explicitly set to
2175 undef).
2176 · Default: false
2178 summarize
2182 Whether to print a transaction summary.
2183 · Default: false
2185 supported_checksum_types
2189 Checksum types supported by this agent for use in file resources of a
2190 static catalog. Values must be comma-separated. Valid types are md5,
2191 md5lite, sha256, sha256lite, sha384, sha512, sha224, sha1, sha1lite,
2192 mtime, ctime. Default is md5, sha256, sha384, sha512, sha224.
2193 · Default: ["md5", "sha256", "sha384", "sha512", "sha224"]
2195 syslogfacility
2199 What syslog facility to use when logging to syslog. Syslog has a fixed
2200 list of valid facilities, and you must choose one of those; you cannot
2201 just make one up.
2202 · Default: daemon
2204 tags
2208 Tags to use to find resources. If this is set, then only resources
2209 tagged with the specified tags will be applied. Values must be
2210 comma-separated.
2211 tasks
2213 Turns on experimental support for tasks and plans in the puppet lan‐
2214 guage. This is for internal API use only. Do not change this setting.
2215 · Default: false
2217 trace
2221 Whether to print stack traces on some errors. Will print internal Ruby
2222 stack trace interleaved with Puppet function frames.
2223 · Default: false
2225 transactionstorefile
2229 Transactional storage file for persisting data between transactions for
2230 the purposes of infering information (such as corrective_change) on new
2231 data received.
2232 · Default: $statedir/transactionstore.yaml
2234 trusted_oid_mapping_file
2238 File that provides mapping between custom SSL oids and user-friendly
2239 names
2240 · Default: $confdir/custom_trusted_oid_mapping.yaml
2242 trusted_server_facts
2246 The ´trusted_server_facts´ setting is deprecated and has no effect as
2247 the feature this enabled is now always on. The setting will be removed
2248 in a future version of puppet.
2249 · Default: true
2251 use_cached_catalog
2255 Whether to only use the cached catalog rather than compiling a new cat‐
2256 alog on every run. Puppet can be run with this enabled by default and
2257 then selectively disabled when a recompile is desired. Because a Puppet
2258 agent using cached catalogs does not contact the master for a new cata‐
2259 log, it also does not upload facts at the beginning of the Puppet run.
2260 · Default: false
2262 use_srv_records
2266 Whether the server will search for SRV records in DNS for the current
2267 domain.
2268 · Default: false
2270 usecacheonfailure
2274 Whether to use the cached configuration when the remote configuration
2275 will not compile. This option is useful for testing new configurations,
2276 where you want to fix the broken configuration rather than reverting to
2277 a known-good one.
2278 · Default: true
2280 user
2284 The user Puppet Server will run as. Used to ensure the agent side pro‐
2285 cesses (agent, apply, etc) create files and directories readable by
2286 Puppet Server when necessary.
2287 · Default: puppet
2289 vardir
2293 Where Puppet stores dynamic and growing data. The default for this set‐
2294 ting is calculated specially, like confdir_.
2295 · Default: Unix/Linux: /opt/puppetlabs/puppet/cache -- Windows:
2297 C:\ProgramData\PuppetLabs\puppet\cache -- Non-root user: ~/.puppet‐
2298 labs/opt/puppet/cache
2299 waitforcert
2303 How frequently puppet agent should ask for a signed certificate.
2304 When starting for the first time, puppet agent will submit a certifi‐
2306 cate signing request (CSR) to the server named in the ca_server setting
2307 (usually the puppet master); this may be autosigned, or may need to be
2308 approved by a human, depending on the CA server´s configuration.
2309 Puppet agent cannot apply configurations until its approved certificate
2311 is available. Since the certificate may or may not be available immedi‐
2312 ately, puppet agent will repeatedly try to fetch it at this interval.
2313 You can turn off waiting for certificates by specifying a time of 0, in
2314 which case puppet agent will exit if it cannot get a cert. This setting
2315 can be a time interval in seconds (30 or 30s), minutes (30m), hours
2316 (6h), days (2d), or years (5y).
2317 · Default: 2m
2319 yamldir
2323 The directory in which YAML data is stored, usually in a subdirectory.
2324 · Default: $vardir/yaml
2326Puppet, Inc. January 2020 PUPPETCONF(5)