puppet.conf: The main config file

The puppet.conf file is Puppet’s main config file. It configures all of the Puppet commands and services, including Puppet agent, the primary Puppet server, Puppet apply, and puppetserver ca. Nearly all of the settings listed in the configuration reference can be set in puppet.conf.

It resembles a standard INI file, with a few syntax extensions. Settings can go into application-specific sections, or into a [main] section that affects all applications.

For a complete list of Puppet's settings, see the configuration reference.

Location

The puppet.conf file is always located at $confdir/puppet.conf.

Although its location is configurable with the config setting, it can be set only on the command line. For example: 
puppet agent -t --config ./temporary_config.conf

The location of the confdir depends on your operating system. See the confdir documentation for details.

Examples

Example agent config: 
[main]
certname = agent01.example.com
server = puppet
runinterval = 1h
Example server config: 
[main]
certname = puppetserver01.example.com
server = puppet
runinterval = 1h
strict_variables = true

[server]
dns_alt_names = primaryserver01,primaryserver01.example.com,puppet,puppet.example.com
reports = puppetdb
storeconfigs_backend = puppetdb
storeconfigs = true

Format

The puppet.conf file consists of one or more config sections, each of which can contain any number of settings.

The file can also include comment lines at any point.

Config sections

[main]
    certname = primaryserver01.example.com
A config section is a group of settings. It consists of:

  • Its name, enclosed in square brackets. The [name] of the config section must be on its own line, with no leading space.

  • Any number of setting lines, which can be indented for readability.

  • Any number of empty lines or comment lines

As soon as a new config section [name] appears in the file, the former config section is closed and the new one begins. A given config section only occurs one time in the file.

Puppet uses four config sections:

  • main is the global section used by all commands and services. It can be overridden by the other sections.

  • server is used by the primary Puppet server service and the Puppet Server ca command.

    Important: Be sure to apply settings only in main unless there is a specific case where you have to override a setting for the server run mode. For example, when Puppet Server is configured to use an external node classifier, you must add these settings to the server section. If those settings are added to main, then the agent tries and fails to run the server-only script /usr/local/bin/puppet_node_classifier during its run.

  • agent is used by the Puppet agent service.

  • user is used by the Puppet apply command, as well as many of the less common Puppet subcommands

Puppet prefers to use settings from one of the three application-specific sections (server, agent, or user). If it doesn’t find a setting in the application section, it uses the value from main. (If main doesn’t set one, it falls back to the default value.)
Note: Puppet Server ignores some config settings. It honors almost all settings in puppet.conf and picks them up automatically. However, some Puppet Server settings differ from a Ruby primary server's puppet.conf settings.

Comment lines

# This is a comment.
Comment lines start with a hash sign (#). They can be indented with any amount of leading space.

Partial-line comments such as report = true # this enables reporting are not allowed, and the intended comment is treated as part of the value of the setting. To be treated as a comment, the hash sign must be the first non-space character on the line.

Setting lines

certname = primaryserver01.example.com
A setting line consists of:

  • Any amount of leading space (optional).

  • The name of a setting.

  • An equals sign (=), which can optionally be surrounded by any number of spaces.

  • A value for the setting.

Special types of values for settings

Generally, the value of a setting is a single word. However, listed below are a few special types of values.

List of words: Some settings (like reports) can accept multiple values, which are specified as a comma-separated list (with optional spaces after commas). Example: report = http,puppetdb

Paths: Some settings (like environmentpath) take a list of directories. The directories are separated by the system path separator character, which is colon (:) on *nix platforms and semicolon (;) on Windows. 
# *nix version:
environmentpath = $codedir/special_environments:$codedir/environments
# Windows version:
environmentpath = $codedir/environments;C:\ProgramData\PuppetLabs\code\environment
Path lists are ordered;Puppet always checks the first directory first, then moves on to the others if it doesn’t find what it needs.

Files or directories: Settings that take a single file or directory (like ssldir) can accept an optional hash of permissions. When starting up, Puppet enforces those permissions on the file or directory.

We do not recommend you do this because the defaults are good for most users. However, if you need to, you can specify permissions by putting a hash like this after the path: 
ssldir = $vardir/ssl {owner = service, mode = 0771}
The allowed keys in the hash areowner, group, and mode. There are only two valid values for the owner and group keys:

  • root — the root or Administrator user or group owns the file.

  • service — the user or group that the Puppet service is running as owns the file. The service’s user and group are specified by the user and group settings. On a primary server running open source Puppet, these default to puppet; on Puppet Enterprise they default to pe-puppet.

Interpolating variables in settings

The values of settings are available as variables within puppet.conf, and you can insert them into the values of other settings. To reference a setting as a variable, prefix its name with a dollar sign ($): 
ssldir = $vardir/ssl
Not all settings are equally useful; there’s no real point in interpolating$ssldir into basemodulepath, for example. We recommend that you use only the following variables:

  • $codedir

  • $confdir

  • $vardir