Configure Puppet Server

If needed, you can configure Puppet Server settings to optimize your Puppet Enterprise (PE) installation.

Set the Ruby load path

The ruby_load_path setting determines where Puppet Server finds components such as Puppet and Facter.

The default setting is:
$puppetserver_jruby_puppet_ruby_load_path = [ \
'/opt/puppetlabs/puppet/lib/ruby/vendor_ruby', \
'/opt/puppetlabs/puppet/cache/lib']
Important: If you change the libdir you must also change the vardir.

You can change the load path array in pe.conf.

  1. On your primary server, open the pe.conf file in a text editor.
  2. Add the following parameter and specify the new load path array: 
    puppet_enterprise::master::puppetserver::puppetserver_jruby_puppet_ruby_load_path:  \
['<PATH1>', '<PATH2>']
  3. Save the file and run: puppet agent -t

Enable JRuby multithreading

The jruby_puppet_multithreaded setting enables multithreaded mode, which uses a single JRuby instance to process requests (such as catalog compiles) concurrently.

By default, multithreading is disabled (set to false).

CAUTION: Multithreaded mode is an experimental feature which might experience breaking changes in future releases. Test this feature in a non-production environment before enabling it in production.

You can use Hiera to toggle multithreaded mode.

  1. Open your default Hiera .yaml file in a text editor.
    Tip: For information about Hiera data files, including file paths, refer to Configure settings with Hiera.
  2. Add the jruby_puppet_multithreaded parameter, and set it to either true (enabled) or false (disabled). For example: 
    puppet_enterprise::master::puppetserver::jruby_puppet_multithreaded: true
  3. Save the file and run puppet agent -t to compile the changes.

Use cached data when updating classes

The environment_class_cache_enabled setting specifies whether cached data is used when updating classes in the Puppet Enterprise (PE) console. When true, Puppet Server uses file sync when refreshing classes, which provides improved performance.

The default value for environment_class_cache_enabled depends on whether you use Code Manager:

  • Without Code Manager, the default value is false (disabled).
  • With Code Manager, the default value is true (enabled).
When enabled, file sync automatically clears the environment cache in the background. This means you don't have to manually clear the environment cache if you're using Code Manager.
Important: If you're not using Code Manager and you set environment_class_cache_enabled to true, you must make sure your chosen code deployment method (such as r10k) clears the environment cache when it completes code deployments. If the environment cache isn't cleared, the Node Classifier service doesn't receive new class information until the Puppet Server service is restarted.

You can use Hiera to toggle the environment_class_cache_enabled setting.

  1. Open your default Hiera .yaml file in a text editor.
    Tip: For information about Hiera data files, including file paths, refer to Configure settings with Hiera.
  2. Add the jruby_environment_class_cache_enabled parameter, and set it to either true (enabled) or false (disabled). For example: 
    puppet_enterprise::master::puppetserver::jruby_environment_class_cache_enabled: true
  3. Save the file and run puppet agent -t to compile the changes.

Change the environment_timeout setting

The environment_timeout setting controls if and how long the primary server caches environment data. Environment caching can reduce your Puppet Server's CPU usage, but longer cache times extend the amount of time it takes for environments to reflect changes to their Puppet code.

The environment_timeout parameter accepts these values:
  • No caching: 0
  • Retain environment data caches indefinitely: unlimited
  • Cache environments for a specified length of time after their last use: Any length of time, such as 5m

By default, environment_timeout is set to 0. When you Enable Code Manager, environment_timeout is set to 5m. However, if you set code_manager_auto_configure to true in your Code Manager settings, then environment_timeout is automatically set to unlimited.

Tip: Setting environment_timeout to 0 taxes your primary server's performance but makes it easy for new users to deploy updated Puppet code. Once your code deployment process is mature (or after enabling Code Manager), we recommend changing this setting to unlimited.

Refer to the Puppet documentation for more information About environments, including Environment limitations, such as leakage and resource conflicts.

The following steps explain how to change the environment_timeout setting in pe.conf. You can also change this setting in the PE console in the PE Master node group. For instructions on changing settings in the console, refer to Configure settings in the PE console.

  1. On your primary server, open the pe.conf file in a text editor.
  2. Add the environment_timeout parameter and the desired value. For example: 
    puppet_enterprise::master::environment_timeout: 0
  3. Save the file and run: puppet agent -t

Populate the puppet-admin certificate allowlist

Use pe.conf to add trusted certificates to the puppet-admin certificate allowlist.

  1. On your primary server, open the pe.conf file in a text editor.
  2. Add the puppet_admin_certs parameter and string-formatted certnames to the pe.conf file. For example: 
    puppet_enterprise::master::puppetserver::puppet_admin_certs:'<CERTIFICATE_NAME>'
  3. Save the file and run: puppet agent -t

Disable software update monitoring

The Puppet Server (pe-puppetserver) service checks for updates when it starts, restarts, and every 24 hours while running. You can disable these automatic software update checks.

To check if a software update is available, the pe-puppetserver service sends the following basic, anonymous information to our servers at Puppet by Perforce:
  • Product name
  • Puppet Server version
  • IP address
  • Data collection timestamp

You can turn off automatic software update monitoring in the Puppet Enterprise (PE) console.

  1. In the PE console, go to Node groups and select the PE Master node group.
  2. On the Classes tab, find the puppet_enterprise::profile::master class.
  3. Add the check_for_updates parameter and change the value to false.
  4. Click Add parameter and commit changes.
  5. On the nodes that host your primary server and console, run Puppet.
    Tip: There are several ways to Run Puppet on demand.

