About Puppet Server

Puppet is configured in an agent-server architecture, in which a primary server node manages the configuration information for a fleet of agent nodes. Puppet Server acts as the primary server node. Puppet Server is a Ruby and Clojure application that runs on the Java Virtual Machine (JVM). Puppet Server runs Ruby code for compiling Puppet catalogs and for serving files in several JRuby interpreters. It also provides a certificate authority through Clojure.

This page describes the general requirements and the run environment for Puppet Server.

Puppet Server releases

Puppet Server and Puppet share the same major release (Puppet Server 6.x and Puppet 6.x). However, they are versioned separately and might have different minor or patch versions (Puppet Server 6.5 versus Puppet 6.8). For a list of the maintained versions of Puppet and Puppet Server, visit Puppet releases and lifecycles.

Controlling the Service

The Puppet Server service name is puppetserver. To start and stop the service, use commands such as service puppetserver restart, service puppetserver status for your OS.

Puppet Server's Run Environment

Puppet Server consists of several related services. These services share state and route requests among themselves. The services run inside a single JVM process, using the Trapperkeeper service framework.

Embedded Web Server

Puppet Server uses a Jetty-based web server embedded in the service's JVM process. No additional or unique actions are required to configure and enable the web server. You can modify the web server's settings in webserver.conf. You might need to edit this file if you use an external CA or run Puppet on a non-standard port.

Puppet API Service

Puppet Server provides APIs that are used by the Puppet agent to manage the configuration of your nodes. Visit Puppet V3 HTTP API for more information on the basic APIs.

Certificate Authority Service

Puppet Server includes a certificate authority (CA) service that:

  • Accepts certificate signing requests (CSRs) from nodes.

  • Serves certificates and a certificate revocation list (CRL) to nodes.

  • Optionally accepts commands to sign or revoke certificates.

Signing and revoking certificates over the network is disabled by default. You can use the auth.conf file to allow specific certificate owners the ability to issue commands.

The CA service uses .pem files to stores credentials. You can use the puppetserver ca command to interact with these credentials, including listing, signing, and revoking certificates. See CA V1 HTTP API for more information on these APIs.

Admin API Service

Puppet Server includes an administrative API for triggering maintenance tasks. The most common task refreshes Puppet’s environment cache, which causes all of your Puppet code to reload without the requirement to restart the service. Consequently, you can deploy new code to long-timeout environments without executing a full restart of the service.

For API docs, visit:

For details about environment caching, visit:

JRuby Interpreters

Most of Puppet Server's work is done by Ruby code running in JRuby. JRuby is an implementation of the Ruby interpreter that runs on the JVM. Note that you can’t use the system gem command to install Ruby Gems for the Puppet primary server. Instead, Puppet Server includes a separate puppetserver gem command for installing any libraries your Puppet extensions might require. Visit Using Ruby Gems for details.

If you want to test or debug code to be used by the Puppet Server, you can use the puppetserver ruby and puppetserver irb commands to execute Ruby code in a JRuby environment.

To handle parallel requests from agent nodes, Puppet Server maintains separate JRuby interpreters. These JRuby interpreters individually run Puppet's application code, and distribute agent requests among them. You can configure the JRuby interpreters in the jruby-puppet section of puppetserver.conf.

Tuning Guide

You can maximize Puppet Server's performance by tuning your JRuby configuration. To learn more, visit the Puppet Server Tuning Guide.

User

If you are running Puppet Enterprise:

  • Puppet Server user runs as pe-puppet.

  • You must specify the user in /etc/sysconfig/pe-puppetserver.

If you are running open source Puppet:

  • Puppet Server needs to run as the user puppet.

  • You must specify the user in /etc/sysconfig/puppetserver.

All of the Puppet Server's files and directories must be readable and writable by this user. Note that Puppet Server ignores the user and group settings from puppet.conf.

Ports

By default, Puppet's HTTPS traffic uses port 8140. The OS and firewall must allow Puppet Server's JVM process to accept incoming connections on port 8140. If necessary, you can change the port in webserver.conf. See the Configuration page for details.

Logging

All of Puppet Server's logging is routed through the JVM Logback library. By default, it logs to /var/log/puppetlabs/puppetserver/puppetserver.log. The default log level is 'INFO'. By default, Puppet Server sends nothing to syslog. All log messages follow the same path, including HTTP traffic, catalog compilation, certificate processing, and all other parts of Puppet Server's work.

Puppet Server also relies on Logback to manage, rotate, and archive Server log files. Logback archives Server logs when they exceed 200MB. Also, when the total size of all Server logs exceeds 1GB, Logback automatically deletes the oldest logs. Logback is heavily configurable. If you need something more specialized than a unified log file, it may be possible to obtain. Visit Configuring Puppet Server for more details.

Finally, any errors that cause the logging system to die or occur before logging is set up, display in journalctl.

SSL Termination

By default, Puppet Server handles SSL termination automatically. For network configurations that require external SSL termination (e.g. with a hardware load balancer), additional configuration is required. See the External SSL Termination page for details. In summary, you must:

  • Configure Puppet Server to use HTTP instead of HTTPS.

  • Configure Puppet Server to accept SSL information via insecure HTTP headers.

  • Secure your network so that Puppet Server cannot be directly reached by any untrusted clients.

  • Configure your SSL terminating proxy to set the following HTTP headers:

    • X-Client-Verify (mandatory).

    • X-Client-DN (mandatory for client-verified requests).

    • X-Client-Cert (optional; required for trusted facts).

Configuring Puppet Server

Puppet Server uses a combination of Puppet's configuration files along with its own separate configuration files, which are located in the conf.d directory. Refer to the Config directory for a list of Puppet's configuration files. For detailed information about Puppet Server settings and the conf.d directory, refer to the Configuring Puppet Server page.