Synapse Section: Federation
Federation is the process by which users on different servers can participate in the same room. For this to work, all servers participating in a room must be able to talk to each other.
When Federation is Open
, you will not need to configure anything further, however to privately federate you will need to make use of the Federation
section found under Advanced
.
Where do I set Federation Type?
At the top of the Synapse Section you configure the Federation Type, Open
, Limited
or Closed
within the Profile options. Set to Open
to Federate with all homeservers, Limited
if you wish to make use of the below advanced Federation options to Federate within a trusted network or Closed
to prevent Federation completely.
Previous setups may have used the Synapse Additional config. Configuration of Federation settings via Additional Config, that are in conflict with any set via the UI, will not override the UI set values. As such, we do not advise including them or any related settings within the Additional Config as they are of increased risk to causing issues with your deployment and are not supported.
Client Minimum TLS Version
federation_client_minimum_tls_version
Allows you to choose the minimum TLS version that will be used for outbound federation requests. Defaults to "1.2". Configurable to "1.2" or "1.3".
Setting this value higher than "1.2" will prevent federation to most of the public Matrix network: only configure it to "1.3" if you have an entirely private federation setup and you can ensure TLS 1.3 support.
Certificate Autorities Secret Keys
Configure when you are federating between homeservers' whose certificates are signed by different Certificate Authorities, click the Add Certificate Authorities Secret Keys
/ Add More Certificate Authorities Secret Keys
button to reveal the option to upload your CA certificate.
Uploaded certificates should be PEM encoded and include the full chain of intermediate CAs and the root CA. You can simply concatenate these files prior to uploading.
Trusted Key Servers
Used to specify the trusted servers to download signing keys from. When synapse needs to fetch a signing key, each server is tried in parallel. Normally, the connection to the key server is validated via TLS certificates. Verify keys provide additional security by making synapse check that the response is signed by that key.
Click Add Trusted Key Servers
/ Add More Trusted Key Servers
to add a new key server, then provide the homeservers' federated server name, i.e. the base domain of the homeserver you with to federate with. Under Verify Keys
for the server, you will need to provide it's Key ID
and Public Key
.
Getting a Homeservers' Key ID
and Public Key
from your browser
Simply access the Synapse endpoint GET /_matrix/key/v2/server
. You must use the domain where your Synapse is exposed, this might be different than the domain you have in your Matrix IDs. For example https://matrix.yourcomapany.com/_matrix/key/v2/server
.
For the element.io homeserver, https://element.ems.host/_matrix/key/v2/server returns
{
"old_verify_keys": {},
"server_name": "element.io",
"signatures": {
"element.io": {
"ed25519:DnK8xk": "oOgEpir32XvnuMXQs+GvB6nOuIWgYathJ8kbzDhh9TT/BVSEH116Kk9NYUVPeXHJO0HhzBeTjmAiuUTVFS8nCg"
}
},
"valid_until_ts": 1715307962481,
"verify_keys": {
"ed25519:DnK8xk": {
"key": "EgdGx+0oy/9IX5k7tCobr0JoiwMvmmQ8sDOVlZODh/o"
}
}
}
Under verify_keys
, ed25519:DnK8xk
is the Key ID and EgdGx+0oy/9IX5k7tCobr0JoiwMvmmQ8sDOVlZODh/o
is the Public Key.
Getting an On-Premise Homeservers' Key ID
and Public Key
via the Installer
You can retrieve the Public Key
of an On-Premise Homeserver by re-running the installer on the host, then navigating to the Synapse
section. Under Advanced
, Config
you will be presented with the homeservers' Public Key in a blue box.
Copy the entire string, taking the example above, it would be ed25519 jRheIX llomL0SL2eq6WfzaqtPX8QzYEP3c0a5E9G9NNamU4JQ
. From this string, you can derive the Key ID
and Public Key
required when you wish to add this homeserver to another homeservers' Federation Trusted Key Servers.
- The
Key ID
is the first two sections joined with a:
, soed25519:jRheIX
- The
Public Key
is the remainder of the string, sollomL0SL2eq6WfzaqtPX8QzYEP3c0a5E9G9NNamU4JQ
Allow List
Use the Allow List to restrict federation to the given whitelist of domains, if not specified, the default is to whitelist everything. Simply provide the homeservers' federated server name, i.e. the base domain of the homeservers' you with to federate with.
We recommend also firewalling your federation listener to limit inbound federation traffic as early as possible, rather than relying purely on this application-layer restriction.
This does not stop a server from joining rooms that servers not on the whitelist are in. As such, this option is really only useful to establish a "private federation", where a group of servers all whitelist each other and have the same whitelist.
Please also note that by default an ip_range_blacklist
is configured to block all private IP address ranges. If your servers require communicating on any of the below ranges, you will need to configure ip_range_whitelist
. See Allowing Private Federation via ip_range_whitelist
for information on configuring this.