Installs and configure nginx as reverse proxy. Redirects all http requests to https, certificates are automatically issued by Let's Encrypt.
If necessary, certificates are automatically obtained or renewed, any time ansible-playbook is executed.
Support for Unix-PAM authentication, by setting auth
to true at target server.
Ability to restrict target domains by ip ranges and addresses.
Options to copy obtained certificates to target servers, when requested by them.
When multiple names are given for a served_domain
, only the first name will proxy, while the other names will redirect to the first name.
A Debian based distribution with certbot available in current apt sources. Correctly configured DNS server.
Option | Type | Default | Description | Required |
---|---|---|---|---|
proxy_domains | list of dicts | List of all target servers | Y | |
default_url | string | https://github.com/stuvusIT/reverse_proxy |
Url to redirect to if no target with requested domain is configured | N |
letsencrypt_email | string | E-Mail address to use to request certificates | Y | |
default_cert_mode | string | 0400 |
Default file access mode on certificates at target servers | N |
default_cert_group | string | root |
Default owner group for certificates at target servers | N |
default_cert_owner | string | root |
Default owner user for certificates at target servers | N |
default_crypto | boolean | True |
Use https as default to forward traffic | N |
reverse_proxy_default_proxy_ssl_verify | boolean | False |
Whether the SSL certificate of the proxied host should be verified by default | N |
domain_suffixes | list of strings | [''] |
Domain suffixes to append to every not full qualified domain name | N |
domain_prefixes | list of strings | [''] |
Domain prefixes to append to every not full qualified domain name | N |
letsencrypt_staging | boolean | False |
Use letsencrypt staging servers | N |
client_max_body_size | string | 1m |
Set the maximum upload size at the http context | N |
hsts_max_age | integer | 300 |
Strict Transport Security (HSTS) time of life | N (but recommended) |
reverse_proxy_use_dhparam | bool | True |
Use and generate Diffie-Hellman parameters | N |
reverse_proxy_dhparam_size | integer | 2048 |
Size of Diffie-Hellman parameter | N |
reverse_proxy_dhparam_path | string | /etc/ssl/dhparam.pem |
Path to store the Diffie-Hellman parameters | N |
reverse_proxy_ssl_session_timeout | string | 1d |
nginx ssl_session_timeout option |
N |
reverse_proxy_ssl_session_cache | string | shared:SSL:50m |
nginx ssl_session_cache option |
N |
reverse_proxy_ssl_session_tickets | boolean | False |
nginx ssl_session_tickets option |
N |
reverse_proxy_ssl_protocols | list of strings | TLSv1 TLSv1.1 TLSv1.2 |
nginx ssl_protocols option |
N |
reverse_proxy_ssl_ciphers | list of strings | see defaults/main.yml | nginx ssl_ciphers option |
N |
reverse_proxy_ssl_prefer_server_ciphers | boolean | True |
nginx ssl_prefer_server_ciphers option |
N |
reverse_proxy_ssl_stapling | boolean | True |
Enable OCSP Stapling | N |
reverse_proxy_ssl_trusted_certificate | string | nginx ssl_trusted_certificate option, path to the intermediate certificate of your CA |
N | |
reverse_proxy_redirect_to_first_domain | boolean | True |
Redirect to first domain from every served_domains[].domains list by default |
N |
reverse_proxy_redirect_to_first_domain_code | integer | 302 |
Specify default HTTP redirect code for redirects to first(default) domain | N |
reverse_proxy_https_redirect_code | integer | 302 |
HTTP status code used to direct users to the https version of a page | N |
reverse_proxy_error_log | string | /var/log/nginx/error.log |
Location of the error log | N |
reverse_proxy_redirect_code | integer | 302 |
Default HTTP status code used for custom domain redirects | N |
reverse_proxy_upstreams | dict of strings | {} |
Name-Content dict of upstreams to add to nginx.conf | N |
reverse_proxy_cache_paths | dict of strings | {} |
Path-Options dict of cache paths to add to nginx.conf (see example below) | N |
reverse_proxy_additional_http_locations | dict of strings | {} |
Match-Content dict of additional location blocks to add to the server on port 80 |
N |
reverse_proxy_keep_until_expiring | boolean | True |
If the requested certificate matches an existing certificate, always keep the existing one until it is due for renewal | N |
reverse_proxy_force_renew | boolean | False |
Force certificate renew, regardless of whether it is near expiry | N |
reverse_proxy_additional_config | string | Additional config to be written into the nginx http section once. | N |
Option | Type | Default | Description | Required |
---|---|---|---|---|
target_description | string | A short description of the target server | Y | |
target_host | string | Ansible host name (will be used to copy requested certificates) | Y | |
target_ip | string | IP address of target server (will be used as target address to redirect to) | Y | |
keep_until_expiring | boolean | If the requested certificate matches an existing certificate, always keep the existing one until it is due for renewal | N | |
force_renew | boolean | Force certificate renew, regardless of whether it is near expiry | N | |
served_domains | list of dicts | List of all domain lists served by this target server | Y |
Option | Type | Default | Description | Required |
---|---|---|---|---|
no_proxy | boolean | false |
Don't actually configure anything target-related (use extra_* variables from below) | N |
port | integer | Target port to redirect to | N | |
crypto | boolean | {{ default_crypto }} |
Use https to forward traffic | N |
auth | boolean | false |
restrict access to system users | N |
reverse_proxy_ssl_verify | boolean | {{ reverse_proxy_default_proxy_ssl_verify }} |
Whether the SSL certificate of the proxied host should be verified | N |
domains | list of strings | A list of domains to proxy (see below for more information)¹ | Y | |
redirect_to_first_domain | boolean | {{ reverse_proxy_redirect_to_first_domain }} |
Redirect to first domain from every served_domains[].domains list |
N |
redirect_to_first_domain_code | integer | {{ reverse_proxy_redirect_to_first_domain_code }} |
Specify HTTP redirect code for redirects to first(default) domain | N |
access_control | list of dicts | A list of dicts to restrict access to given set of ip ranges | N | |
fullchain_path | string | Destination path² for fullchain.pem at target_host | N | |
cert_path | string | Destination path² for cert.pem at target_host | N | |
chain_path | string | Destination path² for chain.pem at target_host | N | |
privkey_path | string | Destination path² for privkey.pem at target_host | N | |
fullchain_mode | string | {{ default_cert_mode }} |
File access mode for fullchain.pwm at target_host | N |
cert_mode | string | {{ default_cert_mode }} |
File access mode for cert.pwm at target_host | N |
chain_mode | string | {{ default_cert_mode }} |
File access mode for chain.pwm at target_host | N |
privkey_mode | string | {{ default_cert_mode }} |
File access mode for privkey.pwm at target_host | N |
fullchain_group | string | {{ default_cert_group }} |
Owner group of fullchain.pwm at target_host | N |
cert_group | string | {{ default_cert_group }} |
Owner group of cert.pwm at target_host | N |
chain_group | string | {{ default_cert_group }} |
Owner group of chain.pwm at target_host | N |
privkey_group | string | {{ default_cert_group }} |
Owner group of privkey.pwm at target_host | N |
fullchain_owner | string | {{ default_cert_owner }} |
Owner of fullchain.pwm at target_host | N |
cert_owner | string | {{ default_cert_owner }} |
Owner of cert.pwm at target_host | N |
chain_owner | string | {{ default_cert_owner }} |
Owner of chain.pwm at target_host | N |
privkey_owner | string | {{ default_cert_owner }} |
Owner of privkey.pwm at target_host | N |
client_max_body_size | string | Set the maximum upload size at server context | N | |
extra_server_config | string | Additional configuration items to add to the server block before location blocks | N | |
extra_location_config | string | Additional configuration items to add to the default location block (location /) | N | |
extra_locations | list of key value dicts | [] | Add custom locations to this server block, the key should be a location string, the value defines the location body | N |
redirect | string | Instead of proxying the request, redirect to this URL. The request URI is automatically appended. | N | |
redirect_code | integer | {{ reverse_proxy_redirect_code }} |
HTTP status code used to redirect the user to the URL specified by redirect |
N |
enable_http2_proxy | boolean | true |
Enable http2 for this host | N |
use_keepalive | boolean | false |
Enable keepalive for this host | N |
proxy_keepalive | integer | 1024 |
Number of connections to keepalive between the proxy and the host | N |
keep_until_expiring | boolean | If the requested certificate matches an existing certificate, always keep the existing one until it is due for renewal | N | |
force_renew | boolean | Force certificate renew, regardless of whether it is near expiry | N |
¹ Can be either a fully qualified domain name(with following dot ex. www.example.com.
) or a short internal domain(will be expanded by domain_suffixes
and domain_prefixes
ex. wiki
or static.media
)
² Path must point to a file in a already existing directory. The file will be either overwritten or created.
Option | Type | Default | Description | Required |
---|---|---|---|---|
allow | string | IP address or subnet to allow | N | |
deny | string | IP address or subnet to deny | N |
These dicts are evaluated in given order, so a complete subnet can be allowed with the exception of a given ip, see: nginx doku for future information.
letsencrypt_email: [email protected]
default_url: https://stuvus.uni-stuttgart.de
domain_suffixes:
- "example.com"
reverse_proxy_cache_paths:
/var/mycache:
- keys_zone=my_cache:50m
- max_size=500g
proxy_domains:
- target_description: music player
target_host: mpd01
target_ip: 172.27.10.66
served_domains:
- access_control:
- allow: 172.27.0.0/16
- deny: all
port: 6680
https: false
domains:
- mpd
- target_description: DokuWiki
target_host: validator
target_ip: 172.27.10.101
served_domains:
- auth: true
domains:
- wiki
- www.wiki
- wiki.wiki.de.
This example playbook proxies as follows:
Domain | Proxies to | Redirects to | Restrictions |
---|---|---|---|
mpd.example.com | https://172.27.10.66:6680 | - | allow: 172.27.0.0/16, deny all other |
wiki.example.com | https://172.27.10.101 | - | only system users |
www.wiki.example.com | https://172.27.10.101 | https://wiki.example.com | only system users |
wiki.wiki.de | https://172.27.10.101 | https://wiki.example.com | only system users |
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.