2019-09-17 11:55:29 +00:00
# Using a reverse proxy with Synapse
It is recommended to put a reverse proxy such as
[nginx ](https://nginx.org/en/docs/http/ngx_http_proxy_module.html ),
[Apache ](https://httpd.apache.org/docs/current/mod/mod_proxy_http.html ),
2021-03-06 11:49:19 +00:00
[Caddy ](https://caddyserver.com/docs/quick-starts/reverse-proxy ),
[HAProxy ](https://www.haproxy.org/ ) or
[relayd ](https://man.openbsd.org/relayd.8 ) in front of Synapse. One advantage
2019-09-17 11:55:29 +00:00
of doing so is that it means that you can expose the default https port
(443) to Matrix clients without needing to run Synapse with root
privileges.
2021-02-24 18:11:33 +00:00
You should configure your reverse proxy to forward requests to `/_matrix` or
`/_synapse/client` to Synapse, and have it set the `X-Forwarded-For` and
`X-Forwarded-Proto` request headers.
You should remember that Matrix clients and other Matrix servers do not
necessarily need to connect to your server via the same server name or
port. Indeed, clients will use port 443 by default, whereas servers default to
port 8448. Where these are different, we refer to the 'client port' and the
'federation port'. See [the Matrix
2020-02-18 13:53:46 +00:00
specification](https://matrix.org/docs/spec/server_server/latest#resolving-server-names)
for more details of the algorithm used for federation connections, and
2021-07-15 11:47:55 +00:00
[Delegation ](delegate.md ) for instructions on setting up delegation.
2019-09-17 11:55:29 +00:00
2021-02-24 18:11:33 +00:00
**NOTE**: Your reverse proxy must not `canonicalise` or `normalise`
the requested URI in any way (for example, by decoding `%xx` escapes).
Beware that Apache *will* canonicalise URIs unless you specify
`nocanon` .
2020-09-10 12:26:34 +00:00
2019-09-17 11:55:29 +00:00
Let's assume that we expect clients to connect to our server at
`https://matrix.example.com` , and other servers to connect at
`https://example.com:8448` . The following sections detail the configuration of
the reverse proxy and the homeserver.
2021-08-09 15:12:53 +00:00
## Homeserver Configuration
The HTTP configuration will need to be updated for Synapse to correctly record
client IP addresses and generate redirect URLs while behind a reverse proxy.
In `homeserver.yaml` set `x_forwarded: true` in the port 8008 section and
consider setting `bind_addresses: ['127.0.0.1']` so that the server only
listens to traffic on localhost. (Do not change `bind_addresses` to `127.0.0.1`
when using a containerized Synapse, as that will prevent it from responding
to proxied traffic.)
2022-09-15 20:32:25 +00:00
Optionally, you can also set
2022-12-28 15:45:28 +00:00
[`request_id_header` ](./usage/configuration/config_documentation.md#listeners )
2022-09-15 20:32:25 +00:00
so that the server extracts and re-uses the same request ID format that the
reverse proxy is using.
2021-08-09 15:12:53 +00:00
2020-05-05 10:29:29 +00:00
## Reverse-proxy configuration examples
2019-09-17 11:55:29 +00:00
2020-05-05 10:29:29 +00:00
**NOTE**: You only need one of these.
2019-09-17 11:55:29 +00:00
### nginx
2021-11-01 11:35:55 +00:00
```nginx
2020-05-15 14:13:39 +00:00
server {
2024-01-22 14:22:16 +00:00
listen 443 ssl;
listen [::]:443 ssl;
2020-07-16 15:01:45 +00:00
# For the federation port
2024-01-22 14:22:16 +00:00
listen 8448 ssl default_server;
listen [::]:8448 ssl default_server;
2020-07-16 15:01:45 +00:00
2020-05-15 14:13:39 +00:00
server_name matrix.example.com;
2022-01-04 22:31:45 +00:00
location ~ ^(/_matrix|/_synapse/client) {
2021-08-27 11:54:21 +00:00
# note: do not add a path (even a single /) after the port in `proxy_pass` ,
# otherwise nginx will canonicalise the URI and cause signature verification
# errors.
2020-05-15 14:13:39 +00:00
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
2021-02-24 18:11:33 +00:00
proxy_set_header X-Forwarded-Proto $scheme;
2021-03-03 11:08:11 +00:00
proxy_set_header Host $host;
2020-05-15 14:13:39 +00:00
# Nginx by default only allows file uploads up to 1M in size
# Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
2020-10-09 15:58:23 +00:00
client_max_body_size 50M;
2022-11-11 17:28:05 +00:00
# Synapse responses may be chunked, which is an HTTP/1.1 feature.
proxy_http_version 1.1;
2020-05-15 14:13:39 +00:00
}
}
```
2021-08-27 11:54:21 +00:00
### Caddy v2
2020-05-15 13:36:01 +00:00
2020-05-15 14:13:39 +00:00
```
matrix.example.com {
2022-07-25 16:07:26 +00:00
reverse_proxy /_matrix/* localhost:8008
reverse_proxy /_synapse/client/* localhost:8008
2020-05-15 14:13:39 +00:00
}
2020-05-15 13:36:01 +00:00
2020-05-15 14:13:39 +00:00
example.com:8448 {
2023-07-31 11:25:06 +00:00
reverse_proxy /_matrix/* localhost:8008
2020-05-15 14:13:39 +00:00
}
```
2022-07-25 16:07:26 +00:00
2021-07-14 16:50:30 +00:00
[Delegation ](delegate.md ) example:
2022-07-25 16:07:26 +00:00
```
2021-07-14 16:50:30 +00:00
example.com {
2022-07-25 16:07:26 +00:00
header /.well-known/matrix/* Content-Type application/json
header /.well-known/matrix/* Access-Control-Allow-Origin *
respond /.well-known/matrix/server `{"m.server": "matrix.example.com:443"}`
respond /.well-known/matrix/client `{"m.homeserver":{"base_url":"https://matrix.example.com"},"m.identity_server":{"base_url":"https://identity.example.com"}}`
2021-07-14 16:50:30 +00:00
}
matrix.example.com {
2022-07-25 16:07:26 +00:00
reverse_proxy /_matrix/* localhost:8008
reverse_proxy /_synapse/client/* localhost:8008
2021-07-14 16:50:30 +00:00
}
```
2020-05-15 13:36:01 +00:00
2019-09-17 11:55:29 +00:00
### Apache
2021-11-01 11:35:55 +00:00
```apache
2020-05-15 14:13:39 +00:00
< VirtualHost * :443 >
SSLEngine on
2021-03-26 10:38:31 +00:00
ServerName matrix.example.com
2019-09-17 11:55:29 +00:00
2021-02-24 18:11:33 +00:00
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
2020-05-15 14:13:39 +00:00
AllowEncodedSlashes NoDecode
2021-03-26 10:38:31 +00:00
ProxyPreserveHost on
2020-05-15 14:13:39 +00:00
ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
2020-09-10 12:26:34 +00:00
ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client nocanon
ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
2020-05-15 14:13:39 +00:00
< / VirtualHost >
2019-09-17 11:55:29 +00:00
2020-05-15 14:13:39 +00:00
< VirtualHost * :8448 >
SSLEngine on
2021-03-26 10:38:31 +00:00
ServerName example.com
2019-09-17 11:55:29 +00:00
2021-02-24 18:11:33 +00:00
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
2020-05-15 14:13:39 +00:00
AllowEncodedSlashes NoDecode
ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
< / VirtualHost >
```
2019-09-17 11:55:29 +00:00
2020-05-15 14:13:39 +00:00
**NOTE**: ensure the `nocanon` options are included.
2019-09-17 11:55:29 +00:00
2020-09-23 10:14:08 +00:00
**NOTE 2**: It appears that Synapse is currently incompatible with the ModSecurity module for Apache (`mod_security2`). If you need it enabled for other services on your web server, you can disable it for Synapse's two VirtualHosts by including the following lines before each of the two `</VirtualHost>` above:
2021-11-01 11:35:55 +00:00
```apache
2020-09-23 10:14:08 +00:00
< IfModule security2_module >
SecRuleEngine off
< / IfModule >
```
2021-03-26 10:38:31 +00:00
**NOTE 3**: Missing `ProxyPreserveHost on` can lead to a redirect loop.
2019-09-17 11:55:29 +00:00
### HAProxy
2020-05-15 14:13:39 +00:00
```
frontend https
2022-03-28 10:48:18 +00:00
bind *:443,[::]:443 ssl crt /etc/ssl/haproxy/ strict-sni alpn h2,http/1.1
2021-02-24 18:11:33 +00:00
http-request set-header X-Forwarded-Proto https if { ssl_fc }
http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
http-request set-header X-Forwarded-For %[src]
2019-09-17 11:55:29 +00:00
2020-05-15 14:13:39 +00:00
# Matrix client traffic
2021-11-01 14:16:02 +00:00
acl matrix-host hdr(host) -i matrix.example.com matrix.example.com:443
2020-05-15 14:13:39 +00:00
acl matrix-path path_beg /_matrix
2020-09-10 12:26:34 +00:00
acl matrix-path path_beg /_synapse/client
2019-09-17 11:55:29 +00:00
2020-05-15 14:13:39 +00:00
use_backend matrix if matrix-host matrix-path
2019-09-17 11:55:29 +00:00
2020-05-15 14:13:39 +00:00
frontend matrix-federation
2022-03-28 10:48:18 +00:00
bind *:8448,[::]:8448 ssl crt /etc/ssl/haproxy/synapse.pem alpn h2,http/1.1
2021-02-24 18:11:33 +00:00
http-request set-header X-Forwarded-Proto https if { ssl_fc }
http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
http-request set-header X-Forwarded-For %[src]
2020-05-15 14:13:39 +00:00
default_backend matrix
2019-09-17 11:55:29 +00:00
2020-05-15 14:13:39 +00:00
backend matrix
server matrix 127.0.0.1:8008
```
2023-12-04 12:38:46 +00:00
Example configuration, if using a UNIX socket. The configuration lines regarding the frontends do not need to be modified.
```
backend matrix
server matrix unix@/run/synapse/main_public.sock
```
2022-04-25 12:18:18 +00:00
[Delegation ](delegate.md ) example:
```
frontend https
acl matrix-well-known-client-path path /.well-known/matrix/client
acl matrix-well-known-server-path path /.well-known/matrix/server
use_backend matrix-well-known-client if matrix-well-known-client-path
use_backend matrix-well-known-server if matrix-well-known-server-path
backend matrix-well-known-client
http-after-response set-header Access-Control-Allow-Origin "*"
http-after-response set-header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
http-after-response set-header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization"
http-request return status 200 content-type application/json string '{"m.homeserver":{"base_url":"https://matrix.example.com"},"m.identity_server":{"base_url":"https://identity.example.com"}}'
backend matrix-well-known-server
http-after-response set-header Access-Control-Allow-Origin "*"
http-after-response set-header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
http-after-response set-header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization"
http-request return status 200 content-type application/json string '{"m.server":"matrix.example.com:443"}'
```
2021-03-06 11:49:19 +00:00
### Relayd
```
table < webserver > { 127.0.0.1 }
table < matrixserver > { 127.0.0.1 }
http protocol "https" {
tls { no tlsv1.0, ciphers "HIGH" }
tls keypair "example.com"
match header set "X-Forwarded-For" value "$REMOTE_ADDR"
match header set "X-Forwarded-Proto" value "https"
# set CORS header for .well-known/matrix/server, .well-known/matrix/client
# httpd does not support setting headers, so do it here
match request path "/.well-known/matrix/*" tag "matrix-cors"
match response tagged "matrix-cors" header set "Access-Control-Allow-Origin" value "*"
pass quick path "/_matrix/*" forward to < matrixserver >
pass quick path "/_synapse/client/*" forward to < matrixserver >
# pass on non-matrix traffic to webserver
pass forward to < webserver >
}
relay "https_traffic" {
listen on egress port 443 tls
protocol "https"
forward to < matrixserver > port 8008 check tcp
forward to < webserver > port 8080 check tcp
}
http protocol "matrix" {
tls { no tlsv1.0, ciphers "HIGH" }
tls keypair "example.com"
block
pass quick path "/_matrix/*" forward to < matrixserver >
pass quick path "/_synapse/client/*" forward to < matrixserver >
}
relay "matrix_federation" {
listen on egress port 8448 tls
protocol "matrix"
forward to < matrixserver > port 8008 check tcp
}
```
2020-08-07 13:21:24 +00:00
## Health check endpoint
Synapse exposes a health check endpoint for use by reverse proxies.
Each configured HTTP listener has a `/health` endpoint which always returns
200 OK (and doesn't get logged).
2020-09-10 12:26:34 +00:00
## Synapse administration endpoints
Endpoints for administering your Synapse instance are placed under
`/_synapse/admin` . These require authentication through an access token of an
admin user. However as access to these endpoints grants the caller a lot of power,
we do not recommend exposing them to the public internet without good reason.