mirror of
https://github.com/element-hq/synapse.git
synced 2024-12-14 11:57:44 +00:00
Move ACME docs to docs/ACME.rst and link from UPGRADE.
This commit is contained in:
Andrew Morgan
parent
cd6fee3169
commit
08b26afeee
3 changed files with 102 additions and 98 deletions
69
README.rst
69
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
|
||||
------------------
|
||||
|
||||
|
|
|
|||
33
UPGRADE.rst
33
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
|
||||
====================
|
||||
|
|
|
|||
98
docs/ACME.rst
Normal file
98
docs/ACME.rst
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue