Running Puppet from passenger

The WEBrick server we configured in the previous section is not capable of handling a large number of nodes. To deal with a large number of nodes, a scalable web server is required. Puppet is a ruby process, so we need a way to run a ruby process within a web server. Passenger is the solution to this problem. It allows us to run the Puppet master process within a web server (apache by default). Many distributions ship with a puppetmaster-passenger package that configures this for you. In this section, we'll use the package to configure Puppet to run within passenger.

Getting ready

Install the puppetmaster-passenger package:

# puppet resource package puppetmaster-passenger ensure=installed
Notice: /Package[puppetmaster-passenger]/ensure: ensure changed 'purged'
 to 'present'
package { 'puppetmaster-passenger':
 ensure => '3.7.0-1puppetlabs1',
}

Note

Using puppet resource to install packages ensures the same command will work on multiple distributions (provided the package names are the same).

How to do it...

The steps are as follows:

1. Ensure the Puppet master site is enabled in your apache configuration. Depending on your distribution this may be at /etc/httpd/conf.d or /etc/apache2/sites-enabled. The configuration file should be created for you and contain the following information:

   PassengerHighPerformance on
   PassengerMaxPoolSize 12
   PassengerPoolIdleTime 1500
   # PassengerMaxRequests 1000
   PassengerStatThrottleRate 120
   RackAutoDetect Off
   RailsAutoDetect Off
   Listen 8140
   

2. These lines are tuning settings for passenger. The file then instructs apache to listen on port 8140, the Puppet master port. Next a VirtualHost definition is created that loads the Puppet CA certificates and the Puppet master's certificate:

   <VirtualHost *:8140>
    SSLEngine on
    SSLProtocol ALL -SSLv2 -SSLv3
    SSLCertificateFile /var/lib/puppet/ssl/certs/puppet.pem
    SSLCertificateKeyFile /var/lib/puppet/ssl/private_keys/puppet.pem
    SSLCertificateChainFile /var/lib/puppet/ssl/certs/ca.pem
    SSLCACertificateFile /var/lib/puppet/ssl/certs/ca.pem
    SSLCARevocationFile /var/lib/puppet/ssl/ca/ca_crl.pem
    SSLVerifyClient optional
    SSLVerifyDepth 1
    SSLOptions +StdEnvVars +ExportCertData
   

   Tip

   You may have more or less lines of SSL configuration here depending on your version of the puppetmaster-passenger package.

3. Next, a few important headers are set so that the passenger process has access to the SSL information sent by the client node:

   RequestHeader unset X-Forwarded-For
   RequestHeader set X-SSL-Subject %{SSL_CLIENT_S_DN}e
   RequestHeader set X-Client-DN %{SSL_CLIENT_S_DN}e
   RequestHeader set X-Client-Verify %{SSL_CLIENT_VERIFY}e
   

4. Finally, the location of the passenger configuration file config.ru is given with the DocumentRoot location as follows:

    DocumentRoot /usr/share/puppet/rack/puppetmasterd/public/
    RackBaseURI /
   

5. The config.ru file should exist at /usr/share/puppet/rack/puppetmasterd/ and should have the following content:

   $0 = "master"
   ARGV << "--rack"
   ARGV << "--confdir" << "/etc/puppet"
   ARGV << "--vardir" << "/var/lib/puppet"
   require 'puppet/util/command_line'
   run Puppet::Util::CommandLine.new.execute
   

6. With the passenger apache configuration file in place and the config.ru file correctly configured, start the apache server and verify that apache is listening on the Puppet master port (if you configured the standalone Puppet master previously, you must stop that process now using service puppetmaster stop):

   root@puppet:~ # service apache2 start
   [ ok ] Starting web server: apache2
   root@puppet:~ # lsof -i :8140
   COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
   apache2 9048 root 8u IPv6 16842 0t0 TCP *:8140 (LISTEN)
   apache2 9069 www-data 8u IPv6 16842 0t0 TCP *:8140 (LISTEN)
   apache2 9070 www-data 8u IPv6 16842 0t0 TCP *:8140 (LISTEN)
   

How it works...

The passenger configuration file uses the existing Puppet master certificates to listen on port 8140 and handles all the SSL communication between the server and the client. Once the certificate information has been dealt with, the connection is handed off to a ruby process started from passenger using the command line arguments from the config.ru file.

In this case, the $0 variable is set to master and the arguments variable is set to --rack --confdir /etc/puppet --vardir /var/lib/puppet; this is equivalent to running the following from the command line:

puppet master --rack --confdir /etc/puppet --vardir /var/lib/puppet

There's more...

You can add additional configuration parameters to the config.ru file to further alter how Puppet runs when it's running through passenger. For instance, to enable debugging on the passenger Puppet master, add the following line to config.ru before the run Puppet::Util::CommandLine.new.execute line:

ARGV << "--debug"