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 provides Puppet Server packages for the following platforms:
Red Hat Enterprise Linux
If we do not provide a package for your system, you can run Puppet Server from source on any x86_64 Linux server with JDK 1.8 or 11. See Running from Source for more details.
Tip: Other POSIX compatible servers or versions of Java are unsupported by Puppet, but they may work. Join our community Slack for help with non-supported operating systems, architectures, or JRE versions.
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, Puppet Server, and Puppet DB, see 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. See 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.
See CA V1 HTTP API for more information on these APIs.
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 stores credentials using
.pem files. You can use the puppetserver ca command to interact with these credentials, including listing, signing, and revoking certificates.
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.
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.
You cannot 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. See 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.
You can maximize Puppet Server's performance by tuning your JRuby configuration. To learn more, see the Puppet Server Tuning Guide.
Puppet Server needs to run as the user:
pe-puppetif you are running Puppet Enterprise.
puppetif you are running open source Puppet.
The user is specified in:
/etc/sysconfig/pe-puppetserverfor Puppet Enterprise.
/etc/sysconfig/puppetserverfor open source Puppet.
Note: Puppet Server ignores the
groupsettings from puppet.conf.
All of the Puppet Server's files and directories must be readable and writable by this user.
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.
You can change the port in
webserver.conf if necessary. See the Configuration page for details.
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. See Configuring Puppet Server for more details.
Finally, any errors that happen before logging is set up or cause the logging system to die, displays in journalctl.
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-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 configuration files, which are located in the
conf.d directory. Refer to the Config directory for a list of Puppet's configuration files.
conf.d directory contains:
global.conf: Global configuration settings for Puppet Server.
web-routes.conf: Web server configuration settings.
puppetserver.conf: Settings for Puppet Server itself, including the JRuby interpreter and the administrative API.
auth.conf: Authentication rules for Puppet Server endpoints.
ca.conf: Settings for the Certificate Authority service.
For detailed information about Puppet Server settings and the
conf.d directory, refer to the Configuring Puppet Server page.
Puppet Server uses Puppet's config 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 view a complete list of these differences on the Differing behavior in puppet.conf page.