2021-07-07 13:08:50 +03:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Configuring a Reverse Proxy - Synapse< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "favicon.svg" >
< link rel = "shortcut icon" href = "favicon.png" >
< link rel = "stylesheet" href = "css/variables.css" >
< link rel = "stylesheet" href = "css/general.css" >
< link rel = "stylesheet" href = "css/chrome.css" >
< link rel = "stylesheet" href = "css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "highlight.css" >
< link rel = "stylesheet" href = "tomorrow-night.css" >
< link rel = "stylesheet" href = "ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< link rel = "stylesheet" href = "docs/website_files/table-of-contents.css" >
< link rel = "stylesheet" href = "docs/website_files/remove-nav-buttons.css" >
< link rel = "stylesheet" href = "docs/website_files/indent-section-headers.css" >
2023-12-11 17:58:31 +03:00
< link rel = "stylesheet" href = "docs/website_files/version-picker.css" >
2021-07-07 13:08:50 +03:00
< / head >
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
< ol class = "chapter" > < li class = "chapter-item expanded affix " > < li class = "part-title" > Introduction< / li > < li class = "chapter-item expanded " > < a href = "welcome_and_overview.html" > Welcome and Overview< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Setup< / li > < li class = "chapter-item expanded " > < a href = "setup/installation.html" > Installation< / a > < / li > < li class = "chapter-item expanded " > < a href = "postgres.html" > Using Postgres< / a > < / li > < li class = "chapter-item expanded " > < a href = "reverse_proxy.html" class = "active" > Configuring a Reverse Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "turn-howto.html" > Configuring a Turn Server< / a > < / li > < li class = "chapter-item expanded " > < a href = "delegate.html" > Delegation< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Upgrading< / li > < li class = "chapter-item expanded " > < a href = "upgrade.html" > Upgrading between Synapse Versions< / a > < / li > < li class = "chapter-item expanded " > < a href = "MSC1711_certificates_FAQ.html" > Upgrading from pre-Synapse 1.0< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Usage< / li > < li class = "chapter-item expanded " > < a href = "federate.html" > Federation< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/index.html" > Configuration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "usage/configuration/homeserver_sample_config.html" > Homeserver Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/logging_sample_config.html" > Logging Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "structured_logging.html" > Structured Logging< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/user_authentication/index.html" > User Authentication< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < div > Single-Sign On< / div > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "openid.html" > OpenID Connect< / a > < / li > < li class = "chapter-item expanded " > < div > SAML< / div > < / li > < li class = "chapter-item expanded " > < div > CAS< / div > < / li > < li class = "chapter-item expanded " > < a href = "sso_mapping_providers.html" > SSO Mapping Providers< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "password_auth_providers.html" > Password Auth Providers< / a > < / li > < li class = "chapter-item expanded " > < a href = "jwt.html" > JSON Web Tokens< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "CAPTCHA_SETUP.html" > Registration Captcha< / a > < / li > < li class = "chapter-item expanded " > < a href = "application_services.html" > Application Services< / a > < / li > < li class = "chapter-item expanded " > < a href = "server_notices.html" > Server Notices< / a > < / li > < li class = "chapter-item expanded " > < a href = "consent_tracking.html" > Consent Tracking< / a > < / li > < li class = "chapter-item expanded " > < a href = "url_previews.html" > URL Previews< / a > < / li > < li class = "chapter-item expanded " > < a href = "user_directory.html" > User Directory< / a > < / li > < li class = "chapter-item expanded " > < a href = "message_retention_policies.html" > Message Retention Policies< / a > < / li > < li class = "chapter-item expanded " > < a href = "modules.html" > Pluggable Modules< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < div > Third Party Rules< / div > < / li > < li class = "chapter-item expanded " > < a href = "spam_checker.html" > Spam Checker< / a > < / li > < li class = "chapter-item expanded " > < a href = "presence_router_module.html" > Presence Router< / a > < / li > < li class = "chapter-item expanded " > < div > Media Storage Providers< / div > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "workers.html" > Workers< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "synctl_workers.html" > Using synctl with Workers< / a > < / li > < li class = "chapter-item expanded " > < a href = "systemd-with-workers/index.html" > Systemd< / a > < / li > < / ol > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "usage/administration/index.html" > Administration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "usage/administration/admin_api/index.html" > Admin API< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expa
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
2023-12-11 17:58:31 +03:00
< div class = "version-picker" >
< div class = "dropdown" >
< div class = "select" >
< span > < / span >
< i class = "fa fa-chevron-down" > < / i >
< / div >
< input type = "hidden" name = "version" >
< ul class = "dropdown-menu" >
<!-- Versions will be added dynamically in version - picker.js -->
< / ul >
< / div >
< / div >
2021-07-07 13:08:50 +03:00
< / div >
< h1 class = "menu-title" > Synapse< / h1 >
< div class = "right-buttons" >
< a href = "print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/matrix-org/synapse" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< a href = "https://github.com/matrix-org/synapse/edit/develop/docs/reverse_proxy.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
<!-- Page table of contents -->
< div class = "sidetoc" >
< nav class = "pagetoc" > < / nav >
< / div >
< h1 id = "using-a-reverse-proxy-with-synapse" > < a class = "header" href = "#using-a-reverse-proxy-with-synapse" > Using a reverse proxy with Synapse< / a > < / h1 >
< p > It is recommended to put a reverse proxy such as
< a href = "https://nginx.org/en/docs/http/ngx_http_proxy_module.html" > nginx< / a > ,
< a href = "https://httpd.apache.org/docs/current/mod/mod_proxy_http.html" > Apache< / a > ,
< a href = "https://caddyserver.com/docs/quick-starts/reverse-proxy" > Caddy< / a > ,
< a href = "https://www.haproxy.org/" > HAProxy< / a > or
< a href = "https://man.openbsd.org/relayd.8" > relayd< / a > in front of Synapse. One advantage
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.< / p >
< p > You should configure your reverse proxy to forward requests to < code > /_matrix< / code > or
< code > /_synapse/client< / code > to Synapse, and have it set the < code > X-Forwarded-For< / code > and
< code > X-Forwarded-Proto< / code > request headers.< / p >
< p > 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 < a href = "https://matrix.org/docs/spec/server_server/latest#resolving-server-names" > the Matrix
specification< / a >
for more details of the algorithm used for federation connections, and
< a href = "delegate.html" > delegate.md< / a > for instructions on setting up delegation.< / p >
< p > < strong > NOTE< / strong > : Your reverse proxy must not < code > canonicalise< / code > or < code > normalise< / code >
the requested URI in any way (for example, by decoding < code > %xx< / code > escapes).
Beware that Apache < em > will< / em > canonicalise URIs unless you specify
< code > nocanon< / code > .< / p >
< p > Let's assume that we expect clients to connect to our server at
< code > https://matrix.example.com< / code > , and other servers to connect at
< code > https://example.com:8448< / code > . The following sections detail the configuration of
the reverse proxy and the homeserver.< / p >
< h2 id = "reverse-proxy-configuration-examples" > < a class = "header" href = "#reverse-proxy-configuration-examples" > Reverse-proxy configuration examples< / a > < / h2 >
< p > < strong > NOTE< / strong > : You only need one of these.< / p >
< h3 id = "nginx" > < a class = "header" href = "#nginx" > nginx< / a > < / h3 >
< pre > < code > server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
# For the federation port
listen 8448 ssl http2 default_server;
listen [::]:8448 ssl http2 default_server;
server_name matrix.example.com;
location ~* ^(\/_matrix|\/_synapse\/client) {
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;
# 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
client_max_body_size 50M;
}
}
< / code > < / pre >
< p > < strong > NOTE< / strong > : Do not add a path after the port in < code > proxy_pass< / code > , otherwise nginx will
canonicalise/normalise the URI.< / p >
< h3 id = "caddy-1" > < a class = "header" href = "#caddy-1" > Caddy 1< / a > < / h3 >
< pre > < code > matrix.example.com {
proxy /_matrix http://localhost:8008 {
transparent
}
proxy /_synapse/client http://localhost:8008 {
transparent
}
}
example.com:8448 {
proxy / http://localhost:8008 {
transparent
}
}
< / code > < / pre >
< h3 id = "caddy-2" > < a class = "header" href = "#caddy-2" > Caddy 2< / a > < / h3 >
< pre > < code > matrix.example.com {
reverse_proxy /_matrix/* http://localhost:8008
reverse_proxy /_synapse/client/* http://localhost:8008
}
example.com:8448 {
reverse_proxy http://localhost:8008
}
< / code > < / pre >
< h3 id = "apache" > < a class = "header" href = "#apache" > Apache< / a > < / h3 >
< pre > < code > < VirtualHost *:443>
SSLEngine on
ServerName matrix.example.com
RequestHeader set " X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
AllowEncodedSlashes NoDecode
ProxyPreserveHost on
ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client nocanon
ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
< /VirtualHost>
< VirtualHost *:8448>
SSLEngine on
ServerName example.com
RequestHeader set " X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
AllowEncodedSlashes NoDecode
ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
< /VirtualHost>
< / code > < / pre >
< p > < strong > NOTE< / strong > : ensure the < code > nocanon< / code > options are included.< / p >
< p > < strong > NOTE 2< / strong > : It appears that Synapse is currently incompatible with the ModSecurity module for Apache (< code > mod_security2< / code > ). 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 < code > < /VirtualHost> < / code > above:< / p >
< pre > < code > < IfModule security2_module>
SecRuleEngine off
< /IfModule>
< / code > < / pre >
< p > < strong > NOTE 3< / strong > : Missing < code > ProxyPreserveHost on< / code > can lead to a redirect loop.< / p >
< h3 id = "haproxy" > < a class = "header" href = "#haproxy" > HAProxy< / a > < / h3 >
< pre > < code > frontend https
bind :::443 v4v6 ssl crt /etc/ssl/haproxy/ strict-sni alpn h2,http/1.1
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]
# Matrix client traffic
acl matrix-host hdr(host) -i matrix.example.com
acl matrix-path path_beg /_matrix
acl matrix-path path_beg /_synapse/client
use_backend matrix if matrix-host matrix-path
frontend matrix-federation
bind :::8448 v4v6 ssl crt /etc/ssl/haproxy/synapse.pem alpn h2,http/1.1
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]
default_backend matrix
backend matrix
server matrix 127.0.0.1:8008
< / code > < / pre >
< h3 id = "relayd" > < a class = "header" href = "#relayd" > Relayd< / a > < / h3 >
< pre > < code > 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
}
< / code > < / pre >
< h2 id = "homeserver-configuration" > < a class = "header" href = "#homeserver-configuration" > Homeserver Configuration< / a > < / h2 >
< p > You will also want to set < code > bind_addresses: ['127.0.0.1']< / code > and
< code > x_forwarded: true< / code > for port 8008 in < code > homeserver.yaml< / code > to ensure that
client IP addresses are recorded correctly.< / p >
< p > Having done so, you can then use < code > https://matrix.example.com< / code > (instead
of < code > https://matrix.example.com:8448< / code > ) as the " Custom server" when
connecting to Synapse from a client.< / p >
< h2 id = "health-check-endpoint" > < a class = "header" href = "#health-check-endpoint" > Health check endpoint< / a > < / h2 >
< p > Synapse exposes a health check endpoint for use by reverse proxies.
Each configured HTTP listener has a < code > /health< / code > endpoint which always returns
200 OK (and doesn't get logged).< / p >
< h2 id = "synapse-administration-endpoints" > < a class = "header" href = "#synapse-administration-endpoints" > Synapse administration endpoints< / a > < / h2 >
< p > Endpoints for administering your Synapse instance are placed under
< code > /_synapse/admin< / code > . 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.< / p >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "postgres.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "turn-howto.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "postgres.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "turn-howto.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< script type = "text/javascript" src = "docs/website_files/table-of-contents.js" > < / script >
2023-12-11 17:58:31 +03:00
< script type = "text/javascript" src = "docs/website_files/version-picker.js" > < / script >
< script type = "text/javascript" src = "docs/website_files/version.js" > < / script >
2021-07-07 13:08:50 +03:00
< / body >
2023-12-11 17:58:31 +03:00
< / html >
