Comment configurer la fédération sur Matrix Synapse : un guide étape par étape

La fédération Matrix permet à un serveur Synapse d'échanger des événements de salle avec d'autres serveurs Synapse, permettant ainsi à des utilisateurs de serveurs différents de participer à une même salle. Pour la configurer, rendez l'API de fédération de Synapse accessible via HTTPS, publiez les informations de découverte de serveur correctes, autorisez le trafic réseau requis et testez le point de terminaison public. Démarrer Synapse ou ouvrir le port 8448 ne suffit pas si la configuration DNS, TLS ou le routage proxy sont incorrects.

Ce guide utilise une configuration de proxy inverse classique : le domaine d'identité Matrix est ` <domaine_matrix>` example.org, Synapse s'exécute à l'adresse matrix.example.org`<adresse_synapse>`, et le proxy gère le protocole TLS sur le port 443. Remplacez les deux domaines d'exemple par les vôtres. Si Synapse est déjà accessible via HTTPS à l'adresse `<adresse_synapse>` example.org:8448, la délégation n'est généralement pas nécessaire. Les commandes et les chemins d'accès aux fichiers dépendent de l'environnement d'installation de Synapse : paquet, environnement virtuel ou conteneur.

Quelles conditions doivent être réunies pour qu'une fédération puisse fonctionner ?

• Votre serveur Synapse possède un nom d'hôte public stable server_name. Ce nom apparaît dans les identifiants Matrix, par exemple@alex:example.org ; le modifier ultérieurement ne constitue pas une modification de nom d'hôte classique.
• D'autres serveurs domestiques peuvent accéder à l'API de fédération via HTTPS et valider le certificat TLS.
• La découverte du serveur permet aux serveurs domestiques distants d'accéder à l'hôte et au port appropriés. Le port de fédération standard est le 8448 ; la délégation peut pointer vers HTTPS sur le port 443.
• Les règles du pare-feu autorisent le trafic entrant sur le point de terminaison de fédération que vous avez choisi et les connexions de fédération sortantes.

La fédération concerne la communication entre serveurs. Elle ne rend pas automatiquement les salons privés publics et n'invite pas d'autres utilisateurs. Les utilisateurs doivent toujours rejoindre les salons ou y être invités ; l'appartenance à un salon et ses paramètres déterminent qui peut y participer. Commencez par définir le format de vos identifiants Matrix, puis utilisez le même domaine que celui de Synapse server_name.

Étape 1 : Vérifiez le nom et le déploiement du serveur Synapse

Ouvrez le fichier actif homeserver.yamlet confirmez qu'il server_names'agit bien du domaine que vous souhaitez conserver. Voici une configuration courante :

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

server_nameDétermine le domaine dans les identifiants Matrix des utilisateurs. public_baseurlIl s'agit de l'URL publique accessible au client, telle que celle que les utilisateurs saisissent dans un client ; derrière un proxy inverse, elle doit correspondre à l'URL du proxy. Ces deux éléments ont des fonctions différentes ; par conséquent, ne remplacez pas le nom du serveur par le nom d'un conteneur backend ni ne le modifiez simplement pour qu'il corresponde à un sous-domaine. Si le serveur est déjà en service, sauvegardez sa configuration et sa base de données avant de modifier les paramètres réseau.

Vérifiez comment Synapse est installé et géré. Un service systemd, une pile Docker Compose, un déploiement Kubernetes et un service d'hébergement géré utilisent des procédures de redémarrage et de réseau différentes. Appliquez les exemples ci-dessous au fichier de configuration approprié et conservez les écouteurs existants et les paramètres personnalisés.

Étape 2 : Choisissez la fédération directe sur le port 8448 ou la délégation sur le port 443.

Il existe deux voies courantes pour la fédération entrante :

• Utilisez le port par défaut 8448 : configurez le DNS du server_namedomaine pour qu'il pointe vers le serveur, exposez le protocole HTTPS sur le port 8448 et présentez un certificat valide pour ce domaine. Si les API sont disponibles sur le domaine spécifié server_namesur le port 8448, la documentation Synapse indique que la délégation n'est pas nécessaire.
• Utilisez le port 443 avec délégation : servez-le https://example.org/.well-known/matrix/serveravec du JSON en dirigeant les autres serveurs vers le point de terminaison réel, par exemple `http://example.com/` {"m.server":"matrix.example.org:443"}. Le nom d'hôte délégué doit être résolu publiquement et présenter un certificat valide pour matrix.example.org` http://example.com/`.

Le port 8448 n'est pas obligatoire dans tous les déploiements. Si vous utilisez la délégation vers le port 443, la fédération entrante peut utiliser ce même port. Si les connexions sortantes sont bloquées par un pare-feu de sortie, autorisez les ports 443 et 8448, car les serveurs distants peuvent utiliser l'un ou l'autre. Choisissez une route entrante et configurez l'enregistrement DNS, le certificat TLS, le proxy inverse et le pare-feu en conséquence.

Étape 3 : Faire transiter l’API de fédération de Synapse par le proxy inverse

Synapse écoute généralement sur le port HTTP 8008 derrière un proxy inverse. Ce proxy termine le trafic HTTPS et transmet les points de terminaison Matrix à Synapse. Dans le homeserver.yamllistener concerné, assurez-vous que le listener HTTP inclut les ressources client et de fédération et qu'il approuve les en-têtes du proxy.

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

Il s'agit d'un exemple d'écouteur, et non d'une solution de remplacement directe pour la configuration complète de chaque installation. Si Synapse s'exécute dans un conteneur, la liaison à l' 127.0.0.1intérieur de ce conteneur peut empêcher le conteneur proxy de l'atteindre ; utilisez plutôt le réseau de service et une adresse de liaison appropriée. Gardez l'écouteur backend privé et exposez uniquement le proxy, comme prévu.

Configurez le proxy pour qu'il transfère les requêtes /_matrixvers /_synapse/clientle port 8008, en définissant les paramètres `<proxy>` X-Forwarded-Foret ` X-Forwarded-Proto<proxy>`. Pour NGINX, l'emplacement essentiel peut ressembler à ceci :

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

Utilisez l'adresse IP amont correcte pour votre réseau hôte ou conteneur. N'ajoutez pas de chemin réécritproxy_pass ; les recommandations de Synapse concernant les proxys indiquent que la normalisation des chemins de requêtes encodés peut entraîner des erreurs de vérification de signature de fédération. Alignez la limite de taille des fichiers envoyés par le proxy avec le paramètre d'envoi de médias de Synapse si les utilisateurs doivent envoyer des fichiers volumineux.

Étape 4 : Configurer TLS et DNS

Obtenez un certificat TLS publiquement approuvé pour le nom d'hôte qui gère la fédération. Avec la configuration de proxy inverse décrite ci-dessus, cela s'applique matrix.example.orglors de la délégation vers cet hôte. Vérifiez que le proxy fournit la chaîne de certificats complète, renouvelle automatiquement les certificats et présente le certificat approprié sur le port que les serveurs distants contacteront. Un certificat auto-signé ou un certificat pour un nom d'hôte incorrect ne sera pas validé sur les autres serveurs.

Créez un enregistrement A public et, si vous utilisez IPv6, un enregistrement AAAA pointant matrix.example.orgvers le proxy. Vérifiez que les deux enregistrements atteignent le service prévu ; un enregistrement AAAA incorrect peut entraîner des défaillances pour les serveurs distants compatibles IPv6, même si IPv4 fonctionne. Si vous utilisez directement le port 8448, la requête DNS correspondante example.orgdoit pointer vers le serveur d'écoute et son certificat doit correspondre example.org.

Étape 5 : Publier les informations de découverte du serveur

Dans l'exemple délégué, faites en sorte que l'URL HTTPS ci-dessous renvoie le statut 200 et un JSON avec le point de terminaison exact :

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

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

Servez-le comme application/json. Vérifiez qu'il est accessible publiquement sans authentification, qu'il ne redirige pas en boucle et que le nom d'hôte et le port correspondent au proxy TLS. Ne publiez pas matrix.example.orgdans le fichier si le proxy achemine en réalité la fédération ailleurs.

Synapse peut servir ce fichier lui-même serve_server_wellknown: trueuniquement si les requêtes https://<server_name>/sont correctement acheminées vers Synapse. Si le nom de votre serveur est `<nom_serveur>` example.orgmais que Synapse est hébergé à `<adresse_serveur>` matrix.example.org, un serveur web statique ou un proxy inverse sur ` example.org<adresse_serveur>` est souvent plus approprié pour servir la réponse de délégation.

Une confusion fréquente consiste à considérer les fichiers serveur /.well-known/matrix/clientet /.well-known/matrix/serverclient comme interchangeables. Le fichier serveur permet aux autres serveurs d'accueil de détecter la fédération entrante. Le fichier client, quant à lui, annonce l'URL du serveur d'accueil accessible aux clients et est facultatif pour la fédération. Configurez-le séparément uniquement si vous souhaitez que les clients compatibles puissent découvrir l'URL client à partir des identifiants Matrix des utilisateurs.

Étape 6 : Ouvrir les chemins de pare-feu requis

Pour une fédération entrante directe, autorisez le trafic TCP entrant sur le port 8448 vers le serveur TLS ou le proxy. Dans le cas d'une délégation, autorisez le trafic TCP entrant sur le port 443 vers le proxy. Les connexions clientes utilisent généralement HTTPS sur le port 443. Si l'accès au réseau sortant est restreint, autorisez Synapse à se connecter aux serveurs distants via les ports TCP 443 et 8448. Ne pas ouvrir le port 8008 du serveur Synapse sur Internet lorsque le proxy inverse est conçu comme point d'entrée public.

Si le serveur se trouve derrière un pare-feu cloud, un routeur, un réseau de conteneurs et un pare-feu hôte, vérifiez chaque couche. Une requête locale réussie sur le port 8008 prouve uniquement que Synapse répond localement ; elle ne prouve pas qu’un serveur Matrix distant puisse résoudre votre domaine, valider le protocole TLS ou accéder à l’écouteur public.

Étape 7 : Redémarrez en toute sécurité et vérifiez les points de terminaison publics

Avant de redémarrer, validez le fichier YAML à l'aide de la commande de validation fournie par votre méthode d'installation. Redémarrez ensuite le service ou le déploiement Synapse et consultez ses journaux pour détecter d'éventuelles erreurs de configuration ou d'écoute. Depuis une machine située hors de votre réseau privé, demandez le fichier de découverte et le point de terminaison de version de la fédération.

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

Pour la première commande, attendez-vous à une réponse HTTPS avec un corps JSON contenant l'URL correcte m.server. Pour la seconde, attendez-vous à une réponse HTTPS positive de Synapse, et non à une erreur de proxy, un avertissement de certificat ou un délai de connexion dépassé. Le contenu exact de la réponse peut varier selon la version de Synapse.

Ensuite, saisissez votre Matrix server_name(par exemple, `example.com` example.org, et non nécessairement le nom d'hôte du proxy) dans l' outil de test de fédération Matrix . Corrigez les erreurs DNS, de délégation, de certificat ou de point de terminaison signalées, puis relancez le test. Enfin, invitez un utilisateur d'un autre serveur d'accueil à une salle de test ou rejoignez une salle hébergée ailleurs. Un test réussi permet de vérifier la connectivité publique, mais ne garantit pas un comportement identique pour tous les serveurs distants, les règles de salle, les pare-feu ou les configurations client.

Idées fausses qui mènent à des configurations défectueuses ou inattendues

• « Je dois toujours exposer le port 8448. » Non. Le port par défaut est 8448, mais la délégation de serveur peut rediriger la fédération entrante vers le port 443. Ouvrez le port réellement utilisé par votre route de découverte publiée.
• « Le fichier client connu permet la fédération. » C’est faux. La découverte de fédération utilise le point de terminaison connu du serveur ou un DNS de secours pris en charge ; le point de terminaison client a une autre fonction.
• « La fédération rend chaque salle locale publique. » Non. La fédération permet la communication avec le serveur. La visibilité et l'appartenance à une salle restent les règles de participation ; invitez un compte distant dans une salle de test pour confirmer le cas d'utilisation souhaité.
• « Un contrôle d'intégrité local positif prouve la fédération. » Non. Les contrôles locaux ne testent pas le DNS public, la validation TLS externe, le NAT, les règles de pare-feu cloud ni le routage proxy. Effectuez les tests depuis l'extérieur à l'aide de l'outil de test de fédération.

La documentation Synapse, régulièrement mise à jour, recommande l'utilisation d'un proxy inverse pour la terminaison TLS et explique la distinction entre les ports client et de fédération. Consultez les guides officiels pour la configuration du proxy inverse , la délégation de fédération entrante , les options de configuration de Synapse , ainsi que les recommandations relatives au pare-feu et à la sécurité . Pour les règles de découverte des serveurs, reportez-vous à la spécification de l'API Matrix Server-Server . Les exemples présentés ici supposent une configuration Synapse standard derrière un proxy inverse HTTPS ; la mise en réseau des conteneurs, les déploiements gérés et les configurations d'écoute personnalisées peuvent nécessiter des valeurs différentes.