Delegation

Delegation is a Matrix feature allowing a homeserver admin to retain an URL of example.com so that user IDs, etc. continue to look like *:example.com, whilst having federation traffic routed to a different server and/or port (e.g. matrix.example.com:443). There are multiple ways to do this. This includes with the .well-known file and SRV DNS records.

.well-known delegation

To use this method, you need to be able to configure the server at https://<server_name> to serve a file at https://<server_name>/.well-known/matrix/server. There are two ways to do this, shown below.

Using a web server

This is the more commonly used method, and is the only method if you are using server software that is not Synapse. You need to configure a server such as nginx or Apache to serve the https://<server_name>/.well-known/matrix/server file. Setting up such a server is out of the scope of the wiki, but note that it is often possible to configure your reverse proxy for this.

The URL https://<server_name>/.well-known/matrix/server should be configured to return a JSON structure containing the key m.server like this:

{
    "m.server": "<synapse.server.name>[:<yourport>]"
}

Note:

• Specifying a port is optional. If no port is specified, then it defaults to 8448.

Using Synapse's built in method

If you are able to set up your domain so that https://<server_name> is routed to Synapse (i.e., the only change needed is to direct federation traffic to port 443 instead of port 8448), then it is possible to configure Synapse to serve a suitable .well-known/matrix/server file. To do so, add the following to your homeserver.yaml file:

serve_server_wellknown: true

Note:

• This only works if https://<server_name> is routed to Synapse, so is generally not suitable if Synapse is hosted at a subdomain such as https://matrix.example.com.

SRV DNS record delegation

Warning: This form of delegation is not generally recommended, as it can be difficult to configure the TLS certificates correctly in this case, and it offers little advantage over .well-known delegation.

Note:

• Server delegation is a function of server-server communication, and as such using SRV DNS records will not cover use cases involving client-server communications. This means setting global client settings will still require that you serve a file from the https://<server_name>/.well-known/ endpoints defined in the specification.

To set up SRV DNS record delegation, create a SRV DNS record with _matrix-fed._tcp.<hostname> that points to the delegated hostname.