Come configurare la federazione su Matrix Synapse: una guida passo passo

La federazione Matrix consente a un homeserver Synapse di scambiare eventi di stanza con altri homeserver, in modo che gli utenti che utilizzano server diversi possano partecipare alla stessa stanza. Per configurarla, è necessario rendere l'API di federazione di Synapse accessibile tramite HTTPS, pubblicare le informazioni corrette per il rilevamento del server, consentire il traffico di rete necessario e testare l'endpoint pubblico. Avviare Synapse o aprire la porta 8448 non è sufficiente se DNS, TLS o il routing del proxy sono configurati in modo errato.

Questa guida utilizza una tipica implementazione di reverse proxy: il dominio di identità Matrix è example.org, Synapse è in esecuzione su matrix.example.orge il proxy gestisce TLS sulla porta 443. Sostituisci entrambi i domini di esempio con i tuoi. Se Synapse è già raggiungibile tramite HTTPS su example.org:8448, in genere non è necessaria la delega. I comandi e i percorsi dei file dipendono dal fatto che tu abbia installato Synapse da un pacchetto, un ambiente virtuale o un container.

Quali sono le condizioni necessarie affinché una federazione possa funzionare?

• Il tuo server Synapse ha un nome pubblico stabile server_name. Questo nome appare negli ID Matrix come @alex:example.org; modificarlo in seguito non è una modifica di routine del nome host.
• Altri server domestici possono raggiungere l'API di federazione tramite HTTPS e convalidare il certificato TLS.
• Il rilevamento del server indirizza i server domestici remoti all'host e alla porta corretti. La porta di federazione standard è la 8448; la delega può puntare a HTTPS sulla porta 443.
• Le regole del firewall consentono il traffico in entrata sull'endpoint di federazione scelto e le connessioni di federazione in uscita.

La federazione riguarda la comunicazione da server a server. Non rende automaticamente pubbliche le stanze private né invita altri utenti. Gli utenti devono comunque iscriversi alle stanze o essere invitati, e l'appartenenza alla stanza e le impostazioni della stanza determinano chi può partecipare. Inizia decidendo come dovrebbero essere i tuoi ID Matrix, quindi usa lo stesso dominio di Synapse server_name.

Passaggio 1: Verificare il nome del server Synapse e la distribuzione

Apri il dominio attivo homeserver.yamle conferma che server_namesia quello che intendi mantenere. Una configurazione comune è la seguente:

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

server_namedetermina il dominio negli ID Matrix degli utenti. public_baseurlè l'URL pubblico rivolto al client, come l'URL che le persone inseriscono in un client; dietro un proxy inverso dovrebbe indicare l'URL del proxy. Hanno scopi diversi, quindi non sostituire il nome del server con il nome di un container backend né modificarlo solo per farlo corrispondere a un sottodominio. Se il server è già in uso, eseguire un backup della sua configurazione e del database prima di modificare le impostazioni di rete.

Verifica come Synapse è installato e gestito. Un servizio systemd, uno stack Docker Compose, un'implementazione Kubernetes e un prodotto di hosting gestito utilizzano procedure di riavvio e di rete diverse. Applica gli esempi seguenti al file di configurazione corretto e conserva tutti i listener e le impostazioni personalizzate esistenti.

Passaggio 2: Scegliere la federazione diretta sulla porta 8448 o la delega alla porta 443.

Esistono due percorsi comuni per la federazione in entrata:

• Utilizza la porta predefinita 8448: configura il DNS del server_namedominio in modo che punti al server, esponi HTTPS sulla porta 8448 e presenta un certificato valido per quel dominio. Se le API sono disponibili sul dominio specificato server_namesulla porta 8448, la documentazione di Synapse afferma che la delega non è necessaria.
• Utilizzare la porta 443 con delega: servire https://example.org/.well-known/matrix/servercon JSON indirizzando altri server all'endpoint effettivo, ad esempio {"m.server":"matrix.example.org:443"}. Il nome host delegato deve essere risolvibile pubblicamente e presentare un certificato valido per matrix.example.org.

