Puppet

# Using Passenger

See [http://docs.puppetlabs.com/guides/passenger.html](http://docs.puppetlabs.com/guides/passenger.html) for official docs

**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](http://www.modrails.com/) (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](https://launchpad.net/~bitpusher/+archive/ppa). 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.1.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**

**SDM Passenger 3.0.7 works just fine with Rack 1.2.2 on Red Hat Enterprise Linux 6.**

Pre-compiled passenger RPM's for Enterprise Linux 5 are available at: [http://yum.puppetlabs.com/prosvc/5/](http://yum.puppetlabs.com/prosvc/5/)

n4th4nr1ch verified: rack 1.1.0 with passenger 2.2.15 DOES work and I've updated the versions listed throughout here to reflect those. **As of September 13th 2010 the latest version of rack does NOT work**.

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](http://projects.puppetlabs.com/issues/2386#change-9238). So, passenger 2.2.5 works fine. Passenger 2.2.15 is known working.

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](http://github.com/puppetlabs/puppet/tree/master/ext/rack) 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 rails librack-ruby libmysql-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](http://backports.org), 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](https://fedoraproject.org/wiki/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 -v 1.1.0 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 and RHEL6:

        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/sites-available/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 (look below on where to find this file)

    chown puppet /usr/share/puppet/rack/puppetmasterd/config.ru

For RHEL6:

    cp /usr/share/puppet/ext/rack/files/apache2.conf /etc/httpd/conf.d/rack.conf

    vim /etc/httpd/conf.d/puppetmaster.conf (replace cert paths/filenames with corrent values)

    mkdir -p /etc/puppet/rack/public

    mkdir -p /etc/puppet/rack/tmp

    cp /usr/share/puppet/ext/rack/files/config.ru /etc/puppet/rack

    chown puppet /etc/puppet/rack/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 and RHEL6

    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 must 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/YOUR-PUPPETMASTER-FQDN.pem

        SSLCertificateKeyFile   /var/lib/puppet/ssl/private_keys/YOUR-PUPPETMASTER-FQDN.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.15/ext/apache2/mod_passenger.so

       PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.2.15

       PassengerRuby /usr/bin/ruby

For details about enabling and configuring Passenger, see the [Passenger install guide](http://www.modrails.com/install.html).

## 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. Same for 26.

## Suggested Tweaks

To simply the management of the Puppet Master service, Jeff McCune recommends setting PassengerMaxRequests in Apache.  This setting automatically restarts the ruby process hosting the puppet master application service and will ensure the process remains fresh without any disruption in service.

    PassengerMaxRequests 10000

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"