mirror of
https://github.com/element-hq/synapse
synced 2024-08-20 05:00:20 +00:00
Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change.
194 lines
8.6 KiB
Markdown
194 lines
8.6 KiB
Markdown
Setting up Federation
|
|
=====================
|
|
|
|
Federation is the process by which users on different servers can participate
|
|
in the same room. For this to work, those other servers must be able to contact
|
|
yours to send messages.
|
|
|
|
The ``server_name`` configured in the Synapse configuration file (often
|
|
``homeserver.yaml``) defines how resources (users, rooms, etc.) will be
|
|
identified (eg: ``@user:example.com``, ``#room:example.com``). By
|
|
default, it is also the domain that other servers will use to
|
|
try to reach your server (via port 8448). This is easy to set
|
|
up and will work provided you set the ``server_name`` to match your
|
|
machine's public DNS hostname, and provide Synapse with a TLS certificate
|
|
which is valid for your ``server_name``.
|
|
|
|
Once federation has been configured, you should be able to join a room over
|
|
federation. A good place to start is ``#synapse:matrix.org`` - a room for
|
|
Synapse admins.
|
|
|
|
|
|
## Delegation
|
|
|
|
For a more flexible configuration, you can have ``server_name``
|
|
resources (eg: ``@user:example.com``) served by a different host and
|
|
port (eg: ``synapse.example.com:443``). There are two ways to do this:
|
|
|
|
- adding a ``/.well-known/matrix/server`` URL served on ``https://example.com``.
|
|
- adding a DNS ``SRV`` record in the DNS zone of domain
|
|
``example.com``.
|
|
|
|
Without configuring delegation, the matrix federation will
|
|
expect to find your server via ``example.com:8448``. The following methods
|
|
allow you retain a `server_name` of `example.com` so that your user IDs, room
|
|
aliases, etc continue to look like `*:example.com`, whilst having your
|
|
federation traffic routed to a different server.
|
|
|
|
### .well-known delegation
|
|
|
|
To use this method, you need to be able to alter the
|
|
``server_name`` 's https server to serve the ``/.well-known/matrix/server``
|
|
URL. Having an active server (with a valid TLS certificate) serving your
|
|
``server_name`` domain is out of the scope of this documentation.
|
|
|
|
The URL ``https://<server_name>/.well-known/matrix/server`` should
|
|
return a JSON structure containing the key ``m.server`` like so:
|
|
|
|
{
|
|
"m.server": "<synapse.server.name>[:<yourport>]"
|
|
}
|
|
|
|
In our example, this would mean that URL ``https://example.com/.well-known/matrix/server``
|
|
should return:
|
|
|
|
{
|
|
"m.server": "synapse.example.com:443"
|
|
}
|
|
|
|
Note, specifying a port is optional. If a port is not specified an SRV lookup
|
|
is performed, as described below. If the target of the
|
|
delegation does not have an SRV record, then the port defaults to 8448.
|
|
|
|
Most installations will not need to configure .well-known. However, it can be
|
|
useful in cases where the admin is hosting on behalf of someone else and
|
|
therefore cannot gain access to the necessary certificate. With .well-known,
|
|
federation servers will check for a valid TLS certificate for the delegated
|
|
hostname (in our example: ``synapse.example.com``).
|
|
|
|
.well-known support first appeared in Synapse v0.99.0. To federate with older
|
|
servers you may need to additionally configure SRV delegation. Alternatively,
|
|
encourage the server admin in question to upgrade :).
|
|
|
|
### DNS SRV delegation
|
|
|
|
To use this delegation method, you need to have write access to your
|
|
``server_name`` 's domain zone DNS records (in our example it would be
|
|
``example.com`` DNS zone).
|
|
|
|
This method requires the target server to provide a
|
|
valid TLS certificate for the original ``server_name``.
|
|
|
|
You need to add a SRV record in your ``server_name`` 's DNS zone with
|
|
this format:
|
|
|
|
_matrix._tcp.<yourdomain.com> <ttl> IN SRV <priority> <weight> <port> <synapse.server.name>
|
|
|
|
In our example, we would need to add this SRV record in the
|
|
``example.com`` DNS zone:
|
|
|
|
_matrix._tcp.example.com. 3600 IN SRV 10 5 443 synapse.example.com.
|
|
|
|
Once done and set up, you can check the DNS record with ``dig -t srv
|
|
_matrix._tcp.<server_name>``. In our example, we would expect this:
|
|
|
|
$ dig -t srv _matrix._tcp.example.com
|
|
_matrix._tcp.example.com. 3600 IN SRV 10 0 443 synapse.example.com.
|
|
|
|
Note that the target of a SRV record cannot be an alias (CNAME record): it has to point
|
|
directly to the server hosting the synapse instance.
|
|
|
|
### Delegation FAQ
|
|
#### When do I need a SRV record or .well-known URI?
|
|
|
|
If your homeserver listens on the default federation port (8448), and your
|
|
`server_name` points to the host that your homeserver runs on, you do not need an SRV
|
|
record or `.well-known/matrix/server` URI.
|
|
|
|
For instance, if you registered `example.com` and pointed its DNS A record at a
|
|
fresh server, you could install Synapse on that host,
|
|
giving it a `server_name` of `example.com`, and once [ACME](acme.md) support is enabled,
|
|
it would automatically generate a valid TLS certificate for you via Let's Encrypt
|
|
and no SRV record or .well-known URI would be needed.
|
|
|
|
This is the common case, although you can add an SRV record or
|
|
`.well-known/matrix/server` URI for completeness if you wish.
|
|
|
|
**However**, if your server does not listen on port 8448, or if your `server_name`
|
|
does not point to the host that your homeserver runs on, you will need to let
|
|
other servers know how to find it. The way to do this is via .well-known or an
|
|
SRV record.
|
|
|
|
#### I have created a .well-known URI. Do I still need an SRV record?
|
|
|
|
As of Synapse 0.99, Synapse will first check for the existence of a .well-known
|
|
URI and follow any delegation it suggests. It will only then check for the
|
|
existence of an SRV record.
|
|
|
|
That means that the SRV record will often be redundant. However, you should
|
|
remember that there may still be older versions of Synapse in the federation
|
|
which do not understand .well-known URIs, so if you removed your SRV record
|
|
you would no longer be able to federate with them.
|
|
|
|
It is therefore best to leave the SRV record in place for now. Synapse 0.34 and
|
|
earlier will follow the SRV record (and not care about the invalid
|
|
certificate). Synapse 0.99 and later will follow the .well-known URI, with the
|
|
correct certificate chain.
|
|
|
|
#### Can I manage my own certificates rather than having Synapse renew certificates itself?
|
|
|
|
Yes, you are welcome to manage your certificates yourself. Synapse will only
|
|
attempt to obtain certificates from Let's Encrypt if you configure it to do
|
|
so.The only requirement is that there is a valid TLS cert present for
|
|
federation end points.
|
|
|
|
#### Do you still recommend against using a reverse proxy on the federation port?
|
|
|
|
We no longer actively recommend against using a reverse proxy. Many admins will
|
|
find it easier to direct federation traffic to a reverse proxy and manage their
|
|
own TLS certificates, and this is a supported configuration.
|
|
|
|
See [reverse_proxy.md](reverse_proxy.md) for information on setting up a
|
|
reverse proxy.
|
|
|
|
#### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?
|
|
|
|
Practically speaking, this is no longer necessary.
|
|
|
|
If you are using a reverse proxy for all of your TLS traffic, then you can set
|
|
`no_tls: True` in the Synapse config. In that case, the only reason Synapse
|
|
needs the certificate is to populate a legacy `tls_fingerprints` field in the
|
|
federation API. This is ignored by Synapse 0.99.0 and later, and the only time
|
|
pre-0.99 Synapses will check it is when attempting to fetch the server keys -
|
|
and generally this is delegated via `matrix.org`, which will be running a modern
|
|
version of Synapse.
|
|
|
|
#### Do I need the same certificate for the client and federation port?
|
|
|
|
No. There is nothing stopping you from using different certificates,
|
|
particularly if you are using a reverse proxy. However, Synapse will use the
|
|
same certificate on any ports where TLS is configured.
|
|
|
|
## Troubleshooting
|
|
|
|
You can use the [federation tester](
|
|
<https://matrix.org/federationtester>) to check if your homeserver is
|
|
configured correctly. Alternatively try the [JSON API used by the federation tester](https://matrix.org/federationtester/api/report?server_name=DOMAIN).
|
|
Note that you'll have to modify this URL to replace ``DOMAIN`` with your
|
|
``server_name``. Hitting the API directly provides extra detail.
|
|
|
|
The typical failure mode for federation is that when the server tries to join
|
|
a room, it is rejected with "401: Unauthorized". Generally this means that other
|
|
servers in the room could not access yours. (Joining a room over federation is
|
|
a complicated dance which requires connections in both directions).
|
|
|
|
Another common problem is that people on other servers can't join rooms that
|
|
you invite them to. This can be caused by an incorrectly-configured reverse
|
|
proxy: see [reverse_proxy.md](<reverse_proxy.md>) for instructions on how to correctly
|
|
configure a reverse proxy.
|
|
|
|
## Running a Demo Federation of Synapses
|
|
|
|
If you want to get up and running quickly with a trio of homeservers in a
|
|
private federation, there is a script in the ``demo`` directory. This is mainly
|
|
useful just for development purposes. See [demo/README](<../demo/README>).
|