h1.  passenger on Puppet PE and use foreman as an ENC and reporting engine 

h2. Overview

This how to describes the steps to install foreman's smart proxy on puppet enterprise 2.7.2 with the embedded puppet labs ruby version. It also walks you thru the steps of modifying the reporting engine to "foreman reports" and use "the foreman" as it's ENC. 

h2. Requirements

1. Internet access as you need to do some git pulls and install some rubygems

2. The puppet enterprise tar ball (puppet-enterprise-2.7.2-el-6-x86_64.tar.gz) which you can download from the puppet labs website.

3. A working foreman 1.1 or higher host

h3. Install the needed dependencies to install the rubygems

Go to the troubleshooting section [[http://projects.theforeman.org/projects/foreman/wiki/Troubleshooting]] there is a paragraph "I use puppet enterprise, what now?" and install 

"*pe-ruby-devel-1.8.7.370-1.pe.el6.x86_64.rpm*" from your unpacked puppet-enterprise tar ball. You can find the rpm in puppet-enterprise-2.7.2-el-6-x86_64/packages/el-6-x86_64/. 

<pre>

$ sudo yum localinstall pe-ruby-devel-1.8.7.370-1.pe.el6.x86_64.rpm

</pre>

Pupppet pe 2.7.2 comes with mysql as a database back end. This means we need the mysql-devel to build the mysql rubygem package. 

<pre>

$ sudo yum install mysql-devel gcc make

</pre>

Now follow the steps copied from the trouble shooting wiki page. 

1. Update your path variable to use the ruby version PE ships with 

<pre>

# export PATH=/opt/puppet/bin:$PATH

</pre>

2. Check to make sure your PATH was updated ("which gem" should return /opt/puppet/bin/gem)

<pre>

# which gem

/opt/puppet/bin/gem

</pre>

3. Install json rest-client and mysql 

<pre>

#gem install json

#gem install rest-client

#gem install mysql

</pre>

4. If everything went fine you should see the following output if you list the gem's

<pre>

#gem list

activerecord (2.3.17)

activesupport (2.3.17)

ar-extensions (0.9.5)

builder (3.0.0)

dalli (1.1.2)

excon (0.14.1)

fog (1.5.0)

formatador (0.2.0)

guid (0.1.1)

hiera (0.3.0)

hiera-puppet (0.3.0)

json (1.7.7)

mime-types (1.16)

multi_json (1.0.3)

mysql (2.9.1)

net-scp (1.0.4)

net-ssh (2.1.4)

nokogiri (1.5.0)

rack (1.1.6)

rack_csrf (2.4.0)

rake (0.8.7)

rbvmomi (1.3.0)

rest-client (1.6.7)

ruby-hmac (0.4.0)

sinatra (1.2.6)

stomp (1.1.9)

tilt (1.3.3)

trollop (1.16.2)

</pre>

h2. Install the smart-proxy from git

As we need to modify some ruby files (for [[ mcollective ]] ) along the way, cloning the smart-proxy from git seemed to be the best way to go. 

h3. Cloning the repo

You can download the zip file or just clone the latest smart proxy with git. 

<pre>

# cd /usr/share/

# git clone git://github.com/theforeman/smart-proxy.git foreman-proxy

</pre>

h3. Create the foreman-proxy group / user 

Add the foreman-proxy user and group to the system and make the foreman-proxy user part of the pe-puppet and pe-apache group. 

<pre>

# useradd -r foreman-proxy

# usermod -G pe-puppet,pe-apache foreman-proxy

</pre>

h3. Add a log and ssl directory

Create those addtional directories: 

<pre>

# mkdir -p /var/log/foreman-proxy/

# mkdir -p /usr/share/foreman-proxy/ssl

# mkdir -p /usr/share/foreman-proxy/ssl/certs

# mkdir -p /usr/share/foreman-proxy/ssl/private_keys 

</pre>

After adding the user, log and ssl directory, cd into the foreman-proxy folder and change the following permissions for config.ru, logs and ssl.

<pre>

# chown foreman-proxy:root config.ru

# chown -R foreman-proxy:root ssl 

# chown -R foreman-proxy:foreman-proxy /var/log/foreman-proxy

</pre>

The reason why we change the permission on config.ru is, because we want apache/passenger to spawn an new process as user foreman-proxy and NOT as root. 

h3. Configure the foreman-proxy settings.yml

Its recommended to have ssl enabled in prod envronments so we need to uncomment these 3 lines, 

ssl_certificate: ssl/certs/fqdn.pem (created on foreman)

ssl_ca_file: ssl/certs/ca.pem (this is the foreman ca.pem)

ssl_private_key: ssl/private_keys/fqdn.key (created on foreman)

and generate a new certificate for the connection between the foreman-proxy and the foreman host. As we do not want to waste puppet enterprise licenses for the apache ssl connection we create the certificate on the foreman host which has puppet oss installed. 

You can follow the foreman manual on section 4.3.6 SSL [[http://theforeman.org/manuals/1.1/index.html#4.3.6SSL]] to create the certificates on the foreman host

To generate a certificate for a proxy host that isn't managed by Puppet or is but you do not want to use the certs from it, do the following:

Generate a new certificate on your puppetmaster: 

<pre>

puppet cert --generate <proxy-FQDN> (which is your puppet-enterprise host)

 </pre>

Copy the certificates and key from the puppetmaster (foreman host)  to the smart proxy (puppet enterprise) to  /usr/share/foreman-proxy/ssl :

<pre>

/usr/share/foreman-proxy/ssl/certs/ca.pem

/usr/share/foreman-proxy/ssl/certs/proxy-FQDN.pem

/usr/share/foreman-proxy/ssl/private_keys/proxy-FQDN.pem

</pre>

Please pay attentions that these are NOT the same certs as you are createing on the puppet enterprise CA! these are created by the foreman open source puppetmaster!

You also have to enable the PuppetCA and Puppet management if your puppet master and ca is on the puppet enterprise host. 

<pre>

# enable PuppetCA management

:puppetca: true

:ssldir: /etc/puppet/ssl

:puppetdir: /etc/puppet

# enable Puppet management

:puppet: true

:puppet_conf: /etc/puppet/puppet.conf

</pre>

h3. Allow the foreman-proxy to make puppetca requests

Add the following content to /etc/sudoers.d/foreman-proxy

<pre>

foreman-proxy ALL = NOPASSWD : /usr/sbin/puppetca *

Defaults:foreman-proxy !requiretty

</pre>

h3. Adding the smart-proxy configuration to the puppet httpd directory

You can find the pe-apache folder in /etc/puppetlabs/httpd/conf.d/

Create the follwing file 12-pe-httpd-foreman-proxy.conf 

<pre>

Listen 8443

<VirtualHost YOURIP:8443>

  ServerName puppet-enterprise-fqdn

  SetEnv HOME /usr/share/foreman-proxy

    RailsAutoDetect On

  RailsEnv production

  DocumentRoot /usr/share/foreman-proxy/public

  PassengerAppRoot /usr/share/foreman-proxy

  AddDefaultCharset UTF-8

  SSLEngine On

  SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:-LOW:-SSLv2:-EXP

  SSLProtocol ALL -SSLv2

  SSLCertificateFile      /usr/share/foreman-proxy/ssl/certs/puppet-enterprise-fqdn.pem

  SSLCertificateKeyFile   /usr/share/foreman-proxy/ssl/private_keys/puppet-enterprise-fqdn.pem

  SSLCertificateChainFile /usr/share/foreman-proxy/ssl/certs/ca.pem

  SSLCACertificateFile    /usr/share/foreman-proxy/ssl/certs/ca.pem

  SSLVerifyClient         optional

  SSLOptions              +StdEnvVars

  SSLVerifyDepth          3

  Loglevel Debug

  CustomLog /usr/share/foreman-proxy/logs/access.log combined

  ErrorLog /usr/share/foreman-proxy/logs/error.log

</VirtualHost>

</pre>

h2. Now that we have setup the foreman-proxy we need to add the node.rb file to the /etc/puppetlabs/puppet/ directory so that puppet requests the information from the forman host ENC

You can get the latest node.rb file from here: 

https://github.com/theforeman/puppet-foreman/blob/master/templates/external_node.rb.erb

<pre>

# cd /etc/puppetlabs/puppet/

# git clone https://github.com/theforeman/puppet-foreman/blob/master/templates/external_node.rb.erb node.rb

# chmod +x node.rb

</pre>

h3. Edit node.rb and add the correct url and certificates

That the foreman host and the foreman-proxy host can toak to each other in a secure way, edit the node.rb file and add your certs.

<pre>

SETTINGS = {

  :url          => "https://foreman.youdomain",  # e.g. https://foreman.example.com

  :puppetdir    => "/var/opt/lib/pe-puppet",  #  This is the puppet enterprise dir

  :facts        => true,          # true/false to upload facts

  :storeconfigs => true,   # true/false if sharing ActiveRecord-storeconfigs

  :timeout      => 10,

  # if CA is specified, remote Foreman host will be verified

  :ssl_ca       => "/usr/share/foreman-proxy/ssl/certs/ca.pem",      #  This is the ca.pem form you puppet opensource foreman host

  # ssl_cert and key are required if require_ssl_puppetmasters is enabled in Foreman

  :ssl_cert     => "/usr/share/foreman-proxy/ssl/certs/puppet-enterprise-fqdn.pem",    #  This is the fqdn.pem form you puppet opensource foreman host

  :ssl_key      => "/usr/share/foreman-proxy/ssl/private_keys/puppet-enterprise-fqdn.pem"  # This is the fqdn.pem form you puppet opensource foreman host

</pre>

h3. Add the foreman.rb report to the puppetlabs ruby report dir

<pre>

# cd /opt/puppet/lib/ruby/site_ruby/1.8/puppet/reports/

# git clone https://github.com/theforeman/puppet-foreman/blob/master/templates/foreman-report.rb.erb foreman.rb

# chmod +x foreman.rb

</pre>

Now also add the your certs in foreman.rb

<pre>

# URL of your Foreman installation

$foreman_url='https://foreman.yourdomain

# if CA is specified, remote Foreman host will be verified

$foreman_ssl_ca = "/usr/share/foreman-proxy/ssl/certs/ca.pem"

# ssl_cert and key are required if require_ssl_puppetmasters is enabled in Foreman

$foreman_ssl_cert = "/usr/share/foreman-proxy/ssl/certs/puppet-enterprise-fqdn.pem"

$foreman_ssl_key = "/usr/share/foreman-proxy/ssl/private_keys/puppet-enterprise-fqdn.pem"

</pre>

h3. After adding all these files we need to modify the master section in the puppet.conf file. 

<pre>

[master]

    reports = foreman

    node_terminus = exec

    external_nodes = /etc/puppetlabs/puppet/node.rb

    ### foreman settings

    privatekeydir = $ssldir/private_keys { group = service }

    hostprivkey = $privatekeydir/$certname.pem { mode = 640 }

    #### for passenger

    ssl_client_header = SSL_CLIENT_S_DN

    ssl_client_verify_header = SSL_CLIENT_VERIFY

</pre>

h3. Restart pe-httpd

Restart the puppetlabs httpd server

<pre>

 /etc/init.d/pe-httpd

</pre>

h2. Add the smart-proxy to the Foreman's Smart Proxy page

Go to [FOREMAN_URL]/smart_proxies and klick New Proxy

Then you type in the Name for your Proxy and the URL of your Proxy, with the Port you use.

For example:

Name: Puppet-Proxy

URL: http://puppetpe.your-domain.com:8443