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. Note: You may need
1054 to use a FQDN for the server hostname when using a proxy. Environment
1055 variable http_proxy or HTTP_PROXY will override this value
1056 · Default: none
1058 http_proxy_password
1062 The password for the user of an authenticated HTTP proxy. Requires the
1063 http_proxy_user setting.
1064 Note that passwords must be valid when used as part of a URL. If a
1066 password contains any characters with special meanings in URLs (as
1067 specified by RFC 3986 section 2.2), they must be URL-encoded. (For
1068 example, # would become %23.)
1069 · Default: none
1071 http_proxy_port
1075 The HTTP proxy port to use for outgoing connections
1076 · Default: 3128
1078 http_proxy_user
1082 The user name for an authenticated HTTP proxy. Requires the
1083 http_proxy_host setting.
1084 · Default: none
1086 http_read_timeout
1090 The time to wait for one block to be read from an HTTP connection. If
1091 nothing is read after the elapsed interval then the connection will be
1092 closed. The default value is unlimited. This setting can be a time
1093 interval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d),
1094 or years (5y).
1095 Default:
1097 http_user_agent
1100 The HTTP User-Agent string to send when making network requests.
1101 · Default: Puppet/5.5.9 Ruby/2.4.1-p111 (x86_64-linux)
1103 ignorecache
1107 This setting has no effect and will be removed in a future Puppet ver‐
1108 sion.
1109 · Default: false
1111 ignoremissingtypes
1115 Skip searching for classes and definitions that were missing during a
1116 prior compilation. The list of missing objects is maintained per-envi‐
1117 ronment and persists until the environment is cleared or the master is
1118 restarted.
1119 · Default: false
1121 ignoreschedules
1125 Boolean; whether puppet agent should ignore schedules. This is useful
1126 for initial puppet agent runs.
1127 · Default: false
1129 keylength
1133 The bit length of keys.
1134 · Default: 4096
1136 lastrunfile
1140 Where puppet agent stores the last run report summary in yaml format.
1141 · Default: $statedir/last_run_summary.yaml
1143 lastrunreport
1147 Where puppet agent stores the last run report in yaml format.
1148 · Default: $statedir/last_run_report.yaml
1150 ldapattrs
1154 The LDAP attributes to include when querying LDAP for nodes. All
1155 returned attributes are set as variables in the top-level scope. Multi‐
1156 ple values should be comma-separated. The value ´all´ returns all
1157 attributes.
1158 · Default: all
1160 ldapbase
1164 The search base for LDAP searches. It´s impossible to provide a mean‐
1165 ingful default here, although the LDAP libraries might have one already
1166 set. Generally, it should be the ´ou=Hosts´ branch under your main
1167 directory.
1168 ldapclassattrs
1170 The LDAP attributes to use to define Puppet classes. Values should be
1171 comma-separated.
1172 · Default: puppetclass
1174 ldapparentattr
1178 The attribute to use to define the parent node.
1179 · Default: parentnode
1181 ldappassword
1185 The password to use to connect to LDAP.
1186 ldapport
1188 The LDAP port. Only used if node_terminus is set to ldap.
1189 · Default: 389
1191 ldapserver
1195 The LDAP server. Only used if node_terminus is set to ldap.
1196 · Default: ldap
1198 ldapssl
1202 Whether SSL should be used when searching for nodes. Defaults to false
1203 because SSL usually requires certificates to be set up on the client
1204 side.
1205 · Default: false
1207 ldapstackedattrs
1211 The LDAP attributes that should be stacked to arrays by adding the val‐
1212 ues in all hierarchy elements of the tree. Values should be comma-sepa‐
1213 rated.
1214 · Default: puppetvar
1216 ldapstring
1220 The search string used to find an LDAP node.
1221 · Default: (&(objectclass=puppetClient)(cn=%s))
1223 ldaptls
1227 Whether TLS should be used when searching for nodes. Defaults to false
1228 because TLS usually requires certificates to be set up on the client
1229 side.
1230 · Default: false
1232 ldapuser
1236 The user to use to connect to LDAP. Must be specified as a full DN.
1237 libdir
1239 An extra search path for Puppet. This is only useful for those files
1240 that Puppet will load on demand, and is only guaranteed to work for
1241 those cases. In fact, the autoload mechanism is responsible for making
1242 sure this directory is in Ruby´s search path
1243 · Default: $vardir/lib
1245 localcacert
1249 Where each client stores the CA certificate.
1250 · Default: $certdir/ca.pem
1252 localedest
1256 Where Puppet should store translation files that it pulls down from the
1257 central server.
1258 · Default: $vardir/locales
1260 localesource
1264 From where to retrieve translation files. The standard Puppet file type
1265 is used for retrieval, so anything that is a valid file source can be
1266 used here.
1267 · Default: puppet:///locales
1269 log_level
1273 Default logging level for messages from Puppet. Allowed values are:
1274 · debug
1276 · info
1278 · notice
1280 · warning
1282 · err
1284 · alert
1286 · emerg
1288 · crit
1290 · Default: notice
1292 logdest
1296 Where to send log messages. Choose between ´syslog´ (the POSIX syslog
1297 service), ´eventlog´ (the Windows Event Log), ´console´, or the path to
1298 a log file.
1299 Default:
1301 logdir
1304 The directory in which to store log files
1305 · Default: Unix/Linux: /var/log/puppetlabs/puppet -- Windows: C:\Pro‐
1307 gramData\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppet‐
1308 labs/var/log
1309 manage_internal_file_permissions
1313 Whether Puppet should manage the owner, group, and mode of files it
1314 uses internally
1315 · Default: true
1317 manifest
1321 The entry-point manifest for puppet master. This can be one file or a
1322 directory of manifests to be evaluated in alphabetical order. Puppet
1323 manages this path as a directory if one exists or if the path ends with
1324 a / or .
1325 Setting a global value for manifest in puppet.conf is not allowed (but
1327 it can be overridden from the commandline). Please use directory envi‐
1328 ronments instead. If you need to use something other than the environ‐
1329 ment´s manifests directory as the main manifest, you can set manifest
1330 in environment.conf. For more info, see https://puppet.com/docs/pup‐
1331 pet/latest/environments_about.html
1332 Default:
1334 masterhttplog
1337 Where the puppet master web server saves its access log. This is only
1338 used when running a WEBrick puppet master. When puppet master is run‐
1339 ning under a Rack server like Passenger, that web server will have its
1340 own logging behavior.
1341 · Default: $logdir/masterhttp.log
1343 masterport
1347 The default port puppet subcommands use to communicate with Puppet
1348 Server. (eg puppet facts upload, puppet agent). May be overridden by
1349 more specific settings (see ca_port, report_port).
1350 · Default: 8140
1352 max_deprecations
1356 Sets the max number of logged/displayed parser validation deprecation
1357 warnings in case multiple deprecation warnings have been detected. A
1358 value of 0 blocks the logging of deprecation warnings. The count is per
1359 manifest.
1360 · Default: 10
1362 max_errors
1366 Sets the max number of logged/displayed parser validation errors in
1367 case multiple errors have been detected. A value of 0 is the same as a
1368 value of 1; a minimum of one error is always raised. The count is per
1369 manifest.
1370 · Default: 10
1372 max_warnings
1376 Sets the max number of logged/displayed parser validation warnings in
1377 case multiple warnings have been detected. A value of 0 blocks logging
1378 of warnings. The count is per manifest.
1379 · Default: 10
1381 maximum_uid
1385 The maximum allowed UID. Some platforms use negative UIDs but then ship
1386 with tools that do not know how to handle signed ints, so the UIDs show
1387 up as huge numbers that can then not be fed back into the system. This
1388 is a hackish way to fail in a slightly more useful way when that hap‐
1389 pens.
1390 · Default: 4294967290
1392 mkusers
1396 Whether to create the necessary user and group that puppet agent will
1397 run as.
1398 · Default: false
1400 module_groups
1404 Extra module groups to request from the Puppet Forge. This is an inter‐
1405 nal setting, and users should never change it.
1406 Default:
1408 module_repository
1411 The module repository
1412 · Default: https://forgeapi.puppet.com
1414 module_skeleton_dir
1418 The directory which the skeleton for module tool generate is stored.
1419 · Default: $module_working_dir/skeleton
1421 module_working_dir
1425 The directory into which module tool data is stored
1426 · Default: $vardir/puppet-module
1428 modulepath
1432 The search path for modules, as a list of directories separated by the
1433 system path separator character. (The POSIX path separator is ´:´, and
1434 the Windows path separator is ´;´.)
1435 Setting a global value for modulepath in puppet.conf is not allowed
1437 (but it can be overridden from the commandline). Please use directory
1438 environments instead. If you need to use something other than the
1439 default modulepath of <ACTIVE ENVIRONMENT´S MODULES DIR>:$basemod‐
1440 ulepath, you can set modulepath in environment.conf. For more info, see
1441 https://puppet.com/docs/puppet/latest/environments_about.html
1442 name
1444 The name of the application, if we are running as one. The default is
1445 essentially $0 without the path or .rb.
1446 Default:
1448 node_cache_terminus
1451 How to store cached nodes. Valid values are (none), ´json´, ´msgpack´,
1452 ´yaml´ or write only yaml (´write_only_yaml´).
1453 Default:
1455 node_name
1458 How the puppet master determines the client´s identity and sets the
1459 ´hostname´, ´fqdn´ and ´domain´ facts for use in the manifest, in par‐
1460 ticular for determining which ´node´ statement applies to the client.
1461 Possible values are ´cert´ (use the subject´s CN in the client´s cer‐
1462 tificate) and ´facter´ (use the hostname that the client reported in
1463 its facts)
1464 · Default: cert
1466 node_name_fact
1470 The fact name used to determine the node name used for all requests the
1471 agent makes to the master. WARNING: This setting is mutually exclusive
1472 with node_name_value. Changing this setting also requires changes to
1473 the default auth.conf configuration on the Puppet Master. Please see
1474 http://links.puppet.com/node_name_fact for more information.
1475 node_name_value
1477 The explicit value used for the node name for all requests the agent
1478 makes to the master. WARNING: This setting is mutually exclusive with
1479 node_name_fact. Changing this setting also requires changes to the
1480 default auth.conf configuration on the Puppet Master. Please see
1481 http://links.puppet.com/node_name_value for more information.
1482 · Default: $certname
1484 node_terminus
1488 Which node data plugin to use when compiling node catalogs.
1489 When Puppet compiles a catalog, it combines two primary sources of
1491 info: the main manifest, and a node data plugin (often called a "node
1492 terminus," for historical reasons). Node data plugins provide three
1493 things for a given node name:
1494 1. A list of classes to add to that node´s catalog (and, optionally,
1496 values for their parameters).
1497 2. Which Puppet environment the node should use.
1499 3. A list of additional top-scope variables to set.
1501 The three main node data plugins are:
1505 · plain --- Returns no data, so that the main manifest controls all
1507 node configuration.
1508 · exec --- Uses an external node classifier (ENC) https://pup‐
1510 pet.com/docs/puppet/latest/nodes_external.html, configured by the
1511 external_nodes setting. This lets you pull a list of Puppet classes
1512 from any external system, using a small glue script to perform the
1513 request and format the result as YAML.
1514 · classifier (formerly console) --- Specific to Puppet Enterprise.
1516 Uses the PE console for node data."
1517 · Default: plain
1519 noop
1523 Whether to apply catalogs in noop mode, which allows Puppet to par‐
1524 tially simulate a normal run. This setting affects puppet agent and
1525 puppet apply.
1526 When running in noop mode, Puppet will check whether each resource is
1528 in sync, like it does when running normally. However, if a resource
1529 attribute is not in the desired state (as declared in the catalog),
1530 Puppet will take no action, and will instead report the changes it
1531 would have made. These simulated changes will appear in the report sent
1532 to the puppet master, or be shown on the console if running puppet
1533 agent or puppet apply in the foreground. The simulated changes will not
1534 send refresh events to any subscribing or notified resources, although
1535 Puppet will log that a refresh event would have been sent.
1536 Important note: The noop metaparameter https://puppet.com/docs/pup‐
1538 pet/latest/metaparameter.html#noop allows you to apply individual
1539 resources in noop mode, and will override the global value of the noop
1540 setting. This means a resource with noop => false will be changed if
1541 necessary, even when running puppet agent with noop = true or --noop.
1542 (Conversely, a resource with noop => true will only be simulated, even
1543 when noop mode is globally disabled.)
1544 · Default: false
1546 onetime
1550 Perform one configuration run and exit, rather than spawning a
1551 long-running daemon. This is useful for interactively running puppet
1552 agent, or running puppet agent from cron.
1553 · Default: false
1555 ordering
1559 How unrelated resources should be ordered when applying a catalog.
1560 Allowed values are title-hash, manifest, and random. This setting
1561 affects puppet agent and puppet apply, but not puppet master.
1562 · manifest (the default) will use the order in which the resources
1564 were declared in their manifest files.
1565 · title-hash (the default in 3.x) will order resources randomly, but
1567 will use the same order across runs and across nodes. It is only of
1568 value if you´re migrating from 3.x and have errors running with
1569 manifest.
1570 · random will order resources randomly and change their order with
1572 each run. This can work like a fuzzer for shaking out undeclared
1573 dependencies.
1574 Regardless of this setting´s value, Puppet will always obey explicit
1578 dependencies set with the before/require/notify/subscribe metaparame‐
1579 ters and the ->/~> chaining arrows; this setting only affects the rela‐
1580 tive ordering of unrelated resources.
1581 This setting is deprecated, and will always have a value of manifest in
1583 6.0 and up.
1584 · Default: manifest
1586 passfile
1590 Where puppet agent stores the password for its private key. Generally
1591 unused.
1592 · Default: $privatedir/password
1594 path
1598 The shell search path. Defaults to whatever is inherited from the par‐
1599 ent process.
1600 This setting can only be set in the [main] section of puppet.conf; it
1602 cannot be set in [master], [agent], or an environment config section.
1603 · Default: none
1605 pidfile
1609 The file containing the PID of a running process. This file is intended
1610 to be used by service management frameworks and monitoring systems to
1611 determine if a puppet process is still in the process table.
1612 · Default: $rundir/${run_mode}.pid
1614 plugindest
1618 Where Puppet should store plugins that it pulls down from the central
1619 server.
1620 · Default: $libdir
1622 pluginfactdest
1626 Where Puppet should store external facts that are being handled by plu‐
1627 ginsync
1628 · Default: $vardir/facts.d
1630 pluginfactsource
1634 Where to retrieve external facts for pluginsync
1635 · Default: puppet:///pluginfacts
1637 pluginsignore
1641 What files to ignore when pulling down plugins.
1642 · Default: .svn CVS .git .hg
1644 pluginsource
1648 From where to retrieve plugins. The standard Puppet file type is used
1649 for retrieval, so anything that is a valid file source can be used
1650 here.
1651 · Default: puppet:///plugins
1653 pluginsync
1657 Whether plugins should be synced with the central server. This setting
1658 is deprecated.
1659 · Default: true
1661 postrun_command
1665 A command to run after every agent run. If this command returns a
1666 non-zero return code, the entire Puppet run will be considered to have
1667 failed, even though it might have performed work during the normal run.
1668 preferred_serialization_format
1670 The preferred means of serializing ruby instances for passing over the
1671 wire. This won´t guarantee that all instances will be serialized using
1672 this method, since not all classes can be guaranteed to support this
1673 format, but it will be used for all classes that support it.
1674 · Default: json
1676 prerun_command
1680 A command to run before every agent run. If this command returns a
1681 non-zero return code, the entire Puppet run will fail.
1682 preview_outputdir
1684 The directory where catalog previews per node are generated.
1685 · Default: $vardir/preview
1687 priority
1691 The scheduling priority of the process. Valid values are ´high´, ´nor‐
1692 mal´, ´low´, or ´idle´, which are mapped to platform-specific values.
1693 The priority can also be specified as an integer value and will be
1694 passed as is, e.g. -5. Puppet must be running as a privileged user in
1695 order to increase scheduling priority.
1696 Default:
1698 privatedir
1701 Where the client stores private certificate information.
1702 · Default: $ssldir/private
1704 privatekeydir
1708 The private key directory.
1709 · Default: $ssldir/private_keys
1711 profile
1715 Whether to enable experimental performance profiling
1716 · Default: false
1718 publickeydir
1722 The public key directory.
1723 · Default: $ssldir/public_keys
1725 puppetdlog
1729 The fallback log file. This is only used when the --logdest option is
1730 not specified AND Puppet is running on an operating system where both
1731 the POSIX syslog service and the Windows Event Log are unavailable.
1732 (Currently, no supported operating systems match that description.)
1733 Despite the name, both puppet agent and puppet master will use this
1735 file as the fallback logging destination.
1736 For control over logging destinations, see the --logdest command line
1738 option in the manual pages for puppet master, puppet agent, and puppet
1739 apply. You can see man pages by running puppet <SUBCOMMAND> --help, or
1740 read them online at https://puppet.com/docs/puppet/latest/man/.
1741 · Default: $logdir/puppetd.log
1743 report
1747 Whether to send reports after every transaction.
1748 · Default: true
1750 report_port
1754 The port to communicate with the report_server.
1755 · Default: $masterport
1757 report_server
1761 The server to send transaction reports to.
1762 · Default: $server
1764 reportdir
1768 The directory in which to store reports. Each node gets a separate sub‐
1769 directory in this directory. This setting is only used when the store
1770 report processor is enabled (see the reports setting).
1771 · Default: $vardir/reports
1773 reports
1777 The list of report handlers to use. When using multiple report han‐
1778 dlers, their names should be comma-separated, with whitespace allowed.
1779 (For example, reports = http, store.)
1780 This setting is relevant to puppet master and puppet apply. The puppet
1782 master will call these report handlers with the reports it receives
1783 from agent nodes, and puppet apply will call them with its own report.
1784 (In all cases, the node applying the catalog must have report = true.)
1785 See the report reference for information on the built-in report han‐
1787 dlers; custom report handlers can also be loaded from modules. (Report
1788 handlers are loaded from the lib directory, at puppet/reports/NAME.rb.)
1789 · Default: store
1791 reporturl
1795 The URL that reports should be forwarded to. This setting is only used
1796 when the http report processor is enabled (see the reports setting).
1797 · Default: http://localhost:3000/reports/upload
1799 requestdir
1803 Where host certificate requests are stored.
1804 · Default: $ssldir/certificate_requests
1806 resourcefile
1810 The file in which puppet agent stores a list of the resources associ‐
1811 ated with the retrieved configuration.
1812 · Default: $statedir/resources.txt
1814 rest_authconfig
1818 The configuration file that defines the rights to the different rest
1819 indirections. This can be used as a fine-grained authorization system
1820 for puppet master. The puppet master command is deprecated and Puppet
1821 Server uses its own auth.conf that must be placed within its configura‐
1822 tion directory.
1823 · Default: $confdir/auth.conf
1825 rich_data
1829 Enables having extended data in the catalog by storing them as a hash
1830 with the special key __pcore_type__. When enabled, resource containing
1831 values of the data types Binary, Regexp, SemVer, SemVerRange, Timespan
1832 and Timestamp, as well as instances of types derived from Object retain
1833 their data type.
1834 · Default: false
1836 route_file
1840 The YAML file containing indirector route configuration.
1841 · Default: $confdir/routes.yaml
1843 rundir
1847 Where Puppet PID files are kept.
1848 · Default: Unix/Linux: /var/run/puppetlabs -- Windows: C:\Program‐
1850 Data\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppet‐
1851 labs/var/run
1852 runinterval
1856 How often puppet agent applies the catalog. Note that a runinterval of
1857 0 means "run continuously" rather than "never run." If you want puppet
1858 agent to never run, you should start it with the --no-client option.
1859 This setting can be a time interval in seconds (30 or 30s), minutes
1860 (30m), hours (6h), days (2d), or years (5y).
1861 · Default: 30m
1863 runtimeout
1867 The maximum amount of time an agent run is allowed to take. A Puppet
1868 agent run that exceeds this timeout will be aborted. Defaults to 0,
1869 which is unlimited. This setting can be a time interval in seconds (30
1870 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
1871 · Default: 0
1873 serial
1877 Where the serial number for certificates is stored.
1878 · Default: $cadir/serial
1880 server
1884 The puppet master server to which the puppet agent should connect.
1885 · Default: puppet
1887 server_datadir
1891 The directory in which serialized data is stored, usually in a subdi‐
1892 rectory.
1893 · Default: $vardir/server_data
1895 server_list
1899 The list of puppet master servers to which the puppet agent should con‐
1900 nect, in the order that they will be tried.
1901 · Default: []
1903 show_diff
1907 Whether to log and report a contextual diff when files are being
1908 replaced. This causes partial file contents to pass through Puppet´s
1909 normal logging and reporting system, so this setting should be used
1910 with caution if you are sending Puppet´s reports to an insecure desti‐
1911 nation. This feature currently requires the diff/lcs Ruby library.
1912 · Default: false
1914 signeddir
1918 Where the CA stores signed certificates.
1919 · Default: $cadir/signed
1921 skip_tags
1925 Tags to use to filter resources. If this is set, then only resources
1926 not tagged with the specified tags will be applied. Values must be
1927 comma-separated.
1928 sourceaddress
1930 The address the agent should use to initiate requests.
1931 Default:
1933 splay
1936 Whether to sleep for a random amount of time, ranging from immediately
1937 up to its $splaylimit, before performing its first agent run after a
1938 service restart. After this period, the agent runs periodically on its
1939 $runinterval.
1940 For example, assume a default 30-minute $runinterval, splay set to its
1942 default of false, and an agent starting at :00 past the hour. The agent
1943 would check in every 30 minutes at :01 and :31 past the hour.
1944 With splay enabled, it waits any amount of time up to its $splaylimit
1946 before its first run. For example, it might randomly wait 8 minutes,
1947 then start its first run at :08 past the hour. With the $runinterval at
1948 its default 30 minutes, its next run will be at :38 past the hour.
1949 If you restart an agent´s puppet service with splay enabled, it recal‐
1951 culates its splay period and delays its first agent run after restart‐
1952 ing for this new period. If you simultaneously restart a group of pup‐
1953 pet agents with splay enabled, their checkins to your puppet masters
1954 can be distributed more evenly.
1955 · Default: false
1957 splaylimit
1961 The maximum time to delay before an agent´s first run when splay is
1962 enabled. Defaults to the agent´s $runinterval. The splay interval is
1963 random and recalculated each time the agent is started or restarted.
1964 This setting can be a time interval in seconds (30 or 30s), minutes
1965 (30m), hours (6h), days (2d), or years (5y).
1966 · Default: $runinterval
1968 srv_domain
1972 The domain which will be queried to find the SRV records of servers to
1973 use.
1974 · Default: delivery.puppetlabs.net
1976 ssl_client_ca_auth
1980 Certificate authorities who issue server certificates. SSL servers will
1981 not be considered authentic unless they possess a certificate issued by
1982 an authority listed in this file. If this setting has no value then the
1983 Puppet master´s CA certificate (localcacert) will be used.
1984 Default:
1986 ssl_client_header
1989 The header containing an authenticated client´s SSL DN. This header
1990 must be set by the proxy to the authenticated client´s SSL DN (e.g.,
1991 /CN=puppet.puppetlabs.com). Puppet will parse out the Common Name (CN)
1992 from the Distinguished Name (DN) and use the value of the CN field for
1993 authorization.
1994 Note that the name of the HTTP header gets munged by the web server
1996 common gateway interface: an HTTP_ prefix is added, dashes are con‐
1997 verted to underscores, and all letters are uppercased. Thus, to use the
1998 X-Client-DN header, this setting should be HTTP_X_CLIENT_DN.
1999 · Default: HTTP_X_CLIENT_DN
2001 ssl_client_verify_header
2005 The header containing the status message of the client verification.
2006 This header must be set by the proxy to ´SUCCESS´ if the client suc‐
2007 cessfully authenticated, and anything else otherwise.
2008 Note that the name of the HTTP header gets munged by the web server
2010 common gateway interface: an HTTP_ prefix is added, dashes are con‐
2011 verted to underscores, and all letters are uppercased. Thus, to use the
2012 X-Client-Verify header, this setting should be HTTP_X_CLIENT_VERIFY.
2013 · Default: HTTP_X_CLIENT_VERIFY
2015 ssl_server_ca_auth
2019 Certificate authorities who issue client certificates. SSL clients will
2020 not be considered authentic unless they possess a certificate issued by
2021 an authority listed in this file. If this setting has no value then the
2022 Puppet master´s CA certificate (localcacert) will be used.
2023 Default:
2025 ssldir
2028 Where SSL certificates are kept.
2029 · Default: $confdir/ssl
2031 statedir
2035 The directory where Puppet state is stored. Generally, this directory
2036 can be removed without causing harm (although it might result in spuri‐
2037 ous service restarts).
2038 · Default: $vardir/state
2040 statefile
2044 Where puppet agent and puppet master store state associated with the
2045 running configuration. In the case of puppet master, this file reflects
2046 the state discovered through interacting with clients.
2047 · Default: $statedir/state.yaml
2049 statettl
2053 How long the Puppet agent should cache when a resource was last checked
2054 or synced. This setting can be a time interval in seconds (30 or 30s),
2055 minutes (30m), hours (6h), days (2d), or years (5y). A value of 0 or
2056 unlimited will disable cache pruning.
2057 This setting affects the usage of schedule resources, as the informa‐
2059 tion about when a resource was last checked (and therefore when it
2060 needs to be checked again) is stored in the statefile. The statettl
2061 needs to be large enough to ensure that a resource will not trigger
2062 multiple times during a schedule due to its entry expiring from the
2063 cache.
2064 · Default: 32d
2066 static_catalogs
2070 Whether to compile a static catalog https://puppet.com/docs/puppet/lat‐
2071 est/static_catalogs.html#enabling-or-disabling-static-catalogs, which
2072 occurs only on a Puppet Server master when the code-id-command and
2073 code-content-command settings are configured in its puppetserver.conf
2074 file.
2075 · Default: true
2077 storeconfigs
2081 Whether to store each client´s configuration, including catalogs,
2082 facts, and related data. This also enables the import and export of
2083 resources in the Puppet language - a mechanism for exchange resources
2084 between nodes.
2085 By default this uses the ´puppetdb´ backend.
2087 You can adjust the backend using the storeconfigs_backend setting.
2089 · Default: false
2091 storeconfigs_backend
2095 Configure the backend terminus used for StoreConfigs. By default, this
2096 uses the PuppetDB store, which must be installed and configured before
2097 turning on StoreConfigs.
2098 · Default: puppetdb
2100 strict
2104 The strictness level of puppet. Allowed values are:
2105 · off - do not perform extra validation, do not report
2107 · warning - perform extra validation, report as warning (default)
2109 · error - perform extra validation, fail with error
2111 The strictness level is for both language semantics and runtime evalua‐
2115 tion validation. In addition to controlling the behavior with this mas‐
2116 ter switch some individual warnings may also be controlled by the dis‐
2117 able_warnings setting.
2118 No new validations will be added to a micro (x.y.z) release, but may be
2120 added in minor releases (x.y.0). In major releases it expected that
2121 most (if not all) strictness validation become standard behavior.
2122 · Default: warning
2124 strict_environment_mode
2128 Whether the agent specified environment should be considered authorita‐
2129 tive, causing the run to fail if the retrieved catalog does not match
2130 it.
2131 · Default: false
2133 strict_hostname_checking
2137 Whether to only search for the complete hostname as it is in the cer‐
2138 tificate when searching for node information in the catalogs.
2139 · Default: false
2141 strict_variables
2145 Causes an evaluation error when referencing unknown variables. (This
2146 does not affect referencing variables that are explicitly set to
2147 undef).
2148 · Default: false
2150 summarize
2154 Whether to print a transaction summary.
2155 · Default: false
2157 supported_checksum_types
2161 Checksum types supported by this agent for use in file resources of a
2162 static catalog. Values must be comma-separated. Valid types are md5,
2163 md5lite, sha256, sha256lite, sha384, sha512, sha224, sha1, sha1lite,
2164 mtime, ctime. Default is md5, sha256, sha384, sha512, sha224.
2165 · Default: ["md5", "sha256", "sha384", "sha512", "sha224"]
2167 syslogfacility
2171 What syslog facility to use when logging to syslog. Syslog has a fixed
2172 list of valid facilities, and you must choose one of those; you cannot
2173 just make one up.
2174 · Default: daemon
2176 tags
2180 Tags to use to find resources. If this is set, then only resources
2181 tagged with the specified tags will be applied. Values must be
2182 comma-separated.
2183 tasks
2185 Turns on experimental support for tasks and plans in the puppet lan‐
2186 guage. This is for internal API use only. Do not change this setting.
2187 · Default: false
2189 trace
2193 Whether to print stack traces on some errors
2194 · Default: false
2196 transactionstorefile
2200 Transactional storage file for persisting data between transactions for
2201 the purposes of infering information (such as corrective_change) on new
2202 data received.
2203 · Default: $statedir/transactionstore.yaml
2205 trusted_oid_mapping_file
2209 File that provides mapping between custom SSL oids and user-friendly
2210 names
2211 · Default: $confdir/custom_trusted_oid_mapping.yaml
2213 trusted_server_facts
2217 The ´trusted_server_facts´ setting is deprecated and has no effect as
2218 the feature this enabled is now always on. The setting will be removed
2219 in a future version of puppet.
2220 · Default: true
2222 use_cached_catalog
2226 Whether to only use the cached catalog rather than compiling a new cat‐
2227 alog on every run. Puppet can be run with this enabled by default and
2228 then selectively disabled when a recompile is desired. Because a Puppet
2229 agent using cached catalogs does not contact the master for a new cata‐
2230 log, it also does not upload facts at the beginning of the Puppet run.
2231 · Default: false
2233 use_srv_records
2237 Whether the server will search for SRV records in DNS for the current
2238 domain.
2239 · Default: false
2241 usecacheonfailure
2245 Whether to use the cached configuration when the remote configuration
2246 will not compile. This option is useful for testing new configurations,
2247 where you want to fix the broken configuration rather than reverting to
2248 a known-good one.
2249 · Default: true
2251 user
2255 The user Puppet Server will run as. Used to ensure the agent side pro‐
2256 cesses (agent, apply, etc) create files and directories readable by
2257 Puppet Server when necessary.
2258 · Default: puppet
2260 vardir
2264 Where Puppet stores dynamic and growing data. The default for this set‐
2265 ting is calculated specially, like confdir_.
2266 · Default: Unix/Linux: /opt/puppetlabs/puppet/cache -- Windows:
2268 C:\ProgramData\PuppetLabs\puppet\cache -- Non-root user: ~/.puppet‐
2269 labs/opt/puppet/cache
2270 waitforcert
2274 How frequently puppet agent should ask for a signed certificate.
2275 When starting for the first time, puppet agent will submit a certifi‐
2277 cate signing request (CSR) to the server named in the ca_server setting
2278 (usually the puppet master); this may be autosigned, or may need to be
2279 approved by a human, depending on the CA server´s configuration.
2280 Puppet agent cannot apply configurations until its approved certificate
2282 is available. Since the certificate may or may not be available immedi‐
2283 ately, puppet agent will repeatedly try to fetch it at this interval.
2284 You can turn off waiting for certificates by specifying a time of 0, in
2285 which case puppet agent will exit if it cannot get a cert. This setting
2286 can be a time interval in seconds (30 or 30s), minutes (30m), hours
2287 (6h), days (2d), or years (5y).
2288 · Default: 2m
2290 yamldir
2294 The directory in which YAML data is stored, usually in a subdirectory.
2295 · Default: $vardir/yaml
2297Puppet, Inc. January 2019 PUPPETCONF(5)