Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Neilj/1.0 upgrade notes #5371

Merged
merged 23 commits into from
Jun 6, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
* [Prebuilt packages](#prebuilt-packages)
* [Setting up Synapse](#setting-up-synapse)
* [TLS certificates](#tls-certificates)
* [Email](#email)
* [Registering a user](#registering-a-user)
* [Setting up a TURN server](#setting-up-a-turn-server)
* [URL previews](#url-previews)
Expand Down Expand Up @@ -394,9 +395,31 @@ To configure Synapse to expose an HTTPS port, you will need to edit
instance, if using certbot, use `fullchain.pem` as your certificate, not
`cert.pem`).

For those of you upgrading your TLS certificate in readiness for Synapse 1.0,
For those of you upgrading your TLS certificate for Synapse 1.0 compliance,
please take a look at [our guide](docs/MSC1711_certificates_FAQ.md#configuring-certificates-for-compatibility-with-synapse-100).

## Email

It is desirable for Synapse to have the capability to send email. For example,
this is required to support the 'password reset' feature.

To configure an SMTP server for Synapse, modify the configuration section
headed ``email``, and be sure to have at least the ``smtp_host``, ``smtp_port``
and ``notif_from`` fields filled out. You may also need to set ``smtp_user``,
``smtp_pass``, and ``require_transport_security``..

If Synapse is not configured with an SMTP server, password reset via email will
be disabled by default.

Alternatively it is possible delegate the sending of email to the server's
identity server. Doing so is convenient but not recommended, since a malicious
or compromised identity server could theoretically hijack a given user's
account by redirecting mail.

If you are absolutely certain that you wish to use the server's identity server
for password resets, set ``trust_identity_server_for_password_resets`` to
``true`` under the ``email:`` configuration section.

## Registering a user

You will need at least one user on your server in order to use a Matrix
Expand Down
49 changes: 49 additions & 0 deletions UPGRADE.rst
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,55 @@ returned by the Client-Server API:
# configured on port 443.
curl -kv https://<host.name>/_matrix/client/versions 2>&1 | grep "Server:"

Upgrading to v1.0
=================

Validation of TLS certificates
------------------------------

Synapse v1.0 is the first release to enforce
validation of TLS certificates for the federation API. It is therefore
essential that your certificates are correctly configured. See the `FAQ
<docs/MSC1711_certificates_FAQ.md>`_ for more information.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm really not happy linking to this while it says things like "admins must upgrade to 0.99".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

otoh that's a thing we can fix between RC and release, so <shrug>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay agreed - I'll ship as is and make a separate non-blocking PR to tear the FAQ apart.


Note, v1.0 installations will also no longer be able to federate with servers
that have not correctly configured their certificates.

In rare cases, it may be desirable to disable certificate checking: for
example, it might be essential to be able to federate with a given legacy
server in a closed federation. This can be done in one of two ways:-

* Configure the global switch ``federation_verify_certificates`` to ``false``.
* Configure a whitelist of server domains to trust via ``federation_certificate_verification_whitelist``.

See the `sample configuration file <docs/sample_config.yaml>`_
for more details on these settings.

Email
-----
When a user requests a password reset, Synapse will send an email to the
user to confirm the request.

Previous versions of Synapse delegated the job of sending this email to an
identity server. If the identity server was somehow malicious or became
compromised, it would be theoretically possible to hijack an account through
this means.

Therefore, by default, Synapse v1.0 will send the confirmation email itself. If
Synapse is not configured with an SMTP server, password reset via email will be
disabled.

To configure an SMTP server for Synapse, modify the configuration section
headed ``email``, and be sure to have at least the ``smtp_host``, ``smtp_port``
and ``notif_from`` fields filled out. You may also need to set ``smtp_user``,
``smtp_pass``, and ``require_transport_security``.

If you are absolutely certain that you wish to continue using an identity
server for password resets, set ``trust_identity_server_for_password_resets`` to ``true``.

See the `sample configuration file <docs/sample_config.yaml>`_
for more details on these settings.

Upgrading to v0.99.0
====================

Expand Down
1 change: 1 addition & 0 deletions changelog.d/5371.feature
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update upgrade and installation guides ahead of 1.0.
12 changes: 5 additions & 7 deletions docs/MSC1711_certificates_FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,16 +68,14 @@ Admins should upgrade and configure a valid CA cert. Homeservers that require a
.well-known entry (see below), should retain their SRV record and use it
alongside their .well-known record.

**>= 5th March 2019 - Synapse 1.0.0 is released**
**10th June 2019 - Synapse 1.0.0 is released**

1.0.0 will land no sooner than 1 month after 0.99.0, leaving server admins one
month after 5th February to upgrade to 0.99.0 and deploy their certificates. In
1.0.0 is scheduled for release on 10th June. In
accordance with the the [S2S spec](https://matrix.org/docs/spec/server_server/r0.1.0.html)
1.0.0 will enforce certificate validity. This means that any homeserver without a
valid certificate after this point will no longer be able to federate with
1.0.0 servers.


## Configuring certificates for compatibility with Synapse 1.0.0

### If you do not currently have an SRV record
Expand Down Expand Up @@ -146,9 +144,9 @@ You can do this with a `.well-known` file as follows:
with Synapse 0.34 and earlier.

2. Give Synapse a certificate corresponding to the target domain
(`customer.example.net` in the above example). You can either use Synapse's
built-in [ACME support](./ACME.md) for this (via the `domain` parameter in
the `acme` section), or acquire a certificate yourself and give it to
(`customer.example.net` in the above example). You can either use Synapse's
built-in [ACME support](./ACME.md) for this (via the `domain` parameter in
the `acme` section), or acquire a certificate yourself and give it to
Synapse via `tls_certificate_path` and `tls_private_key_path`.

3. Restart Synapse to ensure the new certificate is loaded.
Expand Down