Puppet Server configuration files

At startup, Puppet Server reads all .conf files in the conf.d directory, which is located at /etc/puppetlabs/puppetserver/conf.d.

The conf.d directory contains these files:

File name Description
auth.conf Contains authentication rules and settings for agents and API endpoint access.

You can learn more about auth.conf in the Puppet documentation.
global.conf Contains global configuration settings for Puppet Server, including logging settings.

You can learn more about global.conf in the Puppet documentation.
metrics.conf Contains settings for Puppet Server metrics services.

You can learn more about metrics.conf in the Puppet documentation.
pe-puppet-server.conf Contains Puppet Server settings specific to Puppet Enterprise.

Refer to pe-puppet-server.conf settings for details about each setting.
webserver.conf Contains SSL service configuration settings.

You can learn more about webserver.conf in the Puppet documentation.
ca.conf Deprecated. Contained rules for Certificate Authority services, but has been superseded by webserver.conf and auth.conf.

Additional files, such as code-manager.conf might exist depending on how you use PE.

pe-puppet-server.conf settings

The pe-puppet-server.conf file contains Puppet Server settings specific to Puppet Enterprise. All the settings are wrapped in a jruby-puppet section.

enable-file-sync-locking or file_sync::file_sync_locking_enabled
Controls whether the file sync client locks the JRuby pool (and, by extension, most requests to Puppet Server) while deploying Puppet code.
Default: true
CAUTION: We do not recommend changing the enable-file-sync-locking setting. Instead, enable Lockless code deploys, which allow the file sync client to update code into versioned code directories without blocking Puppet Server requests or overwriting the live code directory.
gem-home
Determines where JRuby looks for gems. This is also used by the puppetserver gem command line tool.
Default: '/opt/puppetlabs/puppet/cache/jruby-gems'
jruby_max_active_instances
Controls the maximum number of JRuby instances to allow on the Puppet Server.
Default: 4
For more information, refer to JRuby max active instances.
max_requests_per_instance
Sets the maximum number of requests allowed for each JRuby interpretor instance before it is killed.
Default: 100000
For more information, refer to JRuby max requests per instance.
max-queued-requests
Sets the maximum number of requests allowed to be queued waiting to borrow from the JRuby pool.
This setting is optional and defaults to 0 (unlimited). If changed, you must specify a positive integer.
After reaching the limit, all new requests receive a 503 Service Unavailable response until the queue drops below the limit. If the max-retry-delay setting is also set to a positive integer, then the 503 response includes a random sleep time after which the client can retry the request.
Don't use this setting if your managed infrastructure includes multiple agents older than Puppet 5.3. Because older agents treat 503 responses as failures, a thundering herd problem occurs when the agents schedule their next runs at the same time.
max-retry-delay
Sets the maximum number of seconds allowed for the random sleep time set when the max-queued-requests limit is exceeded. The random sleep time is returned as a Retry-After header on the 503 response for each rejected request.
Default: 1800 seconds
If max-queued-requests is 0, there is no limit to the number of queued requests and, therefore, the max-retry-delay is irrelevant.
pre-commit-hook-commands or puppetserver::pre_commit_hook_commands
Specify scripts, as an array of strings, that you want the file sync storage server to execute against a repo after receiving a change but before committing and syncing the change across compilers. This is similar to Configuring post-deployment commands for r10k or Configuring post-environment hooks for Code Manager.
The pe-puppetserver process, acting as the pe-puppet user, executes the scripts in the order supplied. You must supply scripts as absolute paths. Additionally, the pe-puppet user must be able to execute the scripts, and the scripts must be able to consume stdin (even if the script doesn't do anything with it).
Default: ["/opt/puppetlabs/server/bin/generate-puppet-types.rb"]
CAUTION: Removing the default value disables the generate-puppet-types.rb script. Unless you intentionally want to disable this type generation method, make sure to keep the default path in the array.
The output, error, and exit code for these scripts are logged at the trace level of pe-puppetserver logs when the exit code is 0. If the exit code is not 0, the codes are logged at the error level.
This setting is managed in PE modules, and you can override it by setting the puppet_enterprise::master::puppetserver::pre_commit_hook_commands parameter in Hiera. Make sure to include the default path (for generate-puppet-types.rb) to ensure custom type are correctly cached. If you want to disable all pre-commit commands, supply an empty array in Hiera.
puppet-code-repo
Identifies, as a string, the internal name for the Puppet code repo (the codedir) that contains all code to sync across compilers (including user-supplied code repos).
CAUTION: Do not change this setting.
Default: 'puppet-code'
ruby-load-path or puppetserver_jruby_puppet_ruby_load_path
Determines where Puppet Server finds components such as Puppet and Facter. The agent's libdir path is included by default.
Default: ['/opt/puppetlabs/puppet/lib/ruby/vendor_ruby', '/opt/puppetlabs/puppet/cache/lib']
For more information, refer to Set the Ruby load path.
server-conf-dir
Sets the Puppet configuration directory path.
Default: '/etc/puppetlabs/puppet'
server-var-dir
Sets the Puppet Server variable directory path.
Default: '/opt/puppetlabs/server/data/puppetserver'