1# Delegation of incoming federation traffic 2 3In the following documentation, we use the term `server_name` to refer to that setting 4in your homeserver configuration file. It appears at the ends of user ids, and tells 5other homeservers where they can find your server. 6 7By default, other homeservers will expect to be able to reach yours via 8your `server_name`, on port 8448. For example, if you set your `server_name` 9to `example.com` (so that your user names look like `@user:example.com`), 10other servers will try to connect to yours at `https://example.com:8448/`. 11 12Delegation is a Matrix feature allowing a homeserver admin to retain a 13`server_name` of `example.com` so that user IDs, room aliases, etc continue 14to look like `*:example.com`, whilst having federation traffic routed 15to a different server and/or port (e.g. `synapse.example.com:443`). 16 17## .well-known delegation 18 19To use this method, you need to be able to configure the server at 20`https://<server_name>` to serve a file at 21`https://<server_name>/.well-known/matrix/server`. There are two ways to do this, shown below. 22 23Note that the `.well-known` file is hosted on the default port for `https` (port 443). 24 25### External server 26 27For maximum flexibility, you need to configure an external server such as nginx, Apache 28or HAProxy to serve the `https://<server_name>/.well-known/matrix/server` file. Setting 29up such a server is out of the scope of this documentation, but note that it is often 30possible to configure your [reverse proxy](reverse_proxy.md) for this. 31 32The URL `https://<server_name>/.well-known/matrix/server` should be configured 33return a JSON structure containing the key `m.server` like this: 34 35```json 36{ 37 "m.server": "<synapse.server.name>[:<yourport>]" 38} 39``` 40 41In our example (where we want federation traffic to be routed to 42`https://synapse.example.com`, on port 443), this would mean that 43`https://example.com/.well-known/matrix/server` should return: 44 45```json 46{ 47 "m.server": "synapse.example.com:443" 48} 49``` 50 51Note, specifying a port is optional. If no port is specified, then it defaults 52to 8448. 53 54### Serving a `.well-known/matrix/server` file with Synapse 55 56If you are able to set up your domain so that `https://<server_name>` is routed to 57Synapse (i.e., the only change needed is to direct federation traffic to port 443 58instead of port 8448), then it is possible to configure Synapse to serve a suitable 59`.well-known/matrix/server` file. To do so, add the following to your `homeserver.yaml` 60file: 61 62```yaml 63serve_server_wellknown: true 64``` 65 66**Note**: this *only* works if `https://<server_name>` is routed to Synapse, so is 67generally not suitable if Synapse is hosted at a subdomain such as 68`https://synapse.example.com`. 69 70## SRV DNS record delegation 71 72It is also possible to do delegation using a SRV DNS record. However, that is generally 73not recommended, as it can be difficult to configure the TLS certificates correctly in 74this case, and it offers little advantage over `.well-known` delegation. 75 76However, if you really need it, you can find some documentation on what such a 77record should look like and how Synapse will use it in [the Matrix 78specification](https://matrix.org/docs/spec/server_server/latest#resolving-server-names). 79 80## Delegation FAQ 81 82### When do I need delegation? 83 84If your homeserver's APIs are accessible on the default federation port (8448) 85and the domain your `server_name` points to, you do not need any delegation. 86 87For instance, if you registered `example.com` and pointed its DNS A record at a 88fresh server, you could install Synapse on that host, giving it a `server_name` 89of `example.com`, and once a reverse proxy has been set up to proxy all requests 90sent to the port `8448` and serve TLS certificates for `example.com`, you 91wouldn't need any delegation set up. 92 93**However**, if your homeserver's APIs aren't accessible on port 8448 and on the 94domain `server_name` points to, you will need to let other servers know how to 95find it using delegation. 96 97### Should I use a reverse proxy for federation traffic? 98 99Generally, using a reverse proxy for both the federation and client traffic is a good 100idea, since it saves handling TLS traffic in Synapse. See 101[the reverse proxy documentation](reverse_proxy.md) for information on setting up a 102reverse proxy. 103