Configuring PuppetDB

To change the JVM heap size for PuppetDB, edit the init script config file by setting a new value for the -Xmx flag in the JAVA_ARGS variable.

For example, to cap PuppetDB at 192MB of memory:

JAVA_ARGS="-Xmx192m"

To use 1GB of memory:

JAVA_ARGS="-Xmx1g"

While all JMX metrics are exposed using the /metrics namespace, you can also expose direct JMX access using standard JVM means as documented here. This can be done using the JAVA_ARGS init script setting, similar to configuring the heap size.

For example, adding the following JVM options will open up a JMX socket on port 1099:

JAVA_ARGS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=1099"

If you installed PuppetDB with the puppetlabs-puppetdb module, PuppetDB's settings will be managed by Puppet. Most of the settings you care about can be configured with the module's class parameters; see the module's documentation for details.

If you do need to change those rare settings that the module doesn't manage, you can do the following:

Create a new class in a new module (something like site::puppetdb::server::extra), declare any number of ini_setting resources as shown below, set the class to refresh the puppetdb::server class, and assign it to your PuppetDB server.

    # Site-specific PuppetDB settings. Declare this class on any node that gets the puppetdb::server class.
    class site::puppetdb::server::extra {

      # Restart the PuppetDB service if settings change
      Class[site::puppetdb::server::extra] ~> Class[puppetdb::server]

      # Get PuppetDB confdir
      include puppetdb::params
      $confdir = $puppetdb::params::confdir

      # Set resource defaults
      Ini_setting {
        ensure  => present,
        require => Class['puppetdb::server::validate_db'],
      }

      ini_setting {'puppetdb-extra-setting':
        path    => "${confdir}/global.ini",
        section => 'global',
        setting => <some-extra-setting>,
        value   => 'true',
      }
    }

This defines the parent directory for the MQ's data directory. The directory must exist and be writable by the PuppetDB user in order for the application to run.

This describes the full path to a logback.xml file. Covering all the options available for configuring Logback is outside the scope of this guide: see the Logback documentation for exhaustive information.

If this setting isn't provided, PuppetDB defaults to logging at INFO level to standard out.

If you installed from packages, PuppetDB will use the logback.xml file in the /etc/puppetdb/ or /etc/puppetlabs/puppetdb directory. Otherwise, you can find an example file in the ext directory of the source.

You can edit the logging configuration file while PuppetDB is running, and it will automatically react to changes after a few seconds.

The URL to query when checking for newer versions; defaults to https://updates.puppetlabs.com/check-for-updates. Overriding this setting may be useful if your PuppetDB server is firewalled and can't make external HTTP requests. In this case you can configure a proxy server to send requests to the updates.puppetlabs.com URL and override this setting to point to your proxy server.

Optional. This describes the path to a file that contains a list of certificate names, one per line. Incoming HTTPS requests will have their certificates validated against this list of names and only those with an exact matching entry will be allowed through. (For a Puppet Server, this compares against the value of the certname setting, rather than the dns_alt_names setting.)

If not supplied, PuppetDB uses standard HTTPS without any additional authorization. All HTTPS clients must still supply valid, verifiable SSL client certificates.

Note: This setting replaces the deprecated certificate-whitelist setting which will be retired in a future release

Note: This setting has no effect and will be retired in a future release.

Optional. Setting this to true disables checking for updated versions of PuppetDB and sending basic analytics data to Puppet. Defaults to false.

If disable-update-checking is set to false, PuppetDB checks for updates upon start or restart, and every 24 hours thereafter, and sends the following data to Puppet:

• Product name

• Database name

• Database version

• PuppetDB version

• IP address

• Data collection timestamp

The data Puppet collects provides just one of many methods we use for learning about our community of users. The more we know about how you use Puppet, the better we can address your needs. No personally identifiable information is collected, and the data we collect is never used or shared outside Puppet.

Optional. Setting this to true will enable debug level logging of the internal AST and SQL that PuppetDB generates for all queries. This can be useful when debugging query performance. If unset, the default value is false. See the Logback documentation for more information about logging options and how to enable debug level logging.

This controls how often, in minutes, to compact the database. The compaction process reclaims space and deletes unnecessary rows. If not supplied, the default is every 60 minutes. If set to zero, all database GC processes will be disabled.

This controls how often, in minutes, to expire nodes that are no longer submitting commands. If not supplied, this value defaults to gc-interval.

This controls how often, in minutes, to remove nodes that have been expired or deactivated for longer than node-purge-ttl. If not supplied, this value defaults to gc-interval.

