7.6 KiB
Server Delegation
To have a server on a subdomain (e.g. matrix.example.com) handle Matrix federation traffic for the base domain (example.com), 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. 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, 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 some problems that we list in Downsides of well-known-based Server Delegation.
As we already mention in Configuring DNS and Configuring Service Discovery via .well-known,
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 (example.com).
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 (
example.com). If you don't have any server for the base domain at all, you can easily solve it by making the playbook serve the base domain from the Matrix server. -
any downtime on the base domain (
example.com) or network trouble between the matrix subdomain (matrix.example.com) and the baseexample.commay cause Matrix Federation outages. As the Server-Server spec says:
Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures.
For most people, this is a reasonable tradeoff given that it's easy and straightforward to set up. We recommend you stay on this path.
Otherwise, you can decide to go against the default for this playbook, and instead set up Server Delegation via a DNS SRV record (advanced) (much more complicated).
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. This is usually much more complicated to set up, so we don't recommend it. If you're not an experience sysadmin, you'd better stay away from this.
As per the Server-Server spec, 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.
To use DNS SRV record validation, you need to:
-
ensure that
/.well-known/matrix/serveris not 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_static_files_file_matrix_server_enabled: false. -
ensure that you have a
_matrix._tcpDNS SRV record for your base domain (example.com) with a value of10 0 8448 matrix.example.com -
ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for
example.com(notmatrix.example.com!). Getting this certificate to thematrix.example.comserver may be complicated. The playbook's automatic SSL obtaining/renewal flow will likely not work and you'll need to copy certificates around manually. See below.
For more details on how to configure the playbook to work with SRV delegation
Obtaining certificates
How you can obtain a valid certificate for example.com on the matrix.example.com server is up to you.
If example.com and matrix.example.com are hosted on the same machine, you can let the playbook obtain the certificate for you, by following our Obtaining SSL certificates for additional domains guide.
If example.com and matrix.example.com are not hosted on the same machine, you can copy over the certificate files manually.
Don't forget that they may get renewed once in a while, so 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.example.com machine you can put them to use.
Based on your setup, you have different ways to go about it:
- Server Delegation
Serving the Federation API with your certificates and another webserver
If you are using some other webserver, you can set up reverse-proxying for the tcp/8448 port by yourself.
Make sure to use the proper certificates for example.com (not for matrix.example.com) when serving the tcp/8448 port.
As recommended in our Fronting the integrated reverse-proxy webserver with another reverse-proxy documentation section, we recommend you to expose the Matrix Federation entrypoint from traffic at a local port (e.g. 127.0.0.1:8449), so your reverese-proxy should send traffic there.
Serving the Federation API with your certificates and Synapse handling Federation
Alternatively, you can let Synapse handle Federation by itself.
To do that, make sure the certificate files are mounted into the Synapse container:
matrix_synapse_container_extra_arguments:
- "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
You can then tell Synapse to serve Federation traffic over TLS on tcp/8448:
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
Make sure to reload Synapse once in a while (systemctl reload matrix-synapse), so that newer certificates can kick in.
Reloading doesn't cause any downtime.