Update MSC1711 FAQ to be explicit about well-known (#4584)

A surprising number of people are using the well-known method, and are
simply copying the example configuration. This is problematic as the
example includes an explicit port, which causes inbound federation
requests to have the HTTP Host header include the port, upsetting some
reverse proxies.

Given that, we update the well-known example to be more explicit about
the various ways you can set it up, and the consequence of using an
explict port.
This commit is contained in:
Erik Johnston 2019-02-07 19:30:32 +00:00 committed by Richard van der Hoff
parent 7a22a645b5
commit acb2ac5863
2 changed files with 28 additions and 13 deletions

1
changelog.d/4584.misc Normal file
View file

@ -0,0 +1 @@
Update MSC1711 FAQ to calrify .well-known usage

View file

@ -107,12 +107,12 @@ hosted at a target domain of `customer.example.net`. Currently you should have
an SRV record which looks like:
```
_matrix._tcp.example.com. IN SRV 10 5 443 customer.example.net.
_matrix._tcp.example.com. IN SRV 10 5 8000 customer.example.net.
```
In this situation, you have two choices for how to proceed:
In this situation, you have three choices for how to proceed:
#### Option 1: give Synapse (or a reverse-proxy) a certificate for your matrix domain
#### Option 1: give Synapse a certificate for your matrix domain
Synapse 1.0 will expect your server to present a TLS certificate for your
`server_name` (`example.com` in the above example). You can achieve this by
@ -123,12 +123,16 @@ doing one of the following:
and `tls_private_key_path`, or:
* Use Synapse's [ACME support](./ACME.md), and forward port 80 on the
`server_name` domain to your Synapse instance, or:
`server_name` domain to your Synapse instance.
* Set up a reverse-proxy on port 8448 on the `server_name` domain, which
forwards to Synapse. Once it is set up, you can remove the SRV record.
### Option 2: run Synapse behind a reverse proxy
#### Option 2: add a .well-known file to delegate your matrix traffic
If you have an existing reverse proxy set up with correct TLS certificates for
your domain, you can simply route all traffic through the reverse proxy by
updating the SRV record appropriately (or removing it, if the proxy listens on
8448).
#### Option 3: add a .well-known file to delegate your matrix traffic
This will allow you to keep Synapse on a separate domain, without having to
give it a certificate for the matrix domain.
@ -151,15 +155,25 @@ You can do this with a `.well-known` file as follows:
`https://<server_name>/.well-known/matrix/server` with contents:
```json
{"m.server": "<target domain>:<port>"}
{"m.server": "<target server name>"}
```
In the above example, `https://example.com/.well-known/matrix/server`
should have the contents:
where the target server name is resolved as usual (i.e. SRV lookup, falling
back to talking to port 8448).
In the above example, where synapse is listening on port 8000,
`https://example.com/.well-known/matrix/server` should have `m.server` set to one of:
1. `customer.example.net` ─ with a SRV record on
`_matrix._tcp.customer.example.com` pointing to port 8000, or:
2. `customer.example.net` ─ updating synapse to listen on the default port
8448, or:
3. `customer.example.net:8000` ─ ensuring that if there is a reverse proxy
on `customer.example.net:8000` it correctly handles HTTP requests with
Host header set to `customer.example.net:8000`.
```json
{"m.server": "customer.example.net:443"}
```
## FAQ