diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md new file mode 100644 index 000000000..29d570821 --- /dev/null +++ b/docs/howto-server-delegation.md @@ -0,0 +1,131 @@ +# Server Delegation + +To have a server on a subdomain (e.g. `matrix.`) handle Matrix federation traffic for the base domain (``), we need to instruct the Matrix network of such a delegation. + +By default, this playbook guides you into setting up [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file). +However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation. + +It is a complicated matter, so unless you are affected by the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation), we suggest you stay on the simple/default path. + + +## Server Delegation via a well-known file + +Serving a `/.well-known/matrix/server` file from the base domain is the most straightforward way to set up server delegation, but it suffers from the following problems: + +As we already mention in [Configuring DNS](configuring-dns.md) and [Configuring Service Discovery via .well-known](configuring-well-known.md), +this playbook already properly guides you into setting up such delegation by means of a `/.well-known/matrix/server` file served from the base domain (``). + +If this is okay with you, feel free to not read ahead. + + +### Downsides of well-known-based Server Delegation + +Server Delegation by means of a `/.well-known/matrix/server` file is the most straightforward, but suffers from the following downsides: + +- you need to have a working HTTPS server for the base domain (``) + +- any downtime on the base domain (``) or network trouble between the matrix subdomain (`matrix.`) and the base `` may cause Matrix Federation outages. As the [Server-Server spec says](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery): + +> Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures. + +If this is not a concern for you, feel free to not read ahead. + +Otherwise, you can decide to go against the default for this playbook, and instead set up [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-serv-record-advanced). + + +## Server Delegation via a DNS SRV record (advanced) + +**NOTE**: doing Server Delegation via a DNS SRV record is a more advanced way to do it and is not the default for this playbook. + +As per the [Server-Server spec](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), it's possible to do Server Delegation using only a SRV record (without a `/.well-known/matrix/server` file). + +This prevents you from suffering the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation). + +To use DNS SRV record validation, you need to: + +- ensure that no `/.well-known/matrix/server` is served from the base domain, as that would interfere with DNS SRV record Server Delegation. To make the playbook **not** generate and serve the file, use the following configuration: `matrix_well_known_matrix_server_enabled: false`. + +- ensure that you have a `_matrix._tcp` DNS SRV record for your base domain (``) with a value of `10 0 8448 matrix.` + +- ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for `` (not `matrix.`!). See below. + + +### Obtaining certificates + +How you can obtain a valid certificate for `` on the `matrix.` server is up to you. + +If `` and `matrix.` is the same machine, you can let the playbook obtain the certificate for you by redefining the `matrix_ssl_domains_to_obtain_certificates_for` variable. Example: + +```yaml +matrix_ssl_domains_to_obtain_certificates_for: + - '{{ hostname_matrix }}' + - '{{ hostname_riot }}' + - '{{ hostname_identity }}' +``` + +This way, the playbook would obtain certificates for your base domain as well (referred to by the `hostname_identity` variable). +The certificate files would be available in `/matrix/ssl/config/live//...`. + +If `` and `matrix.` are not the same machine, you can copy over the certificate files manually. +If they get renewed automatically, you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire. + + +### Serving the Federation API with your certificates + +Regardless of which method for obtaining certificates you've used, once you've managed to get certificates for your base domain onto the `matrix.` machine you can put them to use. + + +### Serving the Federation API with your certificates and matrix-nginx-proxy + +**If you are using matrix-nginx-proxy**, a reverse-proxy webserver used by default in this playbook, you only need to override the certificates used for the Matrix Federation API. You can do that using: + +```yaml +# Adjust paths below to point to your certificate. +# +# NOTE: these are in-container paths. `/matrix/ssl` on the host is mounted into the container +# at the same path (`/matrix/ssl`) by default, so if that's the path you need, it would be seamless. +matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate: /matrix/ssl/config/live//fullchain.pem +matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: /matrix/ssl/config/live//privkey.pem +``` + +If your files are not in `/matrix/ssl` but in some other location, you would need to mount them into the container: + +```yaml +matrix_nginx_proxy_container_additional_volumes: + - src: /some/path/on/the/host + dst: /some/path/inside/the/container + options: ro +``` + +You then refer to them (for `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate` and `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key`) by using `/some/path/inside/the/container`. + + +### Serving the Federation API with your certificates and another webserver + +**If you are NOT using matrix-nginx-proxy**, but rather some other webserver, you can set up reverse-proxying for the `tcp/8448` port by yourself. +Make sure to use the proper certificates for `` (not for `matrix.`) when serving the `tcp/8448` port. + +Proxying needs to happen to `127.0.0.1:8048` (unencrypted Synapse federation listener). + + +### Serving the Federation API with your certificates and Synapse handling Federation + +**Alternatively**, if you are **NOT using matrix-nginx-proxy** and **would rather not use your own webserver for Federation traffic**, you can let Synapse handle Federation by itself. + +To do that, make sure the certificate files are mounted into the Synapse container: + +```yaml +matrix_synapse_container_additional_volumes: + - src: /some/path/on/the/host + dst: /some/path/inside/the/container + options: ro +``` + +You can then tell Synapse to serve Federation traffic over TLS on `tcp/8448`: + +```yaml +matrix_synapse_no_tls: false +matrix_synapse_tls_federation_listener_enabled: true +matrix_synapse_tls_certificate_path: /some/path/inside/the/container/certificate.crt +matrix_synapse_tls_private_key_path: /some/path/inside/the/container/private.key +``` diff --git a/docs/prerequisites.md b/docs/prerequisites.md index dc6b91f81..4d8aa20c8 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -6,7 +6,7 @@ - the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for version requirements or alternative ways to run Ansible. -- an HTTPS-capable web server at the base domain name (``) which is capable of serving static files +- an HTTPS-capable web server at the base domain name (``) which is capable of serving static files (unless you decide to use DNS SRV records for [Server Delegation](howto-server-delegation.md)) - properly configured DNS records for `` (details in [Configuring DNS](configuring-dns.md))