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/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 -- 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/ACME.md') 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/ACME.md') 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/ACME.md') 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 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/ACME.md') 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