Puppet Server Configuration Files: puppetserver.conf

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


Note: Under most conditions, you won’t change the default settings for master-conf-dir or master-code-dir. However, if you do, also change the equivalent Puppet settings (confdir or codedir) to ensure that commands like puppet cert and puppet module use the same directories as Puppet Server. You must also specify the non-default confdir when running commands, since 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. To use Ruby 2.x with Puppet Server, enable Puppet Server 5.x’s JRuby 9k support by assigning the JRUBY_JAR environment variable. See Puppet Server Configuration for details.

    • 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"].

    • 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.

    • master-conf-dir: Optional. The path to the Puppet configuration directory. The default is /etc/puppetlabs/puppet.

    • master-code-dir: Optional. The path to the Puppet code directory. The default is /etc/puppetlabs/code.

    • master-var-dir: Optional. The path to the Puppet cache directory. The default is /opt/puppetlabs/server/data/puppetserver.

    • master-run-dir: Optional. The path to the run directory, where the service’s PID file is stored. The default is /var/run/puppetlabs/puppetserver.

    • master-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.

    • 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.

    • max-queued-requests: Optional. The maximum number of requests that may be queued waiting to borrow a JRuby from the pool. Once 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.

    • use-legacy-auth-conf: Optional. The method to be used for authorizing access to the HTTP endpoints served by the master service. The applicable endpoints are listed in Puppet v3 HTTP API. As of Puppet Server 5.0, this setting’s default value is false.

      If this setting is set to true, Puppet uses the deprecated Ruby puppet-agent authorization method and Puppet auth.conf format, which will be removed in a future version of Puppet Server.

      For a value of false or is not specified, Puppet uses the HOCON configuration file format and location.

      For more information, see the auth.conf documentation.

    • 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 puppet-admin section configures Puppet Server’s administrative API. (This API is unavailable with Rack or WEBrick Puppet masters.)

    Note: The puppet-admin setting and client-whitelist parameter are deprecated in favor of authorization methods introduced in Puppet Server 2.2. For details, see the auth.conf documentation.

    • authorization-required determines whether a client certificate is required to access the endpoints in this API. If set to false, all requests will be permitted to access this API. If set to true, only the clients whose certnames are included in the client-whitelist setting are allowed access to the admin API. If this setting is not specified but the client-whitelist setting is specified, the default value for this setting is true.

    • client-whitelist contains an array of client certificate names that are allowed to access the admin API. Puppet Server denies any requests made to this endpoint that do not present a valid client certificate mentioned in this array.

    If neither the authorization-required nor the client-whitelist settings are specified, Puppet Server uses the new authorization methods and auth.conf formats to access the admin API endpoints.

  • 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.

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.


# 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" }
    master-conf-dir: /etc/puppetlabs/puppet
    master-code-dir: /etc/puppetlabs/code
    master-var-dir: /opt/puppetlabs/server/data/puppetserver
    master-run-dir: /var/run/puppetlabs/puppetserver
    master-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