Clean up portions of docs that talk about reversing fed port

This commit is contained in:
Andrew Morgan 2019-02-01 14:39:50 +00:00
parent c5fc09322c
commit 57fe91f87b

View File

@ -212,27 +212,26 @@ key in the ``<server name>.signing.key`` file (the second word) to something
different. See `the spec`__ for more information on key management.) different. See `the spec`__ for more information on key management.)
.. __: `key_management`_ .. __: `key_management`_
The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is
configured without TLS; it should be behind a reverse proxy for TLS/SSL configured without TLS; it should be behind a reverse proxy for TLS/SSL
termination on port 443 which in turn should be used for clients. Port 8448 termination on port 443 which in turn should be used for clients. Port 8448
is configured to use TLS with a self-signed certificate. If you would like is configured to use TLS for `Federation`_ with a self-signed or verified
to do initial test with a client without having to setup a reverse proxy, certificate, but please be aware that a valid certificate will be required in
you can temporarly use another certificate. (Note that a self-signed Synapse v1.0.
certificate is fine for `Federation`_). You can do so by changing
``tls_certificate_path`` and ``tls_private_key_path``
in ``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure
to read `Using a reverse proxy with Synapse`_ when doing so.
Apart from port 8448 using TLS, both ports are the same in the default If you would like to do initial testing with a client without having to setup
configuration. a reverse proxy, you can temporarly use another certificate. You can do so by
changing ``tls_certificate_path`` and ``tls_private_key_path`` in
``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure
to read `Using a reverse proxy with Synapse`_ when doing so. Apart from port
8448 using TLS, both ports are the same in the default configuration.
ACME setup ACME setup
---------- ----------
Synapse requires valid TLS certificates for communication between servers Synapse v1.0 requires valid TLS certificates for communication between servers
(port ``8448`` by default) in addition to those that are client-facing (port (port ``8448`` by default) in addition to those that are client-facing (port
``443``). Synapse **will provision server-to-server certificates ``443``). Synapse v0.99.0+ **will provision server-to-server certificates
automatically for you for free** through `Let's Encrypt automatically for you for free** through `Let's Encrypt
<https://letsencrypt.org/>`_ if you tell it to. <https://letsencrypt.org/>`_ if you tell it to.
@ -287,23 +286,12 @@ Allow ``authbind`` to bind port 80::
sudo touch /etc/authbind/byport/80 sudo touch /etc/authbind/byport/80
sudo chmod 777 /etc/authbind/byport/80 sudo chmod 777 /etc/authbind/byport/80
When Synapse is started (do not start it yet), use the following syntax:: When Synapse is started, use the following syntax::
# authbind syntax. don't start Synapse yet
authbind --deep <synapse start command> authbind --deep <synapse start command>
If using the `Systemd`_ service file above, you can change the following line If you would like to use your own certificates, simply specify them in
from:: ``homeserver.yaml``.
ExecStart=/home/matrix/matrix-synapse/bin/python -m synapse.app.homeserver
to::
ExecStart=authbind --deep /home/matrix/matrix-synapse/bin/python -m synapse.app.homeserver
If you would like to use your own certificates, specifying them in Synapse's
config file is sufficient.
Registering a user Registering a user
@ -360,10 +348,11 @@ following the recommended setup, or ``https://localhost:8448`` - remember to spe
port (``:8448``) if not ``:443`` unless you changed the configuration. (Leave the identity port (``:8448``) if not ``:443`` unless you changed the configuration. (Leave the identity
server as the default - see `Identity servers`_.) server as the default - see `Identity servers`_.)
If using port 8448 you will run into errors until you accept the self-signed If using port 8448 you will run into errors if you are using a self-signed
certificate. You can easily do this by going to ``https://localhost:8448`` certificate. To overcome this, simply go to ``https://localhost:8448``
directly with your browser and accept the presented certificate. You can then directly with your browser and accept the presented certificate. You can then
go back in your web client and proceed further. go back in your web client and proceed further. Valid federation certificates
should not have this problem.
If all goes well you should at least be able to log in, create a room, and If all goes well you should at least be able to log in, create a room, and
start sending messages. start sending messages.
@ -632,9 +621,7 @@ you to run your server on a machine that might not have the same name as your
domain name. For example, you might want to run your server at domain name. For example, you might want to run your server at
``synapse.example.com``, but have your Matrix user-ids look like ``synapse.example.com``, but have your Matrix user-ids look like
``@user:example.com``. (A SRV record also allows you to change the port from ``@user:example.com``. (A SRV record also allows you to change the port from
the default 8448. However, if you are thinking of using a reverse-proxy on the the default 8448.
federation port, which is not recommended, be sure to read
`Reverse-proxying the federation port`_ first.)
To use a SRV record, first create your SRV record and publish it in DNS. This To use a SRV record, first create your SRV record and publish it in DNS. This
should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port> should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port>
@ -736,14 +723,10 @@ port. Indeed, clients will use port 443 by default, whereas servers default to
port 8448. Where these are different, we refer to the 'client port' and the port 8448. Where these are different, we refer to the 'client port' and the
'federation port'. 'federation port'.
The next most important thing to know is that using a reverse-proxy on the The recommended setup is therefore to configure your reverse-proxy on port
federation port has a number of pitfalls. It is possible, but be sure to read 443 to port 8008 of synapse for client connections, and port 8448 for
`Reverse-proxying the federation port`_. server-server connections. All Matrix endpoints begin with ``/_matrix``, so an
example nginx configuration might look like::
The recommended setup is therefore to configure your reverse-proxy on port 443
to port 8008 of synapse for client connections, but to also directly expose port
8448 for server-server connections. All the Matrix endpoints begin ``/_matrix``,
so an example nginx configuration might look like::
server { server {
listen 443 ssl; listen 443 ssl;
@ -784,63 +767,7 @@ 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 ``https://matrix.example.com:8448``) as the "Custom server" when `Connecting to
Synapse from a client`_. Synapse from a client`_.
Reverse-proxying the federation port Please see `ACME setup`_ for details on 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`__), Synapse needs to be configured with the path to the SSL
certificate, *even if you do not terminate SSL at Synapse*.
.. __: `key_management`_
* Until v0.33.3, Synapse did not support SNI on the federation port
(`bug #1491 <https://github.com/matrix-org/synapse/issues/1491>`_). This bug
is now fixed, but means that federating with older servers can be unreliable
when using name-based virtual hosting.
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 the
*default* one uses the certificate configured above.
* Forward ``/_matrix`` to Synapse.
* 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`` and then 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 Identity Servers