This role manages the nginx configuration for a host based on the variable `webservers`.
### Structure
Every host (e.g. `web`) has a list of servers, corresponding to a configuration file which can be enabled or disabled.
Each server has a list of sites, corresponding to a `server` block in the configuration file.
Each site has a `type`, general information about the proxy and how to link it to the internal application, and depending on the site type a list of `locations`.
Configuration files are generated in `/etc/nginx/(proxy-)?sites-available/` and - if enabled - linked in `/etc/nginx/(proxy-)?sites-enabled/`.
Two nginx configuration files (`/etc/nginx/nginx.conf` and `/etc/nginx/nginx-proxy.conf`) are generated with their corresponding systemd units.
If no servers are configured (i.e. the `webservers` variables missing), example config files are deployed and all files in the `-enabled` directories are included.
If servers are configured, the generated configuration files end with `.conf` and only those are included.
### Variables
#### Server
*`name`: an identifier, unique
*`enabled`: `yes` or `no`
*`servers`: list of `sites`
#### Site
*`type`: `webapp` or special, e.g. `mediawiki`, determines template in `webserver/templates/sites/`
* one of (used for nginx-proxy-communication):
-`port`: ip port (e.g. 62000)
-`socket`: path to unix socket
* one of:
-`server_name`: domain name of the website
-`server_names`: list of domain names of the website
*`root`: path to website root directory
*`indices`: list of index file names
*`forward_http`: if `yes`, the proxy redirects HTTP requests to HTTPS (cf. `sites/httprewrite.conf`, optional)
*`forward_ip`: if `yes`, the proxy redirects requests to the hosts IP to the hosts domain name (cf. `sites/iprewrite.conf`, optional)
- only useful on one server per host
*`forward_hostnames`: one of (optional)
- list of hostnames to redirect to this servers domain
- dict:
-`path`: path under this domain to redirect the hostnames to
-`hostnames`: list of hostnames to redirect to this domain
*`no_ssl`: if `yes`, the proxy listens to HTTP, not HTTPS
*`certificate`: path to the TLS certificate file (required for HTTPS)
*`private_key`: path to the TLS private key file (required for HTTPS)
*`cipher_strength`: `modern` or `intermediate` (cf. `vars/main.yml`, optional)
*`use_sso`: include single sign on for this server
*`sso_protect_all`: if `no`, proxy locations do not automatically require single sign on auth if `use_sso` is set (default `yes`, optional)
*`include_acme`: if `yes`, the acmetool snippet is included (optional)
*`include_snippets`: list of snippets files (in `/etc/nginx/snippets/`) to include (optional)
*`internal_locations`: list of internal locations
-*required* to generate internal config (empty list != omitted)
- used by site type `webapp`
*`public_locations`:
- list of public locations
- required to generate proxy config
#### Location
*`type`: location block type (cf. `templates/locations/`)
*`path`: which path this location maps to
*`exact`: if `yes`, the path matches exactly, without matching subdirectories (cf. `location =`, optional)
*`prefer_to_regex`: if `yes`, if this location is the longest prefix match, regexes are not matched (cf. `location ^~`, optional)
*`regex`: if yes, the path specification is a regular expression (cf. `location ~`, optional)
*`case_insensitive`: if `yes`, the path regex is case insensitive (cf. `location ~*`, optional)
- only with `regex: yes`
*`locations`: list of locations, nested in this location (optional)
*`root`: the root directory of this location (optional)
*`indices`: the index pages of this location (optional)
*`error_page`: the error page of this location (optional)
*`params`: dictionary of parameters passed through to the nginx config (optional)
*`conditions`: list of condition dictionaries passed for this location (optional)
-`condition`: the part inbetween `if` and `{`
-`actions`: list of lines inbetween `{` and `}`
*`pam_auth`: if set, this location requires PAM authentication
-`name`: the name to show the user (default `FSMPI`, optional)
-`service`: the PAM service required (default `nginx`, optional)
*`basic_auth`: if set, this location requires basic auth
-`name` the name to show to the user (default `FSMPI`, optional)
-`file`: the file to get users and passwords from
*`allow_only_networks`: list of dictionaries this location is limited to (optional)
-`network`: IP/CIDR notation allowed to access this site
-`comment`: comment explaining this location (for config readability, required)
##### fastcgi
To be used with a fastcgi application, e.g. `php-fpm`.
*`socket`: fastcgi socket (either host:port or unix:path)
*`script_name`: `SCRIPT_FILENAME` without `$document_root` (optional)
*`pass_real_ip`: if `yes`, `$http_x_real_ip` is passed as `REMOTE_ADDR` (optional)
*`index`: filename appended to paths ending with `/` (optional)
*`pass_user`: `$remote_user` is passed as `REMOTE_USER` (optional)
##### proxy
Passes this request to a HTTP(S) proxy, used e.g. in the nginx-proxy.
*`sso_protect`: if `yes`, this location requires single sign on authentication
- by default `sso_protect_all` is `yes`, therefore this is only required if only some locations should be protected
* ony of (optional):
-`proxy_host`: domain to pass the request to
-`proxy_port`: port (on localhost) to pass this request to
-`proxy_unix`: path to unix socket to pass this request to
- if none of these, `server.port` or `server.socket` is used
*`proxy_relative`: if `yes`, the request path is passed to the proxy (default: `no`, optional), otherwise all requests are passed to `/`
*`pass_ip`: if `yes`, host, remote address and protocol scheme are passed as headers (optional)
*`proxy_headers`: list of headers to pass along the request (optional)
-`key`: header name
-`value`: header value
##### uwsgi
Passes requests to an uwsgi socket.
*`socket`: unix (with `unix:` prefix) or ip socket uwsgi listens on
*`pass_ip`: if `yes`, host and remote address are passed as headers (optional)
*`pass_real_ip`: if `yes`, host and remote address from `real_ip` are passed (optional)
##### static
Server static files from a directory.
*`alias`: filesstem directory equivalent to this location (optional)
- otherwise, `root` from the location of server is used
##### redirect
Redirects the request to another location.
*`target`: URL (with or without host) to redirect to
*`temporary`: if `yes`, a temporary redirect (302) is used, otherwise a permanent (301) (optional, default `no`)
##### named
Passes this request to a hidden `@location` if the file is not found.
*`name`: the name of the named location to pass this request to (without `@`)
##### param-only
Sets parameters (c.f. `params` above) for this location, does nothing special.
