A common Matrix Synapse failure looks deceptively simple: local clients can log in, your reverse proxy is online, and Synapse itself may appear healthy, yet remote homeservers cannot federate with you. Logs on one side may contain phrases such as certificate verify failed, hostname mismatch, unable to get local issuer certificate, or a generic federation request failure caused by TLS verification.
The fastest way to fix this is to test the exact hostname and port that Matrix federation discovery resolves to, then repair the certificate, chain, or discovery path that is wrong. Do not start by disabling certificate checks. Matrix server-to-server traffic is HTTPS, and the Matrix specification requires the destination to present a certificate signed by a trusted certificate authority. Synapse also keeps outbound federation certificate verification enabled by default. See the Matrix Server-Server API specification and the current Synapse configuration documentation.
Before changing Nginx, Caddy, Synapse, or DNS, determine the certificate name Matrix expects. The answer depends on your server_name and on server discovery.
If your Matrix server name is example.com and you do not delegate federation, other homeservers normally try the federation service associated with that name, commonly on TCP 8448. If you serve https://example.com/.well-known/matrix/server, the m.server value can delegate federation to another hostname such as matrix.example.com:443. In that case, the delegated hostname is part of the TLS validation path. Matrix also supports SRV-based discovery, but the Synapse documentation recommends .well-known delegation for typical deployments because it is easier to reason about and configure correctly. The authoritative behavior is documented in server discovery in the Matrix specification and Synapse federation delegation.
curl -fsS https://example.com/.well-known/matrix/server
A delegated response can look like this:
{
"m.server": "matrix.example.com:443"
}
If the file is absent or invalid, do not assume that is itself the TLS bug. Matrix has fallback discovery rules. The important point is to know which hostname and port a remote server will finally contact.
Once you know the expected federation endpoint, test it directly with SNI and hostname verification. This separates a TLS identity problem from a Synapse application problem.
openssl s_client -connect example.com:8448 -servername example.com -verify_hostname example.com -showcerts </dev/null
For a delegated host on 443, change both the connection target and expected hostname:
openssl s_client -connect matrix.example.com:443 -servername matrix.example.com -verify_hostname matrix.example.com -showcerts </dev/null
Concentratevi sul risultato finale della verifica e sui nomi alternativi del soggetto del certificato. Una connessione può avere successo a livello di protocollo TCP e TLS, pur fallendo la verifica dell'identità. Ecco perché "la porta è aperta" non è sufficiente.
Un errore di mancata corrispondenza del nome host è particolarmente comune quando il sito rivolto al client e l'endpoint di federazione utilizzano host virtuali diversi. Ad esempio, example.compotrebbe ospitare un sito Web mentre matrix.example.comfunge da proxy per Synapse. Se il .well-knownfile delega a matrix.example.com:443, l'endpoint TLS su tale host deve fornire un certificato valido per matrix.example.com.
Per Nginx, esamina l'host virtuale attivo anziché solo il file di configurazione che intendevi utilizzare:
sudo nginx -T | less
Verificare il server_namepercorso della porta di ascolto e del certificato. Una tipica sezione TLS utilizza l'intera catena di certificati:
server {
listen 443 ssl;
server_name matrix.example.com;
ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;
location /_matrix {
proxy_pass http://127.0.0.1:8008;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
Convalidare e ricaricare solo dopo che il test di configurazione ha esito positivo:
sudo nginx -t && sudo systemctl reload nginx
Synapse raccomanda l'utilizzo di un reverse proxy per le implementazioni più comuni e distingue la porta client standard 443 dalla porta di federazione predefinita 8448. Consultare la documentazione ufficiale di Synapse relativa al reverse proxy per conoscere i requisiti attuali.
Un certificato foglia può apparire corretto in un browser che già utilizzi, ma risultare comunque non valido per un altro server domestico se quest'ultimo non invia il certificato intermedio richiesto. La documentazione di Synapse afferma esplicitamente che, quando Synapse stesso è configurato con un certificato, il file PEM dovrebbe contenere l'intera catena; con Certbot, ciò significa utilizzare fullchain.peminvece di solo cert.pem.
Lo stesso principio si applica quando la connessione TLS termina su Nginx, Caddy, HAProxy o un altro proxy: configura quel proxy in modo che presenti la catena completa corretta. Verifica cosa viene effettivamente servito, non solo cosa è presente sul disco:
openssl s_client -connect matrix.example.com:443 -servername matrix.example.com -showcerts </dev/null
Dovresti visualizzare il certificato foglia seguito dal certificato o dai certificati intermedi necessari. In genere, il server non ha bisogno di inviare la CA radice perché i client di solito si fidano già delle CA radice tramite il loro archivio di certificati attendibili.
Se il certificato è corretto su una macchina ma la federazione remota continua a segnalarne uno diverso, è possibile che il DNS stia indirizzando alcuni client altrove. Verifica sia i record IPv4 che IPv6 e ricorda che un record A funzionante non compensa un record AAAA obsoleto se i server remoti preferiscono IPv6.
dig +short A example.com
dig +short AAAA example.com
dig +short A matrix.example.com
dig +short AAAA matrix.example.com
Verifica inoltre tutti i record SRV della federazione che utilizzi intenzionalmente:
dig +short SRV _matrix-fed._tcp.example.com
Se hai apportato modifiche di recente .well-known, abilita la cache. La specifica Matrix consente ai client di memorizzare nella cache le risposte di rilevamento e persino i tentativi di rilevamento falliti per un certo periodo di tempo. Ciò significa che una configurazione può essere corretta al momento, mentre un server remoto continua temporaneamente a utilizzare il routing rilevato in precedenza.
Quando sono presenti sia A che AAAA, eseguire il controllo TLS su ciascuna rotta, se necessario. Se un bilanciatore di carico funge da front-end per più nodi proxy, verificare che ogni nodo disponga dello stesso certificato e della stessa catena di certificati aggiornati.
La federazione privata è il principale caso legittimo in cui un'autorità di certificazione pubblica potrebbe non essere appropriata. Synapse prevede federation_custom_ca_listla possibilità di utilizzare autorità di certificazione personalizzate. La documentazione attuale evidenzia un comportamento importante: questo elenco sostituisce i certificati CA forniti dall'ambiente operativo. Pertanto, se lo si imposta, è necessario includere l'intero set di certificati attendibili effettivamente richiesto dalla propria implementazione.
federation_custom_ca_list:
- /etc/synapse/ca/private-federation-ca.pem
Dopo aver modificato la configurazione di attendibilità, riavviare Synapse utilizzando il meccanismo di servizio previsto per la propria installazione e controllare i log per individuare eventuali errori relativi ai certificati. Anche le implementazioni in container meritano particolare attenzione: l'host potrebbe considerare attendibile un'autorità di certificazione privata, mentre il container di Synapse potrebbe non farlo. Verificare che il materiale di attendibilità sia montato all'interno del container e che il percorso configurato sia leggibile al suo interno.
Synapse espone anche federation_certificate_verification_whitelistl' federation_verify_certificatesopzione globale, ma la documentazione ufficiale ne limita l'utilizzo a scenari eccezionali. Disattivare la verifica a livello globale può far scomparire l'errore, lasciando però irrisolto il problema di identità sottostante. Per la federazione pubblica ordinaria, è preferibile riparare il certificato o il routing.
Dopo aver apportato le modifiche, ripetere esattamente il comando OpenSSL che in precedenza non ha funzionato. L'obiettivo è una verifica corretta del nome host e della catena per l'endpoint a cui si risolve il rilevamento Matrix.
Quindi effettua una richiesta HTTPS a un endpoint di federazione. Per un endpoint diretto sulla porta 8448:
curl -v https://example.com:8448/_matrix/federation/v1/version
Per un endpoint delegato sulla porta 443:
curl -v https://matrix.example.com/_matrix/federation/v1/version
Un risultato TLS positivo dovrebbe indicare che il certificato è stato verificato correttamente. L'endpoint Matrix dovrebbe quindi restituire una risposta HTTP dal server principale o dal percorso proxy, anziché fallire durante la convalida del certificato. L'endpoint della versione è utile per i test di raggiungibilità; non garantisce che ogni stanza o server remoto si federa correttamente.
Se la verifica TLS ora ha successo ma la federazione continua a fallire, smetti di considerarlo un problema di certificato. Risali la gerarchia e controlla i log di Synapse per individuare errori DNS, timeout di connessione, errori di stato HTTP, problemi con la chiave di firma, errori di autorizzazione o backoff del server remoto.
Nelle installazioni basate su systemd, un punto di partenza comune è:
journalctl -u matrix-synapse -n 200 --no-pager
Per Docker, utilizza i log del container del tuo servizio Synapse. Cerca intorno al timestamp di un nuovo tentativo di federazione anziché basarti su vecchi messaggi di certificato che potrebbero non essere più pertinenti.
| Risultato del test | Causa più probabile | Prossima azione |
|---|---|---|
| Nome host non corrispondente | Certificato errato o destinazione di rilevamento errata | Allinea .well-known/DNS con il nome del certificato proxy |
| Emittente/intermediario mancante | Catena servita incompleta | Configura il proxy o Synapse con la catena completa |
| Scaduto/non ancora valido | problema relativo al ciclo di vita del certificato o all'orologio | Rinnova il certificato e verifica la sincronizzazione dell'ora |
| Funziona sull'host, ma non nel container. | Archivio fiduciario CA diverso | Installare/montare la CA necessaria all'interno del container Synapse |
| La verifica TLS va a buon fine, ma la federazione fallisce comunque. | Non è più un problema di certificati. | Esamina i log di federazione di Synapse, il routing e le risposte HTTP. |
Non utilizzare "il servizio è stato riavviato senza errori" come criterio di successo. Una riparazione affidabile presenta tre segnali osservabili: il nome host di federazione esatto supera la verifica del nome host, la catena servita viene convalidata a un'autorità di certificazione attendibile e una nuova richiesta HTTPS di federazione raggiunge Synapse senza un'eccezione di verifica TLS.
Se, dopo questi controlli, solo un homeserver remoto continua a non funzionare, prendi in considerazione la cache, il trust store di quel server remoto o un percorso di rete specifico per l'endpoint. Se molti homeserver pubblici non correlati tra loro presentano lo stesso problema, ricontrolla prima il tuo certificato, la rotta IPv6, i nodi del bilanciatore di carico e la configurazione di rilevamento.
Per i sistemi di produzione, mantieni la verifica del certificato abilitata e rendi osservabile il rinnovo del certificato. La soluzione definitiva non è disabilitare la verifica, bensì garantire che il rilevamento della matrice, il DNS, l'SNI, il proxy inverso e la catena di certificati descrivano tutti lo stesso endpoint di federazione.
Confronta strumenti di monitoraggio open source e proprietari in base a costi, supporto, personalizzazione, sicurezza e opzioni disponibili, tra cui Zabbix, Nagios, PRTG e altri.
Confronta i migliori server TFTP per Windows, Linux e macOS, tra cui SolarWinds, Tftpd64, tftpd-hpa, atftpd, haneWIN e dnsmasq.
Confronta cinque alternative a Microsoft Access per la gestione di database su desktop, SQLite, senza codice e tramite browser, evidenziandone punti di forza, limiti e casi d'uso più adatti.
Comprendere come i termini "ingress" e "egress" descrivono il traffico in entrata e in uscita, perché la direzione dipende dal confine della rete e come monitorare la larghezza di banda e individuare i trasferimenti di dati rischiosi.
Confronta sei server e collettori syslog gratuiti per Windows e Linux, inclusi strumenti con interfaccia grafica, opzioni open source, funzionalità di ricerca, avvisi e trasporto sicuro.
Scopri cosa fa Microsoft IIS, come funzionano la sua pipeline di richieste e i pool di applicazioni e quando Apache, NGINX o Caddy potrebbero essere più adatti alle tue esigenze di server web.
Diagnostica i picchi di utilizzo della CPU del browser Jitsi Meet e riduci il carico del client controllando i riquadri video, gli effetti della fotocamera, la grafica del browser e le impostazioni dell'host.
Monitora lo stato di salute, il carico della conferenza e il traffico di Jitsi Videobridge con il suo endpoint Prometheus integrato, quindi esplora e visualizza i dati in Grafana.
Configura un dominio personalizzato per Jitsi Meet Docker con DNS, URL pubblico, HTTPS, Let's Encrypt, porte del firewall, impostazioni NAT e verifica end-to-end.
Fix Zimbra Admin Console 404 errors after SSL renewal by checking the correct URL and port, proxy routing, service status, deployed certificates, and logs.