La porta 8448 non è obbligatoria in ogni implementazione. Se si utilizza la delega alla porta 443, la federazione in entrata può utilizzare quest'ultima. Se le connessioni in uscita sono limitate da un firewall in uscita, consentire sia la porta 443 che la 8448, poiché i server remoti potrebbero utilizzare entrambe. Scegliere una rotta in entrata e fare in modo che il record DNS, il certificato TLS, il reverse proxy e il firewall siano configurati di conseguenza.

Passaggio 3: Instradare l'API di federazione di Synapse attraverso il proxy inverso

Synapse è generalmente in ascolto sulla porta HTTP 8008 dietro un proxy inverso. Il proxy termina la connessione HTTPS e inoltra gli endpoint Matrix a Synapse. Nel homeserver.yamllistener pertinente, assicurarsi che il listener HTTP includa sia le risorse client che quelle di federazione e che consideri attendibili le intestazioni del proxy:

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

Questo è un listener di esempio, non un sostituto diretto per la configurazione completa di ogni installazione. Se Synapse è in esecuzione in un container, il binding all'interno 127.0.0.1del container potrebbe impedire al container proxy di raggiungerlo; utilizzare invece la rete di servizio e un indirizzo di binding appropriato. Mantenere privato il listener di backend ed esporre solo il proxy come previsto.

Configura il proxy per inoltrare le richieste per /_matrixe /_synapse/clientalla porta 8008, impostando X-Forwarded-Fore X-Forwarded-Proto. Per NGINX, la posizione essenziale può essere simile a questa:

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

Utilizzare l'indirizzo upstream corretto per la rete host o container. Non aggiungere un percorso riscritto a proxy_pass; le linee guida di Synapse per i proxy avvertono che la normalizzazione dei percorsi di richiesta codificati può causare errori di verifica della firma di federazione. Allineare il limite di dimensione di caricamento del proxy con l'impostazione di caricamento multimediale di Synapse se gli utenti devono caricare file di dimensioni maggiori.

Passaggio 4: Configurare TLS e DNS

Ottieni un certificato TLS pubblicamente attendibile per il nome host che gestisce la federazione. Con la configurazione del reverse proxy descritta in precedenza, questo vale matrix.example.orgquando si utilizza la delega a tale host. Verifica che il proxy fornisca l'intera catena di certificati, rinnovi automaticamente i certificati e presenti il ​​certificato corretto sulla porta che i server remoti utilizzeranno. Un certificato autofirmato o un certificato per un nome host errato non supererà la convalida sugli altri server domestici.

Crea un record A pubblico e, se usi IPv6, un record AAAA per matrix.example.orgpuntare al proxy. Verifica che entrambi i record raggiungano il servizio previsto; un record AAAA errato può causare errori per i server remoti compatibili con IPv6 anche quando IPv4 funziona. Se usi direttamente la porta 8448, il DNS per example.orgdeve puntare al listener e il suo certificato deve corrispondere example.org.

Passaggio 5: Pubblicare le informazioni di individuazione del server

Per l'esempio delegato, fai in modo che l'URL HTTPS seguente restituisca lo stato 200 e un JSON con l'endpoint esatto:

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

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

Servilo come application/json. Verifica che sia leggibile pubblicamente senza login, che non reindirizzi in un ciclo infinito e che il nome host e la porta corrispondano al proxy TLS. Non pubblicare matrix.example.orgnel file se il proxy instrada la federazione altrove.

Synapse può servire questo file direttamente serve_server_wellknown: truesolo quando le richieste a https://<server_name>/vengono instradate a Synapse in modo appropriato. Se il nome del server è example.orgma Synapse è ospitato su matrix.example.org, un server web statico o un proxy inverso su example.orgè spesso il luogo più adatto per servire la risposta di delega.

Un errore comune è quello di considerare /.well-known/matrix/cliente /.well-known/matrix/servercome intercambiabili. Il file del server aiuta gli altri homeserver a scoprire la federazione in entrata. Il file del client pubblicizza un URL dell'homeserver rivolto al client ed è facoltativo per la federazione. Configuralo separatamente solo se desideri che i client compatibili scoprano l'URL del client dagli ID Matrix degli utenti.

Passaggio 6: Aprire i percorsi del firewall richiesti

Per la federazione diretta in entrata, consentire il traffico TCP in entrata sulla porta 8448 verso il listener TLS o il proxy. Per l'esempio con delega, consentire il traffico TCP in entrata sulla porta 443 verso il proxy. Le connessioni client utilizzano normalmente anche HTTPS sulla porta 443. Se l'accesso alla rete in uscita è limitato, consentire a Synapse di connettersi ai server remoti tramite TCP 443 e 8448. Non aprire la porta 8008 del backend di Synapse a Internet pubblico quando il reverse proxy è destinato a essere il punto di accesso pubblico.

Se il server si trova dietro un firewall cloud, un router, una rete di container e un firewall host, è necessario verificare ogni livello. Una richiesta locale andata a buon fine alla porta 8008 dimostra solo che Synapse risponde localmente; non dimostra che un server Matrix remoto sia in grado di risolvere il dominio, convalidare TLS o raggiungere il listener pubblico.

Passaggio 7: riavviare in modo sicuro e verificare gli endpoint pubblici

Prima di riavviare, convalida il file YAML utilizzando il comando di convalida supportato dal metodo di installazione. Quindi riavvia il servizio o la distribuzione Synapse e controlla i relativi log per individuare eventuali errori di configurazione o del listener. Da una macchina esterna alla rete privata, richiedi il file di rilevamento e l'endpoint della versione di federazione:

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

Per il primo comando, aspettati una risposta HTTPS con un corpo JSON contenente il corretto m.server. Per il secondo, aspettati una risposta HTTPS di successo da Synapse anziché un errore del proxy, un avviso del certificato o un timeout della connessione. Il corpo esatto della risposta può variare a seconda della versione di Synapse.

Successivamente, inserisci la tua Matrix server_name(ad esempio, example.org, non necessariamente il nome host del proxy) nel Matrix Federation Tester . Correggi eventuali errori DNS, di delega, di certificato o di endpoint segnalati ed esegui nuovamente il test. Infine, invita un utente su un altro homeserver a una stanza di test o unisciti a una stanza ospitata altrove. Un risultato positivo del test è un utile controllo della connettività pubblica, ma non garantisce che ogni server remoto, policy della stanza, firewall o configurazione client si comporti allo stesso modo.

Idee sbagliate che portano a configurazioni errate o inaspettate

• "Devo sempre esporre la porta 8448." No. L'impostazione predefinita è 8448, ma la delega del server può indirizzare la federazione in entrata alla porta 443. Apri la porta effettivamente utilizzata dalla tua route di discovery pubblicata.
• "Il file noto del client abilita la federazione." Non è vero. Il rilevamento della federazione utilizza l'endpoint noto del server o il fallback DNS supportato; l'endpoint del client ha uno scopo diverso.
• "La federazione rende pubbliche tutte le stanze locali." No. La federazione abilita la comunicazione tra server. La visibilità delle stanze e l'appartenenza ai membri regolano comunque la partecipazione; invita un account remoto a una stanza di prova per verificare il caso d'uso di cui hai bisogno.
• "Un controllo locale positivo conferma la federazione." No. I controlli locali non verificano il DNS pubblico, la convalida TLS esterna, il NAT, le regole del firewall cloud o il routing proxy. Eseguite il test dall'esterno utilizzando lo strumento di verifica della federazione.

La documentazione di Synapse, regolarmente aggiornata, raccomanda l'utilizzo di un reverse proxy per la terminazione TLS e spiega la separazione delle porte client e di federazione. Consultare le guide ufficiali per la configurazione del reverse proxy , la delega di federazione in entrata , le opzioni di configurazione di Synapse e le linee guida su firewall e sicurezza . Per le regole di individuazione dei server, consultare la specifica dell'API Matrix Server-Server . Gli esempi qui riportati presuppongono un'installazione standard di Synapse dietro un reverse proxy HTTPS; le reti di container, le implementazioni gestite e i layout di listener personalizzati potrebbero richiedere valori diversi.