Jak skonfigurować federację w Matrix Synapse: przewodnik krok po kroku

Federacja Matrix umożliwia serwerowi domowemu Synapse wymianę zdarzeń w pokoju z innymi serwerami domowymi, dzięki czemu osoby korzystające z różnych serwerów mogą uczestniczyć w tym samym pokoju. Aby to skonfigurować, należy udostępnić API federacji Synapse przez HTTPS, opublikować prawidłowe informacje o wykrywaniu serwerów, zezwolić na wymagany ruch sieciowy i przetestować publiczny punkt końcowy. Samo uruchomienie Synapse lub otwarcie portu 8448 nie wystarczy, jeśli routing DNS, TLS lub proxy jest nieprawidłowy.

W tym przewodniku wykorzystano typowe wdrożenie odwrotnego serwera proxy: domeną tożsamości Matrix jest example.org, Synapse działa w matrix.example.org, a serwer proxy obsługuje TLS na porcie 443. Zastąp obie przykładowe domeny swoimi własnymi. Jeśli Synapse jest już dostępny przez HTTPS w example.org:8448, zazwyczaj nie potrzebujesz delegowania. Polecenia i ścieżki do plików zależą od tego, czy Synapse został zainstalowany z pakietu, środowiska wirtualnego czy kontenera.

Co musi zostać spełnione, aby federacja mogła zadziałać?

• Twój serwer Synapse ma stabilną publiczną nazwę server_name. Ta nazwa pojawia się w identyfikatorach Matrix, takich jak @alex:example.org; jej późniejsza zmiana nie jest rutynową edycją nazwy hosta.
• Inne serwery domowe mogą nawiązać połączenie z interfejsem API federacji za pomocą protokołu HTTPS i zweryfikować certyfikat TLS.
• Wykrywanie serwerów prowadzi zdalne serwery domowe do właściwego hosta i portu. Standardowy port federacyjny to 8448; delegacja może wskazywać na HTTPS na porcie 443.
• Reguły zapory zezwalają na ruch przychodzący do wybranego punktu końcowego federacji i połączenia wychodzące federacji.

Federacja opiera się na komunikacji między serwerami. Nie upublicznia automatycznie prywatnych pokoi ani nie zaprasza innych użytkowników. Użytkownicy nadal muszą dołączyć do pokoi lub zostać do nich zaproszeni, a członkostwo w pokoju i jego ustawienia określają, kto może uczestniczyć. Zacznij od ustalenia, jak powinny wyglądać Twoje identyfikatory Matrix, a następnie użyj tej samej domeny, co w Synapse server_name.

Krok 1: Sprawdź nazwę i wdrożenie serwera Synapse

Otwórz domenę aktywną homeserver.yamli potwierdź, że server_nameto ta, którą chcesz zachować. Typowy układ jest następujący:

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

server_nameOkreśla domenę w identyfikatorach Matrix użytkowników. public_baseurlJest to publiczny adres URL widoczny dla klienta, taki jak adres URL wprowadzany przez użytkowników w kliencie; za odwrotnym serwerem proxy powinien on nazywać adres URL serwera proxy. Służą one różnym celom, dlatego nie należy zastępować nazwy serwera nazwą kontenera zaplecza ani zmieniać jej tylko po to, aby pasowała do subdomeny. Jeśli serwer jest już używany, przed zmianą ustawień sieciowych należy wykonać kopię zapasową jego konfiguracji i bazy danych.

Sprawdź, jak instaluje się i zarządza Synapse. Usługa systemd, stos Docker Compose, wdrożenie Kubernetes i zarządzany produkt hostingowy korzystają z różnych procedur ponownego uruchamiania i sieciowania. Zastosuj poniższe przykłady do prawidłowego pliku konfiguracyjnego i zachowaj wszelkie istniejące programy nasłuchujące oraz ustawienia niestandardowe.

Krok 2: Wybierz bezpośrednią federację na 8448 lub delegację na 443

Istnieją dwie popularne trasy dla federacji przychodzącej:

• Użyj domyślnego portu 8448: skieruj DNS domeny server_namena serwer, udostępnij HTTPS na porcie 8448 i przedstaw certyfikat ważny dla tej domeny. Jeśli interfejsy API są dostępne w domenie o nazwie server_namena porcie 8448, dokumentacja Synapse informuje, że delegowanie nie jest potrzebne.
• Użyj portu 443 z delegacją: obsługuj https://example.org/.well-known/matrix/serverJSON kierujący inne serwery do faktycznego punktu końcowego, na przykład {"m.server":"matrix.example.org:443"}. Delegowana nazwa hosta musi być rozpoznawana publicznie i przedstawiać prawidłowy certyfikat dla matrix.example.org.

Port 8448 nie jest obowiązkowy w każdym wdrożeniu. Jeśli używasz delegowania do 443, federacja przychodząca może używać portu 443. Jeśli połączenia wychodzące są ograniczone przez zaporę wychodzącą, zezwól zarówno na 443, jak i 8448, ponieważ serwery zdalne mogą używać obu. Wybierz jedną trasę przychodzącą i upewnij się, że rekord DNS, certyfikat TLS, odwrotny serwer proxy i zapora sieciowa ją akceptują.

Krok 3: Przekieruj interfejs API federacji Synapse przez odwrotny serwer proxy

Synapse zazwyczaj nasłuchuje na porcie HTTP 8008 za odwrotnym serwerem proxy. Serwer proxy kończy połączenie HTTPS i przekazuje punkty końcowe Matrix do Synapse. homeserver.yamlUpewnij się, że w odpowiednim programie nasłuchującym HTTP uwzględnia on zarówno zasoby klienta, jak i federacji oraz ufa nagłówkom serwera proxy:

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

To przykładowy nasłuchiwacz, a nie zamiennik pełnej konfiguracji każdej instalacji. Jeśli Synapse działa w kontenerze, powiązanie z 127.0.0.1kontenerem może uniemożliwić dotarcie do niego kontenerowi proxy; zamiast tego należy użyć sieci usługi i odpowiedniego adresu powiązania. Zachowaj prywatność nasłuchiwacza zaplecza i udostępniaj tylko serwer proxy zgodnie z przeznaczeniem.

Skonfiguruj serwer proxy, aby przekierowywał żądania dla portu 8008 /_matrixi 8008, ustawiając i . W przypadku NGINX podstawowa lokalizacja może wyglądać następująco:/_synapse/clientX-Forwarded-ForX-Forwarded-Proto

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;
}

Użyj prawidłowego adresu upstream dla swojego hosta lub sieci kontenerów. Nie dodawaj przepisanej ścieżki do proxy_pass; wskazówki dotyczące proxy Synapse ostrzegają, że normalizacja zakodowanych ścieżek żądań może powodować błędy weryfikacji podpisu federacyjnego. Dostosuj limit rozmiaru przesyłanego proxy do ustawienia przesyłania multimediów Synapse, jeśli użytkownicy muszą przesyłać większe pliki.

Krok 4: Skonfiguruj TLS i DNS

Uzyskaj publicznie zaufany certyfikat TLS dla nazwy hosta obsługującej federację. W przypadku powyższej konfiguracji odwrotnego serwera proxy, czyli matrix.example.orgdelegowania do tego hosta, należy upewnić się, że serwer proxy obsługuje cały łańcuch certyfikatów, automatycznie odnawia certyfikaty i prezentuje właściwy certyfikat na porcie, z którym będą się kontaktować serwery zdalne. Certyfikat podpisany samodzielnie lub dla niewłaściwej nazwy hosta nie przejdzie walidacji na innych serwerach domowych.

Utwórz publiczny rekord A, a jeśli używasz IPv6, rekord AAAA, matrix.example.orgwskazujący na serwer proxy. Sprawdź, czy oba rekordy docierają do docelowej usługi; nieprawidłowy rekord AAAA może powodować awarie zdalnych serwerów obsługujących IPv6, nawet gdy działa IPv4. Jeśli używasz portu 8448 bezpośrednio, DNS example.orgmusi prowadzić do nasłuchiwacza, a jego certyfikat musi być zgodny example.org.

Krok 5: Opublikuj informacje o wykrywaniu serwera

W przykładzie delegowanym spraw, aby poniższy adres URL HTTPS zwracał status 200 i JSON z dokładnym punktem końcowym:

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

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

Podaj go jako application/json. Sprawdź, czy jest publicznie czytelny bez logowania, czy nie przekierowuje w pętli oraz czy nazwa hosta i port są zgodne z serwerem proxy TLS. Nie publikuj matrix.example.orgw pliku, jeśli serwer proxy faktycznie kieruje federację gdzie indziej.

Synapse może sam obsłużyć ten plik serve_server_wellknown: truetylko wtedy, gdy żądania do https://<server_name>/są odpowiednio kierowane do Synapse. Jeśli nazwa Twojego serwera to , example.orgale Synapse jest hostowany pod adresem matrix.example.org, statyczny serwer WWW lub odwrotny serwer proxy na example.orgjest często bardziej odpowiednim miejscem do obsługi odpowiedzi delegacji.

Częstym błędem jest traktowanie /.well-known/matrix/clienti /.well-known/matrix/serverjako zamiennych. Plik serwera pomaga innym serwerom domowym wykryć przychodzące federacje. Plik klienta reklamuje adres URL serwera domowego skierowany do klienta i jest opcjonalny dla federacji. Skonfiguruj go osobno tylko wtedy, gdy chcesz, aby zgodne klienty wykrywały adres URL klienta na podstawie identyfikatorów Matrix użytkowników.

