Important: Deprecation warning

Puppet includes a basic Puppet master web server based on Ruby’s WEBrick library. (This is what Puppet uses if you run puppet master on the command line or use most puppetmaster init scripts.)

You cannot use this default server for real-life loads, as it can’t handle concurrent connections; it is only suitable for small tests with ten nodes or fewer. You must configure a production quality web server before you start managing your nodes with Puppet.

Any Rack-based application server stack will work with a Puppet master, but if you don’t have any particular preference, you should use Passenger combined with Apache. This guide shows how to configure Puppet with this software.

What is Passenger?

Passenger (AKA mod_rails or mod_rack)
is an Apache 2.x module which lets you run Rails or Rack
applications inside a general purpose web server, like
Apache httpd or nginx.

Notes on PassengerHighPerformance

The example vhost config above sets PassengerHighPerformance On. This setting basically allows Passenger to shortcut some of Apache’s normal layers of request handling, so the Puppet application can respond earlier. Unfortunately, it can also interfere with other Apache modules, including important ones like mod_proxy, mod_rewrite, and mod_authz_core.

In the example, we’ve limited its effect by setting PassengerHighPerformance at the vhost scope, so it won’t interfere with any non-Puppet requests the Apache process is handling. You can also enable or disable it in a <Location> directive, which may be necessary if you’re proxying traffic to the Puppet CA in a multi-master setup.

Notes on DocumentRoot and PassengerAppRoot

Passenger usually uses Apache’s DocumentRoot directive to guess where to find its config.ru file — it assumes config.ru will be right beside the public directory.

This generally works fine, but some users have seen Passenger fail to guess. If Passenger fails to load the Puppet master app and is displaying a generic error message, our first suggestion is to double-check the directory permissions (remember the Apache user must be able to read and traverse all Puppet master application directories), but you can also try explicitly telling Passenger where to find the config.ru file with the PassengerAppRoot directive:

PassengerAppRoot /usr/share/puppet/rack/puppetmasterd

Notes on SSL Verification

When an agent node makes a request to the Puppet master, Apache’s mod_ssl performs the verification of its certificate, and the Puppet master application will trust mod_ssl’s judgment. The two systems communicate via environment variables — Apache must set two variables containing the client’s subject DN and its verification status, and the Puppet master must know which variables to check when it receives a request.

In our example vhost config above, Apache uses the SSLOptions +StdEnvVars directive to make several SSL-related environment variables available; a full list of these variables is available here. It then uses these variables to construct several RequestHeader set directives, which put the information into the X-Client-DN and X-Client-Verify HTTP headers. The common gateway interface (CGI) standard converts all HTTP headers to environment variables and munges their names (an HTTP_ prefix is added, dashes are converted to underscores, and all letters are uppercased), and Puppet uses these environment variables, which have become the default names we mentioned above (HTTP_X_CLIENT_DN and HTTP_X_CLIENT_VERIFY).

Alternately, you could leave off the RequestHeader directives and use the SSL_CLIENT_S_DN and SSL_CLIENT_VERIFY variables directly, but this is a less standard way to do it, is tied specifically to Apache and mod_ssl, and requires changing your puppet.conf.

Start or Restart the Apache service

Ensure that any WEBrick Puppet master process is stopped before starting
the Apache service; only one can be bound to TCP port 8140.

Debian/Ubuntu:

$ sudo /etc/init.d/apache2 restart

RHEL/CentOS:

$ sudo /etc/init.d/httpd restart

If all works well, you’ll want to make sure the WEBrick service no longer starts on boot: