diff --git a/README.md b/README.md index 960293ed792ee24f4a9ee05ab9981298750ab404..6e4672e17595a2f4dc7af2a6e4f2e0e6d3809c80 100644 --- a/README.md +++ b/README.md @@ -42,16 +42,12 @@ This role needs the patch from this [pull-request](https://github.com/ansible/an - `app_callable`: uwsgi variable <callable>, mostly app - `app_command`: commandline arguments for the app - `app_mountpoint`: the path in the URI, if the app shall be reachable under https://www.example.com/app, usually / - - `app_db_name`: name of the db for the app, can be `""` if not any database is needed, usally same as `app_user` - `app_db_type`: db type: (postgres|mysql|sqlite) - - `app_additional_software`: list of software, which is additionally needed by the app e.g. LaTeX. If no additional software is needed it is `[]` - - `app_deploy_key`: path to a ssh-key which is needed to get the software usually, `{{ inventory_dir }}/files/deploy-keys/<app_name>`. - `app_git_url`: git url of the project - `app_git_version`: git version usually `HEAD` - - `app_config_file`: config file, usally `config.py` - `app_secret_config`: it might be useful to have the cookie's key in seperate config (true|false) @@ -104,6 +100,15 @@ If servers are configured, the generated configuration files end with `.conf` an ### Variables +#### General + +Those variables are not part of the `webservers` variable, but rather single, per-host variables. + +* `webserver_resolver`: list of nameservers, defaults to global configuration +* `webserver_enable_ipv6`: enables ipv6 for internal resolver requests, default `true` +* `webserver_enable_acme_default`: adds a separate default server serving only acme requests for unconfigured sites, default `true` +* `cipher_strength`: selects available tls ciphers and protocol versions, `modern` (default) or `intermediate` + #### Server * `name`: an identifier, unique @@ -121,7 +126,7 @@ If servers are configured, the generated configuration files end with `.conf` an - `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_http`: if `yes`, the proxy redirects HTTP requests to HTTPS (cf. `sites/httprewrite.conf`, optional), default `true` * `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) @@ -133,9 +138,15 @@ If servers are configured, the generated configuration files end with `.conf` an * `certificate`: path to the TLS certificate file (defaults to acmetool path) * `private_key`: path to the TLS private key file (defaults to acmetool path) * `cipher_strength`: `modern` or `intermediate` (cf. `vars/main.yml`, optional) +* `xss_protect`: if `true`, enables browser-side XSS mitigation, default `true` +* `no_sniff`: if `true`, disallows browser-side MIME type sniffing, default `true` +* `referrer_policy`: if `true`, only sends HTTP Referrer header for same origin requests, default `true`, alternativly you may pass any policy string yourself (e.g. `strict-origin-when-cross-origin`, `no-referrer`, `strict-origin`) +* `expect_ct`: if `true`, tells the browser to check the certificate via public CertificateTransparency logs, alternatively you may pass a policy string directly, default `true` +* `cors`: for APIs only, sets allowed request origin, `true` == `*`, default `false`, enforces API-compatible restrictions for MIME sniffing, framing and CSP +* `csp`: set to `true` for a lax default Content Security Policy, `self` for a stricter version without inline code, default `true`, set to a dict containing directives as keys for a custom policy * `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 `no`, the acmetool snippet is not included (optional) +* `include_acme`: if `no`, the acmetool snippet is not included (optional, default `true`) * `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) @@ -156,6 +167,7 @@ If servers are configured, the generated configuration files end with `.conf` an * `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) +* `expires`: expiry time for the content (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) @@ -177,9 +189,9 @@ 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) +* `pass_real_ip`: if `yes`, `$http_x_real_ip` is passed as `REMOTE_ADDR` (optional, usually not needed for passing the correct IP) +* `index`: filename appended to paths ending with `/` (optional, defaults to standard index setting) +* `pass_user`: `$remote_user` is passed as `REMOTE_USER` (optional, default `true`) ##### proxy @@ -193,7 +205,7 @@ Passes this request to a HTTP(S) proxy, used e.g. in the nginx-proxy. - `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_cookie`: if `true`, proxies cookies at path `/` and adds the options `secure`, `httponly` and `SameSite=lax`, set to `strict` for the corresponding `SameSite` option, default `false` * `proxy_headers`: list of headers to pass along the request (optional) - `key`: header name - `value`: header value @@ -203,8 +215,7 @@ Passes this request to a HTTP(S) proxy, used e.g. in the nginx-proxy. 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) +* `pass_real_ip`: if `yes`, remote address from `real_ip` are passed (optional, usually not needed for passing the correct IP) ##### static @@ -212,6 +223,8 @@ Server static files from a directory. * `alias`: filesstem directory equivalent to this location (optional) - otherwise, `root` from the location of server is used +* `try_uri`: which URIs should be searched by `try_files`, default `$uri $uri/` +* `try_default`: which location to select if `try_files` did not find the URI, default `=404` ##### redirect @@ -220,6 +233,10 @@ 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`) +##### rewrite + +* `rewrites`: list of rewrites to apply (cf. nginx rewrite syntax) + ##### named Passes this request to a hidden `@location` if the file is not found. @@ -234,3 +251,7 @@ Sets parameters (c.f. `params` above) for this location, does nothing special. Disallows to see this page (cf. `deny all`). +##### gone + +Tells the user that the content has disappeared, i.e. HTTP 410. +