From cac2e11e36d3d18604b094e1fe24ed457f6c3f3d Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 10 Jun 2019 16:22:31 +0100 Subject: [PATCH 1/9] add a health warning making it clear that the 1711 upgrade FAQ is now out of date --- docs/MSC1711_certificates_FAQ.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index 599462bdcb73..d0d4a88a4819 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -1,5 +1,22 @@ # MSC1711 Certificates FAQ +## Historical Note +This document was originally written to guide server admins through the upgrade +path towards Synapse 1.0.0. Specifically, +[MSC1711](https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md) +required that all servers present valid TLS certificates on their federation +API. Admins were encouraged to achieve compliance from version 0.99.0 (release +in February 2019) ahead of version 1.0 (released June 2019) enforcing the +certificate checks. + +Much of what follows is now outdated since most admins will have already +upgraded, however it may be of use to those with old installs returning to the +project. + +If you are setting up a server from scratch you almost certainly should look at +the [installation guide](INSTALL.md) instead. + +## Introduction The goal of Synapse 0.99.0 is to act as a stepping stone to Synapse 1.0.0. It supports the r0.1 release of the server to server specification, but is compatible with both the legacy Matrix federation behaviour (pre-r0.1) as well From 973b470ea7a4d1fd6607ceef31bfc261bc447d55 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 10 Jun 2019 16:27:18 +0100 Subject: [PATCH 2/9] add FAQ questions to federate.md --- INSTALL.md | 27 +++++++++--------- docs/federate.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 84 insertions(+), 15 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index a1ff91a98eef..2df686b19b07 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,14 +1,14 @@ -* [Installing Synapse](#installing-synapse) - * [Installing from source](#installing-from-source) - * [Platform-Specific Instructions](#platform-specific-instructions) - * [Troubleshooting Installation](#troubleshooting-installation) - * [Prebuilt packages](#prebuilt-packages) -* [Setting up Synapse](#setting-up-synapse) - * [TLS certificates](#tls-certificates) - * [Email](#email) - * [Registering a user](#registering-a-user) - * [Setting up a TURN server](#setting-up-a-turn-server) - * [URL previews](#url-previews) +- [Installing Synapse](#installing-synapse) + - [Installing from source](#installing-from-source) + - [Platform-Specific Instructions](#platform-specific-instructions) + - [Troubleshooting Installation](#troubleshooting-installation) + - [Prebuilt packages](#prebuilt-packages) +- [Setting up Synapse](#setting-up-synapse) + - [TLS certificates](#tls-certificates) + - [Email](#email) + - [Registering a user](#registering-a-user) + - [Setting up a TURN server](#setting-up-a-turn-server) + - [URL previews](#url-previews) # Installing Synapse @@ -395,8 +395,9 @@ To configure Synapse to expose an HTTPS port, you will need to edit instance, if using certbot, use `fullchain.pem` as your certificate, not `cert.pem`). -For those of you upgrading your TLS certificate for Synapse 1.0 compliance, -please take a look at [our guide](docs/MSC1711_certificates_FAQ.md#configuring-certificates-for-compatibility-with-synapse-100). +For a more detailed guide to configuring your server for federation, see +[federate.md](docs/federate.md) + ## Email diff --git a/docs/federate.md b/docs/federate.md index b7fc09661ce3..521e9018e26a 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -14,8 +14,8 @@ up and will work provided you set the ``server_name`` to match your machine's public DNS hostname, and provide Synapse with a TLS certificate which is valid for your ``server_name``. -Once you have completed the steps necessary to federate, you should be able to -join a room via federation. (A good place to start is ``#synapse:matrix.org`` - a +Once you have completed the steps necessary to federate, you should be able to +join a room via federation. (A good place to start is ``#synapse:matrix.org`` - a room for Synapse admins.) @@ -98,6 +98,74 @@ _matrix._tcp.``. In our example, we would expect this: Note that the target of a SRV record cannot be an alias (CNAME record): it has to point directly to the server hosting the synapse instance. +### Delegation FAQ +#### When do I need a SRV record or .well-known URI? + +If your homeserver listens on the default federation port (8448), and your +`server_name` points to the host that your homeserver runs on, you do not need an SRV record or `.well-known/matrix/server` URI. + +For instance, if you registered `example.com` and pointed its DNS A record at a +fresh Upcloud VPS or similar, you could install Synapse on that host, +giving it a server_name of `example.com`, and it would automatically generate a +valid TLS certificate for you via Let's Encrypt and no SRV record or +`.well-known` URI would be needed. + +This is the common case, although you can add an SRV record or +`.well-known/matrix/server` URI for completeness if you wish. + +**However**, if your server does not listen on port 8448, or if your `server_name` +does not point to the host that your homeserver runs on, you will need to let +other servers know how to find it. The way to do this is via .well-known or an +SRV record. + +#### I have created a .well-known URI. Do I still need an SRV record? + +As of Synapse 0.99, Synapse will first check for the existence of a `.well-known` +URI and follow any delegation it suggests. It will only then check for the +existence of an SRV record. + +That means that the SRV record will often be redundant. However, you should +remember that there may still be older versions of Synapse in the federation +which do not understand `.well-known` URIs, so if you removed your SRV record you would no longer be able to federate with them. + +It is therefore best to leave the SRV record in place for now. Synapse 0.34 and +earlier will follow the SRV record (and not care about the invalid +certificate). Synapse 0.99 and later will follow the .well-known URI, with the +correct certificate chain. + +#### Can I manage my own certificates rather than having Synapse renew certificates itself? + +Yes, you are welcome to manage your certificates yourself. Synapse will only +attempt to obtain certificates from Let's Encrypt if you configure it to do +so.The only requirement is that there is a valid TLS cert present for +federation end points. + +#### Do you still recommend against using a reverse proxy on the federation port? + +We no longer actively recommend against using a reverse proxy. Many admins will +find it easier to direct federation traffic to a reverse proxy and manage their +own TLS certificates, and this is a supported configuration. + +See [reverse_proxy.rst](reverse_proxy.rst) for information on setting up a +reverse proxy. + +#### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy? + +Practically speaking, this is no longer necessary. + +If you are using a reverse proxy for all of your TLS traffic, then you can set +`no_tls: True`. In that case, the only reason Synapse needs the certificate is +to populate a legacy 'tls_fingerprints' field in the federation API. This is +ignored by Synapse 0.99.0 and later, and the only time pre-0.99 Synapses will +check it is when attempting to fetch the server keys - and generally this is +delegated via `matrix.org`, which is on 0.99.0. + +#### Do I need the same certificate for the client and federation port? + +No. There is nothing stopping you from using different certificates, +particularly if you are using a reverse proxy. However, Synapse will use the +same certificate on any ports where TLS is configured. + ## Troubleshooting You can use the [federation tester]( From 12d0547e4a09d33dd54281ad8c47af139b32a215 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 10 Jun 2019 17:31:16 +0100 Subject: [PATCH 3/9] reword for clarity --- docs/federate.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/federate.md b/docs/federate.md index 521e9018e26a..52e9c63b6473 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -14,9 +14,9 @@ up and will work provided you set the ``server_name`` to match your machine's public DNS hostname, and provide Synapse with a TLS certificate which is valid for your ``server_name``. -Once you have completed the steps necessary to federate, you should be able to -join a room via federation. (A good place to start is ``#synapse:matrix.org`` - a -room for Synapse admins.) +Once federation has been configured, you should be able to join a room over +federation. A good place to start is ``#synapse:matrix.org`` - a room for +Synapse admins. ## Delegation From 1bfab2f8ad03193852d132e5a8eb29f9134d9f45 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 10 Jun 2019 17:40:00 +0100 Subject: [PATCH 4/9] typos --- docs/MSC1711_certificates_FAQ.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index d0d4a88a4819..7f9a23ff3148 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -2,10 +2,10 @@ ## Historical Note This document was originally written to guide server admins through the upgrade -path towards Synapse 1.0.0. Specifically, +path towards Synapse 1.0. Specifically, [MSC1711](https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md) required that all servers present valid TLS certificates on their federation -API. Admins were encouraged to achieve compliance from version 0.99.0 (release +API. Admins were encouraged to achieve compliance from version 0.99.0 (released in February 2019) ahead of version 1.0 (released June 2019) enforcing the certificate checks. From ed77bb2fcb9520611db61ee1c29ed66dc576958a Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 10 Jun 2019 17:45:34 +0100 Subject: [PATCH 5/9] towncrier --- changelog.d/5419.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/5419.doc diff --git a/changelog.d/5419.doc b/changelog.d/5419.doc new file mode 100644 index 000000000000..74cf5eea8bab --- /dev/null +++ b/changelog.d/5419.doc @@ -0,0 +1 @@ +Expand the federation guide to include relevant content from the MSC1711 FAQ From 0fd8414df199d06209c8c4cb13b5fc7a5d7ef1fb Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 11 Jun 2019 11:11:50 +0100 Subject: [PATCH 6/9] Update docs/federate.md Co-Authored-By: Brendan Abolivier --- docs/federate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/federate.md b/docs/federate.md index 52e9c63b6473..35d214e2f7c1 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -105,7 +105,7 @@ If your homeserver listens on the default federation port (8448), and your `server_name` points to the host that your homeserver runs on, you do not need an SRV record or `.well-known/matrix/server` URI. For instance, if you registered `example.com` and pointed its DNS A record at a -fresh Upcloud VPS or similar, you could install Synapse on that host, +fresh server, you could install Synapse on that host, giving it a server_name of `example.com`, and it would automatically generate a valid TLS certificate for you via Let's Encrypt and no SRV record or `.well-known` URI would be needed. From a4a9db3f88d86c07e44395411ec40ac610f71ff4 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 11 Jun 2019 11:11:57 +0100 Subject: [PATCH 7/9] Update docs/federate.md Co-Authored-By: Brendan Abolivier --- docs/federate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/federate.md b/docs/federate.md index 35d214e2f7c1..87d59d5088f4 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -106,7 +106,7 @@ If your homeserver listens on the default federation port (8448), and your For instance, if you registered `example.com` and pointed its DNS A record at a fresh server, you could install Synapse on that host, -giving it a server_name of `example.com`, and it would automatically generate a +giving it a `server_name` of `example.com`, and it would automatically generate a valid TLS certificate for you via Let's Encrypt and no SRV record or `.well-known` URI would be needed. From ba5422601b140e65a4d93a490882bd0752ce311f Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 11 Jun 2019 11:12:07 +0100 Subject: [PATCH 8/9] Update docs/federate.md Co-Authored-By: Brendan Abolivier --- docs/federate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/federate.md b/docs/federate.md index 87d59d5088f4..5068583854f7 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -155,7 +155,7 @@ Practically speaking, this is no longer necessary. If you are using a reverse proxy for all of your TLS traffic, then you can set `no_tls: True`. In that case, the only reason Synapse needs the certificate is -to populate a legacy 'tls_fingerprints' field in the federation API. This is +to populate a legacy `tls_fingerprints` field in the federation API. This is ignored by Synapse 0.99.0 and later, and the only time pre-0.99 Synapses will check it is when attempting to fetch the server keys - and generally this is delegated via `matrix.org`, which is on 0.99.0. From 29f0af91dda563922d472ba8590cadea27c91c28 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 11 Jun 2019 11:36:19 +0100 Subject: [PATCH 9/9] typos,style --- docs/federate.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/federate.md b/docs/federate.md index 5068583854f7..6d6bb85e15a9 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -14,8 +14,8 @@ up and will work provided you set the ``server_name`` to match your machine's public DNS hostname, and provide Synapse with a TLS certificate which is valid for your ``server_name``. -Once federation has been configured, you should be able to join a room over -federation. A good place to start is ``#synapse:matrix.org`` - a room for +Once federation has been configured, you should be able to join a room over +federation. A good place to start is ``#synapse:matrix.org`` - a room for Synapse admins. @@ -102,13 +102,14 @@ directly to the server hosting the synapse instance. #### When do I need a SRV record or .well-known URI? If your homeserver listens on the default federation port (8448), and your -`server_name` points to the host that your homeserver runs on, you do not need an SRV record or `.well-known/matrix/server` URI. +`server_name` points to the host that your homeserver runs on, you do not need an SRV +record or `.well-known/matrix/server` URI. For instance, if you registered `example.com` and pointed its DNS A record at a fresh server, you could install Synapse on that host, -giving it a `server_name` of `example.com`, and it would automatically generate a -valid TLS certificate for you via Let's Encrypt and no SRV record or -`.well-known` URI would be needed. +giving it a `server_name` of `example.com`, and once [ACME](acme.md) support is enabled, +it would automatically generate a valid TLS certificate for you via Let's Encrypt +and no SRV record or .well-known URI would be needed. This is the common case, although you can add an SRV record or `.well-known/matrix/server` URI for completeness if you wish. @@ -120,13 +121,14 @@ SRV record. #### I have created a .well-known URI. Do I still need an SRV record? -As of Synapse 0.99, Synapse will first check for the existence of a `.well-known` +As of Synapse 0.99, Synapse will first check for the existence of a .well-known URI and follow any delegation it suggests. It will only then check for the existence of an SRV record. That means that the SRV record will often be redundant. However, you should remember that there may still be older versions of Synapse in the federation -which do not understand `.well-known` URIs, so if you removed your SRV record you would no longer be able to federate with them. +which do not understand .well-known URIs, so if you removed your SRV record +you would no longer be able to federate with them. It is therefore best to leave the SRV record in place for now. Synapse 0.34 and earlier will follow the SRV record (and not care about the invalid @@ -154,11 +156,12 @@ reverse proxy. Practically speaking, this is no longer necessary. If you are using a reverse proxy for all of your TLS traffic, then you can set -`no_tls: True`. In that case, the only reason Synapse needs the certificate is -to populate a legacy `tls_fingerprints` field in the federation API. This is -ignored by Synapse 0.99.0 and later, and the only time pre-0.99 Synapses will -check it is when attempting to fetch the server keys - and generally this is -delegated via `matrix.org`, which is on 0.99.0. +`no_tls: True` in the Synapse config. In that case, the only reason Synapse +needs the certificate is to populate a legacy `tls_fingerprints` field in the +federation API. This is ignored by Synapse 0.99.0 and later, and the only time +pre-0.99 Synapses will check it is when attempting to fetch the server keys - +and generally this is delegated via `matrix.org`, which will be running a modern +version of Synapse. #### Do I need the same certificate for the client and federation port?