Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Puppet Module to manage NGINX on various UNIXes
Ruby Puppet HTML Pascal

Merge pull request #571 from mayflower/fix/package-name

Fix possibility to set package name
latest commit e6d1695f82
@jfryman authored

README.markdown

NGINX Module

INSTALLING OR UPGRADING

** Please note **: This module is currently undergoing some structural maintenance. Please take a look at https://github.com/jfryman/puppet-nginx/blob/master/docs/hiera.md before upgrading or installing Version 0.1.0 or greater.

Build Status

This module manages NGINX configuration.

Quick Start

Requirements

  • Puppet-2.7.0 or later
  • Facter 1.7.0 or later
  • Ruby-1.9.3 or later (Support for Ruby-1.8.7 is not guaranteed. YMMV).

Install and bootstrap an NGINX instance

class { 'nginx': }

Setup a new virtual host

nginx::resource::vhost { 'www.puppetlabs.com':
  www_root => '/var/www/www.puppetlabs.com',
}

Add a Proxy Server

nginx::resource::upstream { 'puppet_rack_app':
  members => [
    'localhost:3000',
    'localhost:3001',
    'localhost:3002',
  ],
}

nginx::resource::vhost { 'rack.puppetlabs.com':
  proxy => 'http://puppet_rack_app',
}

Add a smtp proxy

class { 'nginx':
  mail => true,
}

nginx::resource::mailhost { 'domain1.example':
  auth_http   => 'server2.example/cgi-bin/auth',
  protocol    => 'smtp',
  listen_port => 587,
  ssl_port    => 465,
  starttls    => 'only',
  xclient     => 'off',
  ssl         => true,
  ssl_cert    => '/tmp/server.crt',
  ssl_key     => '/tmp/server.pem',
}

SSL configuration

By default, creating a vhost resource will only create a HTTP vhost. To also create a HTTPS (SSL-enabled) vhost, set ssl => true on the vhost. You will have a HTTP server listening on listen_port (port 80 by default) and a HTTPS server listening on ssl_port (port 443 by default). Both vhosts will have the same server_name and a similar configuration.

To create only a HTTPS vhost, set ssl => true and also set listen_port to the same value as ssl_port. Setting these to the same value disables the HTTP vhost. The resulting vhost will be listening on ssl_port.

Locations

Locations require specific settings depending on whether they should be included in the HTTP, HTTPS or both vhosts.

HTTP only vhost (default)

If you only have a HTTP vhost (i.e. ssl => false on the vhost) make sure you don't set ssl => true on any location you associate with the vhost.

HTTP and HTTPS vhost

If you set ssl => true and also set listen_port and ssl_port to different values on the vhost you will need to be specific with the location settings since you will have a HTTP vhost listening on listen_port and a HTTPS vhost listening on ssl_port:

  • To add a location to only the HTTP server, set ssl => false on the location (this is the default).
  • To add a location to both the HTTP and HTTPS server, set ssl => true on the location, and ensure ssl_only => false (which is the default value for ssl_only).
  • To add a location only to the HTTPS server, set both ssl => true and ssl_only => true on the location.

HTTPS only vhost

If you have set ssl => true and also set listen_port and ssl_port to the same value on the vhost, you will have a single HTTPS vhost listening on ssl_port. To add a location to this vhost set ssl => true and ssl_only => true on the location.

Hiera Support

Defining nginx resources in Hiera.

nginx::nginx_upstreams:
  'puppet_rack_app':
    ensure: present
    members:
      - localhost:3000
      - localhost:3001
      - localhost:3002
nginx::nginx_vhosts:
  'www.puppetlabs.com':
    www_root: '/var/www/www.puppetlabs.com'
  'rack.puppetlabs.com':
    proxy: 'http://puppet_rack_app'
nginx::nginx_locations:
  'static':
    location: '~ "^/static/[0-9a-fA-F]{8}\/(.*)$"'
    vhost: www.puppetlabs.com
    www_root: /var/www/html
  'userContent':
    location: /userContent
    vhost: www.puppetlabs.com
    www_root: /var/www/html
nginx::nginx_mailhosts:
  'smtp':
    auth_http: server2.example/cgi-bin/auth
    protocol: smtp
    listen_port: 587
    ssl_port: 465
    starttls: only

Nginx with precompiled Passenger

