Hardening Synapse Proxy Forwarding and TLS Termination
Running a Matrix community alongside web forums provides real-time discussion, but operating a chat homeserver requires careful edge configuration. Placing an intermediary like nginx, Apache, Caddy, HAProxy, relayd, or lighttpd in front of Synapse allows you to expose standard secure ports while keeping internal application processes sandboxed. Review this technical audit checklist based on official guidance from the Synapse Reverse Proxy Documentation to safeguard connection forwarding and cryptographic boundaries.
Checklist Item 1: Terminate TLS and Isolate Local Listener Ports
Terminating TLS at the proxy edge eliminates the requirement for Synapse itself to bind directly to privileged ports below 1024. This architecture removes any need to run the application daemon as root or assign CAP_NET_BIND_SERVICE capabilities. When reviewing your socket exposure:
- Expose public port 443: matrix clients connect to standard HTTPS port 443 by default, where your front-end daemon handles certificates.
- Isolate internal port 8008: In
homeserver.yaml, review the port 8008 section. For bare-metal or virtual machine setups, setbind_addresses: ['127.0.0.1']so Synapse listens solely on localhost. - Preserve container networking: If you run a containerized homeserver, avoid changing
bind_addressesto127.0.0.1, as that restriction stops the instance from accepting forwarded requests from external proxy networks. - Audit UNIX domain sockets: Front-end engines such as HAProxy and lighttpd can alternatively forward backend traffic over local sockets like
/run/synapse/main_public.sockor/var/lib/synapse/main_public.sock.
For more architectural context on deploying chat backends, see our overview of the Synapse Matrix homeserver profile.
Checklist Item 2: Forward Essential Headers Without Altering URIs
Proper connection accounting requires passing client information cleanly to Synapse so the homeserver records genuine source addresses and generates working redirect links. In your homeserver.yaml, confirm that x_forwarded: true is enabled on the internal port 8008 listener.
Your reverse proxy must supply both the X-Forwarded-For and X-Forwarded-Proto headers on forwarded traffic. Optionally, set request_id_header in the homeserver configuration if you want Synapse to extract and log the matching request identification format supplied by your edge server.
Critically, the proxy must never normalize or canonicalize requested URIs, including decoding %xx escapes. When using an NGINX proxy architecture, define proxy_pass http://localhost:8008; without trailing path characters or slashes after the port, because trailing characters force URI canonicalization and trigger cryptographic signature verification failures. For Apache administrators, include AllowEncodedSlashes NoDecode, verify ProxyPreserveHost on to prevent redirect loops, and append the nocanon flag to every ProxyPass rule.
Checklist Item 3: Adjust Upload Buffers and Protocol Capabilities
Real-time rooms regularly exchange media attachments, audio messages, and room state events. Standard proxy defaults often conflict with homeserver transport behavior if left unadjusted:
- Synchronize payload limits: Default nginx installations enforce a client_max_body_size ceiling of 1M. Increase this directive to 50M or match your homeserver max_upload_size value so member uploads do not fail at the edge.
- Enable chunked transfers: Synapse responses may utilize chunked transfer encoding. Ensure your proxy leverages HTTP/1.1 backend communication (such as
proxy_http_version 1.1;in nginx) to parse chunked responses correctly. - Disable conflicting web filters: Synapse is currently incompatible with Apache's ModSecurity module (mod_security2). If mod_security2 operates globally across other virtual hosts, turn off the engine inside Synapse virtual host blocks by adding
SecRuleEngine offinside the relevant configuration blocks.
Checklist Item 4: Secure Federation Routes and Well-Known Delegation
Matrix federation uses port 8448 by default, while client traffic communicates on port 443. Depending on your network design, you can maintain separate listener blocks or unify federation onto port 443 through server delegation.
If operating dual ports, configure listeners for both port 443 and port 8448 with valid certificates. If using delegation to route server federation directly over port 443, your proxy can serve JSON strings from the /.well-known/matrix/server endpoint returning {"m.server": "matrix.example.com:443"}, alongside /.well-known/matrix/client responses. When serving these discovery files directly from your proxy configuration, include an Access-Control-Allow-Origin * response header with an application/json content type.
Checklist Item 5: Lock Down Administrative Endpoints and Monitor Health
The final step in proxy hardening is separating sensitive management functions from ordinary room messaging. Synapse establishes administrative operations under /_synapse/admin. Although these endpoints require authentication with an administrator access token, official documentation recommends against exposing them directly to the public internet.
Forward public traffic strictly for locations starting with /_matrix and /_synapse/client. Internal admin routes can be blocked entirely at the edge or restricted to authorized administrative networks. To keep tabs on homeserver stability without cluttering activity records, configure your proxy or uptime monitors to query the /health listener endpoint, which consistently returns an unlogged 200 status code.
Sources
Configuration rules and deployment specifications in this guide are derived from the official Synapse Reverse Proxy Documentation.
Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.