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


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.


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

Install the needed dependencies to install the rubygems

Go to the troubleshooting section [[]] there is a paragraph "I use puppet enterprise, what now?" and install

"**" 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/.

$ sudo yum localinstall

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.

$ sudo yum install mysql-devel gcc make

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

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

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

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

# which gem

3. Install rest-client and mysql

#gem install rest-client
#gem install mysql

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

#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)

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.

Cloning the repo

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

# cd /usr/share/
# git clone git:// foreman-proxy

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.

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

Add a log and ssl directory

Create those addtional directories:

# 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 

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

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

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

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 [[]] 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:

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

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

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.

# enable PuppetCA management
:puppetca: true
:ssldir: /etc/puppetlabs/puppet/ssl
:puppetdir: /etc/puppetlabs/puppet

# enable Puppet management
:puppet: true
:puppet_conf: /etc/puppetlabs/puppet/puppet.conf

Allow the foreman-proxy to make puppetca requests

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

foreman-proxy ALL = NOPASSWD : /opt/puppet/sbin/puppetca *
Defaults:foreman-proxy !requiretty

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

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
  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

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 foreman as it's ENC. Make sure if you run pe and oss that the node.rb is the same.

You can get the node.rb file from here:

# cd /etc/puppetlabs/puppet/
# wget -O node.rb
# chmod 550 node.rb
# chown pe-puppet:pe-puppet node.rb

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.

  :url          => "https://foreman.youdomain",  # e.g.
  :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

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

# cd /opt/puppet/lib/ruby/site_ruby/1.8/puppet/reports/
# wget -O foreman.rb
# chmod +x foreman.rb

Now also add the your certs in foreman.rb

# URL of your Foreman installation
# 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" 

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

    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

Restart pe-httpd

Restart the puppetlabs httpd server


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