Puppet is configured in an agent-server architecture, in which a primary server node controls configuration information for a fleet of managed agent nodes. Puppet Server performs the role of the primary server node. Puppet Server is a Ruby and Clojure application that runs on the Java Virtual Machine (JVM). It runs Ruby code for compiling Puppet catalogs and serving files in several JRuby interpreters, and provides a certificate authority and other informational services via Clojure.
Puppet provides Puppet Server packages for Red Hat Enterprise Linux, Centos, Debian, and Ubuntu.
If we don't 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. Other POSIX compatible servers or versions of Java are unsupported by Puppet, although they may work. Join our community Slack for help with non-supported operating systems, architectures, or JRE versions.
Note that Puppet Server is versioned separately from Puppet itself. Major Puppet Server releases are compatible with the same major Puppet release, such as Puppet 6.x and Puppet Server 6.x, but might have different minor or patch versions, such as Puppet 6.9 and Puppet Server 6.6. 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, you'll use the usual commands for your OS, such as
service puppetserver restart,
service puppetserver status, etc.
Puppet Server's Run Environment
Puppet Server consists of several related services that share state and route requests among themselves. These services run inside a single JVM process, using the Trapperkeeper service framework.
From a user's perspective, it mostly acts like a single monolithic service. Most of the architectural complexity is wrapped and hidden; the main exception is the handful of extra config files that manage different internal services.
Embedded Web Server
Puppet Server uses a Jetty-based web server embedded in the service's JVM process. You don't need to do anything special to configure or enable the web server; it works out of the box. It performs well under production-level loads.
The web server's settings can be modified in
webserver.conf. You might need to edit this file if you're using an external CA or running Puppet on a non-standard port.
Puppet API Service
Puppet Server provides APIs that are used by the Puppet agent to manage configuration on 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, and 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 disallowed by default; you can use the
auth.conf file to let specific certificate owners issue commands.
The CA service uses
.pem files to store credentials. 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.
Right now, the main administrative task is forcing expiration of all environment caches. This lets you deploy new code to long-timeout environments without having to do a lengthy full restart of the service.
Most of Puppet Server's work — compiling catalogs, receiving reports, etc. — is still done by Ruby code. But instead of using the operating system's MRI Ruby runtime, Puppet Server runs this code in JRuby, an implementation of the Ruby interpreter that runs on the JVM.
Because we don't use the system Ruby, you can't use the system
gem command to install Ruby Gems for use by the Puppet primary server. Instead, Puppet Server includes a separate
puppetserver gem command for installing any libraries that your Puppet extensions might require. See the "Using Ruby Gems" page for details.
Note: To set custom arguments to be passed into the Java process for the
puppetserver rubycommand with the
JAVA_ARGS_CLIenvironment variable, either temporarily on the command line or persistently by adding it to the sysconfig/default file (typically located at
JAVA_ARGS_CLIenvironment variable also controls the arguments used when running the
Additionally, if you need to test or debug code that will be used by Puppet Server, we include
puppetserver ruby and
puppetserver irb commands that execute Ruby code in a JRuby environment.
To handle parallel requests from agent nodes, Puppet Server maintains several separate JRuby interpreters, all independently running Puppet's application code, and distributes agent requests among them. Today, agent requests are distributed more or less randomly, without regard to their environment; this may change in the future.
You can configure the JRuby interpreters in the
jruby-puppet section of the
You can maximize Puppet Server's performance by tuning your JRuby configuration. To learn more about tuning your configuration, see our Puppet Server Tuning Guide.
Puppet Server needs to run as the user
pe-puppet if you are running Puppet Enterprise, or
puppet if you are running open source Puppet.
The user is specified in
/etc/sysconfig/pe-puppetserver for PE, or in
/etc/sysconfig/puppetserver for open source Puppet. (Puppet Server ignores the
group settings from puppet.conf.)
All of the Puppet primary 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 this port.
You can change the port in
webserver.conf if necessary. See the Configuration page for details.
Puppet Server completely ignores the
serverport setting in the puppet.conf file.
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, and when the total size of all Server logs exceeds 1GB, it automatically deletes the oldest logs.
Logback is heavily configurable; if you need something more specialized than a unified log file, you can probably get it. See the configuration docs for info on configuring logging.
Finally, errors that happen before logging is set up or which cause the logging system to die will appear in journalctl.
By default, Puppet Server handles SSL termination automatically.
In network configurations that require external SSL termination (e.g. with a hardware load balancer), you'll need to configure a few other things. See the External SSL Termination page for details. In summary, you'll need to:
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 config files along with its own configuration files, which are located in the
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 Configuration page.
As mentioned above, Puppet Server also uses Puppet's config files, including most of the settings in
puppet.conf. However, Puppet Server treats some
puppet.conf settings differently, and you should be aware of these differences.