So richten Sie die Föderation in Matrix Synapse ein: Eine Schritt-für-Schritt-Anleitung

Die Matrix-Federation ermöglicht es einem Synapse-Homeserver, Raumereignisse mit anderen Homeservern auszutauschen, sodass Benutzer verschiedener Server am selben Raum teilnehmen können. Zur Einrichtung muss die Synapse-Federations-API über HTTPS erreichbar sein, die korrekten Server-Discovery-Informationen müssen veröffentlicht, der erforderliche Netzwerkverkehr zugelassen und der öffentliche Endpunkt getestet werden. Das bloße Starten von Synapse oder das Öffnen von Port 8448 reicht nicht aus, wenn DNS, TLS oder das Proxy-Routing fehlerhaft sind.

Diese Anleitung verwendet eine typische Reverse-Proxy-Bereitstellung: Die Matrix-Identitätsdomäne ist example.org, Synapse läuft unter matrix.example.org, und der Proxy verarbeitet TLS auf Port 443. Ersetzen Sie beide Beispieldomänen durch Ihre eigenen. Wenn Synapse bereits über HTTPS unter erreichbar ist example.org:8448, benötigen Sie in der Regel keine Delegierung. Befehle und Dateipfade hängen davon ab, ob Sie Synapse als Paket, in einer virtuellen Umgebung oder in einem Container installiert haben.

Was muss erfüllt sein, damit eine Föderation funktionieren kann?

• Ihr Synapse-Server hat einen stabilen öffentlichen Hostnamen server_name. Dieser Name erscheint in Matrix-IDs wie z. B. @alex:example.org; eine spätere Änderung ist keine routinemäßige Hostnamensbearbeitung.
• Andere Homeserver können die Federation-API über HTTPS erreichen und das TLS-Zertifikat validieren.
• Die Servererkennung leitet entfernte Homeserver zum richtigen Host und Port. Der Standard-Federationsport ist 8448; die Delegierung kann auf HTTPS über Port 443 verweisen.
• Die Firewall-Regeln erlauben eingehenden Datenverkehr am von Ihnen gewählten Verbundendpunkt sowie ausgehende Verbundverbindungen.

Federation ermöglicht die Kommunikation zwischen Servern. Private Räume werden dadurch nicht automatisch öffentlich gemacht oder andere Benutzer eingeladen. Benutzer müssen weiterhin Räumen beitreten oder eingeladen werden, und die Raummitgliedschaft sowie die Raumeinstellungen bestimmen, wer teilnehmen kann. Legen Sie zunächst fest, wie Ihre Matrix-IDs aussehen sollen, und verwenden Sie dann dieselbe Domäne wie Synapse server_name.

Schritt 1: Überprüfen Sie den Synapse-Servernamen und die Bereitstellung.

Öffnen Sie die aktive Domain homeserver.yamlund bestätigen Sie, dass server_namees sich um die Domain handelt, die Sie behalten möchten. Eine gängige Vorgehensweise ist:

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

server_nameBestimmt die Domäne in den Matrix-IDs der Benutzer. public_baseurlEs handelt sich um die öffentliche, clientseitige URL, z. B. die URL, die Benutzer in einen Client eingeben; hinter einem Reverse-Proxy sollte sie die Proxy-URL angeben. Sie dienen unterschiedlichen Zwecken, ersetzen Sie daher den Servernamen nicht durch einen Backend-Containernamen und ändern Sie ihn nicht nur, um ihn an eine Subdomain anzupassen. Wenn der Server bereits in Betrieb ist, sichern Sie seine Konfiguration und Datenbank, bevor Sie die Netzwerkeinstellungen ändern.

Prüfen Sie, wie Synapse installiert und verwaltet wird. Systemd-Dienste, Docker-Compose-Stacks, Kubernetes-Bereitstellungen und Managed-Hosting-Produkte verwenden unterschiedliche Neustart- und Netzwerkverfahren. Wenden Sie die folgenden Beispiele auf die korrekte Konfigurationsdatei an und behalten Sie alle vorhandenen Listener und benutzerdefinierten Einstellungen bei.

