From cd6fee3169659b13bfdb0f4b4d2a6132fd6b542c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 14:29:09 +0000 Subject: [PATCH 01/12] Don't imply self-signed certs are required --- UPGRADE.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) 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 ==================== From 08b26afeee7b7db8c9d511cb63244927cf48ba9d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:29:42 +0000 Subject: [PATCH 02/12] 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 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 From 9793bf366e85a39507b43bbbf7bdcb387ff5bf83 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:34:52 +0000 Subject: [PATCH 03/12] Add link to ACME docs from README --- README.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.rst b/README.rst index 829de0864c..47f8ef62db 100644 --- a/README.rst +++ b/README.rst @@ -225,6 +225,12 @@ 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 +---------- + +For details on having Synapse manage your federation TLS certificates +automatically, please see ``_. + Registering a user ------------------ From cbdc01cc3b826879b43ad4e8e9c1acacc60cd34b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:38:27 +0000 Subject: [PATCH 04/12] 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 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 From d75e15edce64ee48a80f5f7f253464be1ec6866d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:45:00 +0000 Subject: [PATCH 05/12] Re-add link to ACME docs from README --- README.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.rst b/README.rst index b8c1909101..8db7bf94de 100644 --- a/README.rst +++ b/README.rst @@ -134,6 +134,12 @@ create the account. Your name will take the form of:: As when logging in, you will need to specify a "Custom server". Specify your desired ``localpart`` in the 'User name' box. +ACME setup +---------- + +For details on having Synapse manage your federation TLS certificates +automatically, please see ``_. + Security Note ============= From 0af50020fd9bb591fde82876a6b543d50683bae0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:49:34 +0000 Subject: [PATCH 06/12] Move ACME docs from INSTALL.md to ACME.md --- INSTALL.md | 79 +----------------------------------------------------- 1 file changed, 1 insertion(+), 78 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index fd37c2d9b9..cbe4bda120 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -355,90 +355,13 @@ configured without TLS; it should be behind a reverse proxy for TLS/SSL termination on port 443 which in turn should be used for clients. Port 8448 is configured to use TLS for Federation with a self-signed or verified certificate, but please be aware that a valid certificate will be required in -Synapse v1.0. +Synapse v1.0. Instructions for having Synapse automatically provision and renew federation certificates through ACME can be found at [ACME.md](docs/ACME.md). 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. -### 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 -``` - ## Registering a user You will need at least one user on your server in order to use a Matrix From ffcbd80982ad4164eda38c45d8b367b1748904c4 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:50:18 +0000 Subject: [PATCH 07/12] Actually add ACME docs --- docs/ACME.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/ACME.md 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 From ed8b3289ff1d82f7fa512000ac085e8f395f44d3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 16:44:31 +0000 Subject: [PATCH 08/12] Update README --- README.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 8db7bf94de..e666b3b427 100644 --- a/README.rst +++ b/README.rst @@ -84,13 +84,6 @@ Synapse Installation For details on how to install synapse, see ``_. -To actually run your new homeserver, pick a working directory for Synapse to -run (e.g. ``~/synapse``), and:: - - cd ~/synapse - source env/bin/activate - synctl start - Connecting to Synapse from a client =================================== @@ -135,7 +128,7 @@ As when logging in, you will need to specify a "Custom server". Specify your desired ``localpart`` in the 'User name' box. ACME setup ----------- +========== For details on having Synapse manage your federation TLS certificates automatically, please see ``_. From e119cec229202b8c6f0429fa1586c1a28f1925e3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 16:45:41 +0000 Subject: [PATCH 09/12] Update INSTALL --- UPGRADE.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 ==================== 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: [PATCH 10/12] 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(-) 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 +``` From 2ca63df83b49599613b3801be2577a1d869a918b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 16:50:00 +0000 Subject: [PATCH 11/12] Update ACME --- docs/ACME.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) 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`: From a6345009f92d8ffef4bd0d42196d18eac9b9bf38 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 17:04:34 +0000 Subject: [PATCH 12/12] Add TL;DR and final step details to ACME --- docs/ACME.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) 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