Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README updates #230

Merged
merged 2 commits into from
Jan 9, 2014
Merged

README updates #230

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
12ecdad
add SSL configuration instructions to README
3flex Jan 9, 2014
dd7df92
cleanup README
3flex Jan 9, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 83 additions & 60 deletions README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ class { 'nginx': }

```puppet
nginx::resource::vhost { 'www.puppetlabs.com':
ensure => present,
www_root => '/var/www/www.puppetlabs.com',
}
```
Expand All @@ -27,42 +26,61 @@ nginx::resource::vhost { 'www.puppetlabs.com':

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

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

### Add a smtp proxy

```puppet

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

nginx::resource::mailhost { 'domain1.example':
ensure => present,
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',
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) maks 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.
Expand All @@ -79,7 +97,6 @@ nginx::nginx_vhosts:
'www.puppetlabs.com':
www_root: '/var/www/www.puppetlabs.com'
'rack.puppetlabs.com':
ensure: present
proxy: 'http://puppet_rack_app'
nginx::nginx_locations:
'static':
Expand All @@ -95,50 +112,56 @@ nginx::nginx_locations:

Currently this works only for Debian family.

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

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.

vhost_cfg_append => {
'passenger_enabled' => 'on',
'passenger_ruby' => '/usr/bin/ruby'
}
```puppet
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,
ssl_cache => 'shared:SSL:128m',
ssl_ciphers => 'SSLv2:-LOW:-EXPORT:RC4+RSA',
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',
},
}

```puppet
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',
},
}
```