Key configuration settings

Puppet has about 200 settings, all of which are listed in the configuration reference. Most of the time, you interact with only a couple dozen of them. This page lists the most important ones, assuming that you're okay with default values for things like the port Puppet uses for network traffic. See the configuration reference for more details on each.

There are a lot of settings that are rarely useful but still make sense, but there are also at least a hundred that are not configurable at all. This is a Puppet design choice. Because of the way Puppet code is arranged, the settings system is the easiest way to publish global constants that are dynamically initialized on startup. This means a lot of things have been introduced to Puppet as configurable settings regardless of whether they needed to be configurable.

For a full list of Puppet settings, see the configuration reference.

Settings for agents (all nodes)

The following settings for agents are listed approximately in order of importance. Most of these can go in either [main] or [agent] sections, or be specified on the command line.

Basics

  • server — The primary server to request configurations from. Defaults to puppet. Change it if that’s not your server’s name.

    • ca_server and report_server — If you’re using multiple Puppet primary servers, you’ll need to centralize the CA. One of the ways to do this is by configuring ca_server on all agents. See Scaling Puppet Server with compile servers for more details. The report_server setting works the same way, although whether you need to use it depends on how you’re processing reports.

  • certname — The node’s certificate name, and the unique identifier it uses when requesting catalogs. Defaults to the fully qualified domain name.

    • For best compatibility, limit the value of certname to only use lowercase letters, numbers, periods, underscores, and dashes. That is, it matches /\A[a-z0-9._-]+\Z/.

    • The special value ca is reserved, and can’t be used as the certname for a normal node.

  • environment — The environment to request when contacting the primary server. It’s only a request, though; the primary server’s ENC can override this if it chooses. Defaults to production.

  • sourceaddress — The address on a multihomed host to use for the agent’s communication with the primary server.

Note: Although it’s possible to set something other than the certname as the node name (using either the node_name_fact or node_name_value setting), we don’t generally recommend it. It allows you to re-use one node certificate for many nodes, but it reduces security, makes it harder to reliably identify nodes, and can interfere with other features. Setting a non-certname node name is not officially supported in Puppet Enterprise.

Run behavior

These settings affect the way Puppet applies catalogs:

  • noop — If enabled, the agent won’t make any changes to the node. Instead, it looks for changes that would be made if the catalog were applied, and report to the primary server about what it would have done. This can be overridden per-resource with the noop metaparameter.

  • priority — Allows you to make the agent share CPU resources so that other applications have access to processing power while agent is applying a catalog.

  • report — Indicates whether to send reports. Defaults to true.

  • tags — Lets you limit the Puppet run to include only those resources with certain tags.

  • trace, profile, graph, and show_diff — Tools for debugging or learning more about an agent run. Useful when combined with the --test and --debug command options.

  • usecacheonfailure — Indicates whether to fall back to the last known good catalog if the primary server fails to return a good catalog. The default behavior is usually what you want, but you might have a reason to disable it.

  • ignoreschedules — If you use schedules, this can be useful when doing an initial Puppet run to set up new nodes.

  • prerun_command and postrun_command — Commands to run on either side of a Puppet run.

  • ignore_plugin_errors — If set to false, the agent aborts the run if pluginsync fails. Defaults to true.

Service behavior

These settings affect the way Puppet agent acts when running as a long-lived service:

  • runinterval — How often to do a Puppet run, when running as a service.

  • waitforcert — Whether to keep trying if the agent can’t initially get a certificate. The default behavior is good, but you might have a reason to disable it.

Useful when running agent from cron

  • splay and splaylimit — Together, these allow you to spread out agent runs. When running the agent as a daemon, the services usually have been started far enough out of sync to make this a non-issue, but it’s useful with cron agents. For example, if your agent cron job happens on the hour, you could set splay = true and splaylimit = 60m to keep the primary server from getting briefly overworked and then left idle for the next 50 minutes.

  • daemonize — Whether to daemonize. Set this to false when running the agent from cron.

  • onetime — Whether to exit after finishing the current Puppet run. Set this to true when running the agent from cron.

For more information on these settings, see the configuration reference.

Settings for primary servers

Many of these settings are also important for standalone Puppet apply nodes, because they act as their own primary server. These settings go in the [server] section, unless you’re using Puppet apply in production, in which case put them in the [main] section instead.

Basics

  • dns_alt_names — A list of hostnames the server is allowed to use when acting as a primary server. The hostname your agents use in their server setting must be included in either this setting or the primary server’s certname setting. Note that this setting is only used when initially generating the primary server’s certificate — if you need to change the DNS names, you must:

    1. Run: sudo puppetserver ca clean --certname <SERVER'S CERTNAME>

    2. Turn off the Puppet Server service.

    3. Run: sudo puppetserver ca generate --certname <SERVER'S CERTNAME> --subject-alt-names <ALT NAME 1>,<ALT NAME 2>,...

    4. Re-start the Puppet Server service.

  • environment_timeout — For better performance, you can set this to unlimited and make refreshing the primary server a part of your standard code deployment process.

  • environmentpath — Controls where Puppet finds directory environments. For more information on environments, see Creating environments.

  • basemodulepath — A list of directories containing Puppet modules that can be used in all environments. See modulepath for details.

  • reports — Which report handlers to use. For a list of available report handlers, see the report reference. You can also write your own report handlers. Note that the report handlers might require settings of their own.

  • digest_algorithm — To accept requests from older agents when using a remote filebucket, Puppet Server needs to specify digest_algorithm=md5.

Extensions

These features configure add-ons and optional features:

  • node_terminus and external_nodes — The ENC settings. If you’re using an ENC, set these to exec and the path to your ENC script, respectively.

  • storeconfigs and storeconfigs_backend — Used for setting up PuppetDB. See the PuppetDB docs for details.

  • catalog_terminus — This can enable the optional static compiler. If you have lots of file resources in your manifests, the static compiler lets you sacrifice some extra CPU work on your primary server to gain faster configuration and reduced HTTPS traffic on your agents. See the indirection reference for details.

CA settings

  • ca_ttl — How long newly signed certificates are valid. Deprecated.

  • autosign — Whether and how to autosign certificates. See Autosigning for detailed information.

For more information on these settings, see the configuration reference.