puppetserver.conf

The puppetserver.conf file contains settings for the Puppet Server application. For an overview, see Puppet Server Configuration.

Settings

Note: Under most conditions, you won't change the default settings for server-conf-dir or server-code-dir. However, if you do, also change the equivalent Puppet settings (confdir or codedir) to ensure that commands like puppetserver ca and puppet module use the same directories as Puppet Server. You must also specify the non-default confdir when running commands, because that setting must be set before Puppet tries to find its config file.

The jruby-puppet settings configure the interpreter.

Deprecation Note: Puppet Server 5.0 removed the compat-version setting, which is incompatible with JRuby 1.7.27, and the service won't start if compat-version is set. Puppet Server 6.0 uses JRuby 9.1 which supports Ruby 2.3.
- ruby-load-path: The location where Puppet Server expects to find Puppet, Facter, and other components.
- gem-home: The location where JRuby looks for gems. It is also used by the puppetserver gem command line tool. If nothing is specified, JRuby uses the Puppet default:
- /opt/puppetlabs/server/data/puppetserver/jruby-gems
- gem-path: The complete "GEM_PATH" for jruby. If set, it should include the gem-home directory, as well as any other directories that gems can be loaded from (including the vendored gems directory for gems that ship with puppetserver). The default value is: ["/opt/puppetlabs/server/data/puppetserver/jruby-gems", "/opt/puppetlabs/server/data/puppetserver/vendored-jruby-gems", "/opt/puppetlabs/puppet/lib/ruby/vendor_gems"]
- instance-creation-concurrency: Optional. Specifies the number of JRuby instances that are created concurrently when Puppet Server is started. The default value is 3, which means that a single JRuby instance is created when Puppet Server is started, and then additional instances are created up to three at a time. Concurrent creation helps to accelerate the Puppet Server startup process. You can set a value of 1 to revert to the previous behavior of creating one JRuby instance at a time. Valid values are 1 up to the max-active-instances value minus 1.
- environment-vars: Optional. A map of environment variables which are made visible to Ruby code running within JRuby, for example, via the Ruby ENV class.
  
  By default, the only environment variables whose values are set into JRuby from the shell are HOME and PATH.
  
  The default value for the GEM_HOME environment variable in JRuby is set from the value provided for the jruby-puppet.gem-home key.
  
  Any variable set from the map for the environment-vars key overrides these defaults. Avoid overriding HOME, PATH, or GEM_HOME here because these values are already configurable via the shell or jruby-puppet.gem-home.
- server-conf-dir: Optional. The path to the Puppet configuration directory. The default is /etc/puppetlabs/puppet.
- server-code-dir: Optional. The path to the Puppet code directory. The default is /etc/puppetlabs/code.
- server-var-dir: Optional. The path to the Puppet cache directory. The default is /opt/puppetlabs/server/data/puppetserver.
- server-run-dir: Optional. The path to the run directory, where the service's PID file is stored. The default is /var/run/puppetlabs/puppetserver.
- server-log-dir: Optional. The path to the log directory. If nothing is specified, it uses the Puppet default /var/log/puppetlabs/puppetserver.
- max-active-instances: Optional. The maximum number of JRuby instances allowed. The default is 'num-cpus - 1', with a minimum value of 1 and a maximum value of 4. In multithreaded mode, this controls the number of threads allowed to run concurrently through the single JRuby instance.
- max-requests-per-instance: Optional. The number of HTTP requests a given JRuby instance will handle in its lifetime. When a JRuby instance reaches this limit, it is flushed from memory and replaced with a fresh one. The default is 0, which disables automatic JRuby flushing.
  
  JRuby flushing can be useful for working around buggy module code that would otherwise cause memory leaks, but it slightly reduces performance whenever a new JRuby instance reloads all of the Puppet Ruby code. If memory leaks from module code are not an issue in your deployment, the default value of 0 performs best.
- multithreaded: Optional, false by default. Configures Puppet Server to use a single JRuby instance to process requests that require a JRuby, processing a number of threads up to max-active-instances at a time. Reduces the memory footprint of the server by only requiring a single JRuby.
Note: Multithreaded mode is an experimental feature which might experience breaking changes in future releases. Test the feature in a non-production environment before enabling it in production.
- max-queued-requests: Optional. The maximum number of requests that may be queued waiting to borrow a JRuby from the pool. When this limit is exceeded, a 503 "Service Unavailable" response will be returned for all new requests until the queue drops below the limit. If max-retry-delay is set to a positive value, then the 503 responses will include a Retry-After header indicating a random sleep time after which the client may retry the request. The default is 0, which disables the queue limit.
- max-retry-delay: Optional. Sets the upper limit for the random sleep set as a Retry-After header on 503 responses returned when max-queued-requests is enabled. A value of 0 will cause the Retry-After header to be omitted. Default is 1800 seconds which corresponds to the default run interval of the Puppet daemon.
- borrow-timeout: Optional. The timeout in milliseconds, when attempting to borrow an instance from the JRuby pool. The default is 1200000.
- environment-class-cache-enabled: Optional. Used to control whether the master service maintains a cache in conjunction with the use of the environment_classes API.
  
  If this setting is set to true, Puppet Server maintains the cache. It also returns an Etag header for each GET request to the API. For subsequent GET requests that use the prior Etag value in an If-None-Match header, when the class information available for an environment has not changed, Puppet Server returns an HTTP 304 (Not Modified) response with no body.
  
  If this setting is set to false or is not specified, Puppet Server doesn't maintain a cache, an Etag header is not returned for GET requests, and the If-None-Match header for an incoming request is ignored. It therefore parses the latest available code for an environment from disk on every incoming request.
  
  For more information, see the environment_classes API documentation.
