Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

nginx

Puppet NGINX management module
Project URLRSS FeedReport issues

48,529,418 downloads

1,463 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 6.0.1 (latest)
  • 6.0.0
  • 5.0.0
  • 4.4.0
  • 4.3.0
  • 4.2.0
  • 4.1.0
  • 4.0.0
  • 3.3.0
  • 3.2.1
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.1.1
  • 2.1.0
  • 2.0.0
  • 1.1.0
  • 1.0.0
  • 0.16.0
  • 0.15.0
  • 0.14.0
  • 0.13.0
  • 0.12.0
  • 0.11.0
  • 0.10.0
  • 0.9.0
  • 0.8.0
  • 0.7.1
  • 0.7.0
  • 0.6.0
  • 0.5.0
  • 0.4.0
released Sep 12th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , OpenBSD, , , , , , SLES, Solaris, AIX, FreeBSD, DragonFly, NetBSD, Archlinux,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppet-nginx', '6.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppet-nginx
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppet-nginx --version 6.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

puppet/nginx — version 6.0.1 Sep 12th 2024

NGINX module for Puppet

Build Status Code Coverage Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores

This module was migrated from James Fryman james@frymanet.com to Vox Pupuli.

INSTALLING OR UPGRADING

This module manages NGINX configuration.

Requirements

  • Puppet 4.6.1 or later. Puppet 3 was supported up until release 0.6.0.
  • apt is now a soft dependency. If your system uses apt, you'll need to configure an appropriate version of the apt module. Version 4.4.0 or higher is recommended because of the proper handling of apt-transport-https.

Additional Documentation

Install and bootstrap an NGINX instance

include nginx

A simple reverse proxy

nginx::resource::server { 'kibana.myhost.com':
  listen_port => 80,
  proxy       => 'http://localhost:5601',
}

A virtual host with static content

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

A more complex proxy example

nginx::resource::upstream { 'puppet_rack_app':
  members => {
    'localhost:3000' => {
      server => 'localhost',
      port   => 3000,
      weight => 1,
    },
    'localhost:3001' => {
      server => 'localhost',
      port   => 3001,
      weight => 1,
    },
    'localhost:3002' => {
      server => 'localhost',
      port   => 3002,
      weight => 2,
      },
  },
}

nginx::resource::server { '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',
  proxy_protocol  => 'off',
  proxy_smtp_auth => 'off',
  ssl             => true,
  ssl_cert        => '/tmp/server.crt',
  ssl_key         => '/tmp/server.pem',
}

Convert upstream members from Array to Hash

The datatype Array for members of a nginx::resource::upstream is replaced by a Hash. The following configuration is no longer valid:

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

From now on, the configuration must look like this:

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

SSL configuration

By default, creating a server resource will only create a HTTP server. To also create a HTTPS (SSL-enabled) server, set ssl => true on the server. 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 servers will have the same server_name and a similar configuration.

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

Idempotency with nginx 1.15.0 and later

By default, this module might configure the deprecated ssl on directive. When you next run puppet, this will be removed since the nginx_version fact will now be available. To avoid this idempotency issue, you can manually set the base class's nginx_version parameter.

Locations

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

HTTP only server (default)

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

HTTP and HTTPS server

If you set ssl => true and also set listen_port and ssl_port to different values on the server you will need to be specific with the location settings since you will have a HTTP server listening on listen_port and a HTTPS server 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 server

If you have set ssl => true and also set listen_port and ssl_port to the same value on the server, you will have a single HTTPS server listening on ssl_port. To add a location to this server 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':
        server: 'localhost'
        port: 3000
      'localhost:3001':
        server: 'localhost'
        port: 3001
      'localhost:3002':
        server: 'localhost'
        port: 3002
nginx::nginx_servers:
  '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}\/(.*)$"'
    server: www.puppetlabs.com
    www_root: /var/www/html
  'userContent':
    location: /userContent
    server: 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

A stream syslog UDP proxy


nginx::stream: true

nginx::nginx_cfg_prepend:
  include:
    - '/etc/nginx/modules-enabled/*.conf'

nginx::nginx_streamhosts:
  'syslog':
    ensure:                 'present'
    listen_port:            514
    listen_options:         'udp'
    proxy:                  'syslog'
    proxy_read_timeout:     '1'
    proxy_connect_timeout:  '1'
    raw_append:
      - 'error_log off;'

nginx::nginx_upstreams:
  'syslog':
    context: 'stream'
    members:
      '10.0.0.1:514':
        server: '10.0.0.1'
        port: 514
      '10.0.0.2:514':
        server: '10.0.0.2'
        port: 514
      '10.0.0.3:514':
        server: '10.0.0.3'
        port: 514

Nginx with precompiled Passenger

Example configuration for Debian and RHEL / CentOS (>6), pulling the Nginx and Passenger packages from the Phusion repo. See additional notes in https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md

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::server { 'www.puppetlabs.com':
  www_root          => '/var/www/www.puppetlabs.com',
  server_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::server { '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,
  server_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::server 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::server { "${name}.${facts['networking']['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::server { "${name}.${facts['networking']['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              => '/path/to/wildcard_mydomain.crt',
    ssl_key               => '/path/to/wildcard_mydomain.key',
  }


  if $php {
    nginx::resource::location { "${name}_root":
      ensure          => present,
      ssl             => true,
      ssl_only        => true,
      server           => "${name}.${facts['networking']['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,
  }