Configuration: Short list of important settings

Puppet has about 200 settings, all of which are listed in the configuration reference. Most users can ignore about 170 of those.

This page lists the most important ones. (We assume here that you’re okay with default values for things like the port Puppet uses for network traffic.) The link for each setting will go to the long description in the configuration reference.

Why so many settings? There are a lot of settings that are rarely useful but still make sense, but there are also at least a hundred that shouldn’t be configurable at all.

This is basically a historical accident. Due to the way Puppet’s code is arranged, the settings system was always the easiest way to publish global constants that are dynamically initialized on startup. This means a lot of things have crept in there regardless of whether they needed to be configurable.

Settings for agents (all nodes)

Roughly in order of importance. Most of these can go in either [main] or [agent], or be specified on the command line.

Basics

  • server — The Puppet master 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 masters, you’ll need to centralize the CA; one of the ways to do this is by configuring ca_server on all agents. See the multiple masters guide for more details. The report_server setting works about 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, you should limit the value of certname to only use letters, numbers, periods, underscores, and dashes. (That is, it should match /\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 Puppet master. It’s only a request, though; the master’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 master server.

Note on Non-Certname Node Names

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 do any work; instead, it will look for changes that should be made, then report to the master about what it would have done. This can be overridden per-resource with the noop metaparameter.
  • priority — Allows you to “nice” Puppet agent so it won’t starve other applications of CPU resources while it’s applying a catalog.
  • report — Whether to send reports. Defaults to true; usually shouldn’t be disabled, but you might have a reason.
  • tags — Lets you limit the Puppet run to only include resources with certain tags.
  • trace, profile, graph, and show_diff — Tools for debugging or learning more about an agent run. Extra-useful when combined with the --test and --debug CLI options.
  • usecacheonfailure — Whether to fall back to the last known good catalog if the master fails to return a good catalog. The default behavior is good, 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.

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 back 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 will 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 master from getting briefly hammered 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.

Settings for Puppet master servers

Many of these settings are also important for standalone Puppet apply nodes, since they act as their own Puppet master.

These settings should usually go in [master]. However, if you’re using Puppet apply in production, put them in [main] instead.

Basics

  • dns_alt_names — A list of hostnames the server is allowed to use when acting as a Puppet master. The hostname your agents use in their server setting must be included in either this setting or the master’s certname setting. Note that this setting is only used when initially generating the Puppet master’s certificate — if you need to change the DNS names, you must:
    1. Turn off the Puppet server service (or your Rack server).
    2. Run sudo puppet cert clean <MASTER'S CERTNAME>.
    3. Run sudo puppet cert generate <MASTER'S CERTNAME> --dns_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 Puppet master a part of your standard code deployment process. See the timeout section of the Configuring Environments page for more details.
  • environmentpath — Controls where Puppet finds directory environments. See the page on directory environments for details.
  • basemodulepath — A list of directories containing Puppet modules that can be used in all environments. See the modulepath page 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.

Puppet Server has its own configuration files; consequently, there are several settings in puppet.conf that Puppet Server ignores.

  • puppet-admin — Settings to control which authorized clients can use the admin interface.
  • jruby-puppet — Provides details on tuning JRuby for better performance.
  • JAVA_ARGS — Instructions on tuning the Puppet Server memory allocation.
  • ssl_client_header and ssl_client_verify_header — These are used when running Puppet master as a Rack application, a method deprecated in favor of running Puppet Server. See the Passenger setup guide for more context about how these settings work; depending on how you configure your Rack server, you can usually leave these settings with their default values.
  • always_retry_plugins — If this setting is set to false, then types and features will only be checked once, and if they are not available, the negative result is cached and returned for all subsequent attempts to load the type or feature. This replaces the always_cache_features setting.

Extensions

These features configure add-ons and optional features.

CA settings

  • ca — Whether to act as a CA. There should only be one CA at a Puppet deployment. If you’re using multiple Puppet masters, you’ll need to set ca = false on all but one of them.

    Note that the ca setting is not valid for Puppet Server. Refer to these sections about the Puppet Server ca and service bootstrapping.

  • ca_ttl — How long newly signed certificates should be valid for.
  • autosign — Whether (and how) to autosign certificates. See the autosigning page for details.