Como configurar a federação no Matrix Synapse: um guia passo a passo

A federação Matrix permite que um servidor doméstico Synapse troque eventos de sala com outros servidores domésticos, para que pessoas usando servidores diferentes possam participar da mesma sala. Para configurá-la, torne a API de federação do Synapse acessível via HTTPS, publique as informações corretas de descoberta do servidor, permita o tráfego de rede necessário e teste o endpoint público. Simplesmente iniciar o Synapse ou abrir a porta 8448 não é suficiente se o DNS, TLS ou roteamento de proxy estiverem incorretos.

Este guia utiliza uma implementação típica de proxy reverso: o domínio de identidade do Matrix é `<nome_do_domínio>` example.org, o Synapse é executado em ` matrix.example.org<nome_do_domínio>`, e o proxy lida com TLS na porta 443. Substitua ambos os domínios de exemplo pelos seus próprios. Se o Synapse já estiver acessível via HTTPS em `<nome_do_domínio>` example.org:8448, geralmente não é necessário delegar o protocolo. Os comandos e caminhos de arquivos dependem de como você instalou o Synapse: a partir de um pacote, um ambiente virtual ou um contêiner.

O que precisa ser verdade para que a federação funcione?

• Seu servidor Synapse possui um nome de host público estável server_name. Esse nome aparece em IDs do Matrix, como @alex:example.org; alterá-lo posteriormente não é uma edição rotineira de nome de host.
• Outros servidores domésticos podem acessar a API de federação via HTTPS e validar o certificado TLS.
• A descoberta de servidores direciona servidores domésticos remotos para o host e a porta corretos. A porta de federação padrão é 8448; a delegação pode apontar para HTTPS na porta 443.
• As regras do firewall permitem tráfego de entrada no ponto de extremidade de federação escolhido e conexões de federação de saída.

A federação trata da comunicação entre servidores. Ela não torna automaticamente salas privadas públicas nem convida outros usuários. Os usuários ainda precisam entrar ou ser convidados para as salas, e a associação e as configurações da sala determinam quem pode participar. Comece decidindo como seus IDs do Matrix devem ser, e então use o mesmo domínio do Synapse server_name.

Etapa 1: Verifique o nome e a implantação do servidor Synapse.

Abra o domínio ativo homeserver.yamle confirme se server_nameé o domínio que você pretende manter. Uma configuração comum é:

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

server_nameDetermina o domínio nos IDs Matrix dos usuários. public_baseurlÉ a URL pública voltada para o cliente, como a URL que as pessoas inserem em um cliente; atrás de um proxy reverso, deve ser a URL do proxy. Eles têm propósitos diferentes, portanto, não substitua o nome do servidor pelo nome de um contêiner de backend nem o altere apenas para corresponder a um subdomínio. Se o servidor já estiver em uso, faça backup de sua configuração e banco de dados antes de alterar as configurações de rede.

Verifique como o Synapse está instalado e gerenciado. Um serviço systemd, um stack Docker Compose, uma implantação Kubernetes e um produto de hospedagem gerenciada utilizam procedimentos de reinicialização e rede diferentes. Aplique os exemplos abaixo ao arquivo de configuração correto e preserve quaisquer listeners e configurações personalizadas existentes.

Etapa 2: Escolha a federação direta no canal 8448 ou a delegação para o canal 443.

Existem duas rotas comuns para a federação de entrada:

• Use a porta padrão 8448: aponte o DNS do server_namedomínio para o servidor, exponha o HTTPS na porta 8448 e apresente um certificado válido para esse domínio. Se as APIs estiverem disponíveis no domínio especificado server_namena porta 8448, a documentação do Synapse afirma que a delegação não é necessária.
• Use a porta 443 com delegação: sirva https://example.org/.well-known/matrix/servercom JSON direcionando outros servidores para o endpoint real, por exemplo {"m.server":"matrix.example.org:443"}. O nome do host delegado deve ser resolvido publicamente e apresentar um certificado válido para matrix.example.org.

