Setting up Nginx + Passenger¶

Passenger packages/repos are available at http://passenger.stealthymonkeys.com/

Nginx + Passenger with foreman on CentOS¶

Install packages

    # yum install -y nginx-passenger

Create self signed certificate

    # cd /etc/nginx/
    # openssl genrsa -des3 -out server.key 1024
    # openssl req -new -key server.key -out server.csr
    # cp server.key server.key.org
    # openssl rsa -in server.key.org -out server.key
    # openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Make a local copy of the apps `public` directory (local to rails, as nginx/passenger doesn't seem to like symbolic links)

    # cd /usr/share/foreman
    # rm public
    # cp -a /var/lib/foreman/public .

Add to `/etc/nginx/nginx.conf`:

    env PATH;

Create foreman application config file `/etc/nginx/conf.d/foreman.conf`:

    server {
        listen 443;
        server_name _;
        ssl on;
        ssl_certificate /etc/nginx/server.crt;
        ssl_certificate_key /etc/nginx/server.key;

        # Verify puppetmaster clients against Puppet CA
        ssl_crl /var/lib/puppet/ssl/ca/ca_crl.pem;
        ssl_client_certificate /var/lib/puppet/ssl/certs/ca.pem;
        ssl_verify_client optional;
        ssl_verify_depth 1;

        access_log /var/log/nginx/foreman_access.log;
        error_log /var/log/nginx/foreman_error.log debug;
        root /usr/share/foreman/public;

        passenger_enabled on;
        passenger_set_cgi_param HTTPS on;
        passenger_set_cgi_param SSL_CLIENT_S_DN $ssl_client_s_dn;
        passenger_set_cgi_param SSL_CLIENT_VERIFY $ssl_client_verify;

        # If using Passenger 5 then something similar to the following should be used, and the corresponding values updated in Settings/Authentication:
        # passenger_env_var HTTPS on;
        # passenger_set_header X-Client-DN $ssl_client_s_dn;       # Set to HTTP_X_CLIENT_DN
        # passenger_set_header X-Client-Verify $ssl_client_verify; # Set to HTTP_X_CLIENT_VERIFY

        #location / {
        #}
    }

The SSL configuration here can verify clients for SSL communications with puppetmaster scripts, as per the Securing Communications with SSL documentation. It verifies clients using the Puppet CA and passes the information to Passenger and Foreman.

This guide uses a self-signed certificate for the Foreman server, so the ENC and report scripts will need to reference the certificate generated here in the :ssl_ca and $foreman_ssl_ca settings.

Nginx + Passenger with foreman 1.2 on RHEL6.x/Scientific Linux¶

To run both puppermaster and foreman 1.2 on the same host using nginx + passenger an upgrade to phusion passenger 4.0 is required. To not break your existing puppetmaster setup, which uses the system supplied ruby follow the following steps:

setup assumes you are upgrading from foreman 1.1 and have a working nginx-passenger setup already.

the current phusion supplied rpm is still a 3 version, so using yum upgrade won't help
yum info passenger-release
Loaded plugins: security
Available Packages
Name        : passenger-release
Arch        : noarch
Version     : 3
Release     : 6.el6
Size        : 5.5 k
Repo        : passenger
Summary     : Phusion Passenger release RPM/Yum repository configuration
URL         : http://passenger.stealthymonkeys.com/
License     : MIT
Description : Phusion Passenger Yum/RPM configuration. This package contains the Yum
            : repository configuration to install & update Phusion Passenger, as
            : well as the GPG signing key to verify them.

So instead use gem to install the correct package (as per: https://www.phusionpassenger.com/download#open_source):

gem install passenger
Fetching: daemon_controller-1.1.4.gem (100%)
Fetching: passenger-4.0.5.gem (100%)
Successfully installed daemon_controller-1.1.4
Successfully installed passenger-4.0.5
2 gems installed
Installing ri documentation for daemon_controller-1.1.4...
Installing ri documentation for passenger-4.0.5...
Installing RDoc documentation for daemon_controller-1.1.4...
Installing RDoc documentation for passenger-4.0.5...

Configure nginx:
you might need to install some packages ( yum install libcurl-devel libcurl )

passenger-install-nginx-module
Welcome to the Phusion Passenger Nginx module installer, v4.0.5.

This installer will guide you through the entire installation process. It
shouldn't take more than 5 minutes in total.

Here's what you can expect from the installation process:

 1. This installer will compile and install Nginx with Passenger support.
 2. You'll learn how to configure Passenger in Nginx.
 3. You'll learn how to deploy a Ruby on Rails application.

Don't worry if anything goes wrong. This installer will advise you on how to
solve any problems.

Press Enter to continue, or Ctrl-C to abort.

--------------------------------------------

Checking for required software...

 * Checking for GNU C compiler...
      Found: yes
      Location: /usr/bin/gcc
 * Checking for GNU C++ compiler...
      Found: yes
      Location: /usr/bin/g++
 * Checking for A download tool like 'wget' or 'curl'...
      Found: yes
      Location: /usr/bin/wget
 * Checking for Ruby development headers...
      Found: yes
      Location: /usr/lib64/ruby/1.8/x86_64-linux/ruby.h
 * Checking for OpenSSL support for Ruby...
      Found: yes
 * Checking for RubyGems...
      Found: yes
 * Checking for Rake (associated with /usr/bin/ruby)...
      Found: yes
      Location: /usr/bin/ruby /usr/bin/rake
 * Checking for rack...
      Found: yes
 * Checking for Curl development headers with SSL support...
      Found: yes
      Version: libcurl 7.19.7
      Usable: yes
      curl-config location: /usr/bin/curl-config
      Supports SSL: yes
      Header location: /usr/include/curl/curl.h
 * Checking for OpenSSL development headers...
      Found: yes
      Location: /usr/include/openssl/ssl.h
 * Checking for Zlib development headers...
      Found: yes
      Location: /usr/include/zlib.h

Stop nginx and update /etc/init.d/nginx to use the correct binary

vi /etc/init.d/nginx
#nginx="/usr/sbin/nginx" 
nginx="/opt/nginx/sbin/nginx" 

Make sure passenger.conf in /etc/nginx/conf,d still points to the system ruby passenger version

# cat passenger.conf

passenger_root /usr/lib/ruby/gems/1.8/gems/passenger-4.0.5;
passenger_ruby /usr/bin/ruby;

Update foreman.conf (do not set the passenger_root)

 # cat foreman.conf

server {
  passenger_ruby /usr/bin/ruby193-ruby;

  .....
}
 <snip>

Start nginx and check if the website is working now.

Post-install setup for Foreman 1.1+ to support certificate authentication via Nginx¶

Starting from Foreman 1.1 it requires a bit more configuration because by default it supports only Apache webserver environment but Foreman also provides a configuration to make it fit to any other webserver.

Log in to the administration area and go to Administer -> Setting page. Find ssl_client_dn_env variable and set its value to HTTP_X_CLIENT_DN . Also find ssl_client_verify_env and set it to HTTP_X_CLIENT_VERIFY .

These modifications are required since nginx behaves a bit different than Apache and passes SSL certificate informations on different way.

If you plan to use Nginx for Puppet Master too, check the corresponding variables in puppet.conf: ssl_client_header and ssl_client_verify_header

http://www.modrails.com/documentation/Users%20guide%20Nginx.html#_configuring_phusion_passenger has more information