Cómo configurar la federación en Matrix Synapse: una guía paso a paso

La federación matricial permite que un servidor Synapse intercambie eventos de sala con otros servidores, de modo que usuarios de distintos servidores puedan participar en la misma sala. Para configurarla, asegúrese de que la API de federación de Synapse sea accesible mediante HTTPS, publique la información correcta de detección de servidores, permita el tráfico de red necesario y pruebe el punto final público. Simplemente iniciar Synapse o abrir el puerto 8448 no es suficiente si el DNS, TLS o el enrutamiento proxy son incorrectos.

Esta guía utiliza una implementación típica de proxy inverso: el dominio de identidad de Matrix es example.org, Synapse se ejecuta en matrix.example.org, y el proxy gestiona TLS en el puerto 443. Reemplace ambos dominios de ejemplo con los suyos. Si Synapse ya es accesible a través de HTTPS en example.org:8448, normalmente no necesita delegación. Los comandos y las rutas de archivo dependen de si instaló Synapse desde un paquete, un entorno virtual o un contenedor.

¿Qué condiciones deben cumplirse para que la federación funcione?

• Tu servidor Synapse tiene un nombre público estable server_name. Este nombre aparece en los ID de Matrix, como por ejemplo @alex:example.org; cambiarlo posteriormente no es una edición rutinaria del nombre de host.
• Otros servidores domésticos pueden acceder a la API de federación a través de HTTPS y validar el certificado TLS.
• El descubrimiento del servidor dirige a los servidores remotos al host y puerto correctos. El puerto de federación estándar es el 8448; la delegación puede apuntar a HTTPS en el puerto 443.
• Las reglas del firewall permiten el tráfico entrante en el punto final de federación que usted eligió y las conexiones de federación salientes.

La federación se refiere a la comunicación entre servidores. No convierte automáticamente las salas privadas en públicas ni invita a otros usuarios. Los usuarios aún deben unirse o ser invitados a las salas, y la membresía y la configuración de la sala determinan quién puede participar. Comience por decidir cómo deben ser sus ID de Matrix y luego use ese mismo dominio como el de Synapse server_name.

Paso 1: Compruebe el nombre del servidor Synapse y la implementación.

Abra el archivo activo homeserver.yamly confirme que ese server_namees el dominio que desea conservar. Una configuración común es:

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

server_nameDetermina el dominio en los ID de matriz de los usuarios. public_baseurlEs la URL pública visible para el cliente, como la que las personas ingresan en un cliente; detrás de un proxy inverso, debe indicar la URL del proxy. Cumplen funciones diferentes, así que no reemplace el nombre del servidor con el nombre de un contenedor de backend ni lo cambie solo para que coincida con un subdominio. Si el servidor ya está en uso, haga una copia de seguridad de su configuración y base de datos antes de cambiar la configuración de red.

Verifique cómo se instala y administra Synapse. Un servicio systemd, una pila Docker Compose, una implementación de Kubernetes y un producto de alojamiento administrado utilizan diferentes procedimientos de reinicio y red. Aplique los ejemplos a continuación al archivo de configuración correcto y conserve los oyentes y la configuración personalizada existentes.

Paso 2: Elija la federación directa en el puerto 8448 o la delegación al puerto 443.

Existen dos rutas comunes para la federación entrante:

• Utilice el puerto predeterminado 8448: configure el DNS del server_namedominio para que apunte al servidor, exponga HTTPS en el puerto 8448 y presente un certificado válido para ese dominio. Si las API están disponibles en el dominio especificado server_nameen el puerto 8448, la documentación de Synapse indica que no se requiere delegación.
• Utilice el puerto 443 con delegación: sirva https://example.org/.well-known/matrix/servercon JSON que dirija a otros servidores al punto final real, por ejemplo {"m.server":"matrix.example.org:443"}. El nombre de host delegado debe resolverse públicamente y presentar un certificado válido para matrix.example.org.