- compile-mode: The default value depends on JRuby versions, for 1.7 it is off, for 9k it is jit. Used to control JRuby's "CompileMode", which may improve performance. A value of jit enables JRuby's "just-in-time" compilation of Ruby code. A value of force causes JRuby to attempt to pre-compile all Ruby code.
- profiling-mode: Optional. Used to enable JRuby's profiler for service startup and set it to one of the supported modes. The default value is off, but it can be set to one of api, flat, graph, html, json, off, and service. See ruby-prof for details on what the various modes do.
- profiler-output-file: Optional. Used to set the output file to direct JRuby profiler output. Should be a fully qualified path writable by the service user. If not set will default to a random name inside the service working directory.
The profiler settings configure profiling:
- enabled: If this is set to true, Puppet Server enables profiling for the Puppet Ruby code. The default is true.
The versioned-code settings configure commands required to use static catalogs:
- code-id-command: the path to an executable script that Puppet Server invokes to generate a code_id. When compiling a static catalog, Puppet Server uses the output of this script as the catalog's code_id. The code_id associates the catalog with the compile-time version of any file resources that has a source attribute with a puppet:/// URI value.
- code-content-command contains the path to an executable script that Puppet Server invokes when an agent makes a static_file_content API request for the contents of a file resource that has a source attribute with a puppet:/// URI value.
The dropsonde settings configure whether and how often Puppet Server submits usage telemetry:
- enabled: If this is set to true, Puppet Server submits public content usage data to Puppet development. Defaults to false.
- interval: how long, in seconds, Puppet Server waits between telemetry submissions if enabled. Defaults to 604800 (one week).

Note: The Puppet Server process must be able to execute the code-id-command and code-content-command scripts, and the scripts must return valid content to standard output and an error code of 0. For more information, see the static catalogs and static_file_content API documentation.

If you're using static catalogs, you must set and use both code-id-command and code-content-command. If only one of those settings are specified, Puppet Server fails to start. If neither setting is specified, Puppet Server defaults to generating catalogs without static features even when an agent requests a static catalog, which the agent will process as a normal catalog.

Examples

# Configuration for the JRuby interpreters.

jruby-puppet: {
    ruby-load-path: [/opt/puppetlabs/puppet/lib/ruby/vendor_ruby]
    gem-home: /opt/puppetlabs/server/data/puppetserver/jruby-gems
    gem-path: [/opt/puppetlabs/server/data/puppetserver/jruby-gems, /opt/puppetlabs/server/data/puppetserver/vendored-jruby-gems]
    environment-vars: { "FOO" : ${FOO}
                        "LANG" : "de_DE.UTF-8" }
    server-conf-dir: /etc/puppetlabs/puppet
    server-code-dir: /etc/puppetlabs/code
    server-var-dir: /opt/puppetlabs/server/data/puppetserver
    server-run-dir: /var/run/puppetlabs/puppetserver
    server-log-dir: /var/log/puppetlabs/puppetserver
    max-active-instances: 1
    max-requests-per-instance: 0
}

# Settings related to HTTP client requests made by Puppet Server.
# These settings only apply to client connections using the Puppet::Network::HttpPool
# classes. Client connections using net/http or net/https directly will not be
# configured with these settings automatically.
http-client: {
    # A list of acceptable protocols for making HTTP requests
    #ssl-protocols: [TLSv1, TLSv1.1, TLSv1.2]

    # A list of acceptable cipher suites for making HTTP requests. For more info on available cipher suites, see:
    # http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider
    #cipher-suites: [TLS_RSA_WITH_AES_256_CBC_SHA256,
    #                TLS_RSA_WITH_AES_256_CBC_SHA,
    #                TLS_RSA_WITH_AES_128_CBC_SHA256,
    #                TLS_RSA_WITH_AES_128_CBC_SHA]

    # The amount of time, in milliseconds, that an outbound HTTP connection
    # will wait for data to be available before closing the socket. If not
    # defined, defaults to 20 minutes. If 0, the timeout is infinite and if
    # negative, the value is undefined by the application and governed by the
    # system default behavior.
    #idle-timeout-milliseconds: 1200000

    # The amount of time, in milliseconds, that an outbound HTTP connection will
    # wait to connect before giving up. Defaults to 2 minutes if not set. If 0,
    # the timeout is infinite and if negative, the value is undefined in the
    # application and governed by the system default behavior.
    #connect-timeout-milliseconds: 120000

    # Whether to enable http-client metrics; defaults to 'true'.
    #metrics-enabled: true
}

# Settings related to profiling the puppet Ruby code.
profiler: {
    enabled: true
}

# Settings related to static catalogs. These paths are examples. There are no default
# scripts provided with Puppet Server, and no default path for the scripts. To use static catalog features, you must set
# the paths and provide your own scripts.
versioned-code: {
    code-id-command: /opt/puppetlabs/server/apps/puppetserver/code-id-command_script.sh
    code-content-command: /opt/puppetlabs/server/apps/puppetserver/code-content-command_script.sh
}

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.