From 9b6523a0b1bf63f02c69a8eab15cbe4a8fc0587a Mon Sep 17 00:00:00 2001 From: Emilien Mantel Date: Tue, 12 Jan 2016 12:14:36 +0100 Subject: [PATCH] Doc split + SSL + minor changes --- README.md | 120 ++++++---------------------------------------- defaults/main.yml | 2 +- doc/auth.md | 41 ++++++++++++++++ doc/php.md | 17 +++++++ doc/ssl.md | 52 ++++++++++++++++++++ doc/upstream.md | 29 +++++++++++ doc/vhost.md | 55 +++++++++++++++++++++ 7 files changed, 210 insertions(+), 106 deletions(-) create mode 100644 doc/auth.md create mode 100644 doc/php.md create mode 100644 doc/ssl.md create mode 100644 doc/upstream.md create mode 100644 doc/vhost.md diff --git a/README.md b/README.md index ad885c3..8c8f83e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Nginx for Debian Ansible role ============================= -[![Ansible Galaxy](http://img.shields.io/badge/ansible--galaxy-HanXHX.nginx-blue.svg)](https://galaxy.ansible.com/list#/roles/4399) [![Build Status](https://travis-ci.org/HanXHX/ansible-nginx.svg?branch=master)](https://travis-ci.org/HanXHX/ansible-nginx) +[![Ansible Galaxy](http://img.shields.io/badge/ansible--galaxy-HanXHX.nginx-blue.svg)](https://galaxy.ansible.com/list#/roles/4399) [![Build Status](https://travis-ci.org/HanXHX/ansible-nginx.svg?branch=master)](https://travis-ci.org/HanXHX/ansible-nginx) Install and configure Nginx on Debian. @@ -15,131 +15,41 @@ None. If you set true to `nginx_backports`, you must install backports repositor Role Variables -------------- +### Packaging + - `nginx_apt_package`: APT nginx package (try: apt-cache search ^nginx) - `nginx_backports`: Install nginx from backport repository (bool) + +### Shared + - `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_ssl_dir`: directory where you install your SSL/TLS keys - `nginx_resolver`: list of DNS resolver (default: OpenDNS) - `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_user` - `nginx_worker_processes` - - `nginx_pid`: daemon pid file + - `nginx_pid`: daemon pid file - `nginx_events_*`: all variables in events block - `nginx_http_*`: all variables in http block - `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. - - `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. +[Vhost configuration](doc/vhost.md) -(O): Optional -(M): Mandatory -(D): Depends other keys... +[SSL/TLS Configuration](doc/ssl.md) -#### 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 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 +[Basic Auth](doc/auth.md) Dependencies diff --git a/defaults/main.yml b/defaults/main.yml index d36474f..f0c802f 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -98,7 +98,7 @@ nginx_htpasswd: [] nginx_ssl_pairs: [] # -# Diffie-Helman +# Diffie-Hellman # nginx_dh: null nginx_dh_path: '{{ nginx_ssl_dir }}/dhparam.pem' diff --git a/doc/auth.md b/doc/auth.md new file mode 100644 index 0000000..7f4237f --- /dev/null +++ b/doc/auth.md @@ -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' +``` diff --git a/doc/php.md b/doc/php.md new file mode 100644 index 0000000..47a686e --- /dev/null +++ b/doc/php.md @@ -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` + diff --git a/doc/ssl.md b/doc/ssl.md new file mode 100644 index 0000000..04b8614 --- /dev/null +++ b/doc/ssl.md @@ -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----- +``` + diff --git a/doc/upstream.md b/doc/upstream.md new file mode 100644 index 0000000..efc3045 --- /dev/null +++ b/doc/upstream.md @@ -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` + diff --git a/doc/vhost.md b/doc/vhost.md new file mode 100644 index 0000000..2d1ce6f --- /dev/null +++ b/doc/vhost.md @@ -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 +