Schritt 2: Wählen Sie die direkte Föderation auf 8448 oder die Delegation auf 443.

Es gibt zwei gängige Wege für den Eintritt in den Föderationsverbund:

• Verwenden Sie den Standardport 8448: Richten Sie die DNS-Einträge für die server_nameDomain auf den Server ein, stellen Sie HTTPS auf Port 8448 bereit und legen Sie ein für diese Domain gültiges Zertifikat vor. Wenn die APIs unter der angegebenen Domain server_nameauf Port 8448 verfügbar sind, ist laut Synapse-Dokumentation keine Delegierung erforderlich.
• Verwenden Sie Port 443 mit Delegierung: Stellen Sie die Anfrage https://example.org/.well-known/matrix/servermit JSON bereit, das andere Server zum tatsächlichen Endpunkt weiterleitet, zum Beispiel {"m.server":"matrix.example.org:443"}. Der delegierte Hostname muss öffentlich auflösbar sein und ein gültiges Zertifikat für vorweisen matrix.example.org.

Port 8448 ist nicht in jeder Bereitstellung zwingend erforderlich. Bei Verwendung der Portdelegierung auf Port 443 kann eingehender Datenverkehr stattdessen Port 443 nutzen. Falls ausgehende Verbindungen durch eine Firewall eingeschränkt sind, sollten Sie sowohl Port 443 als auch 8448 zulassen, da Remote-Server beide Ports verwenden können. Wählen Sie eine eingehende Route und stellen Sie sicher, dass DNS-Eintrag, TLS-Zertifikat, Reverse-Proxy und Firewall darauf abgestimmt sind.

Schritt 3: Leiten Sie die Synapse-Federations-API über den Reverse-Proxy weiter.

Synapse lauscht üblicherweise auf HTTP-Port 8008 hinter einem Reverse-Proxy. Der Proxy beendet HTTPS-Anfragen und leitet die Matrix-Endpunkte an Synapse weiter. Stellen Sie im entsprechenden homeserver.yamlListener sicher, dass der HTTP-Listener sowohl die Client- als auch die Verbundressourcen enthält und den Proxy-Headern vertraut.

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]

Dies ist ein Beispiel-Listener und kein direkter Ersatz für die vollständige Konfiguration jeder Installation. Wenn Synapse in einem Container ausgeführt wird, 127.0.0.1kann die Bindung innerhalb des Containers verhindern, dass der Proxy-Container den Listener erreicht. Verwenden Sie stattdessen das Service-Netzwerk und eine geeignete Bindungsadresse. Halten Sie den Backend-Listener privat und geben Sie wie vorgesehen nur den Proxy frei.

Konfigurieren Sie den Proxy so, dass er Anfragen an Port 8008 weiterleitet /_matrix, /_synapse/clientindem Sie die entsprechenden Einstellungen X-Forwarded-Forvornehmen X-Forwarded-Proto. Für NGINX kann die entsprechende Stelle wie folgt aussehen:

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

Verwenden Sie die korrekte Upstream-Adresse für Ihren Host oder Ihr Containernetzwerk. Hängen Sie keinen umgeschriebenen Pfad an proxy_pass; die Proxy-Richtlinien von Synapse weisen darauf hin, dass die Normalisierung kodierter Anfragepfade zu Fehlern bei der Überprüfung der Verbundsignatur führen kann. Passen Sie die Upload-Größenbeschränkung des Proxys an die Synapse-Einstellungen für Medien-Uploads an, wenn Benutzer größere Dateien hochladen müssen.

Schritt 4: TLS und DNS konfigurieren

