The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

« Previous - Version 10/25 (diff) - Next » - Current version
Klavs Klavsen, 08/04/2010 06:41 am


Using Passenger

This support is present in release 0.24.6 and later versions only – it is not supported in earlier releases This documentation is found in updated form in each puppet release source tarball under ext/rack folder – look there for correct info for your puppet version

Alternatively see: Using Mongrel

Why You’d Do This

Traditionally, the puppetmaster would embed a WEBrick or Mongrel Web Server to serve the puppet clients. This may work well for you, but a few people feel like using a proven web server like Apache would be superior for this purpose.

What is Passenger ?

Passenger (AKA mod_rails or mod_rack) is the Apache 2.x Extension which lets you run Rails or Rack applications inside Apache.

Puppet (>0.24.6) now ships with a Rack application which can embed a puppetmaster. While it should be compatible with every Rack application server, it has only been tested with Passenger.

Depending on your operating system, the versions of Puppet, Apache and Passenger may not support this implementation. Specifically, Ubuntu Hardy ships with an older version of puppet (0.24.4) and doesn’t include passenger at all, however updated packages for puppet can be found here. There are also some passenger packages there, but as of 2009-09-28 they do not seem to have the latest passenger (2.2.5), so better install passenger from a gem as per the instructions at [modrails.com].

Dependency versions

Puppet: (>0.24.6)

Passenger: See below

Rack: version 1.0.0 is known to work. 0.3.0 is known to NOT work

JJM Recommended Versions: As of July 2010, Passenger 2.2.11 and Rack 1.0.1 are confirmed to be working. To install, gem install -v=1.0.1 rack, gem install -v=2.2.11 passenger

Note: Passenger versions 2.2.3 and 2.2.4 have known bugs regarding to the SSL environment variables, which make them unsuitable for hosting a puppetmaster. So use either 2.2.2, or 2.2.5. Note that while it was expected that Passenger 2.2.2 would be the last version which can host a 0.24.x puppetmaster, that turns out to be not true, cf. this bug report. So, passenger 2.2.5 works fine.

Another Note: It appears that the Rack 0.4.0 distributed in EPEL does not work with Puppet 0.25.5 or 0.26 (git as of 2010-07-09). Updating Rack to 1.0.1 as recommended above makes things start working.

Installation Summary for Debian/Ubuntu and RHEL5

Please see ext/rack/README in the puppet source tree for instructions.

Whatever you do, make sure your config.ru file is owned by the puppet user! Passenger will setuid to that user.

Make sure puppetmasterd ran at least once, so puppetmasterd SSL certificates are setup initially.

Setup your puppet.conf

Make sure you have the following set in your puppetmaster’s puppet.conf:

[puppetmasterd]] ssl_client_header = SSL_CLIENT_S_DN ssl_client_verify_header = SSL_CLIENT_VERIFY

Install Apache2, Rack and Passenger

For Debian/Ubuntu you just need to do the following (no gems needed):

apt-get install apache2 libapache2-mod-passenger librack-ruby

NOTE: you should have 0.25.4-6 or later of the puppetmaster package installed NOTE2: if you are running Debian Stable (ie. Lenny), you will need to use the backports.org packages, specifically make sure you install at least version 2.2.11debian-1~bpo50+1 of libapache2-mod-passenger, and 1.0.0-2~bpo50+1 of librack-ruby. The rack library in Lenny is too old, and passenger does not exist in Lenny.

For RHEL5 (needs the EPEL repository enabled) do the following:

yum install httpd httpd-devel ruby-devel rubygems
The latest version of Passenger (2.2.5) appears to work fine on RHEL5:
gem install rack
gem install passenger
passenger-install-apache2-module

