Doc split + SSL + minor changes

pull/14/head
Emilien Mantel 2016-01-12 12:14:36 +01:00
parent 883948f081
commit 9b6523a0b1
7 changed files with 210 additions and 106 deletions

116
README.md
View File

@ -15,29 +15,17 @@ None. If you set true to `nginx_backports`, you must install backports repositor
Role Variables Role Variables
-------------- --------------
### Packaging
- `nginx_apt_package`: APT nginx package (try: apt-cache search ^nginx) - `nginx_apt_package`: APT nginx package (try: apt-cache search ^nginx)
- `nginx_backports`: Install nginx from backport repository (bool) - `nginx_backports`: Install nginx from backport repository (bool)
### Shared
- `nginx_root`: root directory where you want to have your files - `nginx_root`: root directory where you want to have your files
- `nginx_log_dir`: log directory (if you change it, don't forget to change logrotate config) - `nginx_log_dir`: log directory (if you change it, don't forget to change logrotate config)
- `nginx_ssl_dir`: directory where you install your SSL/TLS keys
- `nginx_resolver`: list of DNS resolver (default: OpenDNS) - `nginx_resolver`: list of DNS resolver (default: OpenDNS)
- `nginx_error_log_level`: default log level - `nginx_error_log_level`: default log level
- `nginx_dh_length`: DH key length (default is 2048)
### PHP
- `nginx_php`: boolean if you need to preconfigure PHP (default: false)
- `nginx_php_sockets`: list of //sockets//
You should see [Nginx upstream module doc](http://nginx.org/en/docs/http/ngx_http_upstream_module.html).
Socket:
- `unix_socket`
- `host`
- `port`
- `weight`
- `max_fails`
- `fail_timeout`
### Nginx Configuration ### Nginx Configuration
@ -48,98 +36,20 @@ Socket:
- `nginx_http_*`: all variables in http block - `nginx_http_*`: all variables in http block
- `nginx_custom_http`: instructions list (will put data in `/etc/nginx/conf.d/custom.conf`) - `nginx_custom_http`: instructions list (will put data in `/etc/nginx/conf.d/custom.conf`)
### Vhost management Fine configuration
------------------
You can see many examples in: [tests/test.yml](tests/test.yml). [Vhost configuration](doc/vhost.md)
- `nginx_vhosts`: List of dict. A vhost has few keys. See bellow. [PHP configuration](doc/php.md)
#### Common [Upstream Configuration](doc/upstream.md)
- `name`: (M) Domain or list of domain used. [Vhost configuration](doc/vhost.md)
- `template`: (D) template used to create vhost. Optional if you set `delete` to true or using `redirect_tor`.
- `enable`: (O) Enable the vhost (default is true)
- `delete`: (O) Delete the vhost (default is false)
- `redirect_from`: (O) Domain list to redirect to the first `name`. You can use this key to redirect non-www to www
- `redirect_to`: (O) Redirect all requests to this domain. Please set scheme (http:// or https:// or $sheme).
- `redirect_to_code`: Redirect code (default: 302)
- `location`: (O) Add new custom locations (it does not overwrite!)
- `more`: (O) Add more custom infos.
- `upstream_params`: (O) Add upstream params (useful when you want to pass variables to PHP)
- `override_try_files`: (O) overrides default try\_files defined in template
- `manage_local_content`: (O) Boolean. Set to false if you don't want to manage local content (images, css...). This option is useless if you use `_proxy` template or `redirect_to` feature.
- `htpasswd`: (0) References name key in `nginx_htpasswd`. Enable auth basic on all vhost.
(O): Optional [SSL/TLS Configuration](doc/ssl.md)
(M): Mandatory
(D): Depends other keys...
#### Templates [Basic Auth](doc/auth.md)
- `_base`: static template
- `_backuppc`: access to [BackupPC](http://backuppc.sourceforge.net/) (be careful: you need to install [fcgiwrap](https://packages.debian.org/jessie/fcgiwrap))
- `_dokuwiki`
- `_redirect`: should not be called explicitly
- `_phalcon`: Phalcon PHP Framework
- `_php`: PHP base template. Can work with many frameworks/tools
- `_php_index`: Same as above. But you can only run index.php
- `_proxy`
- `_wordpress`
Templates works as parent-child.
#### About proxy template
Proxy template allow you to use Nginx as reverse proxy. Usefull when you have application serveur such as Redmine, Jenkins...
You have many key added to vhost key:
- `upstream_name`: (O) upstream name used to pass proxy
- `proxy_params`: (M) list of raw params passed to the vhost
(O) : Optional
(M) : Mandatory
#### About custom location
`location` is list of instructions (like *echo*, *return*...). Do not forget to end all your instructions with *;*. You can use a special key to use auth basic. It works in the same way as in `nginx_vhost`
### Upstream management
- `nginx_upstreams`: List of dict. An upstream has few keys. See bellow.
Note: Few params are unavailable on old Nginx version. But this role don't put it if your version is too old!
#### Upstream params
- `name`: upstream name. Can be use in vhost with *proxy_pass http://upstream_name*
- `params`: list of param (hash, zone...)
- `servers`: each upstream MUST have at least 1 server
#### Server params
You must set a `path`. For example: *192.168.0.50:8080* or *unix:/tmp/my.sock*.
All this params are optional. You should see [Nginx upstream doc](http://nginx.org/en/docs/http/ngx_http_upstream_module.html).
- `weight`
- `max_fails`
- `fail_timeout`
- `backup`
- `down`
- `route`
- `slow`start`
### Auth Basic management
Auth basic is managed in a separate list. Each auth file can be shared between locations or vhosts.
Each htpasswd has few keys:
- `name`: (M) used to create file and as pointee
- `description`: (M) Used for the message box :)
- `users`: each users is composed with 3 keys: `name` (M), `password` (M) and `state` present/absent (default: present)
- `state`: (O) present or absent. Default: present
Dependencies Dependencies

View File

@ -98,7 +98,7 @@ nginx_htpasswd: []
nginx_ssl_pairs: [] nginx_ssl_pairs: []
# #
# Diffie-Helman # Diffie-Hellman
# #
nginx_dh: null nginx_dh: null
nginx_dh_path: '{{ nginx_ssl_dir }}/dhparam.pem' nginx_dh_path: '{{ nginx_ssl_dir }}/dhparam.pem'

41
doc/auth.md 100644
View File

@ -0,0 +1,41 @@
Auth Basic management
=====================
Description
-----------
Auth basic is managed in a separate list. Each auth file can be shared between locations or vhosts.
Each htpasswd has few keys:
- `name`: (M) used to create file and as pointee
- `description`: (M) Used for the message box :)
- `users`: each users is composed with 3 keys: `name` (M), `password` (M) and `state` present/absent (default: present)
- `state`: (O) present or absent. Default: present
`nginx_htpasswd` should be placed in a vaut file.
Exemple
-------
```
nginx_vhosts:
# htpasswd on all vhost
- name: test.local
htpasswd: 'hello'
template: '_base'
# htpasswd only in /hello
- name: test-location.local
template: '_base'
location:
'/hello':
- htpasswd: 'hello'
nginx_htpasswd:
- name: 'hello'
description: 'Please login!'
users:
- name: 'bob'
password: 'my_pass'
```

17
doc/php.md 100644
View File

@ -0,0 +1,17 @@
PHP
===
- `nginx_php`: boolean if you need to preconfigure PHP (default: false)
- `nginx_php_sockets`: list of sockets (see bellow)
You should see [Nginx upstream module doc](http://nginx.org/en/docs/http/ngx_http_upstream_module.html).
Each socket have:
- `unix_socket`
- `host`
- `port`
- `weight`
- `max_fails`
- `fail_timeout`

52
doc/ssl.md 100644
View File

@ -0,0 +1,52 @@
SSL/TLS Management
==================
You can put all this variables in a separated vault file.
Variables
---------
- `nginx_dh`: DH content
- `nginx_dh_length`: DH key length (default is 2048)
- `nginx_dh_path`: file localation
- `nginx_ssl_dir`: directory where you install your SSL/TLS keys
- `nginx_ssl_pairs`
Cert/Key pairs
--------------
This list have 3 mandatory keys:
- `name`: MUST be unique
- `key`: content of the private key
- `cert`: content of the public key
Note: `name` is used to deploy key/cert. With defaults values dans `name` = "foo", key is -> /etc/nginx/ssl/foo/foo.key
Diffie-Hellman
--------------
If you do not specify any dh param, this role auto generates it.
Example
-------
```
nginx_vhosts;
- name: 'test-ssl.local'
proto: ['http', 'https']
template: '_base'
ssl_name: 'mysuperkey'
nginx_ssl_pairs:
- name: mysuperkey
key: |
-----BEGIN RSA PRIVATE KEY-----
....(snip)....
-----END RSA PRIVATE KEY-----
cert: |
-----BEGIN CERTIFICATE-----
....(snip)....
-----END CERTIFICATE-----
```

29
doc/upstream.md 100644
View File

@ -0,0 +1,29 @@
Upstream management
===================
`nginx_upstreams`: List of dict. An upstream has few keys. See bellow.
Note: Few params are unavailable on old Nginx version. But this role do _not_ put it if your version is too old!
Upstream params
---------------
- `name`: upstream name. Can be use in vhost with *proxy_pass http://upstream_name*
- `params`: list of param (hash, zone...)
- `servers`: each upstream MUST have at least 1 server
Server params
-------------
You must set a `path`. For example: *192.168.0.50:8080* or *unix:/tmp/my.sock*.
All this params are optional. You should see [Nginx upstream doc](http://nginx.org/en/docs/http/ngx_http_upstream_module.html).
- `weight`
- `max_fails`
- `fail_timeout`
- `backup`
- `down`
- `route`
- `slow`start`

55
doc/vhost.md 100644
View File

@ -0,0 +1,55 @@
Vhost management
================
You can see many examples in: [tests/test.yml](../tests/test.yml).
`nginx_vhosts`: List of dict. A vhost has few keys. See bellow.
Common
------
- `name`: (M) Domain or list of domain used.
- `template`: (D) template used to create vhost. Optional if you set `delete` to true or using `redirect_tor`.
- `enable`: (O) Enable the vhost (default is true)
- `delete`: (O) Delete the vhost (default is false)
- `redirect_from`: (O) Domain list to redirect to the first `name`. You can use this key to redirect non-www to www
- `redirect_to`: (O) Redirect all requests to this domain. Please set scheme (http:// or https:// or $sheme).
- `redirect_to_code`: Redirect code (default: 302)
- `location`: (O) Add new custom locations (it does not overwrite!)
- `more`: (O) Add more custom infos.
- `upstream_params`: (O) Add upstream params (useful when you want to pass variables to PHP)
- `override_try_files`: (O) overrides default try\_files defined in template
- `manage_local_content`: (O) Boolean. Set to false if you do not want to manage local content (images, css...). This option is useless if you use `_proxy` template or `redirect_to` feature.
- `htpasswd`: (0) References name key in `nginx_htpasswd`. Enable auth basic on all vhost.
(O): Optional
(M): Mandatory
(D): Depends other keys...
Templates
---------
- `_base`: static template
- `_backuppc`: access to [BackupPC](http://backuppc.sourceforge.net/) (be careful: you need to install [fcgiwrap](https://packages.debian.org/jessie/fcgiwrap))
- `_dokuwiki`
- `_redirect`: should not be called explicitly
- `_phalcon`: Phalcon PHP Framework
- `_php`: PHP base template. Can work with many frameworks/tools
- `_php_index`: Same as above. But you can only run index.php
- `_proxy`
- `_wordpress`
Templates works as parent-child.
About proxy template
--------------------
Proxy template allow you to use Nginx as reverse proxy. Usefull when you have an application service such as Redmine, Jenkins...
You have many key added to vhost key:
- `upstream_name`: (O) upstream name used to pass proxy
- `proxy_params`: (M) list of raw params passed to the vhost
(O) : Optional