A porta 8448 não é obrigatória em todas as implementações. Se você usar delegação para a porta 443, a federação de entrada poderá usar a porta 443 em vez da 8448. Se as conexões de saída forem restritas por um firewall de saída, permita as portas 443 e 8448, pois os servidores remotos podem usar qualquer uma delas. Escolha uma rota de entrada e configure o registro DNS, o certificado TLS, o proxy reverso e o firewall para que estejam de acordo com ela.

Etapa 3: Direcione a API de federação do Synapse através do proxy reverso.

Normalmente, o Synapse escuta na porta HTTP 8008 por trás de um proxy reverso. O proxy encerra as requisições HTTPS e encaminha os endpoints do Matrix para o Synapse. No homeserver.yamllistener correspondente, certifique-se de que o listener HTTP inclua os recursos do cliente e da federação e confie nos cabeçalhos do proxy.

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

Este é um exemplo de listener, não um substituto direto para a configuração completa de todas as instalações. Se o Synapse estiver sendo executado em um contêiner, a vinculação 127.0.0.1dentro do contêiner pode impedir que o contêiner proxy o alcance; use a rede de serviço e um endereço de vinculação adequado. Mantenha o listener de backend privado e exponha apenas o proxy, conforme o esperado.

Configure o proxy para encaminhar solicitações para /_matrixa /_synapse/clientporta 8008, definindo `<endereço_ip>` X-Forwarded-Fore ` X-Forwarded-Proto<porta_ip>`. Para o NGINX, o caminho essencial pode ser semelhante a este:

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

Use o endereço upstream correto para sua rede de host ou contêiner. Não anexe um caminho reescrito a proxy_pass; as diretrizes de proxy do Synapse alertam que a normalização de caminhos de solicitação codificados pode causar erros de verificação de assinatura de federação. Alinhe o limite de tamanho de upload do proxy com a configuração de upload de mídia do Synapse se os usuários precisarem enviar arquivos maiores.

Etapa 4: Configurar TLS e DNS

Obtenha um certificado TLS publicamente confiável para o nome de host que serve à federação. Com a configuração de proxy reverso acima, isso se aplica matrix.example.orgao uso de delegação para esse host. Confirme se o proxy fornece a cadeia de certificados completa, renova os certificados automaticamente e apresenta o certificado correto na porta que os servidores remotos irão contatar. Um certificado autoassinado ou um certificado para um nome de host incorreto resultará em falha na validação em outros servidores domésticos.

Crie um registro A público e, se usar IPv6, um registro AAAA matrix.example.orgapontando para o proxy. Verifique se ambos os registros alcançam o serviço pretendido; um registro AAAA incorreto pode causar falhas em servidores remotos compatíveis com IPv6, mesmo quando o IPv4 estiver funcionando. Se usar a porta 8448 diretamente, o DNS example.orgdeve apontar para o servidor de escuta e o certificado deste deve corresponder example.org.

Etapa 5: Publicar informações de descoberta do servidor

Para o exemplo delegado, faça com que a URL HTTPS abaixo retorne o status 200 e o JSON com o endpoint exato:

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

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

Sirva-o como application/json. Verifique se ele é publicamente legível sem login, se não redireciona em loop e se o nome do host e a porta correspondem ao proxy TLS. Não publique matrix.example.orgno arquivo se o proxy rotear a federação para outro lugar.

O Synapse pode servir este arquivo diretamente, serve_server_wellknown: truesomente quando as requisições para https://<server_name>/ele forem roteadas corretamente. Se o nome do seu servidor for `server` example.org, mas o Synapse estiver hospedado em `server.example.com` matrix.example.org, um servidor web estático ou um proxy reverso em ` example.orgserver.example.com` costuma ser o local mais adequado para servir a resposta de delegação.

Um erro comum é tratar `server` /.well-known/matrix/cliente ` /.well-known/matrix/serverclient` como intercambiáveis. O arquivo `server` ajuda outros servidores domésticos a descobrirem a federação recebida. O arquivo `client` anuncia um URL de servidor doméstico voltado para o cliente e é opcional para a federação. Configure-o separadamente apenas se desejar que clientes compatíveis descubram o URL do cliente a partir dos IDs Matrix dos usuários.