If you want the older 2.2.2 gem, you could manually download the .gem file from [RubyForge](http://rubyforge.org/frs/?group_id=5873). Or, you could just add the
correct versions to your gem command:

  gem install -v 0.4.0 rack
  gem install -v 2.2.2 passenger 

Enable Apache modules "ssl" and "headers":

# for RHEL5
yum install mod_ssl

# Debian and Ubuntu have these enabled by default, but if you need to, this is how you enable them:
a2enmod ssl
a2enmod headers

Configure Apache

For Debian/Ubuntu:

cp /usr/share/doc/puppetmaster/examples/apache2.conf /etc/apache2/sites-available/puppetmasterd  (see below for the file contents)
$EDITOR /etc/apache2/conf.d/puppetmasterd (replace the hostnames)
a2ensite puppetmasterd

For RHEL5:

cp puppetmaster.conf /etc/httpd/conf.d/ (see below for file contents)
vim /etc/httpd/conf.d/puppetmaster.conf (replace hostnames with corrent values)

Install the rack application [1] (Debian users do not need to do this)

mkdir -p /usr/share/puppet/rack/puppetmasterd
mkdir /usr/share/puppet/rack/puppetmasterd/public /usr/share/puppet/rack/puppetmasterd/tmp
cp config.ru /usr/share/puppet/rack/puppetmasterd
chown puppet /usr/share/puppet/rack/puppetmasterd/config.ru

Restart apache:

# For Debian/Ubuntu
/etc/init.d/puppetmaster stop - make sure puppetmaster is stopped before you continue
/etc/init.d/apache2 restart

# For RHEL5
/etc/init.d/httpd restart

If all works well, you’ll want to make sure your puppmetmasterd init script does not get called anymore:

# For Debian/Ubuntu
$EDITOR /etc/default/puppetmaster - change START=yes to START=no

# For RHEL5
chkconfig puppetmaster off
chkconfig httpd on

[1] Passenger will not let applications run as root or the Apache user, instead an implicit setuid will be done, to the user whom owns config.ru. Therefore, config.ru shall be owned by the puppet user.

Apache Configuration for Puppet 0.24.x

This Apache Virtual Host configures the puppetmaster on the default puppetmaster port (8140).

Listen 8140
<VirtualHost *:8140>

    SSLEngine on
    SSLCipherSuite SSLv2:-LOW:-EXPORT:RC4+RSA
    SSLCertificateFile      /var/lib/puppet/ssl/certs/puppet-server.inqnet.at.pem
    SSLCertificateKeyFile   /var/lib/puppet/ssl/private_keys/puppet-server.inqnet.at.pem
    SSLCertificateChainFile /var/lib/puppet/ssl/ca/ca_crt.pem
    SSLCACertificateFile    /var/lib/puppet/ssl/ca/ca_crt.pem
    # CRL checking should be enabled; if you have problems with Apache complaining about the CRL, disable the next line
    SSLCARevocationFile     /var/lib/puppet/ssl/ca/ca_crl.pem
    SSLVerifyClient optional
    SSLVerifyDepth  1
    SSLOptions +StdEnvVars

    # The following client headers allow the same configuration to work with Pound.
    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

    RackAutoDetect On
    DocumentRoot /usr/share/puppet/rack/puppetmasterd/public/
    <Directory /usr/share/puppet/rack/puppetmasterd/>
        Options None
        AllowOverride None
        Order allow,deny
        allow from all
    </Directory>
</VirtualHost>

If the current puppetmaster is not a certificate authority, you may need to change the following lines. The certs/ca.pem file should exist as long as the puppetmaster has been signed by the CA.

  SSLCertificateChainFile /var/lib/puppet/ssl/certs/ca.pem
  SSLCACertificateFile    /var/lib/puppet/ssl/certs/ca.pem

For RHEL hosts you may need to add:

   LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.2.5/ext/apache2/mod_passenger.so
   PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.2.5
   PassengerRuby /usr/bin/ruby

For details about enabling and configuring Passenger, see the Passenger install guide.

The config.ru file for Puppet 0.24.x

# This file is mostly based on puppetmasterd, which is part of
# the standard puppet distribution.

require 'rack'
require 'puppet'
require 'puppet/network/http_server/rack'

# startup code stolen from bin/puppetmasterd
Puppet.parse_config
Puppet::Util::Log.level = :info
Puppet::Util::Log.newdestination(:syslog)
# A temporary solution, to at least make the master work for now.
Puppet::Node::Facts.terminus_class = :yaml
# Cache our nodes in yaml.  Currently not configurable.
Puppet::Node.cache_class = :yaml


# The list of handlers running inside this puppetmaster
handlers = {
    :Status => {},
    :FileServer => {},
    :Master => {},
    :CA => {},
    :FileBucket => {},
    :Report => {}
}

# Fire up the Rack-Server instance
server = Puppet::Network::HTTPServer::Rack.new(handlers)

# prepare the rack app
app = proc do |env|
    server.process(env)
end

# Go.
run app

If you don’t want to run with the CA enabled, you could drop the :CA => {} line from the config.ru above.

The config.ru file for 0.25.x

Please see ext/rack in the 0.25 source tree for the proper config.ru file.

Suggested Tweaks

Based upon my (Larry Ludwig) testing of passenger/puppetmasterd I recommend adjusting these options in your apache configuration.

  • PassengerPoolIdleTime 300 – Set to 5 min (300 seconds) or less. The shorting this option allows for puppetmasterd to get refreshed at some interval. This option is also somewhat dependent upon the amount of puppetd nodes connecting and at what interval.
  • PassengerMaxPoolSize 15 – to 15% more instances than what’s needed. This will allow idle puppetmasterd to get recycled. The net effect is less memory will be used, not more.
  • PassengerUseGlobalQueue on – Since communication with the puppetmaster from puppetd is a long process (more than 20 seconds in most cases) and will allow for processes to get recycled better
  • PassengerHighPerformance on – The additional Passenger features for apache compatibility are not needed with Puppet.

No different than with traditional web servers, once your service starts using swap performance degradation will occur. So be mindful of your memory/swap usage on your Puppetmaster.

To monitor the age of your puppetmasterd processes within Passenger, run

passenger-status | grep PID | sort

  PID: 14590   Sessions: 1    Processed: 458     Uptime: 3m 40s
  PID: 7117    Sessions: 0    Processed: 10980   Uptime: 1h 43m 41s
  PID: 7355    Sessions: 0    Processed: 9736    Uptime: 1h 38m 38s
  PID: 7575    Sessions: 0    Processed: 9395    Uptime: 1h 32m 27s
  PID: 9950    Sessions: 0    Processed: 6581    Uptime: 1h 2m 35s

My personal preference is having Passenger recycling puppetmasterd every few hours to ensure memory/garbage collection from Ruby is not a factor.

Troubleshooting

JJM GOTCHA: When working with Apache, make sure the CA certificate and the SSL certificate configured contain a different CN field. For example, if /etc/puppet/ssl/certs/hyel.puppetlabs.lan.pem and /etc/puppet/ssl/ca/ca_crt.pem have the same CN field, Apache will have an issue verifying certificate revocation lists. The error received looks like: err: Could not retrieve catalog from remote server: tlsv1 alert decrypt error. To fix, use the —ca_name configuration setting/option, e.g. ca_name = “Puppet CA”