This controls how often, in minutes, to remove reports and that have been expired or deactivated for longer than reports-ttl or resource-events-ttl respectively. If not supplied, this value defaults to gc-interval.

This controls how often, in minutes, to remove packages that are no longer associated with any nodes. If not supplied, this value defaults to gc-interval.

This controls how often, in minutes, to remove catalog data that is no longer associated with any nodes. If not supplied, this value defaults to gc-interval.

This controls how often, in minutes, to remove fact paths that are no longer associated with any factsets. If not supplied, this value defaults to 24 hours or gc-interval, which ever is longer.

Mark as 'expired' nodes that haven't seen any activity (no new catalogs, facts, or reports) in the specified amount of time. Expired nodes behave the same as manually-deactivated nodes.

You may specify the time as a string using any of the following suffixes:

`d`  - days
`h`  - hours
`m`  - minutes
`s`  - seconds
`ms` - milliseconds

For example, a value of 30d would set the time-to-live to 30 days, and a value of 48h would set the time-to-live to 48 hours.

Nodes will be checked for staleness every gc-interval minutes. Manual deactivation will continue to work as always.

If unset, nodes are auto-expired after 7 days of inactivity. If set to 0s, auto-expiration of nodes is disabled.

Automatically delete nodes that have been deactivated or expired for the specified amount of time. This will also delete all facts, catalogs, and reports for the relevant nodes. This TTL may be specified the same way as node-ttl above.

If unset, nodes are purged after 14 days. If set to 0s, auto-deletion of nodes is disabled.

Nodes will be purged in batches of this size, one batch per gc-interval. If unset, the batch limit will be 25, and if you expect to generate eligible nodes faster than that (on average), you should either increase this limit so that PuppetDB will be able to keep up, or complement the automatic GC process with manual purge_node requests to the cmd endpoint to cover the excess.

Automatically delete reports that are older than the specified amount of time. You may specify the time as a string using any of the suffixes described in the node-ttl section above.

Outdated reports will be deleted during the database garbage collection, which runs every gc-interval minutes.

If unset, the default value is 14 days.

Automatically delete report events older than the specified time. Reports are unaffected until their respective TTLs.

This allows for more fine-grained control of the expiration of reports. If unset, it will default to the value of report-ttl. It may not be set to a value larger than report-ttl.

Note: this value is in UTC days - any value will be rounded to the nearest day. Example: 14 hours will be 1 day, 25 hours will be 2 days.

See node-ttl above for the format of this value.

This describes where to find the database. Set this to //<HOST>:<PORT>/<DATABASE> when using PostgreSQL, replacing <HOST> with the DB server's hostname, <PORT> with the port on which PostgreSQL is listening, and <DATABASE> with the name of the database. See the Postgres SSL doc for details on configuring the subname option for an encrypted connection between PuppetDB and Postgres. Without additional parameters, PuppetDB's database connections will communicate in plaintext.

The database user specified for connections performing normal operations (queries, command processing, etc.).

The database user for special cases when the database connection username is different from the username reported by the database. An example is managed PostgreSQL in Azure, in order to connect we need to specify username@hostname, but the user reported by the database is username. If not specified, it will default to username

This is the password to use when connecting. Only used with PostgreSQL. This password is stored in plain-text in the configuration file. You can remove this configuration option if you configure an SSL connection and configure postgres to use certificates to authorize the database connections. If your PostgreSQL server is on a different server, you should configure an SSL connection between PuppetDB and Postgres, otherwise the database communication is done via plaintext.

The database user specified for database migration operations, in particular the database validation and migration at startup. Defaults to the username. See the PostgreSQL configuration section for some important requirements for the privileges of this user (role), and the migration coordination section for an overview of the process.

The database migrator user for special cases when the database connection username is different from the username reported by the database. An example is managed PostgreSQL in Azure, in order to connect we need to specify username@hostname, but the user reported by the database is username. If not specified, it will default to migrator-username

This is the password to use when connecting for database migrations. Defaults to password. This password is stored in plain-text in the configuration file. You can remove this configuration option if you configure an SSL connection and configure postgres to use certificates to authorize the database connection. If your PostgreSQL server is on a different server, you should configure an SSL connection between PuppetDB and Postgres, otherwise the database communication is done via plaintext.

When set to true (the default), PuppetDB will upgrade the data in the database to the latest format at startup. When false, PuppetDB will exit with an error status if the format version is not the one it expects, whether newer or older. See the PostgreSQL configuration section for some important requirements for the privileges of this user (role), and the migration coordination section for an overview of the process.

