Puppet

# Mongrel and Apache on Enterprise Linux

This is a sample configuration process to configure the Puppet

Master to use Mongrel behind an Apache Proxy Balancer on Enterprise

Linux, i.e. Red Hat, CentOS or Oracle. This has been tested on

CentOS 5 and Oracle Enterprise Linux 5, but should also work for

EL4 distributions.

## Prerequisites

Enable and configure the appropriate Yum repositories. Puppet and

Facter can be found in the

[EPEL](https://fedoraproject.org/wiki/EPEL) repository. You

should follow the instructions on that site to enable EPEL prior to

starting this process. You should also ensure that your chosen

package manager (up2date or yum) is configured correctly.

*In this example I use **puppet.server.fqdn** to represent the fully qualified domain name of your Puppet Master. You should be sure to use your own fully qualified domain name instead of my example. This should be set in **/etc/hosts** and **/etc/sysconfig/network** before you start. Ensure that the **/etc/hosts** entry points to your proper IP address and is not set to 127.0.0.1.*

Sample **/etc/hosts**:

    # Do not remove the following line, or various programs

    # that require network functionality will fail.

    127.0.0.1       localhost.localdomain   localhost

    192.168.0.1     puppet.server.fqdn puppet

Note that Puppet clients try to connect to a server called "puppet"

unless otherwise configured. You should add a DNS CNAME of "puppet"

for your Puppet Master and ensure that the **/etc/resolv.conf**

contains an appropriate *search* line so that your clients can

successfully resolve the "puppet" alias. Both the fully qualified

domain name *and* the "puppet" alias should be resolvable.

## Puppet Master RPM Installation

To install the Puppet Master, run the following as root:

    # yum install subversion puppet-server rubygem-mongrel

*(You may need to use **up2date** instead of **yum** if you are running Red Hat Enterprise Linux 4 or Oracle Enterprise Linux).*

This will install all the necessary RPMs.

## Puppet Master Configuration

Either use the [[Simplest Puppet Install Recipe]] to get started or

copy your existing manifests to **/etc/puppet**. At the very least,

you should have a **site.pp** file in **/etc/puppet/manifests/** so

that the Puppet Master can start successfully.

Next, start the Puppet Master once to create local certificates:

    # service puppetmaster start

    # service puppetmaster stop

This first run is required to create the following certificates:

    ./ssl/private_keys/puppet.server.fqdn.pem

    ./ssl/public_keys/puppet.server.fqdn.pem

    ./ssl/ca/signed/puppet.server.fqdn.pem

    ./ssl/certs/puppet.server.fqdn.pem

if *./ssl/certs/puppet.server.fqdn.pem* doesn't exist type :

    # puppetca --generate puppet.server.fqdn

These certificates are used for the Apache Proxy configuration and

must exist before you continue. You can verify that Puppet has

successfully created these certificates by issuing the command:

    # puppetca --list --all

This should list the Puppet Master as a signed certificate. Once

this has been verified, edit **/etc/sysconfig/puppetmaster** to

enable the Mongrel-based webserver by uncommenting the following

line:

    PUPPETMASTER_PORTS=( 18140 18141 18142 18143 )

This will configure the Puppet Master to start using the Mongrel

webserver on all four specified ports. You can verify this by

issuing:

    # service puppetmaster start

The startup sequence should show all four ports starting up

successfully. If this is true, then set the service to start

automatically on boot:

    # chkconfig puppetmaster on

## Apache Proxy Configuration

Apache is used to provide an SSL proxy from the Puppet clients to

the four Mongrel-based Puppet Master servers. First, ensure that

Apache is installed with SSL support:

    # yum install httpd mod_ssl

*(Again, you may need to use **up2date** instead of **yum** in certain circumstances).*

You can now create the following configuration file at

**/etc/httpd/conf.d/puppet.conf**:

    Listen 8140

    <Proxy balancer://puppetmaster>

            BalancerMember http://127.0.0.1:18140

            BalancerMember http://127.0.0.1:18141

            BalancerMember http://127.0.0.1:18142

            BalancerMember http://127.0.0.1:18143

    </Proxy>

    <VirtualHost *:8140>

            SSLEngine On

            SSLCipherSuite SSLv2:-LOW:-EXPORT:RC4+RSA

            SSLCertificateFile /var/lib/puppet/ssl/certs/puppet.server.fqdn.pem

            SSLCertificateKeyFile /var/lib/puppet/ssl/private_keys/puppet.server.fqdn.pem

            SSLCertificateChainFile /var/lib/puppet/ssl/ca/ca_crt.pem

            SSLCACertificateFile /var/lib/puppet/ssl/ca/ca_crt.pem

            SSLCARevocationFile /var/lib/puppet/ssl/ca/ca_crl.pem

            SSLVerifyClient require

            SSLVerifyDepth 1

            SSLOptions +StdEnvVars

            RequestHeader set X-Client-DN %{SSL_CLIENT_S_DN}e

            RequestHeader set X-Client-Verify %{SSL_CLIENT_VERIFY}e

            <Location />

                    SetHandler balancer-manager

                    Order allow,deny

                    Allow from all

            </Location>

            ProxyPass / balancer://puppetmaster/

            ProxyPassReverse / balancer://puppetmaster/

            ProxyPreserveHost On

            ErrorLog /var/log/httpd/balancer_error_log

            CustomLog /var/log/httpd/balancer_access_log combined

            CustomLog /var/log/httpd/balancer_ssl_requests "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

    </VirtualHost>

Note that I reference **puppet.server.fqdn** in the configuration

file. This should be changed to your proper Puppet Master fully

qualified domain name.

You can now test the Apache configuration:

    # service httpd configtest

If you get a “Syntax OK” message, start Apache and configure it to

automatically start on boot:

    # service httpd start

    # chkconfig httpd on

You may see an error like this when starting httpd:

    Starting httpd: (13)Permission denied: make_sock: could not bind to address [::]:8140

    (13)Permission denied: make_sock: could not bind to address 0.0.0.0:8140

    no listening sockets available, shutting down

    Unable to open logs

                                                               [FAILED]

This may be caused by SELinux restrictions. You can fix it with

semanage:

    semanage port -a -t http_port_t -p tcp 8140

    service httpd start

Configuration of the Puppet Master is now complete! Your Puppet

clients will connect to Apache on port 8140 and Apache will balance

those requests across the four Puppet Master Mongrel instances.

# Client certificate verification 

With the apache option:

    SSLVerifyClient optional|require

you control how Apache wil check the client certification. You can either, set the different certificate request path to not require verification, or disable it (unless you have another ca server or another way of distributing the certificates). So:

 * by enabling require, you basically say - the client is already suppose to have a certificate that I could verify. If certificate is not signed in puppetmaster you will get the error:

    err: Could not request certificate: SSL_connect returned=1 errno=0 state=SSLv3 read finished A: sslv3 alert handshake failure

 * "optional" will simulate the behaviour of an default standalone puppetmaster (without apache).