El puerto 8448 no es obligatorio en todas las implementaciones. Si utiliza la delegación al puerto 443, la federación de entrada puede usar el puerto 443. Si las conexiones salientes están restringidas por un firewall de salida, permita tanto el puerto 443 como el 8448, ya que los servidores remotos pueden usar cualquiera de ellos. Elija una ruta de entrada y asegúrese de que el registro DNS, el certificado TLS, el proxy inverso y el firewall sean compatibles con ella.

Paso 3: Enrutar la API de federación de Synapse a través del proxy inverso.

Synapse suele escuchar en el puerto HTTP 8008 detrás de un proxy inverso. El proxy finaliza HTTPS y reenvía los puntos finales de Matrix a Synapse. En el homeserver.yamloyente correspondiente, asegúrese de que el oyente HTTP incluya tanto los recursos del cliente como los de la federación y confíe en los encabezados del proxy:

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

Este es un ejemplo de oyente, no un reemplazo directo para la configuración completa de cada instalación. Si Synapse se ejecuta en un contenedor, vincularlo 127.0.0.1dentro del contenedor puede impedir que el contenedor proxy lo alcance; en su lugar, utilice la red de servicio y una dirección de enlace adecuada. Mantenga el oyente de backend privado y exponga solo el proxy, como se prevé.

Configure el proxy para reenviar las solicitudes para /_matrixy /_synapse/cliental puerto 8008, estableciendo X-Forwarded-Fory X-Forwarded-Proto. Para NGINX, la ubicación esencial puede verse así:

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

Utilice la dirección de origen correcta para su host o red de contenedores. No agregue una ruta reescrita a proxy_pass; la guía de proxy de Synapse advierte que normalizar las rutas de solicitud codificadas puede causar errores de verificación de firma de federación. Alinee el límite de tamaño de carga del proxy con la configuración de carga de medios de Synapse si los usuarios necesitan cargar archivos más grandes.

Paso 4: Configurar TLS y DNS

Obtenga un certificado TLS de confianza pública para el nombre de host que gestiona la federación. Con la configuración de proxy inverso descrita anteriormente, esto se aplica matrix.example.orgal usar la delegación a dicho host. Confirme que el proxy gestiona la cadena de certificados completa, renueva los certificados automáticamente y presenta el certificado correcto en el puerto al que se conectarán los servidores remotos. Un certificado autofirmado o un certificado para un nombre de host incorrecto provocará un fallo de validación en otros servidores.

Cree un registro A público y, si usa IPv6, un registro AAAA para matrix.example.orgapuntar al proxy. Verifique que ambos registros lleguen al servicio previsto; un registro AAAA incorrecto puede causar fallos en servidores remotos compatibles con IPv6 incluso cuando IPv4 funciona. Si usa el puerto 8448 directamente, el DNS example.orgdebe apuntar al oyente y su certificado debe coincidir example.org.

Paso 5: Publicar la información de detección del servidor

Para el ejemplo delegado, haga que la URL HTTPS que aparece a continuación devuelva el estado 200 y JSON con el punto final exacto:

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

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

Sírvelo como application/json. Verifica que sea legible públicamente sin iniciar sesión, que no genere redirecciones en un bucle y que el nombre de host y el puerto coincidan con el proxy TLS. No publiques matrix.example.orgen el archivo si el proxy enruta la federación a otro lugar.

Synapse puede servir este archivo por sí mismo serve_server_wellknown: truesolo cuando las solicitudes a https://<server_name>/se enrutan a Synapse adecuadamente. Si el nombre de su servidor es example.orgpero Synapse está alojado en matrix.example.org, un servidor web estático o un proxy inverso en example.orgsuele ser el lugar más adecuado para servir la respuesta de delegación.

Un error común es considerarlos /.well-known/matrix/clientintercambiables /.well-known/matrix/server. El archivo del servidor ayuda a otros servidores domésticos a descubrir la federación entrante. El archivo del cliente anuncia una URL del servidor doméstico visible para el cliente y es opcional para la federación. Configúrelo por separado solo si desea que los clientes compatibles descubran la URL del cliente a partir de los ID de Matrix de los usuarios.

Paso 6: Abra las rutas de firewall necesarias.

Para la federación directa entrante, permita el tráfico TCP entrante en el puerto 8448 al receptor TLS o al proxy. En el ejemplo de delegación, permita el tráfico TCP entrante en el puerto 443 al proxy. Las conexiones de cliente también suelen usar HTTPS en el puerto 443. Si el acceso a la red saliente está restringido, permita que Synapse se conecte a servidores remotos a través de los puertos TCP 443 y 8448. No abra el puerto 8008 del backend de Synapse a internet cuando el proxy inverso sea el punto de entrada público.

Si el servidor se encuentra detrás de un firewall en la nube, un enrutador, una red de contenedores y un firewall del host, verifique cada capa. Una solicitud local exitosa al puerto 8008 solo demuestra que Synapse responde localmente; no demuestra que un servidor remoto de Matrix pueda resolver su dominio, validar TLS o acceder al oyente público.

Paso 7: Reinicie de forma segura y verifique los puntos finales públicos.

Valide el archivo YAML antes de reiniciar, utilizando el comando de validación compatible con su método de instalación. A continuación, reinicie el servicio o la implementación de Synapse e inspeccione sus registros en busca de errores de configuración o del oyente. Desde una máquina fuera de su red privada, solicite el archivo de descubrimiento y el punto final de la versión de la federación:

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

Para el primer comando, espere una respuesta HTTPS con un cuerpo JSON que contenga la información correcta m.server. Para el segundo, espere una respuesta HTTPS exitosa de Synapse en lugar de un error de proxy, una advertencia de certificado o un tiempo de espera de conexión agotado. El cuerpo exacto de la respuesta puede variar según la versión de Synapse.

A continuación, introduzca su Matrix server_name(por ejemplo, example.org, no necesariamente el nombre de host del proxy) en el Probador de federación de Matrix . Corrija cualquier error de DNS, delegación, certificado o punto final que se detecte y vuelva a ejecutar la prueba. Por último, invite a un usuario de otro servidor a una sala de prueba o únase a una sala alojada en otro lugar. Un resultado satisfactorio de la prueba es una útil comprobación de conectividad pública, pero no garantiza que todos los servidores remotos, políticas de sala, cortafuegos o configuraciones de cliente se comporten de la misma manera.

Ideas erróneas que conducen a configuraciones defectuosas o inesperadas.

• «Siempre debo exponer el puerto 8448». No. El valor predeterminado es 8448, pero la delegación del servidor puede dirigir la federación entrante al puerto 443. Abra el puerto que realmente utiliza su ruta de descubrimiento publicada.
• «El archivo de configuración conocida del cliente habilita la federación». No es cierto. El descubrimiento de la federación utiliza el punto final conocido del servidor o un sistema DNS alternativo compatible; el punto final del cliente tiene una función diferente.
• «La federación hace públicas todas las salas locales». No. La federación permite la comunicación entre servidores. La visibilidad de la sala y la membresía siguen rigiendo la participación; invita a una cuenta remota a una sala de prueba para confirmar el caso de uso que necesitas.
• «Una comprobación de estado local positiva demuestra la federación». No. Las comprobaciones locales no prueban el DNS público, la validación TLS externa, NAT, las reglas del firewall en la nube ni el enrutamiento proxy. Realice la prueba desde fuera y utilice la herramienta de prueba de federación.

La documentación actualizada de Synapse recomienda un proxy inverso para la terminación TLS y explica los puertos de cliente y federación por separado. Consulte las guías oficiales para la configuración del proxy inverso , la delegación de federación entrante , las opciones de configuración de Synapse y las directrices de firewall y seguridad . Para las reglas de detección de servidores, consulte la especificación de la API Matrix Server-Server . Los ejemplos aquí presentados asumen Synapse estándar detrás de un proxy inverso HTTPS; las redes de contenedores, las implementaciones administradas y las configuraciones de escucha personalizadas pueden requerir valores diferentes.