Passo 6: Abra os caminhos de firewall necessários

Para federação direta de entrada, permita o tráfego TCP de entrada na porta 8448 para o servidor TLS ou proxy. Para o exemplo de delegação, permita o tráfego TCP de entrada na porta 443 para o proxy. As conexões de clientes normalmente também usam HTTPS na porta 443. Se o acesso à rede de saída for restrito, permita que o Synapse se conecte a servidores domésticos remotos pelas portas TCP 443 e 8448. Não abra a porta 8008 do backend do Synapse para a internet pública quando o proxy reverso for o ponto de entrada público.

Se o servidor estiver atrás de um firewall de nuvem, roteador, rede de contêineres e firewall de host, verifique cada camada. Uma solicitação local bem-sucedida para a porta 8008 prova apenas que o Synapse responde localmente; não prova que um servidor Matrix remoto possa resolver seu domínio, validar o TLS ou alcançar o ouvinte público.

Etapa 7: Reinicie com segurança e verifique os endpoints públicos.

Valide o arquivo YAML antes de reiniciar, usando o comando de validação compatível com seu método de instalação. Em seguida, reinicie o serviço ou a implantação do Synapse e verifique os logs em busca de erros de configuração ou do listener. De uma máquina fora da sua rede privada, solicite o arquivo de descoberta e o endpoint da versão da federação:

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

Para o primeiro comando, espere uma resposta HTTPS com um corpo JSON contendo o endereço correto m.server. Para o segundo, espere uma resposta HTTPS bem-sucedida do Synapse, em vez de um erro de proxy, aviso de certificado ou tempo limite de conexão. O corpo exato da resposta pode variar de acordo com a versão do Synapse.

Em seguida, insira sua Matriz server_name(por exemplo, ` example.org<nome_do_host>`, não necessariamente o nome do host do proxy) no Testador de Federação de Matriz . Corrija quaisquer erros relatados de DNS, delegação, certificado ou endpoint e execute o teste novamente. Por fim, convide um usuário em outro servidor doméstico para uma sala de teste ou entre em uma sala hospedada em outro local. Um resultado bem-sucedido no teste é uma verificação útil de conectividade pública, mas não garante que todos os servidores remotos, políticas de sala, firewalls ou configurações de clientes se comportarão da mesma maneira.

Conceitos errôneos que levam a configurações desastrosas ou inesperadas

• "Devo sempre expor a porta 8448." Não. O padrão é 8448, mas a delegação de servidor pode direcionar a federação de entrada para a porta 443. Abra a porta que sua rota de descoberta publicada realmente utiliza.
• "O arquivo de endpoints bem conhecidos do cliente permite a federação." Não permite. A descoberta de federação usa o endpoint de endpoints bem conhecidos do servidor ou um fallback de DNS compatível; o endpoint do cliente tem uma finalidade diferente.
• “A federação torna todas as salas locais públicas.” Não. A federação permite a comunicação com o servidor. A visibilidade e a participação na sala ainda regem a participação; convide uma conta remota para uma sala de teste para confirmar o caso de uso desejado.
• “Um teste de integridade local verde comprova a federação.” Não. Os testes locais não verificam DNS público, validação TLS externa, NAT, regras de firewall na nuvem ou roteamento de proxy. Faça o teste externamente usando o testador de federação.

A documentação do Synapse recomenda o uso de um proxy reverso para a terminação TLS e explica as portas separadas para cliente e federação. Consulte os guias oficiais para obter informações sobre configuração de proxy reverso , delegação de federação de entrada , opções de configuração do Synapse e orientações sobre firewall e segurança . Para regras de descoberta de servidores, consulte a especificação da API Matrix Server-Server . Os exemplos aqui pressupõem o uso do Synapse padrão por trás de um proxy reverso HTTPS; redes de contêineres, implantações gerenciadas e layouts de ouvintes personalizados podem exigir valores diferentes.