Krok 6: Otwórz wymagane ścieżki zapory

W przypadku federacji przychodzącej bezpośrednio zezwól na przychodzący port TCP 8448 do odbiornika TLS lub serwera proxy. W przypadku delegowania zezwól na przychodzący port TCP 443 do serwera proxy. Połączenia klienckie również zazwyczaj korzystają z protokołu HTTPS na porcie 443. Jeśli dostęp do sieci wychodzącej jest ograniczony, zezwól Synapse na łączenie się ze zdalnymi serwerami domowymi przez porty TCP 443 i 8448. Nie otwieraj portu zaplecza Synapse 8008 dla publicznego internetu, gdy odwrotny serwer proxy ma być publicznym punktem wejścia.

Jeśli serwer znajduje się za zaporą sieciową w chmurze, routerem, siecią kontenerową i zaporą hosta, sprawdź każdą warstwę. Udane lokalne żądanie do portu 8008 dowodzi jedynie, że Synapse odpowiada lokalnie; nie dowodzi, że zdalny serwer Matrix może rozwiązać domenę, zweryfikować protokół TLS ani nawiązać połączenie z publicznym odbiornikiem.

Krok 7: Bezpieczne ponowne uruchomienie i sprawdzenie publicznych punktów końcowych

Przed ponownym uruchomieniem sprawdź poprawność pliku YAML, używając polecenia walidacji obsługiwanego przez metodę instalacji. Następnie uruchom ponownie usługę lub wdrożenie Synapse i sprawdź logi pod kątem błędów konfiguracji lub programu nasłuchującego. Z komputera spoza sieci prywatnej zażądaj pliku wykrywania i punktu końcowego wersji federacyjnej:

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

W przypadku pierwszego polecenia należy oczekiwać odpowiedzi HTTPS z treścią JSON zawierającą poprawny kod m.server. W przypadku drugiego polecenia należy oczekiwać pomyślnej odpowiedzi HTTPS od Synapse, a nie błędu serwera proxy, ostrzeżenia o certyfikacie lub przekroczenia limitu czasu połączenia. Dokładna treść odpowiedzi może się różnić w zależności od wersji Synapse.

Następnie wprowadź swoją macierz server_name(na przykład, example.orgniekoniecznie nazwę hosta proxy) w narzędziu Matrix Federation Tester . Napraw wszelkie zgłoszone błędy DNS, delegacji, certyfikatów lub punktów końcowych i uruchom test ponownie. Na koniec zaproś użytkownika z innego serwera domowego do pokoju testowego lub dołącz do pokoju hostowanego gdzie indziej. Pomyślny wynik testu jest przydatnym testem łączności publicznej, ale nie gwarantuje, że każdy zdalny serwer, polityka pokoju, zapora sieciowa lub konfiguracja klienta będą działać identycznie.

Nieporozumienia prowadzące do zepsutych lub nieoczekiwanych konfiguracji

• „Zawsze muszę udostępniać port 8448”. Nie. Domyślnie jest to 8448, ale delegacja serwera może skierować federację przychodzącą na 443. Otwórz port, z którego faktycznie korzysta opublikowana trasa odnajdywania.
• „Dobrze znany plik klienta umożliwia federację”. Nie umożliwia. Odkrywanie federacji wykorzystuje dobrze znany punkt końcowy serwera lub obsługiwany zapasowy serwer DNS; punkt końcowy klienta służy innemu celowi.
• „Federacja upublicznia każdy lokalny pokój”. Nie. Federacja umożliwia komunikację z serwerem. Widoczność pokoju i członkostwo nadal regulują uczestnictwo; zaproś zdalne konto do pokoju testowego, aby potwierdzić potrzebny przypadek użycia.
• „Zielona lokalna kontrola stanu potwierdza federację”. Nie. Lokalne kontrole nie testują publicznego DNS, zewnętrznej walidacji TLS, NAT, reguł zapory sieciowej w chmurze ani routingu proxy. Przeprowadź test z zewnątrz i użyj testera federacji.

Utrzymywana dokumentacja Synapse zaleca odwrotny serwer proxy do zakończenia protokołu TLS i wyjaśnia oddzielne porty klienta i federacji. Zapoznaj się z oficjalnymi przewodnikami dotyczącymi konfiguracji odwrotnego serwera proxy , delegowania federacji przychodzącej , opcji konfiguracji Synapse oraz wskazówek dotyczących zapory sieciowej i bezpieczeństwa . Reguły wykrywania serwerów można znaleźć w specyfikacji API Matrix Server-Server . Poniższe przykłady zakładają standardowy serwer Synapse działający za odwrotnym serwerem proxy HTTPS; sieci kontenerowe, zarządzane wdrożenia i niestandardowe układy programów nasłuchujących mogą wymagać innych wartości.