diff options
| -rw-r--r-- | README.rst | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/README.rst b/README.rst index bc422d92ab..de45cd6d24 100644 --- a/README.rst +++ b/README.rst @@ -568,6 +568,105 @@ For information on how to install and use PostgreSQL, please see `docs/postgres.rst <docs/postgres.rst>`_. +.. _reverse-proxy: + +Using a reverse proxy with Synapse +================================== + +It is possible to put a reverse proxy such as +`nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`_, +`Apache <https://httpd.apache.org/docs/current/mod/mod_proxy_http.html>`_ or +`HAProxy <http://www.haproxy.org/>`_ in front of Synapse. One advantage of +doing so is that it means that you can expose the default https port (443) to +Matrix clients without needing to run Synapse with root privileges. + +The most important thing to know here is that Matrix clients and other Matrix +servers do not necessarily need to connect to your server via the same +port. Indeed, clients will use port 443 by default, whereas other servers +default to port 8448. Where these are different, we refer to the 'client port' +and the 'federation port'. + +The next most important thing to know is that using a reverse-proxy on the +federation port has a number of pitfalls. It is possible, but be sure to read +`Reverse-proxying the federation port`_. + +The recommended setup is therefore to configure your reverse-proxy on port 443 +for client connections, but to also expose port 8448 for server-server +connections. All the Matrix endpoints begin ``/_matrix``, so an example nginx +configuration might look like:: + + server { + listen 443 ssl; + listen [::]:443 ssl; + server_name matrix.example.com; + + location /_matrix { + proxy_pass http://localhost:8008; + proxy_set_header X-Forwarded-For $remote_addr; + } + } + +You will also want to set ``bind_address: 127.0.0.1`` and ``x_forwarded: true`` +for port 8008 in ``homeserver.yaml`` to ensure that client IP addresses are +recorded correctly. + +Having done so, you can then use ``https://matrix.example.com`` (instead of +``https://matrix.example.com:8448``) as the "Custom server" when `Connecting to +Synapse from a client`_. + +Reverse-proxying the federation port +------------------------------------ + +There are two issues to consider before using a reverse-proxy on the federation +port: + +* Due to the way SSL certificates are managed in the Matrix federation protocol + (see `spec <https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys>`_), + Synapse needs to be configured with the path to the SSL certificate, *even if + you do not terminate SSL at Synapse*. + +* Synapse does not currently support SNI on the federation protocol + (`bug #1491 <https://github.com/matrix-org/synapse/issues/1491>`_), which + means that using name-based virtual hosting is unreliable. + +Furthermore, a number of the normal reasons for using a reverse-proxy do not +apply: + +* Other servers will connect on port 8448 by default, so there is no need to + listen on port 443 (for federation, at least), which avoids the need for root + privileges and virtual hosting. + +* A self-signed SSL certificate is fine for federation, so there is no need to + automate renewals. (The certificate generated by ``--generate-config`` is + valid for 10 years.) + +If you want to set up a reverse-proxy on the federation port despite these +caveats, you will need to do the following: + +* In ``homeserver.yaml``, set ``tls_certificate_path`` to the path to the SSL + certificate file used by your reverse-proxy, and set ``no_tls`` to ``True``. + (``tls_private_key_path`` will be ignored if ``no_tls`` is ``True``.) + +* In your reverse-proxy configuration, if there are other virtual hosts on the + same port, make sure that Synapse is the default. + +* If your reverse-proxy is not listening on port 8448, publish a SRV record to + tell other servers how to find you. See `Setting up Federation`_. + +When updating the SSL certificate, just update the file pointed to by +``tls_certificate_path``: there is no need to restart synapse. (You may like to +use a symbolic link to help make this process atomic.) + +The most common mistake when setting up federation is not to tell Synapse about +your SSL certificate. To check it, you can visit +``https://matrix.org/federationtester/api/report?server_name=<your_server_name>``. +Unfortunately, there is no UI for this yet, but, you should see +``"MatchingTLSFingerprint": true``. If not, check that +``Certificates[0].SHA256Fingerprint`` (the fingerprint of the certificate +presented by your reverse-proxy) matches ``Keys.tls_fingerprints[0].sha256`` +(the fingerprint of the certificate Synapse is using). + + Identity Servers ================ |