| layout | title | canonical |
|---|---|---|
default |
Puppet's Services: Puppet Server |
/puppetserver/latest/services_master_puppetserver.html |
Puppet is configured in an agent-master architecture, in which a master node controls configuration information for a fleet of managed agent nodes. Puppet Server performs the role of the master node. Puppet Server is a Ruby and Clojure application that runs on the Java Virtual Machine (JVM) and provides the same services as the classic Puppet master application. It mostly does this by running the existing Puppet master code in several JRuby interpreters, but it replaces some parts of the classic application with new services written in Clojure.
This page describes the generic requirements and run environment for Puppet Server; for practical instructions, see the docs for installing and configuring it.
Puppet provides Puppet Server packages for Red Hat Enterprise Linux, RHEL-derived distros, Fedora, 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.
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 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.
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 Server includes a "master" service. See Puppet V3 HTTP API for more information on the basic APIs.
-
For docs on the Puppet Server-specific APIs hosted by the master service, see:
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. (The specific endpoints are certificate, certificate_request, certificate_revocation_list, and certificate_status.)
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 in the standard Puppet ssldir to store credentials. You can use the standard puppetserver ca command to interact with these credentials, including listing, signing, and revoking certificates.
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.
- For API docs, see:
- For details about environment caching, see the Puppet environments documentation.
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 Puppet 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 master. 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 theJAVA_ARGS_CLIenvironment variable, either temporarily on the command line or persistently by adding it to the sysconfig/default file (typically located at/etc/sysconfig/puppetserveror/etc/defaults/puppetserver). TheJAVA_ARGS_CLIenvironment variable also controls the arguments used when running thepuppetserver gemandpuppetserver irbsubcommands.
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 puppetserver.conf file.
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 user and group settings from puppet.conf.)
All of the Puppet master'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 masterport 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, there's a special "daemon" log file used only for errors that happen before logging is set up or which cause the logging system to die. This file can be found at /var/log/puppetlabs/puppetserver/puppetserver-daemon.log on platforms using SysV-style init, and in journalctl on platforms using systemd.
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-Verify(mandatory).X-Client-DN(mandatory for client-verified requests).X-Client-Cert(optional; required for trusted facts).
Puppet Server uses a combination of Puppet's usual config files along with its own configuration files, which are located in the conf.d directory.
Puppet Server's conf.d directory contains:
global.conf: Global configuration settings for Puppet Server.webserver.confandweb-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 usual 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.