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 ====================