From the HikariCP documentation:

"This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. Basically this value will determine the maximum number of actual connections to the database backend. A reasonable value for this is best determined by your execution environment."

When the pool reaches this size, and no idle connections are available, attempts to get a connection will wait for connection-timeout milliseconds before timing out.

The default value is 25. Note that PuppetDB will use one pool for writes and another for reads, so the total number of connections used will be twice this setting.

The maximum time (in minutes), for a pooled connection to remain unused before it is closed off.

If not supplied, the default value is 60 minutes.

The maximum time (in minutes) a pooled connection should remain open. Any connections older than this setting will be closed off. Connections currently in use will not be affected until they are returned to the pool.

If not supplied, we won't terminate connections based on their age alone.

The maximum time to wait (in milliseconds) to acquire a connection from the pool of database connections. If not supplied, defaults to 3000.

Optional. A list of fact names to be ignored whenever submitted. The facts-blocklist-type determines whether the names are matched literally or as Java regular expresions.

The names must be comma-separated in an INI configuration file, or a list in a HOCON file:

• INI: facts-blocklist = fact1, fact2, fact3

• HOCON: facts-blocklist = ["fact1", "fact2", "fact3"]

When matching lterally, the entire fact name (not including the path) must completely match one of the facts-blocklist entries in order to be blocklisted. When matching regular expressions, the name must match the entire pattern. For example the pattern "xyz" will not match the fact "123xyzabc", but ".*xyz.*" will.

Note: This setting replaces the deprecated facts-blacklist setting which will be retired in a future release

Optional. When set to literal (or not set) the facts-blocklist names will be matched literally. When set to regex (the only other legal value), the names will be matched as Java regular expresions. See the facts-blocklist description above for additional information.

Note: This setting replaces the deprecated facts-blacklist-type setting which will be retired in a future release

This controls how often, in milliseconds, to check the schema version PuppetDB is compatible with against the database's schema version. The default is every 30 seconds. If a mismatch is detected PuppetDB will exit with an error message suggesting appropriate action. If set to zero, this check is disabled.

This describes where to find the database. Set this to //<HOST>:<PORT>/<DATABASE> when using PostgreSQL, replacing <HOST> with the DB server's hostname, <PORT> with the port on which PostgreSQL is listening, and <DATABASE> with the name of the database. See the Postgres SSL doc for details on configuring the subname option for an encrypted connection between PuppetDB and Postgres. Without additional parameters, PuppetDB's database connections will communicate in plaintext.

This is the username to use when connecting. See the PostgreSQL configuration section for some important requirements for the privileges of this user (role).

This is the password to use when connecting. Only used with PostgreSQL. This password is stored in plain-text in the configuration file. You can remove this configuration option if you configure an SSL connection and configure postgres to use certificates to authorize the database connection. If your PostgreSQL server is on a different server, you should configure an SSL connection between PuppetDB and Postgres, otherwise the database communication is done via plaintext.

From the HikariCP documentation:

"This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. Basically this value will determine the maximum number of actual connections to the database backend. A reasonable value for this is best determined by your execution environment."

When the pool reaches this size, and no idle connections are available, attempts to get a connection will wait for connection-timeout milliseconds before timing out.

The default value is 10.

The maximum time (in minutes) for a pooled connection to remain unused before it is closed off.

If not supplied, the default value is 60 minutes.

The maximum time (in minutes) a pooled connection should remain open. Any connections older than this setting will be closed off. Connections currently in use will not be affected until they are returned to the pool.

If not supplied, we won't terminate connections based on their age alone.

The maximum time to wait (in milliseconds) to acquire a connection from the pool of database connections. If not supplied, defaults to 500.

This defines how many command processing threads to use. Each thread can process a single command at a time. The number of threads can be tuned based on what you see in the performance dashboard.

This setting defaults to half the number of cores in your system.

This sets a limit on the number of threads that can write to the disk at any one time. The default value is the smaller number of half the number of CPU cores and 4.

If your load is low, your disk is fast (i.e. an SSD), and commands aren't being processed quickly enough, then you could increasing this value in order to alleviate that, but this is unlikely to be the bottleneck for command processing.

This is a Boolean that enables rejecting (returning an HTTP 413 error) commands that are too large to process, such as a catalog that is too large, causing PuppetDB to run out of memory. This setting can be used along with max-command-size.

This setting is false by default.

This is an integer that specifies (in bytes) which commands are "too large" to process with PuppetDB. By default this setting is a fraction of the total heap space. It is strongly recommended that users set this manually as the default is probably too conservative. To help determine the current size of commands being processed, enable debug logging for the puppetlabs.puppetdb.middleware appender in the logback.xml. This setting has no effect when reject-large-commands is set to false.

