Mastodon Federation Behind a Cloudflare Proxy: Setup Notes

When you run a Mastodon instance behind a Cloudflare proxy, federation with other instances can break silently. Mastodon relies on the real IP address of remote servers to verify signatures and enforce rate limits. Cloudflare’s proxy hides the true origin IP and may alter HTTPS headers. This article explains how to configure Mastodon, Nginx, and Cloudflare so that federation works reliably.

Without proper setup, other instances see Cloudflare’s IP instead of your server’s IP. Signature verification fails, and your instance may be blocked or ignored by the fediverse. We cover the required Cloudflare settings, Nginx configuration changes, and Mastodon environment variables to restore proper federation.

Why Cloudflare Proxy Breaks Mastodon Federation

Mastodon uses HTTP signatures to verify that incoming ActivityPub messages come from a legitimate remote instance. The signature includes the IP address of the sender. When Cloudflare acts as a reverse proxy, it replaces the remote server’s IP with one of Cloudflare’s own IP addresses. Mastodon then sees the proxy IP and fails signature validation.

Additionally, Mastodon enforces rate limits based on the connecting IP. If all remote servers appear to come from Cloudflare’s IP range, your instance may rate-limit legitimate traffic or allow abuse from a single point. The solution involves three layers: Cloudflare SSL configuration, Nginx real IP module, and Mastodon trusted proxy settings.

Cloudflare SSL/TLS Encryption Mode

Cloudflare offers several SSL/TLS modes. For Mastodon federation, you must use Full (strict). This mode requires a valid SSL certificate on your origin server and encrypts traffic end-to-end. Flexible mode decrypts traffic at Cloudflare and re-encrypts it to your server, which breaks the certificate chain that other instances use to verify your server’s identity. Full (strict) ensures that the certificate presented to federating servers is the same one your origin serves.

Nginx Real IP Module

Nginx can replace the client IP in the request with the value from a trusted header. Cloudflare sends the original client IP in the CF-Connecting-IP header. You must configure Nginx to read this header and set the real IP for all proxied requests. Without this, Mastodon receives Cloudflare’s IP as the remote address.

Mastodon Trusted Proxy Configuration

Mastodon’s TRUSTED_PROXY_IP environment variable tells the application which IP ranges are safe to extract the real client IP from. You must include Cloudflare’s published IP ranges. This allows Mastodon to use the real IP for signature verification and rate limiting instead of the proxy IP.

Steps to Configure Mastodon Federation Behind Cloudflare

1. Set Cloudflare SSL/TLS to Full (strict)
   In the Cloudflare dashboard for your domain, go to SSL/TLS > Overview and select Full (strict). Ensure your origin server has a valid SSL certificate installed. This mode encrypts traffic end-to-end and presents your origin certificate to federating instances.
2. Install the Nginx real IP module
   Most Nginx installations include the ngx_http_realip_module by default. Verify with nginx -V 2>&1 | grep realip. If missing, recompile Nginx with --with-http_realip_module.
3. Add real IP configuration to the server block
   Edit your Mastodon Nginx configuration file (commonly /etc/nginx/sites-available/mastodon). Inside the server block, add:
   set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;
real_ip_header CF-Connecting-IP;
   These are Cloudflare’s IPv4 ranges. Add similar lines for IPv6 if your instance supports it. The real_ip_header directive tells Nginx which header contains the original IP.
4. Restart Nginx
   Run sudo systemctl restart nginx to apply the changes. Verify that Nginx is using the real IP by checking access logs: tail -f /var/log/nginx/access.log. You should see remote IPs that are not Cloudflare addresses.
5. Set the Mastodon TRUSTED_PROXY_IP environment variable
   Edit the Mastodon environment file (usually .env.production). Add or update the line:
   TRUSTED_PROXY_IP=173.245.48.0/20,103.21.244.0/22,103.22.200.0/22,103.31.4.0/22,141.101.64.0/18,108.162.192.0/18,190.93.240.0/20,188.114.96.0/20,197.234.240.0/22,198.41.128.0/17,162.158.0.0/15,104.16.0.0/13,104.24.0.0/14,172.64.0.0/13,131.0.72.0/22
   Include IPv6 ranges if applicable. Save the file.
6. Restart Mastodon services
   Run sudo systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming. This reloads the environment variable and applies the trusted proxy configuration.
7. Test federation from another instance
   Use a Mastodon account on a different instance to follow an account on your instance. Check the logs on your server for signature errors. Run sudo journalctl -u mastodon-web -f and look for lines containing HTTP Signature or verification failed. If you see no errors, federation is working correctly.

Common Issues After Cloudflare Proxy Setup

Federation Requests Time Out or Return 502 Bad Gateway

This usually means Cloudflare cannot reach your origin server. Check that your firewall allows traffic from Cloudflare IP ranges. Also verify that your SSL certificate is valid and that the server block listens on port 443. If you use a self-signed certificate, Cloudflare Full (strict) will reject it.

Remote Instances Receive SSL Certificate Errors

When Cloudflare is set to Flexible SSL, your origin certificate is not validated. Other instances see Cloudflare’s certificate, which does not match your domain’s expected certificate. Switch to Full (strict) and ensure your origin has a trusted certificate from a public CA like Let’s Encrypt.

Rate Limiting Blocks Legitimate Traffic

If Mastodon still sees Cloudflare IPs, rate limits will apply to all traffic from Cloudflare’s IP pool. Verify that TRUSTED_PROXY_IP includes the correct ranges and that Nginx’s real_ip_header is set to CF-Connecting-IP. Restart both Nginx and Mastodon after changes.

Cloudflare vs Direct Connection for Mastodon Federation

Item	Behind Cloudflare Proxy	Direct Connection
IP visibility	Cloudflare IP shown to federating instances	Your server’s real IP shown
SSL configuration	Full (strict) required; certificate must be on origin	Any valid certificate on origin works
Rate limiting	Must configure TRUSTED_PROXY_IP to avoid false blocks	Works automatically
DDoS protection	Cloudflare filters malicious traffic before it reaches your server	You must handle DDoS yourself
Latency	Added hop may increase latency slightly	Direct connection is faster

After completing the setup, your Mastodon instance will federate correctly with the rest of the fediverse. Test by following an account on a remote instance and verifying that posts appear in your federated timeline. For advanced monitoring, enable MASTODON_DEBUG=true in the environment file temporarily to log detailed federation handshake data. Remove it after testing to reduce log noise.