|
|
@@ -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 |
|
|
|
================ |
|
|
|
|
|
|
|