Sets the IP interface to listen on for unencrypted HTTP traffic. If not supplied, we bind to localhost, which will reject connections from anywhere but the PuppetDB server itself. To listen on all available interfaces, use 0.0.0.0.

To avoid DNS resolution confusion, if you wish to set this to something other than localhost, we reccomend using an IP address instead of a hostname.

Note: Unencrypted HTTP is the only way to view the performance dashboard, because PuppetDB uses host verification for SSL. However, it can also be used to make any call to PuppetDB's API, including inserting exported resources and retrieving arbitrary data about your Puppet-managed nodes. If you enable cleartext HTTP, you MUST configure your firewall to protect unverified access to PuppetDB.

Establishes which port to use for unencrypted HTTP traffic. If not supplied, we won't listen for unencrypted traffic at all.

Sets the maximum number of threads assigned to responding to HTTP and HTTPS requests, effectively changing how many concurrent requests can be made at one time. Defaults to 50.

Note: Due to the behaviour of our web server (Jetty 9), this setting must be higher then the number of CPUs on your system or it will stop processing any HTTP requests.

Sets which IP interface to listen on for encrypted HTTPS traffic. If not supplied, we bind to localhost. To listen on all available interfaces, use 0.0.0.0.

To avoid DNS resolution confusion, if you wish to set this to something other than localhost, we reccomend using an IP address instead of a hostname

Establishes which port to use for encrypted HTTPS traffic. If not supplied, we won't listen for encrypted traffic at all.

Sets the path to the server certificate PEM file used by the PuppetDB web service for HTTPS. During the SSL handshake for a connection, certificates extracted from this file are presented to the client for the client's use in validating the server. This file may contain a single certificate or a chain of certificates ordered from the end certificate first to the most-root certificate last. For example, a certificate chain could contain:

• An end certificate.

• An intermediate CA certificate with which the end certificate was issued.

• A root CA certificate with which the intermediate CA certificate was issued.

In the PEM file, the end certificate should appear first, the intermediate CA certificate should appear second, and the root CA certificate should appear last.

If a chain is present, it is not required to be complete. If a path has been specified for the ssl-cert-chain setting, the server will construct the cert chain starting with the first certificate found in the ssl-cert PEM and followed by any certificates in the ssl-cert-chain PEM. In the latter case, any certificates in the ssl-cert PEM beyond the first one are ignored.

This sets the path to the private key PEM file that corresponds with the ssl-cert, if used by the PuppetDB web service for HTTPS.

This sets the path to the CA certificate PEM file used for client authentication. Authorized clients must be signed by the CA that corresponds to this certificate.

Optional. A comma-separated list of cryptographic ciphers to allow for incoming SSL connections. Valid names are listed in the official JVM cryptographic providers documentation. Note that you must use the all-caps cipher suite name.

If not supplied, PuppetDB will use only non-DHE cipher suites.

Optional. A comma-separated list of protocols to allow for incoming SSL connections. Valid names are listed in the official JVM cryptographic protocol documentation. Note that you must use the names with verbatim capitalization. For example: TLSv1.2, TLSv1.3.

If not supplied, PuppetDB uses a default of TLSv1, TLSv1.1, TLSv1.2. By default, SSLv3 is not included in that list due to known vulnerabilities. Users wanting to use SSLv3 need to explicitly specify it in their list.

Optional. This describes a path to a Certificate Revocation List file. Incoming SSL connections will be rejected if the client certificate matches a revocation entry in the file.

This sets the path to a PEM with CA certificates for use in presenting a client with the server's chain of trust. Certs found in this PEM file are appended after the first certificate from the ssl-cert PEM in the construction of the certificate chain. This is an optional setting. The certificates in the ssl-cert-chain PEM file should be ordered from the least-root CA certificate first to the most-root CA certificate last. For example, a certificate chain could contain:

• An end certificate.

• An intermediate CA certificate with which the end certificate was issued.

• A root CA certificate with which the intermediate CA certificate was issued.

The end certificate should appear in the ssl-cert PEM file. In the ssl-cert-chain PEM file, the intermediate CA certificate should appear first and the root CA certificate should appear last.

The chain is not required to be complete.

Note: This setting overrides the alternate configuration settings keystore and key-password.

Optional. This is a path to an XML file containing configuration information for the logback-access module. If present, a logger will be set up to log information about any HTTP requests Jetty receives according to the logging configuration, as long as the XML file pointed to exists and is valid. Information on configuring the logback-access module is available here and additional information about configuring the pattern layout can be found here.

