The Matrix Federation: Follow the White Rabbit

Note: This is Chapter 2 of our deep dive into Matrix Federation. If you haven’t already laid the groundwork, start with [“Build Your Own Secure Chat System with Matrix”] – that article covers all the essentials before we get into the nitty-gritty of server-to-server handshakes.

Matrix Federation isn’t a central server – it’s a network of free individuals: autonomous homeservers communicating through open standards.
Your Synapse server doesn’t report to a corporate overlord. It becomes part of a decentralized network — by choice, not coercion.

You take the red pill – you stay in Wonderland, and I show you how deep the rabbit hole goes.

Like Zion, this digital underground is built on trust, resilience, and freedom.

Welcome to Federation.

1. What Is Matrix Federation?

Each homeserver chooses who to trust. No single point of failure. No corporation scanning your messages. Just you and the connections you allow.

Technically, federation works like this:

  • Server-to-server communication uses HTTPS (usually on port 443) with signed JSON over TLS.
  • User identities are domain-based: @neo:zion.org tells other servers where to find Neo.
  • DNS-based routing uses SRV records or a .well-known/matrix/server file to locate the real server behind a domain.
  • Mutual trust is established via TLS certificates and cryptographic signatures.
  • No central authority – every server operates independently and can choose to federate selectively.

Welcome to Zion. You’re not connecting to a platform — you’re connecting to people.

2. Requirements for Federation

Before your homeserver can federate securely and reliably with others, a few critical requirements must be met:

Public Accessibility

  • Your server must be reachable on port 443 from the public internet.
  • Use a domain name (e.g. matrix.example.com) pointing to your server’s public IP.

TLS Certificate

  • Your homeserver must present a valid TLS certificate for the domain used in federation.
  • SAN (Subject Alternative Name) must match the federation domain exactly (e.g. matrix.example.com).
  • Wildcard certificates (like *.example.com) do not work for federation.

DNS Records

  • You can use either:
    • A _matrix._tcp SRV record to point to a different hostname and port, or
    • A .well-known/matrix/server file to redirect federation traffic.
  • Without either, federation defaults to port 8448, which many servers block. Use .well-known or SRV to ensure federation over 443.

Firewall Rules

  • Open TCP port 443 for incoming federation traffic.
  • Ensure your firewall or reverse proxy allows large HTTP requests and long-lived TLS connections.

Static IP & DNS

  • Use a stable DNS name and avoid dynamic IPs or unreliable hosting setups.

A homeserver in Zion must be seen and trusted. It must speak clearly, securely, and on open channels.

3. TLS Certificates for Matrix Synapse – What You Need to Know

When running a Matrix Synapse server, securing your connections with proper TLS certificates is essential. These certificates ensure that clients and other servers can trust your instance and communicate securely.

Why Are Certificates Important?

TLS certificates verify your server’s identity and encrypt data in transit. Without valid certificates, Matrix federation and client connections will fail due to mistrust or insecure connections.

Certificate Requirements

  • Use Trusted CA-Issued Certificates:
    Avoid self-signed certificates in production. Instead, use certificates issued by well-known Certificate Authorities (CAs) like Let’s Encrypt. They are free, widely trusted, and support automatic renewal.
  • Common Name (CN) and Subject Alternative Name (SAN):
    Modern TLS validation relies primarily on the Subject Alternative Name (SAN) field. Your certificate must include your Matrix server’s hostname (e.g., matrix.example.com) in both the SAN list and the Common Name (CN).
    While SAN is the primary field checked by clients, setting the CN correctly remains important for compatibility and fallback. Certificates lacking the correct SAN entry will cause connection failures.

Practical Recommendations

  • Obtain certificates that include your Matrix server domain in both CN and SAN.
  • If you use multiple domains or subdomains, include all relevant ones in the SAN extension.
  • Automate issuance and renewal using tools like certbot or acme.sh.
  • Configure Synapse with paths to the correct certificate and private key in your homeserver.yaml.

Summary

  • Always use certificates from trusted authorities (Let’s Encrypt is highly recommended).
  • Ensure your certificate includes your server’s hostname both in the CN and in the SAN field.
  • Avoid self-signed certificates in production to maintain smooth federation and client connectivity.

4. Federation Configuration in Synapse

Server-to-Server Discovery (Federation)

Only required if you want to federate with the wider Matrix network.

Create this file:
https://example.com/.well-known/matrix/server

Content:

{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  }
}

To enable federation in your Synapse configuration, review and adjust the following settings in homeserver.yaml:

# The public domain name of your server used for federation.
server_name: "matrix.example.com"

# Enable or disable federation (should be true).
federation_enabled: true

# Optional but recommended: limit outbound federation for privacy or control.
federation_domain_whitelist:
  - "trusted-homeserver1.org"
  - "matrix.org"

# Configure your server to send presence updates only to local users (optional).
send_presence_to_federation: false

# Optionally require TLS for all outbound federation requests (default: true).
federation_verify_certificates: true

.well-known Delegation (if using port 443 reverse proxy)

If your Synapse is not directly reachable on matrix.example.com:443, add this file to https://matrix.example.com/.well-known/matrix/server:

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

Make sure this endpoint is publicly accessible and serves correct Content-Type: application/json.

DNS Configuration

Ensure correct A/AAAA records for matrix.example.com

If using .well-known, make sure the server delegation works properly.

4. SRV Record for Federation

In case your Matrix homeserver (matrix.example.com) differs from your user domain (example.com), an SRV record allows other servers to discover your actual endpoint – especially if you’re not using a .well-known configuration.

Example SRV Record for example.com

For DNS providers without dedicated SRV fields (e.g., SchlundTech), use a value format like this:

TypeName / HostValueTTL
SRV_matrix._tcp10 5 443 matrix.example.com.3600

✅ Note: Include the trailing dot after the hostname (matrix.example.com.)

Test Your SRV Record

ℹ️ If you already use a .well-known/matrix/server file, the SRV record is not required but can act as a fallback or future-proofing.

Federation Testing

Use the official Matrix federation tester to verify your setup:

https://federationtester.matrix.org/#matrix.example.com

A successful test confirms federation readiness — the final step before you become part of the wider Matrix universe.

Federation is not just about being online. It’s about being trusted, verifiable, and reachable in a network where every peer is equal.

Related Posts