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. --- docs/ACME.rst | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/ACME.rst (limited to 'docs') 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 'docs') 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 ffcbd80982ad4164eda38c45d8b367b1748904c4 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:50:18 +0000 Subject: Actually add ACME docs --- docs/ACME.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/ACME.md (limited to 'docs') diff --git a/docs/ACME.md b/docs/ACME.md new file mode 100644 index 0000000000..f1a0c25697 --- /dev/null +++ b/docs/ACME.md @@ -0,0 +1,107 @@ +# 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](https://letsencrypt.org/) 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 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 +``` \ No newline at end of file -- cgit 1.5.1 From 13828f7d5811c6c0de1ccc4d734a68d01a004dec Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 5 Feb 2019 16:46:28 +0000 Subject: Update docs/ACME.md Co-Authored-By: anoadragon453 <1342360+anoadragon453@users.noreply.github.com> --- docs/ACME.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ACME.md b/docs/ACME.md index f1a0c25697..309296cc0b 100644 --- a/docs/ACME.md +++ b/docs/ACME.md @@ -2,7 +2,7 @@ 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 +way to get one is with Synapse's ACME support (new as of Synapse 0.99), 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. @@ -104,4 +104,4 @@ to true under the `acme` section in `homeserver.yaml`: ``` acme: enabled: true -``` \ No newline at end of file +``` -- cgit 1.5.1 From 2ca63df83b49599613b3801be2577a1d869a918b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 16:50:00 +0000 Subject: Update ACME --- docs/ACME.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/ACME.md b/docs/ACME.md index f1a0c25697..341044dac1 100644 --- a/docs/ACME.md +++ b/docs/ACME.md @@ -1,15 +1,23 @@ # 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. +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`). 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. Synapse v0.99.0+ +will provision server-to-server certificates automatically for you for free +through [Let's Encrypt](https://letsencrypt.org/) if you tell it to. + +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. For a sample configuration, please inspect the new ACME section in the example -generated config by running the `generate-config` executable. For example:: +generated config by running the `generate-config` executable. For example: - ~/synapse/env3/bin/generate-config +``` +~/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 @@ -31,13 +39,6 @@ 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](https://letsencrypt.org/) 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 @@ -97,6 +98,8 @@ When Synapse is started, use the following syntax:: authbind --deep ``` +## Config file editing + Finally, once Synapse 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`: -- cgit 1.5.1 From a6345009f92d8ffef4bd0d42196d18eac9b9bf38 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 17:04:34 +0000 Subject: Add TL;DR and final step details to ACME --- docs/ACME.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ACME.md b/docs/ACME.md index 15752ad9c9..8fb2bd66a9 100644 --- a/docs/ACME.md +++ b/docs/ACME.md @@ -39,13 +39,23 @@ placed in Synapse's config directory without the need for any ACME setup. ## ACME setup +The main steps for enabling ACME support in short summary are: + +1. Allow Synapse to listen on port 80 with authbind, or forward it from a reverse-proxy. +1. Set `acme:enabled` to `true` in homeserver.yaml. +1. Move your old certificates (files `example.com.tls.crt` and `example.com.tls.key` out of the way if they currently exist at the paths specified in `homeserver.yaml`. +1. Restart Synapse + +Detailed instructions for each step are provided below. + +### Listening on port 80 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 +#### 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 @@ -70,7 +80,7 @@ ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-cha Make sure to restart/reload your webserver after making changes. -### Authbind +#### 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 @@ -98,9 +108,9 @@ When Synapse is started, use the following syntax:: authbind --deep ``` -## Config file editing +### Config file editing -Finally, once Synapse is able to listen on port 80 for ACME challenge +Once Synapse 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`: @@ -108,3 +118,9 @@ to true under the `acme` section in `homeserver.yaml`: acme: enabled: true ``` + +### Starting synapse + +Ensure that the certificate paths specified in `homeserver.yaml` (`tls_certificate_path` and `tls_private_key_path`) do not currently point to any files. Synapse will not provision certificates if files exist, as it does not want to overwrite existing certificates. + +Finally, start/restart Synapse. \ No newline at end of file -- 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 'docs') 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 39bf0ea2e860948adcd47f0f9cf8ff73b8abf841 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 5 Feb 2019 18:11:26 +0000 Subject: Add notes on SRV and .well-known (#4573) --- docs/MSC1711_certificates_FAQ.md | 158 +++++++++++++++++++++++++++++---------- 1 file changed, 117 insertions(+), 41 deletions(-) (limited to 'docs') diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index 0dcef57733..efe6330647 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -19,19 +19,9 @@ 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. +Full details on how to carry out this configuration change is given +[below](#configuring-certificates-for-compatibility-with-synapse-100). A +timeline and some frequently asked questions are also given below. 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 @@ -39,25 +29,26 @@ imminent Matrix 1.0 release, you can also see our ## 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 +* Configuring certificates for compatibility with Synapse 1.0 +* FAQ + * 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.** @@ -82,10 +73,96 @@ alongside their .well-known record. 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 +1.0.0 will enforce certificate validity. This means that any homeserver without a valid certificate after this point will no longer be able to federate with 1.0.0 servers. + +## Configuring certificates for compatibility with Synapse 1.0.0 + +### If you do not currently have an SRV record + +In this case, your `server_name` points to the host where your Synapse is +running. There is no need to create a `.well-known` URI or an SRV record, but +you will need to give Synapse a valid, signed, certificate. + +The easiest way to do that is with Synapse's built-in ACME (Let's Encrypt) +support. Full details are in [ACME.md](./ACME.md) but, in a nutshell: + + 1. Allow Synapse to listen on port 80 with `authbind`, or forward it from a + reverse proxy. + 2. Enable acme support in `homeserver.yaml`. + 3. Move your old certificates out of the way. + 4. Restart Synapse. + +### If you do have an SRV record currently + +If you are using an SRV record, your matrix domain (`server_name`) may not +point to the same host that your Synapse is running on (the 'target +domain'). (If it does, you can follow the recommendation above; otherwise, read +on.) + +Let's assume that your `server_name` is `example.com`, and your Synapse is +hosted at a target domain of `customer.example.net`. Currently you should have +an SRV record which looks like: + +``` +_matrix._tcp.example.com. IN SRV 10 5 443 customer.example.net. +``` + +In this situation, you have two choices for how to proceed: + +#### Option 1: give Synapse a certificate for your matrix domain + +Synapse 1.0 will expect your server to present a TLS certificate for your +`server_name` (`example.com` in the above example). You can achieve this by +doing one of the following: + + * Acquire a certificate for the `server_name` yourself (for example, using + `certbot`), and give it and the key to Synapse via `tls_certificate_path` + and `tls_private_key_path`, or: + + * Use Synapse's [ACME support](./ACME.md), and forward port 80 on the + `server_name` domain to your Synapse instance, or: + + * Set up a reverse-proxy on port 8448 on the `server_name` domain, which + forwards to Synapse. Once it is set up, you can remove the SRV record. + +#### Option 2: add a .well-known file to delegate your matrix traffic + +This will allow you to keep Synapse on a separate domain, without having to +give it a certificate for the matrix domain. + +You can do this with a `.well-known` file as follows: + + 1. Keep the SRV record in place - it is needed for backwards compatibility + with Synapse 0.34 and earlier. + + 2. Give synapse a certificate corresponding to the target domain + (`customer.example.net` in the above example). Currently Synapse's ACME + support [does not support + this](https://github.com/matrix-org/synapse/issues/4552), so you will have + to acquire a certificate yourself and give it to Synapse via + `tls_certificate_path` and `tls_private_key_path`. + + 3. Restart Synapse to ensure the new certificate is loaded. + + 4. Arrange for a `.well-known` file at + `https:///.well-known/matrix/server` with contents: + + ```json + {"m.server": ":"} + ``` + + In the above example, `https://example.com/.well-known/matrix/server` + should have the contents: + + ```json + {"m.server": "customer.example.net:443"} + ``` + +## FAQ + ### 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. @@ -126,14 +203,13 @@ 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` +"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: -with contents: - -`{"m.server": "example.matrixhosting.com:8448"}` +```json +{"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 @@ -231,7 +307,7 @@ 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? +### 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. -- cgit 1.5.1 From b05dd4ac06e88797477ef1991d1b2e44583afb9a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 5 Feb 2019 18:59:57 +0000 Subject: faq cleanups --- UPGRADE.rst | 2 +- docs/MSC1711_certificates_FAQ.md | 54 ++++++++++++++-------------------------- 2 files changed, 19 insertions(+), 37 deletions(-) (limited to 'docs') diff --git a/UPGRADE.rst b/UPGRADE.rst index 3643477250..d869b7111b 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -57,7 +57,7 @@ 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 `_. -For more information on configuring TLS certificates see the `FAQ `_ +For more information on configuring TLS certificates see the `FAQ `_. Upgrading to v0.34.0 ==================== diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index efe6330647..eee37d9457 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -1,4 +1,4 @@ -# MSC 1711 Certificates FAQ +# MSC1711 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 @@ -165,11 +165,8 @@ You can do this with a `.well-known` file as follows: ### 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) +Upgrade as soon as you can in preparation for Synapse 1.0.0, and update your +TLS certificates as [above](#configuring-certificates-for-compatibility-with-synapse-100). ### What will happen if I do not set up a valid federation certificate immediately? @@ -186,39 +183,24 @@ 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 +`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 +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. +`.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. +`.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 +**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: - -```json -{"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?". +In this case, you should see ["If you do have an SRV record +currently"](#if-you-do-have-an-srv-record-currently) above. ### Can I still use an SRV record? @@ -244,13 +226,13 @@ also need to use a .well-known URI instead. However, see also "I have created a ### 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 +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 +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 @@ -332,5 +314,5 @@ 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. +example `kill -HUP $(cat homeserver.pid)`. Alternatively, simply restart +Synapse, though this will result in downtime while it restarts. -- cgit 1.5.1 From 9b7aa543d9fc90d3a754ab129a619cfff6a71355 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 7 Feb 2019 18:46:02 +0000 Subject: clarify option 1 --- docs/MSC1711_certificates_FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index eee37d9457..414af96ef3 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -112,7 +112,7 @@ _matrix._tcp.example.com. IN SRV 10 5 443 customer.example.net. In this situation, you have two choices for how to proceed: -#### Option 1: give Synapse a certificate for your matrix domain +#### Option 1: give Synapse (or a reverse-proxy) a certificate for your matrix domain Synapse 1.0 will expect your server to present a TLS certificate for your `server_name` (`example.com` in the above example). You can achieve this by -- cgit 1.5.1 From c17b128b837f58cb59ba75803e32c8a720cf8501 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 7 Feb 2019 19:18:08 +0000 Subject: Update ACME docs to include port instructions (#4578) --- changelog.d/4578.misc | 1 + docs/ACME.md | 26 +++++++++++++++----------- 2 files changed, 16 insertions(+), 11 deletions(-) create mode 100644 changelog.d/4578.misc (limited to 'docs') diff --git a/changelog.d/4578.misc b/changelog.d/4578.misc new file mode 100644 index 0000000000..d1c006bb6b --- /dev/null +++ b/changelog.d/4578.misc @@ -0,0 +1 @@ +Add port configuration information to ACME instructions. \ No newline at end of file diff --git a/docs/ACME.md b/docs/ACME.md index 8fb2bd66a9..e555c7c939 100644 --- a/docs/ACME.md +++ b/docs/ACME.md @@ -41,10 +41,10 @@ placed in Synapse's config directory without the need for any ACME setup. The main steps for enabling ACME support in short summary are: -1. Allow Synapse to listen on port 80 with authbind, or forward it from a reverse-proxy. -1. Set `acme:enabled` to `true` in homeserver.yaml. +1. Allow Synapse to listen for incoming ACME challenges. +1. Enable ACME support in `homeserver.yaml`. 1. Move your old certificates (files `example.com.tls.crt` and `example.com.tls.key` out of the way if they currently exist at the paths specified in `homeserver.yaml`. -1. Restart Synapse +1. Restart Synapse. Detailed instructions for each step are provided below. @@ -71,7 +71,7 @@ location /.well-known/acme-challenge { } ``` -For Apache, add the following to your existing webserver config:: +For Apache, add the following to your existing webserver config: ``` ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge @@ -79,6 +79,14 @@ ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-cha Make sure to restart/reload your webserver after making changes. +Now make the relevant changes in `homeserver.yaml` to enable ACME support: + +``` +acme: + enabled: true + port: 8009 +``` + #### Authbind @@ -102,24 +110,20 @@ sudo touch /etc/authbind/byport/80 sudo chmod 777 /etc/authbind/byport/80 ``` -When Synapse is started, use the following syntax:: +When Synapse is started, use the following syntax: ``` authbind --deep ``` -### Config file editing - -Once Synapse 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`: +Make the relevant changes in `homeserver.yaml` to enable ACME support: ``` acme: enabled: true ``` -### Starting synapse +### (Re)starting synapse Ensure that the certificate paths specified in `homeserver.yaml` (`tls_certificate_path` and `tls_private_key_path`) do not currently point to any files. Synapse will not provision certificates if files exist, as it does not want to overwrite existing certificates. -- cgit 1.5.1 From acb2ac5863d34e2d01fa53598aecda274dc2fb26 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 7 Feb 2019 19:30:32 +0000 Subject: Update MSC1711 FAQ to be explicit about well-known (#4584) A surprising number of people are using the well-known method, and are simply copying the example configuration. This is problematic as the example includes an explicit port, which causes inbound federation requests to have the HTTP Host header include the port, upsetting some reverse proxies. Given that, we update the well-known example to be more explicit about the various ways you can set it up, and the consequence of using an explict port. --- changelog.d/4584.misc | 1 + docs/MSC1711_certificates_FAQ.md | 40 +++++++++++++++++++++++++++------------- 2 files changed, 28 insertions(+), 13 deletions(-) create mode 100644 changelog.d/4584.misc (limited to 'docs') diff --git a/changelog.d/4584.misc b/changelog.d/4584.misc new file mode 100644 index 0000000000..4dec2e2b5c --- /dev/null +++ b/changelog.d/4584.misc @@ -0,0 +1 @@ +Update MSC1711 FAQ to calrify .well-known usage diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index 414af96ef3..0a781d00e3 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -107,12 +107,12 @@ hosted at a target domain of `customer.example.net`. Currently you should have an SRV record which looks like: ``` -_matrix._tcp.example.com. IN SRV 10 5 443 customer.example.net. +_matrix._tcp.example.com. IN SRV 10 5 8000 customer.example.net. ``` -In this situation, you have two choices for how to proceed: +In this situation, you have three choices for how to proceed: -#### Option 1: give Synapse (or a reverse-proxy) a certificate for your matrix domain +#### Option 1: give Synapse a certificate for your matrix domain Synapse 1.0 will expect your server to present a TLS certificate for your `server_name` (`example.com` in the above example). You can achieve this by @@ -123,12 +123,16 @@ doing one of the following: and `tls_private_key_path`, or: * Use Synapse's [ACME support](./ACME.md), and forward port 80 on the - `server_name` domain to your Synapse instance, or: + `server_name` domain to your Synapse instance. - * Set up a reverse-proxy on port 8448 on the `server_name` domain, which - forwards to Synapse. Once it is set up, you can remove the SRV record. +### Option 2: run Synapse behind a reverse proxy -#### Option 2: add a .well-known file to delegate your matrix traffic +If you have an existing reverse proxy set up with correct TLS certificates for +your domain, you can simply route all traffic through the reverse proxy by +updating the SRV record appropriately (or removing it, if the proxy listens on +8448). + +#### Option 3: add a .well-known file to delegate your matrix traffic This will allow you to keep Synapse on a separate domain, without having to give it a certificate for the matrix domain. @@ -151,15 +155,25 @@ You can do this with a `.well-known` file as follows: `https:///.well-known/matrix/server` with contents: ```json - {"m.server": ":"} + {"m.server": ""} ``` - In the above example, `https://example.com/.well-known/matrix/server` - should have the contents: + where the target server name is resolved as usual (i.e. SRV lookup, falling + back to talking to port 8448). + + In the above example, where synapse is listening on port 8000, + `https://example.com/.well-known/matrix/server` should have `m.server` set to one of: + + 1. `customer.example.net` ─ with a SRV record on + `_matrix._tcp.customer.example.com` pointing to port 8000, or: + + 2. `customer.example.net` ─ updating synapse to listen on the default port + 8448, or: + + 3. `customer.example.net:8000` ─ ensuring that if there is a reverse proxy + on `customer.example.net:8000` it correctly handles HTTP requests with + Host header set to `customer.example.net:8000`. - ```json - {"m.server": "customer.example.net:443"} - ``` ## FAQ -- cgit 1.5.1 From c475275926aeee906b76621444468280d5bf569b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 11 Feb 2019 11:44:28 +0000 Subject: Clarifications for reverse proxy docs (#4607) Factor out the reverse proxy info to a separate file, add some more info on reverse-proxying the federation port. --- INSTALL.md | 5 ++- README.rst | 52 ++-------------------- changelog.d/4607.misc | 1 + docs/MSC1711_certificates_FAQ.md | 22 ++++++---- docs/reverse_proxy.rst | 94 ++++++++++++++++++++++++++++++++++++++++ docs/workers.rst | 5 +-- 6 files changed, 117 insertions(+), 62 deletions(-) create mode 100644 changelog.d/4607.misc create mode 100644 docs/reverse_proxy.rst (limited to 'docs') diff --git a/INSTALL.md b/INSTALL.md index cbe4bda120..e496a13b21 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -359,8 +359,9 @@ Synapse v1.0. Instructions for having Synapse automatically provision and renew If you would like to use your own certificates, you can do so by changing `tls_certificate_path` and `tls_private_key_path` in `homeserver.yaml`; -alternatively, you can use a reverse-proxy. Apart from port 8448 using TLS, -both ports are the same in the default configuration. +alternatively, you can use a reverse proxy. See +[docs/reverse_proxy.rst](docs/reverse_proxy.rst) for information on configuring +a reverse proxy. ## Registering a user diff --git a/README.rst b/README.rst index e666b3b427..bc7cb5f784 100644 --- a/README.rst +++ b/README.rst @@ -263,6 +263,8 @@ So, things to check are: (it should be ``_matrix._tcp.``), and that the port and hostname it specifies are reachable from outside your network. +.. TODO: add a note about forgetting ``nocanon`` on a reverse-proxy config + Running a Demo Federation of Synapses ------------------------------------- @@ -290,7 +292,6 @@ The advantages of Postgres include: For information on how to install and use PostgreSQL, please see `docs/postgres.rst `_. - .. _reverse-proxy: Using a reverse proxy with Synapse @@ -304,54 +305,7 @@ It is recommended to put a reverse proxy such as 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. -The most important thing to know here is that Matrix clients and other Matrix -servers do not necessarily need to connect to your server via the same -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'. - -All Matrix endpoints begin with ``/_matrix``, so an example nginx -configuration for forwarding client connections to Synapse might look like:: - - server { - listen 443 ssl; - listen [::]:443 ssl; - server_name matrix.example.com; - - location /_matrix { - proxy_pass http://localhost:8008; - proxy_set_header X-Forwarded-For $remote_addr; - } - } - -an example Caddy configuration might look like:: - - matrix.example.com { - proxy /_matrix http://localhost:8008 { - transparent - } - } - -and an example Apache configuration might look like:: - - - SSLEngine on - ServerName matrix.example.com; - - - ProxyPass http://127.0.0.1:8008/_matrix nocanon - ProxyPassReverse http://127.0.0.1:8008/_matrix - - - -You will also want to set ``bind_addresses: ['127.0.0.1']`` and ``x_forwarded: true`` -for port 8008 in ``homeserver.yaml`` to ensure that client IP addresses are -recorded correctly. - -Having done so, you can then use ``https://matrix.example.com`` (instead of -``https://matrix.example.com:8448``) as the "Custom server" when `Connecting to -Synapse from a client`_. - +For information on configuring one, see ``_. Identity Servers ================ diff --git a/changelog.d/4607.misc b/changelog.d/4607.misc new file mode 100644 index 0000000000..160a824378 --- /dev/null +++ b/changelog.d/4607.misc @@ -0,0 +1 @@ +Clarifications for reverse proxy docs diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index 0a781d00e3..2c52b0d517 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -42,9 +42,9 @@ imminent Matrix 1.0 release, you can also see our * 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 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? + 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? @@ -132,6 +132,9 @@ your domain, you can simply route all traffic through the reverse proxy by updating the SRV record appropriately (or removing it, if the proxy listens on 8448). +See [reverse_proxy.rst](reverse_proxy.rst) for information on setting up a +reverse proxy. + #### Option 3: add a .well-known file to delegate your matrix traffic This will allow you to keep Synapse on a separate domain, without having to @@ -297,17 +300,20 @@ 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? +### 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 +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 +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 @@ -321,9 +327,9 @@ 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. +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. ### How do I tell Synapse to reload my keys/certificates after I replace them? diff --git a/docs/reverse_proxy.rst b/docs/reverse_proxy.rst new file mode 100644 index 0000000000..d8aaac8a08 --- /dev/null +++ b/docs/reverse_proxy.rst @@ -0,0 +1,94 @@ +Using a reverse proxy with Synapse +================================== + +It is recommended to put a reverse proxy such as +`nginx `_, +`Apache `_, +`Caddy `_ or +`HAProxy `_ 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. + +**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 specifify ``nocanon``. + +When setting up a reverse proxy, 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 `Setting up federation +<../README.rst#setting-up-federation>`_ for more details of the algorithm used for +federation connections. + +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``. Here are some example configurations: + +* nginx:: + + server { + listen 443 ssl; + listen [::]:443 ssl; + server_name matrix.example.com; + + location /_matrix { + proxy_pass http://localhost:8008; + proxy_set_header X-Forwarded-For $remote_addr; + } + } + + server { + listen 8448 ssl default_server; + listen [::]:8448 ssl default_server; + server_name example.com; + + location / { + proxy_pass http://localhost:8008; + proxy_set_header X-Forwarded-For $remote_addr; + } + } + +* Caddy:: + + matrix.example.com { + proxy /_matrix http://localhost:8008 { + transparent + } + } + + example.com:8448 { + proxy / http://localhost:8008 { + transparent + } + } + +* Apache (note the ``nocanon`` options here!):: + + + SSLEngine on + ServerName matrix.example.com; + + + ProxyPass http://127.0.0.1:8008/_matrix nocanon + ProxyPassReverse http://127.0.0.1:8008/_matrix + + + + + SSLEngine on + ServerName example.com; + + + ProxyPass http://127.0.0.1:8008/_matrix nocanon + ProxyPassReverse http://127.0.0.1:8008/_matrix + + + +You will also want to set ``bind_addresses: ['127.0.0.1']`` and ``x_forwarded: true`` +for port 8008 in ``homeserver.yaml`` to ensure that client IP addresses are +recorded correctly. + +Having done so, you can then use ``https://matrix.example.com`` (instead of +``https://matrix.example.com:8448``) as the "Custom server" when connecting to +Synapse from a client. diff --git a/docs/workers.rst b/docs/workers.rst index 101e950020..dd3a84ba0d 100644 --- a/docs/workers.rst +++ b/docs/workers.rst @@ -26,9 +26,8 @@ Configuration To make effective use of the workers, you will need to configure an HTTP reverse-proxy such as nginx or haproxy, which will direct incoming requests to the correct worker, or to the main synapse instance. Note that this includes -requests made to the federation port. The caveats regarding running a -reverse-proxy on the federation port still apply (see -https://github.com/matrix-org/synapse/blob/master/README.rst#reverse-proxying-the-federation-port). +requests made to the federation port. See ``_ for +information on setting up a reverse proxy. To enable workers, you need to add two replication listeners to the master synapse, e.g.:: -- cgit 1.5.1