A configuration file may resemble the following:

<configuration debug="false">
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>./dev-resources/access.log</file>
      <encoder>
        <pattern>%h %l %u %user %date "%r" %s %b</pattern>
      </encoder>
    </appender>
    <appender-ref ref="FILE" />
</configuration>

This example configures a FileAppender that outputs to a file, access.log, in the dev-resources directory. It will log the remote host making the request, the log name, the remote user making the request, the date/time of the request, the URL and method of the request, the status of the response, and the size in bytes of the response.

After receiving a shutdown, this is the number of milliseconds the server will wait for in-flight requests to complete before actually shutting down. New requests will be blocked during this time. Defaults to 30000.

This sets the maximum size of an HTTP request header. If a header is sent that exceeds this value, Jetty will return an HTTP 413 error response. This defaults to 8192 bytes, and only needs to be configured if an exceedingly large header is being sent in an HTTP request.

To enable the REPL, set to true. Defaults to false.

The port to use for the REPL.

Specifies the host or IP address for the REPL service to listen on. By default this is 127.0.0.1 only. As this is an insecure channel this is the only recommended setting for production environments.

If you wish to listen on all interfaces, you can specify 0.0.0.0, for example, although this is generally not recommended for production.

Enables/disables default pretty-printing of API responses. Defaults to false. Enabling default pretty-printing is not recommended in production because it incurs a penalty in data transfer speed and size. Users may override this setting on a per-query basis by supplying a ?pretty= parameter in the URL, valued true or false.

The remotes configuration key indicates that PuppetDB should poll a remote PuppetDB server for changes. When it finds changed or updated records on that server, it will download the records and submit them to the local command queue.

In the configuration file, you specify a remote for each server you want to pull data from. It is perfectly reasonable, and expected, for two servers to pull data from each other. For each remote, you must provide:

• The remote server url. This is a root url which should include the protocol and port to use (eg. "https://puppetdb.myco.net:8081"). The protocol is mandatory and must be either "http" or "https". If the port is not provided, it will default to 8080 for http and 8081 for https.

• The interval at which to poll the remote server for new data. This is formatted as a timespan with units (e.g. '2m'). See the node-ttl documentation for further reference.

You should not configure PuppetDB to sync with itself.

Set the maximum time that an entity can sync for (default: "30m"). PuppetDB syncs one entity (catalogs, factsets, reports, and nodes) at a time. While the sync is running it keeps a query open on the PostgreSQL database that will prevent the removal of old rows. If that connection is open long enough, it can degrade database performance. You shouldn't need to modify this setting unless you are experiencing an issue.

PuppetDB's initial sync, which occurs during startup, will only sync reports newer than initial-report-threshold (default: "0s"). While starting up, PuppetDB will not respond to queries or accept command submissions, so this can be used to get PuppetDB online faster, at the expense that it could return query responses that are not up to date. Subsequent periodic syncs will transfer the remaining data.

Controls how many milliseconds (by default 10 minutes) PuppetDB will wait for an SQL command to complete during an attempt to process a command (store a report, update a factset, etc.). When set to 0 it will wait forever (the default before 6.13), and when set to system, it won't specify any timeout, deferring to PostgreSQL's configuration.

Controls how many milliseconds (by default 5 minutes) PuppetDB will wait for the required lock when it attempts to drop a report or resource event partition that has expired. When set to 0 it will wait forever (the default before 6.13), and when set to system, it won't specify any timeout, deferring to PostgreSQL's configuration.

Controls how many milliseconds PuppetDB's fact path garbage collection process will wait for the lock it needs. When set to 0 it will wait forever (the default), and when set to system, it won't specify any timeout, deferring to PostgreSQL's configuration.

Can be set to true (the default) or false. When true, will attempt to interrupt the thread performing sync when the entity-time-limit is exceeded during a sync attempt, in addition to the normal periodic checks for for a timeout.

When set to true, (the default before PuppetDB 7), use the deprecated query streaming method which retries queries internally when certain kinds of transient errors are encountered. The deprecated method also holds an extra database connection open during the initial phase of the response. In newer versions (since 7.0.0), the default is false.

Controls how many milliseconds (by default 5 minutes) PuppetDB GC will wait for the query bulldozer thread it spawns to be cleaned up before logging an error. When set to 0 the query bulldozer thread is disabled and PuppetDB GC will wait in line to get the AccessExclusiveLock it needs to drop partitioned tables.