Besorgen Sie sich ein öffentlich vertrauenswürdiges TLS-Zertifikat für den Hostnamen, der für die Föderation verwendet wird. Bei der oben beschriebenen Reverse-Proxy-Konfiguration ist dies erforderlich, matrix.example.orgwenn Sie die Delegierung an diesen Host nutzen. Stellen Sie sicher, dass der Proxy die vollständige Zertifikatskette bereitstellt, Zertifikate automatisch erneuert und das richtige Zertifikat auf dem Port bereitstellt, den die Remote-Server kontaktieren. Ein selbstsigniertes Zertifikat oder ein Zertifikat für den falschen Hostnamen führt bei der Validierung auf anderen Homeservern zu einem Fehler.

Erstellen Sie einen öffentlichen A-Eintrag und, falls Sie IPv6 verwenden, einen AAAA-Eintrag, der matrix.example.orgauf den Proxy verweist. Stellen Sie sicher, dass beide Einträge den gewünschten Dienst erreichen; ein fehlerhafter AAAA-Eintrag kann zu Fehlern bei IPv6-fähigen Remote-Servern führen, selbst wenn IPv4 funktioniert. Wenn Sie Port 8448 direkt verwenden, example.orgmuss der DNS-Eintrag zum Listener führen und dessen Zertifikat muss übereinstimmen example.org.

Schritt 5: Serverermittlungsinformationen veröffentlichen

Im delegierten Beispiel soll die unten stehende HTTPS-URL den Statuscode 200 und JSON mit dem genauen Endpunkt zurückgeben:

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

Stellen Sie die Datei bereit application/json. Prüfen Sie, ob sie ohne Anmeldung öffentlich lesbar ist, keine Weiterleitungsschleife verursacht und ob Hostname und Port mit dem TLS-Proxy übereinstimmen. Veröffentlichen Sie matrix.example.orgdie Datei nicht, wenn der Proxy die Föderation über einen anderen Kanal leitet.

Synapse kann diese Datei serve_server_wellknown: truenur dann selbst bereitstellen, wenn Anfragen https://<server_name>/an Synapse entsprechend weitergeleitet werden. Lautet Ihr Servername beispielsweise „example.com“, example.orgSynapse befindet sich aber unter „example.com“ matrix.example.org, ist ein statischer Webserver oder ein Reverse-Proxy auf „ example.orgexample.com“ oft der geeignetere Ort, um die Delegierungsantwort bereitzustellen.

Ein häufiger Fehler ist die Verwechslung von Server- /.well-known/matrix/clientund /.well-known/matrix/serverClientdatei. Die Serverdatei hilft anderen Homeservern, eingehende Föderationsverbindungen zu erkennen. Die Clientdatei stellt eine clientseitige Homeserver-URL bereit und ist für die Föderation optional. Richten Sie sie nur dann separat ein, wenn kompatible Clients die Client-URL anhand der Matrix-IDs der Benutzer ermitteln sollen.

Schritt 6: Öffnen Sie die erforderlichen Firewall-Pfade

Bei direkter Föderation muss der eingehende TCP-Verkehr über Port 8448 an den TLS-Listener oder Proxy freigegeben werden. Im delegierten Beispiel muss der eingehende TCP-Verkehr über Port 443 an den Proxy freigegeben werden. Client-Verbindungen verwenden üblicherweise ebenfalls HTTPS über Port 443. Wenn der ausgehende Netzwerkzugriff eingeschränkt ist, muss Synapse Verbindungen zu entfernten Homeservern über die TCP-Ports 443 und 8448 ermöglichen. Der Backend-Port 8008 von Synapse darf nicht für das öffentliche Internet freigegeben werden, wenn der Reverse-Proxy als öffentlicher Zugangspunkt dienen soll.

Befindet sich der Server hinter einer Cloud-Firewall, einem Router, einem Containernetzwerk und einer Host-Firewall, überprüfen Sie jede einzelne Ebene. Eine erfolgreiche lokale Anfrage an Port 8008 beweist lediglich, dass Synapse lokal antwortet; sie beweist nicht, dass ein entfernter Matrix-Server Ihre Domain auflösen, TLS validieren oder den öffentlichen Listener erreichen kann.

