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.

1 files changed, 27 insertions, 13 deletions

diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md
index 414af96ef3..0a781d00e3 100644
--- a/docs/MSC1711_certificates_FAQ.md
+++ b/docs/MSC1711_certificates_FAQ.md
@@ -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