Move ACME docs to docs/ACME.rst and link from UPGRADE.

3 files changed, 102 insertions, 98 deletions

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
-<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 <synapse start command>
-
-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 <docs/ACME.rst>`_.
 
 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
+<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 <synapse start command>
+
+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