Schritt 7: Sicher neu starten und die öffentlichen Endpunkte überprüfen

Überprüfen Sie die YAML-Datei vor dem Neustart mithilfe des von Ihrer Installationsmethode unterstützten Validierungsbefehls. Starten Sie anschließend den Synapse-Dienst oder die Bereitstellung neu und prüfen Sie die Protokolle auf Konfigurations- oder Listenerfehler. Fordern Sie von einem Rechner außerhalb Ihres privaten Netzwerks die Discovery-Datei und den Federation-Versionsendpunkt an.

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

Beim ersten Befehl erwarten Sie eine HTTPS-Antwort mit einem JSON-Body, der die korrekten Daten enthält m.server. Beim zweiten Befehl erwarten Sie eine erfolgreiche HTTPS-Antwort von Synapse und keine Fehlermeldung wie Proxy-Fehler, Zertifikatswarnung oder Verbindungstimeout. Der genaue Antworttext kann je nach Synapse-Version variieren.

Geben Sie als Nächstes Ihre Matrix server_name(z. B. example.org, nicht unbedingt den Proxy-Hostnamen) im Matrix Federation Tester ein . Beheben Sie alle gemeldeten DNS-, Delegierungs-, Zertifikats- oder Endpunktfehler und führen Sie den Test erneut aus. Laden Sie anschließend einen Benutzer eines anderen Homeservers in einen Testraum ein oder treten Sie einem Raum bei, der an einem anderen Ort gehostet wird. Ein erfolgreiches Testergebnis ist ein nützlicher Test der öffentlichen Konnektivität, garantiert jedoch nicht, dass sich jeder Remote-Server, jede Raumrichtlinie, jede Firewall oder jede Clientkonfiguration identisch verhält.

Fehlannahmen, die zu fehlerhaften oder unerwarteten Situationen führen

• „Ich muss Port 8448 immer freigeben.“ Nein. Standardmäßig ist Port 8448, aber die Serverdelegierung kann eingehende Föderationsanfragen an Port 443 weiterleiten. Öffnen Sie den Port, den Ihre veröffentlichte Discovery-Route tatsächlich verwendet.
• „Die bekannte Client-Datei ermöglicht die Föderation.“ Das stimmt nicht. Die Föderationserkennung verwendet den bekannten Server-Endpunkt oder einen unterstützten DNS-Fallback; der Client-Endpunkt dient einem anderen Zweck.
• „Federation macht jeden lokalen Raum öffentlich.“ Nein. Federation ermöglicht die Serverkommunikation. Die Sichtbarkeit des Raums und die Mitgliedschaft regeln weiterhin die Teilnahme; laden Sie ein externes Konto in einen Testraum ein, um den benötigten Anwendungsfall zu bestätigen.
• „Ein positiver lokaler Gesundheitscheck beweist die Föderation.“ Nein. Lokale Prüfungen testen weder öffentliche DNS-Server noch externe TLS-Validierung, NAT, Cloud-Firewall-Regeln oder Proxy-Routing. Führen Sie die Prüfung von extern mit dem Föderationstester durch.

Die aktualisierte Synapse-Dokumentation empfiehlt einen Reverse-Proxy für die TLS-Terminierung und erläutert die separaten Client- und Federation-Ports. Informationen zur Reverse-Proxy-Konfiguration , zur eingehenden Federation-Delegierung , zu Synapse-Konfigurationsoptionen sowie zu Firewall- und Sicherheitsrichtlinien finden Sie in den offiziellen Anleitungen. Server-Discovery-Regeln sind in der Matrix Server-Server-API-Spezifikation beschrieben . Die hier aufgeführten Beispiele setzen ein Standard-Synapse hinter einem HTTPS-Reverse-Proxy voraus; Container-Netzwerke, verwaltete Bereitstellungen und benutzerdefinierte Listener-Layouts erfordern möglicherweise andere Werte.