From cd6fee3169659b13bfdb0f4b4d2a6132fd6b542c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 14:29:09 +0000 Subject: Don't imply self-signed certs are required --- UPGRADE.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index c46f70f699..f6cdec4734 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,34 +51,35 @@ returned by the Client-Server API: Upgrading to v0.99.0 ==================== -In preparation for Synapse v1.0, you must update your TLS certificates from -self-signed ones to verifiable ones signed by a trusted root CA. +In preparation for Synapse v1.0, you must ensure your federation TLS +certificates are verifiable by signed by a trusted root CA. -If you do not already have a certificate for your domain, the easiest way to get -one is with Synapse's new ACME support, which will use the ACME protocol to -provision a certificate automatically. By default, certificates will be obtained -from the publicly trusted CA Let's Encrypt. +If you do not already have a valid certificate for your domain, the easiest +way to get one is with Synapse's new ACME support, which will use the ACME +protocol to provision a certificate automatically. By default, certificates +will be obtained from the publicly trusted CA Let's Encrypt. For a sample configuration, please inspect the new ACME section in the example generated config by running the ``generate-config`` executable. For example:: ~/synapse/env3/bin/generate-config -You will need to provide Let's Encrypt (or other ACME provider) access to your -Synapse ACME challenge responder on port 80, at the domain of your homeserver. -This requires you either change the port of the ACME listener provided by -Synapse to a high port and reverse proxy to it, or use a tool like authbind to -allow Synapse to listen on port 80 without root access. (Do not run Synapse with -root permissions!) +You will need to provide Let's Encrypt (or another ACME provider) access to +your Synapse ACME challenge responder on port 80, at the domain of your +homeserver. This requires you to either change the port of the ACME listener +provided by Synapse to a high port and reverse proxy to it, or use a tool +like ``authbind`` to allow Synapse to listen on port 80 without root access. +(Do not run Synapse with root permissions!) -You will need to back up or delete your self signed TLS certificate -(``example.com.tls.crt`` and ``example.com.tls.key``), Synapse's ACME -implementation will not overwrite them. +If you are already using self-signed ceritifcates, you will need to back up +or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in +Synapse's root directory), Synapse's ACME implementation will not overwrite +them. You may wish to use alternate methods such as Certbot to obtain a certificate from Let's Encrypt, depending on your server configuration. Of course, if you already have a valid certificate for your homeserver's domain, that can be -placed in Synapse's config directory without the need for ACME. +placed in Synapse's config directory without the need for any ACME setup. Upgrading to v0.34.0 ==================== -- cgit 1.5.1 From 08b26afeee7b7db8c9d511cb63244927cf48ba9d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:29:42 +0000 Subject: Move ACME docs to docs/ACME.rst and link from UPGRADE. --- README.rst | 69 ----------------------------------------- UPGRADE.rst | 33 +++----------------- docs/ACME.rst | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 102 insertions(+), 98 deletions(-) create mode 100644 docs/ACME.rst (limited to 'UPGRADE.rst') diff --git a/README.rst b/README.rst index 9e3d85de4c..829de0864c 100644 --- a/README.rst +++ b/README.rst @@ -225,75 +225,6 @@ If you would like to use your own certificates, you can do so by changing alternatively, you can use a reverse-proxy. Apart from port 8448 using TLS, both ports are the same in the default configuration. - -ACME setup ----------- - -Synapse v1.0 will require valid TLS certificates for communication between servers -(port ``8448`` by default) in addition to those that are client-facing (port -``443``). In the case that your `server_name` config variable is the same as -the hostname that the client connects to, then the same certificate can be -used between client and federation ports without issue. Synapse v0.99.0+ -**will provision server-to-server certificates automatically for you for -free** through `Let's Encrypt -`_ if you tell it to. - -In order for Synapse to complete the ACME challenge to provision a -certificate, it needs access to port 80. Typically listening on port 80 is -only granted to applications running as root. There are thus two solutions to -this problem. - -**Using a reverse proxy** - -A reverse proxy such as Apache or nginx allows a single process (the web -server) to listen on port 80 and proxy traffic to the appropriate program -running on your server. It is the recommended method for setting up ACME as -it allows you to use your existing webserver while also allowing Synapse to -provision certificates as needed. - -For nginx users, add the following line to your existing ``server`` block:: - - location /.well-known/acme-challenge { - proxy_pass http://localhost:8009/; - } - -For Apache, add the following to your existing webserver config:: - - ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge - -Make sure to restart/reload your webserver after making changes. - - -**Authbind** - -``authbind`` allows a program which does not run as root to bind to -low-numbered ports in a controlled way. The setup is simpler, but requires a -webserver not to already be running on port 80. **This includes every time -Synapse renews a certificate**, which may be cumbersome if you usually run a -web server on port 80. Nevertheless, if you're sure port 80 is not being used -for any other purpose then all that is necessary is the following: - -Install ``authbind``. For example, on Debian/Ubuntu:: - - sudo apt-get install authbind - -Allow ``authbind`` to bind port 80:: - - sudo touch /etc/authbind/byport/80 - sudo chmod 777 /etc/authbind/byport/80 - -When Synapse is started, use the following syntax:: - - authbind --deep - -Finally, once Synapse's is able to listen on port 80 for ACME challenge -requests, it must be told to perform ACME provisioning by setting ``enabled`` -to true under the ``acme`` section in ``homeserver.yaml``:: - - acme: - enabled: true - - Registering a user ------------------ diff --git a/UPGRADE.rst b/UPGRADE.rst index f6cdec4734..74d2452749 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,35 +51,10 @@ returned by the Client-Server API: Upgrading to v0.99.0 ==================== -In preparation for Synapse v1.0, you must ensure your federation TLS -certificates are verifiable by signed by a trusted root CA. - -If you do not already have a valid certificate for your domain, the easiest -way to get one is with Synapse's new ACME support, which will use the ACME -protocol to provision a certificate automatically. By default, certificates -will be obtained from the publicly trusted CA Let's Encrypt. - -For a sample configuration, please inspect the new ACME section in the example -generated config by running the ``generate-config`` executable. For example:: - - ~/synapse/env3/bin/generate-config - -You will need to provide Let's Encrypt (or another ACME provider) access to -your Synapse ACME challenge responder on port 80, at the domain of your -homeserver. This requires you to either change the port of the ACME listener -provided by Synapse to a high port and reverse proxy to it, or use a tool -like ``authbind`` to allow Synapse to listen on port 80 without root access. -(Do not run Synapse with root permissions!) - -If you are already using self-signed ceritifcates, you will need to back up -or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in -Synapse's root directory), Synapse's ACME implementation will not overwrite -them. - -You may wish to use alternate methods such as Certbot to obtain a certificate -from Let's Encrypt, depending on your server configuration. Of course, if you -already have a valid certificate for your homeserver's domain, that can be -placed in Synapse's config directory without the need for any ACME setup. +No special steps are required, but please be aware that you will need to +replace any self-signed certificates with those verified by a root CA before +Synapse v1.0 releases in roughly a month's time after v0.99.0. Information on +how to do so can be found at `the ACME docs `_. Upgrading to v0.34.0 ==================== diff --git a/docs/ACME.rst b/docs/ACME.rst new file mode 100644 index 0000000000..2562e85dbc --- /dev/null +++ b/docs/ACME.rst @@ -0,0 +1,98 @@ +ACME +==== + +Synapse v1.0 requires that federation TLS certificates are verifiable by a +trusted root CA. If you do not already have a valid certificate for your domain, the easiest +way to get one is with Synapse's new ACME support, which will use the ACME +protocol to provision a certificate automatically. By default, certificates +will be obtained from the publicly trusted CA Let's Encrypt. + +For a sample configuration, please inspect the new ACME section in the example +generated config by running the ``generate-config`` executable. For example:: + + ~/synapse/env3/bin/generate-config + +You will need to provide Let's Encrypt (or another ACME provider) access to +your Synapse ACME challenge responder on port 80, at the domain of your +homeserver. This requires you to either change the port of the ACME listener +provided by Synapse to a high port and reverse proxy to it, or use a tool +like ``authbind`` to allow Synapse to listen on port 80 without root access. +(Do not run Synapse with root permissions!) Detailed instructions are +available under "ACME setup" below. + +If you are already using self-signed certificates, you will need to back up +or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in +Synapse's root directory), Synapse's ACME implementation will not overwrite +them. + +You may wish to use alternate methods such as Certbot to obtain a certificate +from Let's Encrypt, depending on your server configuration. Of course, if you +already have a valid certificate for your homeserver's domain, that can be +placed in Synapse's config directory without the need for any ACME setup. + +ACME setup +---------- + +Synapse v1.0 will require valid TLS certificates for communication between servers +(port ``8448`` by default) in addition to those that are client-facing (port +``443``). In the case that your `server_name` config variable is the same as +the hostname that the client connects to, then the same certificate can be +used between client and federation ports without issue. Synapse v0.99.0+ +will provision server-to-server certificates automatically for you for +free through `Let's Encrypt +`_ if you tell it to. + +In order for Synapse to complete the ACME challenge to provision a +certificate, it needs access to port 80. Typically listening on port 80 is +only granted to applications running as root. There are thus two solutions to +this problem. + +**Using a reverse proxy** + +A reverse proxy such as Apache or nginx allows a single process (the web +server) to listen on port 80 and proxy traffic to the appropriate program +running on your server. It is the recommended method for setting up ACME as +it allows you to use your existing webserver while also allowing Synapse to +provision certificates as needed. + +For nginx users, add the following line to your existing ``server`` block:: + + location /.well-known/acme-challenge { + proxy_pass http://localhost:8009/; + } + +For Apache, add the following to your existing webserver config:: + + ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge + +Make sure to restart/reload your webserver after making changes. + + +**Authbind** + +``authbind`` allows a program which does not run as root to bind to +low-numbered ports in a controlled way. The setup is simpler, but requires a +webserver not to already be running on port 80. **This includes every time +Synapse renews a certificate**, which may be cumbersome if you usually run a +web server on port 80. Nevertheless, if you're sure port 80 is not being used +for any other purpose then all that is necessary is the following: + +Install ``authbind``. For example, on Debian/Ubuntu:: + + sudo apt-get install authbind + +Allow ``authbind`` to bind port 80:: + + sudo touch /etc/authbind/byport/80 + sudo chmod 777 /etc/authbind/byport/80 + +When Synapse is started, use the following syntax:: + + authbind --deep + +Finally, once Synapse's is able to listen on port 80 for ACME challenge +requests, it must be told to perform ACME provisioning by setting ``enabled`` +to true under the ``acme`` section in ``homeserver.yaml``:: + + acme: + enabled: true -- cgit 1.5.1 From cbdc01cc3b826879b43ad4e8e9c1acacc60cd34b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:38:27 +0000 Subject: Convert ACME docs to md --- README.rst | 2 +- UPGRADE.rst | 2 +- docs/ACME.rst | 98 ----------------------------------------------------------- 3 files changed, 2 insertions(+), 100 deletions(-) delete mode 100644 docs/ACME.rst (limited to 'UPGRADE.rst') diff --git a/README.rst b/README.rst index 47f8ef62db..b7b3b20159 100644 --- a/README.rst +++ b/README.rst @@ -229,7 +229,7 @@ ACME setup ---------- For details on having Synapse manage your federation TLS certificates -automatically, please see ``_. +automatically, please see ``_. Registering a user ------------------ diff --git a/UPGRADE.rst b/UPGRADE.rst index 74d2452749..948867f189 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -54,7 +54,7 @@ Upgrading to v0.99.0 No special steps are required, but please be aware that you will need to replace any self-signed certificates with those verified by a root CA before Synapse v1.0 releases in roughly a month's time after v0.99.0. Information on -how to do so can be found at `the ACME docs `_. +how to do so can be found at `the ACME docs `_. Upgrading to v0.34.0 ==================== diff --git a/docs/ACME.rst b/docs/ACME.rst deleted file mode 100644 index 2562e85dbc..0000000000 --- a/docs/ACME.rst +++ /dev/null @@ -1,98 +0,0 @@ -ACME -==== - -Synapse v1.0 requires that federation TLS certificates are verifiable by a -trusted root CA. If you do not already have a valid certificate for your domain, the easiest -way to get one is with Synapse's new ACME support, which will use the ACME -protocol to provision a certificate automatically. By default, certificates -will be obtained from the publicly trusted CA Let's Encrypt. - -For a sample configuration, please inspect the new ACME section in the example -generated config by running the ``generate-config`` executable. For example:: - - ~/synapse/env3/bin/generate-config - -You will need to provide Let's Encrypt (or another ACME provider) access to -your Synapse ACME challenge responder on port 80, at the domain of your -homeserver. This requires you to either change the port of the ACME listener -provided by Synapse to a high port and reverse proxy to it, or use a tool -like ``authbind`` to allow Synapse to listen on port 80 without root access. -(Do not run Synapse with root permissions!) Detailed instructions are -available under "ACME setup" below. - -If you are already using self-signed certificates, you will need to back up -or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in -Synapse's root directory), Synapse's ACME implementation will not overwrite -them. - -You may wish to use alternate methods such as Certbot to obtain a certificate -from Let's Encrypt, depending on your server configuration. Of course, if you -already have a valid certificate for your homeserver's domain, that can be -placed in Synapse's config directory without the need for any ACME setup. - -ACME setup ----------- - -Synapse v1.0 will require valid TLS certificates for communication between servers -(port ``8448`` by default) in addition to those that are client-facing (port -``443``). In the case that your `server_name` config variable is the same as -the hostname that the client connects to, then the same certificate can be -used between client and federation ports without issue. Synapse v0.99.0+ -will provision server-to-server certificates automatically for you for -free through `Let's Encrypt -`_ if you tell it to. - -In order for Synapse to complete the ACME challenge to provision a -certificate, it needs access to port 80. Typically listening on port 80 is -only granted to applications running as root. There are thus two solutions to -this problem. - -**Using a reverse proxy** - -A reverse proxy such as Apache or nginx allows a single process (the web -server) to listen on port 80 and proxy traffic to the appropriate program -running on your server. It is the recommended method for setting up ACME as -it allows you to use your existing webserver while also allowing Synapse to -provision certificates as needed. - -For nginx users, add the following line to your existing ``server`` block:: - - location /.well-known/acme-challenge { - proxy_pass http://localhost:8009/; - } - -For Apache, add the following to your existing webserver config:: - - ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge - -Make sure to restart/reload your webserver after making changes. - - -**Authbind** - -``authbind`` allows a program which does not run as root to bind to -low-numbered ports in a controlled way. The setup is simpler, but requires a -webserver not to already be running on port 80. **This includes every time -Synapse renews a certificate**, which may be cumbersome if you usually run a -web server on port 80. Nevertheless, if you're sure port 80 is not being used -for any other purpose then all that is necessary is the following: - -Install ``authbind``. For example, on Debian/Ubuntu:: - - sudo apt-get install authbind - -Allow ``authbind`` to bind port 80:: - - sudo touch /etc/authbind/byport/80 - sudo chmod 777 /etc/authbind/byport/80 - -When Synapse is started, use the following syntax:: - - authbind --deep - -Finally, once Synapse's is able to listen on port 80 for ACME challenge -requests, it must be told to perform ACME provisioning by setting ``enabled`` -to true under the ``acme`` section in ``homeserver.yaml``:: - - acme: - enabled: true -- cgit 1.5.1 From e119cec229202b8c6f0429fa1586c1a28f1925e3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 16:45:41 +0000 Subject: Update INSTALL --- UPGRADE.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 948867f189..eee38d5228 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,10 +51,10 @@ returned by the Client-Server API: Upgrading to v0.99.0 ==================== -No special steps are required, but please be aware that you will need to -replace any self-signed certificates with those verified by a root CA before -Synapse v1.0 releases in roughly a month's time after v0.99.0. Information on -how to do so can be found at `the ACME docs `_. +Please be aware that, before Synapse v1.0 is released around March 2019, you +will need to replace any self-signed certificates with those verified by a +root CA. Information on how to do so can be found at `the ACME docs +`_. Upgrading to v0.34.0 ==================== -- cgit 1.5.1 From 6585ef47991478ed1617f78f992b35b63475a2d7 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 5 Feb 2019 17:19:28 +0000 Subject: Neilj/1711faq (#4572) MSC1711 certificates FAQ --- UPGRADE.rst | 2 + changelog.d/4572.misc | 1 + docs/MSC1711_certificates_FAQ.md | 260 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 263 insertions(+) create mode 100644 changelog.d/4572.misc create mode 100644 docs/MSC1711_certificates_FAQ.md (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index c46f70f699..7bd631f14c 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -80,6 +80,8 @@ from Let's Encrypt, depending on your server configuration. Of course, if you already have a valid certificate for your homeserver's domain, that can be placed in Synapse's config directory without the need for ACME. +For more information on configuring TLS certificates see the `FAQ `_ + Upgrading to v0.34.0 ==================== diff --git a/changelog.d/4572.misc b/changelog.d/4572.misc new file mode 100644 index 0000000000..ea5d49b706 --- /dev/null +++ b/changelog.d/4572.misc @@ -0,0 +1 @@ +FAQ to help server admins configure TLS certs in 0.99.0 diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md new file mode 100644 index 0000000000..0dcef57733 --- /dev/null +++ b/docs/MSC1711_certificates_FAQ.md @@ -0,0 +1,260 @@ +# MSC 1711 Certificates FAQ + +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 +as post-r0.1 behaviour, in order to allow for a smooth upgrade across the +federation. + +The most important thing to know is that Synapse 1.0.0 will require a valid TLS +certificate on federation endpoints. Self signed certificates will not be +sufficient. + +Synapse 0.99.0 makes it easy to configure TLS certificates and will +interoperate with both >= 1.0.0 servers as well as existing servers yet to +upgrade. + +**It is critical that all admins upgrade to 0.99.0 and configure a valid TLS +certificate.** Admins will have 1 month to do so, after which 1.0.0 will be +released and those servers without a valid certificate will not longer be able +to federate with >= 1.0.0 servers. + +If you are unable to generate a valid TLS certificate for your server (e.g. +because you run it on behalf of someone who doesn't want to give you a TLS +certificate for their domain, or simply because the matrix domain is hosted on +a different server), then you can now create a /.well-known/matrix/server file +on the matrix domain in order to delegate Matrix hosting to another domain. + Admins who currently use SRV records to delegate a domain **which they do not +control TLS for** will need to switch to using .well-known/matrix/server - though +they should retain their SRV record while the federation upgrades over the +course of the month.  Other SRV records are unaffected. + +Full upgrade notes can be found in +[UPGRADE.rst](https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst). +What follows is a timeline and some frequently asked questions. + +For more details and context on the release of the r0.1 Server/Server API and +imminent Matrix 1.0 release, you can also see our +[main talk from FOSDEM 2019](https://matrix.org/blog/2019/02/04/matrix-at-fosdem-2019/). + +## Contents +* Timeline +* Synapse 0.99.0 has just been released, what do I need to do right now? +* How do I upgrade? +* What will happen if I do not set up a valid federation certificate + immediately? +* What will happen if I do nothing at all? +* When do I need a SRV record or .well-known URI? +* Can I still use an SRV record? +* I have created a .well-known URI. Do I still need an SRV record? +* It used to work just fine, why are you breaking everything? +* Can I manage my own certificates rather than having Synapse renew + certificates itself? +* Do you still recommend against using a reverse-proxy on the federation port? +* Do I still need to give my TLS certificates to Synapse if I am using a + reverse-proxy? +* Do I need the same certificate for the client and federation port? +* How do I tell Synapse to reload my keys/certificates after I replace them? + + +### Timeline + +**5th Feb 2019 - Synapse 0.99.0 is released.** + +All server admins are encouraged to upgrade. + +0.99.0: + +- provides support for ACME to make setting up Let's Encrypt certs easy, as + well as .well-known support. + +- does not enforce that a valid CA cert is present on the federation API, but + rather makes it easy to set one up. + +- provides support for .well-known + +Admins should upgrade and configure a valid CA cert. Homeservers that require a +.well-known entry (see below), should retain their SRV record and use it +alongside their .well-known record. + +**>= 5th March 2019 - Synapse 1.0.0 is released** + +1.0.0 will land no sooner than 1 month after 0.99.0, leaving server admins one +month after 5th February to upgrade to 0.99.0 and deploy their certificates. In +accordance with the the [S2S spec](https://matrix.org/docs/spec/server_server/r0.1.0.html) +1.0.0 will enforce federation checks. This means that any homeserver without a +valid certificate after this point will no longer be able to federate with +1.0.0 servers. + +### Synapse 0.99.0 has just been released, what do I need to do right now? + +Upgrade as soon as you can in preparation for Synapse 1.0.0. + +### How do I upgrade? + +Follow the upgrade notes here [UPGRADE.rst](https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst) + +### What will happen if I do not set up a valid federation certificate immediately? + +Nothing initially, but once 1.0.0 is in the wild it will not be possible to +federate with 1.0.0 servers. + +### What will happen if I do nothing at all? + +If the admin takes no action at all, and remains on a Synapse < 0.99.0 then the +homeserver will be unable to federate with those who have implemented +.well-known. Then, as above, once the month upgrade window has expired the +homeserver will not be able to federate with any Synapse >= 1.0.0 + +### 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 0.99 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 easiest way to do this is with a .well-known/matrix/server URI on the +webroot of the domain to advertise your server. For instance, if you ran +"matrixhosting.com" and you were hosting a Matrix server for example.com, you +would ask example.com to create a file at: + +`https://example.com/.well-known/matrix/server` + +with contents: + +`{"m.server": "example.matrixhosting.com:8448"}` + +...which would tell servers trying to connect to example.com to instead connect +to example.matrixhosting.com on port 8448. You would then configure Synapse +with a server_name of "example.com", but generate a TLS certificate for +example.matrixhosting.com. + +As an alternative, you can still use an SRV DNS record for the delegation, but +this will require you to have a certificate for the matrix domain (example.com +in this example). See "Can I still use an SRV record?". + +### Can I still use an SRV record? + +Firstly, if you didn't need an SRV record before (because your server is +listening on port 8448 of your server_name), you certainly don't need one now: +the defaults are still the same. + +If you previously had an SRV record, you can keep using it provided you are +able to give Synapse a TLS certificate corresponding to your server name. For +example, suppose you had the following SRV record, which directs matrix traffic +for example.com to matrix.example.com:443: + +``` +_matrix._tcp.example.com. IN SRV 10 5 443 matrix.example.com +``` + +In this case, Synapse must be given a certificate for example.com - or be +configured to acquire one from Let's Encrypt. + +If you are unable to give Synapse a certificate for your server_name, you will +also need to use a .well-known URI instead. However, see also "I have created a +.well-known URI. Do I still need 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 +URL 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. + +### It used to work just fine, why are you breaking everything? + +We have always wanted Matrix servers to be as easy to set up as possible, and +so back when we started federation in 2014 we didn't want admins to have to go +through the cumbersome process of buying a valid TLS certificate to run a +server. This was before Let's Encrypt came along and made getting a free and +valid TLS certificate straightforward. So instead, we adopted a system based on +[Perspectives](https://en.wikipedia.org/wiki/Convergence_(SSL)): an approach +where you check a set of "notary servers" (in practice, homeservers) to vouch +for the validity of a certificate rather than having it signed by a CA. As long +as enough different notaries agree on the certificate's validity, then it is +trusted. + +However, in practice this has never worked properly. Most people only use the +default notary server (matrix.org), leading to inadvertent centralisation which +we want to eliminate. Meanwhile, we never implemented the full consensus +algorithm to query the servers participating in a room to determine consensus +on whether a given certificate is valid. This is fiddly to get right +(especially in face of sybil attacks), and we found ourselves questioning +whether it was worth the effort to finish the work and commit to maintaining a +secure certificate validation system as opposed to focusing on core Matrix +development. + +Meanwhile, Let's Encrypt came along in 2016, and put the final nail in the +coffin of the Perspectives project (which was already pretty dead). So, the +Spec Core Team decided that a better approach would be to mandate valid TLS +certificates for federation alongside the rest of the Web. More details can be +found in +[MSC1711](https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#background-the-failure-of-the-perspectives-approach). + +This results in a breaking change, which is disruptive, but absolutely critical +for the security model. However, the existence of Let's Encrypt as a trivial +way to replace the old self-signed certificates with valid CA-signed ones helps +smooth things over massively, especially as Synapse can now automate Let's +Encrypt certificate generation if needed. + +### 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. + +### 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. + +However, there is a bug in Synapse 0.99.0 +[4554]() which prevents +Synapse from starting if you do not give it a TLS certificate. To work around +this, you can give it any TLS certificate at all. This will be fixed soon. + +### Do I need the same certificate for the client and federation port? + +No. There is nothing stopping you doing so, particularly if you are using a +reverse-proxy. However, Synapse will use the same certificate on any ports +where TLS is configured. + +### How do I tell Synapse to reload my keys/certificates after I replace them? + +Synapse will reload the keys and certificates when it receives a SIGHUP - for +example kill -HUP $(cat homeserver.pid). Alternatively, simply restart Synapse, +though this will result in downtime while it restarts. -- cgit 1.5.1 From 61dc53abe9ac6fce9a69a6655262853a66c09b11 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 5 Feb 2019 17:36:05 +0000 Subject: fix some thinkos in UPGRADE.rst --- UPGRADE.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 75aef366bd..3643477250 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -5,20 +5,20 @@ Before upgrading check if any special steps are required to upgrade from the what you currently have installed to current version of synapse. The extra instructions that may be required are listed later in this document. -1. If synapse was installed in a virtualenv then active that virtualenv before - upgrading. If synapse is installed in a virtualenv in ``~/.synapse/`` then +1. If synapse was installed in a virtualenv then activate that virtualenv before + upgrading. If synapse is installed in a virtualenv in ``~/synapse/env`` then run: .. code:: bash - source ~/.synapse/bin/activate + source ~/synapse/env/bin/activate 2. If synapse was installed using pip then upgrade to the latest version by running: .. code:: bash - pip install --upgrade matrix-synapse + pip install --upgrade matrix-synapse[all] # restart synapse synctl restart @@ -31,8 +31,9 @@ instructions that may be required are listed later in this document. # Pull the latest version of the master branch. git pull - # Update the versions of synapse's python dependencies. - python synapse/python_dependencies.py | xargs pip install --upgrade + + # Update synapse and its python dependencies. + pip install --upgrade .[all] # restart synapse ./synctl restart -- cgit 1.5.1