Currently this works only for Debian family and OpenBSD.

On Debian it might look like:

class { 'nginx':
  package_source  => 'passenger',
  http_cfg_append => {
    'passenger_root' => '/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini',
  }
}

Here the example for OpenBSD:

class { 'nginx':
  package_flavor => 'passenger',
  service_flags  => '-u'
  http_cfg_append => {
    passenger_root          => '/usr/local/lib/ruby/gems/2.1/gems/passenger-4.0.44',
    passenger_ruby          =>  '/usr/local/bin/ruby21',
    passenger_max_pool_size => '15',
  }
}

Package source passenger will add Phusion Passenger repository to APT sources. For each virtual host you should specify which ruby should be used.

nginx::resource::vhost { 'www.puppetlabs.com':
  www_root         => '/var/www/www.puppetlabs.com',
  vhost_cfg_append => {
    'passenger_enabled' => 'on',
    'passenger_ruby'    => '/usr/bin/ruby',
  }
}

Puppet master served by Nginx and Passenger

Virtual host config for serving puppet master:

nginx::resource::vhost { 'puppet':
  ensure               => present,
  server_name          => ['puppet'],
  listen_port          => 8140,
  ssl                  => true,
  ssl_cert             => '/var/lib/puppet/ssl/certs/example.com.pem',
  ssl_key              => '/var/lib/puppet/ssl/private_keys/example.com.pem',
  ssl_port             => 8140,
  vhost_cfg_append     => {
    'passenger_enabled'      => 'on',
    'passenger_ruby'         => '/usr/bin/ruby',
    '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,
  },
  www_root             => '/etc/puppet/rack/public',
  use_default_location => false,
  access_log           => '/var/log/nginx/puppet_access.log',
  error_log            => '/var/log/nginx/puppet_error.log',
  passenger_cgi_param  => {
    'HTTP_X_CLIENT_DN'     => '$ssl_client_s_dn',
    'HTTP_X_CLIENT_VERIFY' => '$ssl_client_verify',
  },
}

Example puppet class calling nginx::vhost with HTTPS FastCGI and redirection of HTTP

$full_web_path = '/var/www'

define web::nginx_ssl_with_redirect (
  $backend_port         = 9000,
  $php                  = true,
  $proxy                = undef,
  $www_root             = "${full_web_path}/${name}/",
  $location_cfg_append  = undef,
) {
  nginx::resource::vhost { "${name}.${::domain}":
    ensure              => present,
    www_root            => "${full_web_path}/${name}/",
    location_cfg_append => { 'rewrite' => '^ https://$server_name$request_uri? permanent' },
  }

  if !$www_root {
    $tmp_www_root = undef
  } else {
    $tmp_www_root = $www_root
  }

  nginx::resource::vhost { "${name}.${::domain} ${name}":
    ensure                => present,
    listen_port           => 443,
    www_root              => $tmp_www_root,
    proxy                 => $proxy,
    location_cfg_append   => $location_cfg_append,
    index_files           => [ 'index.php' ],
    ssl                   => true,
    ssl_cert              => 'puppet:///modules/sslkey/wildcard_mydomain.crt',
    ssl_key               => 'puppet:///modules/sslkey/wildcard_mydomain.key',
  }


  if $php {
    nginx::resource::location { "${name}_root":
      ensure          => present,
      ssl             => true,
      ssl_only        => true,
      vhost           => "${name}.${::domain} ${name}",
      www_root        => "${full_web_path}/${name}/",
      location        => '~ \.php$',
      index_files     => ['index.php', 'index.html', 'index.htm'],
      proxy           => undef,
      fastcgi         => "127.0.0.1:${backend_port}",
      fastcgi_script  => undef,
      location_cfg_append => {
        fastcgi_connect_timeout => '3m',
        fastcgi_read_timeout    => '3m',
        fastcgi_send_timeout    => '3m'
      }
    }
  }
}

Add custom fastcgi_params

nginx::resource::location { "some_root":
  ensure         => present,
  location       => '/some/url',
  fastcgi        => "127.0.0.1:9000",
  fastcgi_param  => {
    'APP_ENV' => 'local',
  },
}

Call class web::nginx_ssl_with_redirect

web::nginx_ssl_with_redirect { 'sub-domain-name':
    backend_port => 9001,
  }
Something went wrong with that request. Please try again.