Configuring Puppet Server

Puppet Server uses a combination of Puppet's configuration files along with its own configuration files. You can refer to a complete list of Puppet’s configuration files in the Config directory.

Puppet Server and puppet.conf settings

Puppet Server uses Puppet's configuration files, including most of the settings in puppet.conf. However, Puppet Server treats some puppet.conf settings differently. You must be aware of these differences. You can visit a complete list of these differences at Differing behavior in puppet.conf. Puppet Server automatically loads the puppet.conf settings in the configuration file’s main and server sections. Puppet Server uses the values in the server section but if they are not present, it uses the values in the main section.

Puppet Server honors the following puppet.conf settings:

  • allow_duplicate_certs

  • autosign

  • cacert

  • cacrl

  • cakey

  • ca_name

  • capub

  • ca_ttl

  • certdir

  • certname

  • cert_inventory

  • codedir (PE only)

  • csrdir

  • csr_attributes

  • dns_alt_names

  • hostcert

  • hostcrl

  • hostprivkey

  • hostpubkey

  • keylength

  • localcacert

  • manage_internal_file_permissions

  • privatekeydir

  • requestdir

  • serial

  • signeddir

  • ssl_client_header

  • ssl_client_verify_header

  • trusted_oid_mapping_file

Configuration Files

Most of Puppet Server's configuration files and settings (with the exception of the logging config file) are in the conf.d directory. The conf.d directory is located at /etc/puppetlabs/puppetserver/conf.d by default. These configuration files are in the HOCON format, which retains the basic structure of JSON but is more readable. For more information, visit the HOCON documentation.

At startup, Puppet Server reads all the .conf files in the conf.d directory. You must restart Puppet Server to implement your changes to these files. The conf.d directory contains the following files and settings:

Note: The product.conf file is optional and is not included by default. You can create product.conf in the conf.d directory to configure product-related settings (such as automatic update checking and analytics data collection).

Logging

There is a Logback configuration file that controls how Puppet Server logs. Its default location is at /etc/puppetlabs/puppetserver/logback.xml. If you want to place it elsewhere, visit the documentation on global.conf.

For additional information on the logback.xml file, visit Logback.xm or Logback documentation. For tips on configuring Logstash or outputting logs in JSON, visit Advanced logging configuration

HTTP Traffic

Puppet Server logs HTTP traffic in a format similar to Apache and to a separate file that isn’t the main log file. By default, the access log is located at /var/log/puppetlabs/puppetserver/puppetserver-access.log.

The following information is logged for each HTTP request by default:

  • remote host

  • remote log name

  • remote user

  • date of the logging event

  • URL requested

  • status code of the request

  • response content length

  • remote IP address

  • local port

  • elapsed time to serve the request, in milliseconds

There is a Logback configuration file that controls Puppet Server’s logging behavior. Its default location is at /etc/puppetlabs/puppetserver/request-logging.xml. If you want to place it elsewhere, visit the documentation on webserver.conf

Authorization

To enable additional logging related to auth.conf, edit Puppet Server's logback.xml file. By default, only a single message is logged when a request is denied.

To enable a one-time logging of the parsed and transformed auth.conf file, add the following to Puppet Server's logback.xml file:

<logger name="puppetlabs.trapperkeeper.services.authorization.authorization-service" level="DEBUG"/>

To enable rule-by-rule logging for each request as it's checked for authorization, add the following to Puppet Server's logback.xml file:

<logger name="puppetlabs.trapperkeeper.authorization.rules" level="TRACE"/>

Service Bootstrapping

Puppet Server is built on top of our open-source Clojure application framework, Trapperkeeper.

One of the features that Trapperkeeper provides is the ability to enable or disable individual services that an application provides. In Puppet Server, you can use this feature to enable or disable the CA service. The CA service is enabled by default, but if you're running a multi-server environment or using an external CA, you might want to disable the CA service on some nodes.

The service bootstrap configuration files are in two locations:

  • /etc/puppetlabs/puppetserver/services.d/: For services that users are expected to manually configure if necessary, such as CA-related services.

  • /opt/puppetlabs/server/apps/puppetserver/config/services.d/: For services users shouldn’t need to configure.

Any files with a .cfg extension in either of these locations are combined to form the final set of services Puppet Server will use.

The CA-related configuration settings are set in /etc/puppetlabs/puppetserver/services.d/ca.cfg. If services added in future versions have user-configurable settings, the configuration files will also be in this directory. When upgrading Puppet Server with a package manager, it should not overwrite files already in this directory.

In the ca.cfg file, find and modify these lines as directed to enable or disable the service:

# To enable the CA service, leave the following line uncommented
puppetlabs.services.ca.certificate-authority-service/certificate-authority-service
# To disable the CA service, comment out the above line and uncomment the line below
#puppetlabs.services.ca.certificate-authority-disabled-service/certificate-authority-disabled-service

Adding Java JARs

Puppet Server can load any provided Java Jars upon its initial startup. When launched, Puppet Server automatically loads any JARs placed in /opt/puppetlabs/server/data/puppetserver/jars into the classpath. JARs placed here are not modified or removed when upgrading Puppet Server.