Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/voxpupuli/puppet-nginx
Puppet Module to manage NGINX on various UNIXes
https://github.com/voxpupuli/puppet-nginx
archlinux-puppet-module bsd-puppet-module centos-puppet-module debian-puppet-module freebsd-puppet-module hacktoberfest linux-puppet-module nginx openbsd-puppet-module puppet redhat-puppet-module sles-puppet-module ubuntu-puppet-module
Last synced: 5 days ago
JSON representation
Puppet Module to manage NGINX on various UNIXes
- Host: GitHub
- URL: https://github.com/voxpupuli/puppet-nginx
- Owner: voxpupuli
- License: mit
- Created: 2011-05-24T01:53:48.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2024-10-22T07:37:03.000Z (2 months ago)
- Last Synced: 2024-12-18T17:21:32.863Z (13 days ago)
- Topics: archlinux-puppet-module, bsd-puppet-module, centos-puppet-module, debian-puppet-module, freebsd-puppet-module, hacktoberfest, linux-puppet-module, nginx, openbsd-puppet-module, puppet, redhat-puppet-module, sles-puppet-module, ubuntu-puppet-module
- Language: Ruby
- Homepage: https://forge.puppet.com/puppet/nginx
- Size: 3.01 MB
- Stars: 471
- Watchers: 79
- Forks: 882
- Open Issues: 121
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# NGINX module for Puppet
[](https://github.com/voxpupuli/puppet-nginx/actions?query=workflow%3ACI)
[](https://coveralls.io/github/voxpupuli/puppet-nginx)
[](https://forge.puppetlabs.com/puppet/nginx)
[](https://forge.puppetlabs.com/puppet/nginx)
[](https://forge.puppetlabs.com/puppet/nginx)
[](https://forge.puppetlabs.com/puppet/nginx)
This module was migrated from James Fryman 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
* [A Quickstart Guide to the NGINX Puppet Module](https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md)
### Install and bootstrap an NGINX instance
```puppet
include nginx
```
### A simple reverse proxy
```puppet
nginx::resource::server { 'kibana.myhost.com':
listen_port => 80,
proxy => 'http://localhost:5601',
}
```
### A virtual host with static content
```puppet
nginx::resource::server { 'www.puppetlabs.com':
www_root => '/var/www/www.puppetlabs.com',
}
```
### A more complex proxy example
```puppet
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
```puppet
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:
```puppet
nginx::resource::upstream { 'puppet_rack_app':
members => {
'localhost:3000',
'localhost:3001',
'localhost:3002',
},
}
```
From now on, the configuration must look like this:
```puppet
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.
```yaml
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
```yaml
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](https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md)
```puppet
class { 'nginx':
package_source => 'passenger',
http_cfg_append => {
'passenger_root' => '/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini',
}
}
```
Here the example for OpenBSD:
```puppet
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](https://oss-binaries.phusionpassenger.com/apt/passenger)
to APT sources. For each virtual host you should specify which ruby should be used.
```puppet
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:
```puppet
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
```puppet
$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
```puppet
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
```puppet
web::nginx_ssl_with_redirect { 'sub-domain-name':
backend_port => 9001,
}
```