From fbaee26c68a0db562994c50b4ac869ea8af3320f Mon Sep 17 00:00:00 2001 From: Amber Brown Date: Wed, 30 Jan 2019 16:22:37 +0000 Subject: [PATCH] ACME Upgrade Docs (#4528) --- UPGRADE.rst | 32 ++++++++++++++++++++++++++++++++ changelog.d/4528.doc | 1 + 2 files changed, 33 insertions(+) create mode 100644 changelog.d/4528.doc diff --git a/UPGRADE.rst b/UPGRADE.rst index 47a8cb9c8..c46f70f69 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -48,6 +48,38 @@ returned by the Client-Server API: # configured on port 443. curl -kv https:///_matrix/client/versions 2>&1 | grep "Server:" +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. + +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. + +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 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. + +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. + Upgrading to v0.34.0 ==================== diff --git a/changelog.d/4528.doc b/changelog.d/4528.doc new file mode 100644 index 000000000..432ef55aa --- /dev/null +++ b/changelog.d/4528.doc @@ -0,0 +1 @@ +Add documentation on enabling ACME support when upgrading to v0.99.