diff --git a/README.md b/README.md index 95f293fe37b2e17496ce685a164742e359633226..a85bb32400c64028536e8adb3883a93ee64aadcf 100644 --- a/README.md +++ b/README.md @@ -89,3 +89,153 @@ Define in your host_vars/<host> the dictionary `webapps` - name: restart uwsgi instance <instance_name> service: name="uwsgi@<instance_name>" state=restarted + +## webserver + +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. + +##### deny + +Disallows to see this page (cf. `deny all`). + +