diff --git a/CHANGELOG.md b/CHANGELOG.md index 034c4276a..f69d25270 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,52 @@ +# 2024-01-14 + +## (Backward Compatibility) Configuration changes required for people fronting the integrated reverse-proxy webserver with another reverse-proxy + +If you're on the default setup (using the Traefik reverse-proxy as installed by the playbook), you don't need to do anything. + +People who are [Fronting the integrated Traefik reverse-proxy webserver with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), as per our previous instructions are redefining `devture_traefik_additional_entrypoints_auto` in their `vars.yml` configuration. + +Such a full variable redefinion is intrustive, because it prevents the playbook from injecting additional entrypoints into the Traefik webserver. In the future, the playbook may have a need to do so. + +For this reason, we no longer recommend completely redefining `devture_traefik_additional_entrypoints_auto`. +The playbook now defines [various `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_*` variables in the `defaults/main.yml` file](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/custom/matrix-base/defaults/main.yml) of the `matrix-base` role which can be used as a safer alternative to `devture_traefik_additional_entrypoints_auto`. + +Adapt your configuration as seen below: + +```diff +-devture_traefik_additional_entrypoints_auto: +- - name: matrix-federation +- port: 8449 +- host_bind_port: '127.0.0.1:8449' +- config: {} +- # If your reverse-proxy runs on another machine, remove the config above and use this config instead: +- # config: +- # forwardedHeaders: +- # insecure: true +- # # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY'] ++# Uncomment and tweak the variable below if the name of your federation entrypoint is different ++# than the default value (matrix-federation). ++# matrix_federation_traefik_entrypoint: matrix-federation ++ ++# Uncomment and tweak the variable below if you really wish to change the internal port number ++# that the federation endpoint uses. Changing it is generally not necessary. ++# Usually, changing `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port` below is enough. ++#matrix_playbook_public_matrix_federation_api_traefik_entrypoint_port: 8449 ++ ++matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: 127.0.0.1:8449 ++ ++# Adapt the variable below based on where your reverse-proxy runs: ++# - if it's on the Matrix server: keep `forwardedHeaders` and `insecure: true` as is ++# - if it's on another machine: remove `forwardedHeaders` and `insecure: true` and enable/configure `trustedIPs` ++matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom: ++ forwardedHeaders: ++ insecure: true ++ # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY'] +``` + +Also, feel free to read the [Fronting the integrated Traefik reverse-proxy webserver with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) documentation section again for additional details. + + # 2024-01-13 ## matrix-reminder-bot update with more secure (backward-incompatible) default settings diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md index 477530c8e..f0e640d11 100644 --- a/docs/configuring-playbook-own-webserver.md +++ b/docs/configuring-playbook-own-webserver.md @@ -32,6 +32,10 @@ matrix_playbook_reverse_proxy_type: other-traefik-container matrix_playbook_reverse_proxyable_services_additional_network: your-traefik-network devture_traefik_certs_dumper_ssl_dir_path: "/path/to/your/traefiks/acme.json/directory" + +# Uncomment and tweak the variable below if the name of your federation entrypoint is different +# than the default value (matrix-federation). +# matrix_federation_traefik_entrypoint: matrix-federation ``` In this mode all roles will still have Traefik labels attached. You will, however, need to configure your Traefik instance and its entrypoints. @@ -81,7 +85,7 @@ services: - "--providers.docker.network=traefik" - "--providers.docker.exposedbydefault=false" - "--entrypoints.web-secure.address=:443" - - "--entrypoints.federation.address=:8448" + - "--entrypoints.matrix-federation.address=:8448" - "--certificatesresolvers.default.acme.tlschallenge=true" - "--certificatesresolvers.default.acme.email=YOUR EMAIL" - "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json" @@ -136,25 +140,28 @@ devture_traefik_container_web_host_bind_port: '127.0.0.1:81' # We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from # a reverse-proxy running on the local machine is safe enough. +# If you're publishing the port (`devture_traefik_container_web_host_bind_port` above) to a public network interface: +# - remove the `devture_traefik_config_entrypoint_web_forwardedHeaders_insecure` variable definition below +# - uncomment and adjust the `devture_traefik_config_entrypoint_web_forwardedHeaders_trustedIPs` line below devture_traefik_config_entrypoint_web_forwardedHeaders_insecure: true - -# Or, if you're publishing the port (`devture_traefik_container_web_host_bind_port` above) to a public network interfaces: -# - remove the `devture_traefik_config_entrypoint_web_forwardedHeaders_insecure` variable definition above -# - uncomment and adjust the line below # devture_traefik_config_entrypoint_web_forwardedHeaders_trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY'] -# Likewise (to `devture_traefik_container_web_host_bind_port` above), -# if your reverse-proxy runs on another machine, consider changing the `host_bind_port` setting below. -devture_traefik_additional_entrypoints_auto: - - name: matrix-federation - port: 8449 - host_bind_port: '127.0.0.1:8449' - config: {} - # If your reverse-proxy runs on another machine, remove the config above and use this config instead: - # config: - # forwardedHeaders: - # insecure: true - # # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY'] +# Expose the federation entrypoint on a custom port (other than port 8448, which is normally used publicly). +# +# We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from +# a reverse-proxy running on the local machine is safe enough. +# +# If your reverse-proxy runs on another machine, consider: +# - using `0.0.0.0:8449`, just `8449` or `SOME_IP_ADDRESS_OF_THIS_MACHINE:8449` below +# - adjusting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom` (below) - removing `insecure: true` and enabling/configuring `trustedIPs` +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: 127.0.0.1:8449 + +# Depending on the value of `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port` above, +# this may need to be reconfigured. See the comments above. +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom: + forwardedHeaders: + insecure: true + # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY'] ``` For an example where the playbook's Traefik reverse-proxy is fronted by another reverse-proxy running on the same server, see [Nginx reverse-proxy fronting the playbook's Traefik](../examples/nginx/README.md) or [Caddy reverse-proxy fronting the playbook's Traefik](../examples/caddy2/README.md). diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 7ded441eb..71ee781ba 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -31,6 +31,9 @@ matrix_playbook_ssl_retrieval_method: "{{ 'lets-encrypt' if devture_traefik_cert matrix_playbook_ssl_enabled: "{{ matrix_playbook_ssl_retrieval_method in ['lets-encrypt', 'self-signed', 'manually-managed'] }}" +# A separate Matrix Federation entrypoint is always enabled, unless the federation port matches one of the ports for existing (default) entrypoints +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled: "{{ matrix_federation_public_port not in [devture_traefik_config_entrypoint_web_port, devture_traefik_config_entrypoint_web_secure_port] }}" + ######################################################################## # # # /Playbook # @@ -5197,15 +5200,9 @@ devture_traefik_base_path: "{{ matrix_base_data_path }}/traefik" devture_traefik_uid: "{{ matrix_user_uid }}" devture_traefik_gid: "{{ matrix_user_gid }}" -devture_traefik_federation_entrypoint: - name: matrix-federation - port: "{{ matrix_federation_public_port }}" - host_bind_port: "{{ matrix_federation_public_port }}" - config: {} - devture_traefik_additional_entrypoints_auto: | {{ - ([devture_traefik_federation_entrypoint] if (matrix_federation_public_port != devture_traefik_config_entrypoint_web_port) and (matrix_federation_public_port != devture_traefik_config_entrypoint_web_secure_port) else []) + ([matrix_playbook_public_matrix_federation_api_traefik_entrypoint_definition] if matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled else []) }} devture_traefik_additional_domains_to_obtain_certificates_for: "{{ matrix_ssl_additional_domains_to_obtain_certificates_for }}" diff --git a/roles/custom/matrix-base/defaults/main.yml b/roles/custom/matrix-base/defaults/main.yml index 61e6663f9..03ba082ff 100644 --- a/roles/custom/matrix-base/defaults/main.yml +++ b/roles/custom/matrix-base/defaults/main.yml @@ -110,6 +110,7 @@ matrix_server_fqn_rageshake: "rageshake.{{ matrix_domain }}" matrix_federation_public_port: 8448 # The name of the Traefik entrypoint for handling Matrix Federation +# Also see the `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_*` variables. matrix_federation_traefik_entrypoint: matrix-federation # The architecture that your server runs. @@ -240,6 +241,23 @@ matrix_playbook_reverse_proxy_type: '' matrix_playbook_service_host_bind_interface_prefix: "{{ '' if matrix_playbook_reverse_proxy_type not in ['other-nginx-non-container', 'other-on-same-host', 'other-on-another-host'] else ('0.0.0.0:' if matrix_playbook_reverse_proxy_type == 'other-on-another-host' else '127.0.0.1:') }}" +# Controls whether to enable an additional Traefik entrypoint for the purpose of serving Matrix Federation. +# By default, federation is served on a special port (8448), so a separate entrypoint is necessary. +# Group variables may influence whether this is enabled based on the port number and on the default entrypoints of the Traefik reverse-proxy. +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled: true +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_name: "{{ matrix_federation_traefik_entrypoint }}" +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_port: "{{ matrix_federation_public_port }}" +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: "{{ matrix_federation_public_port }}" +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_auto | combine(matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom, recursive=True) }}" +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_auto: {} +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom: {} + +matrix_playbook_public_matrix_federation_api_traefik_entrypoint_definition: + name: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_name }}" + port: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_port }}" + host_bind_port: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port }}" + config: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config }}" + # Variables to Control which parts of our roles run. run_postgres_import: true run_postgres_upgrade: true