@@ -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) | |||
@@ -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). | |||
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 | |||
@@ -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. | |||
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. | |||
----- | |||
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 | |||
==================== | |||
@@ -0,0 +1 @@ | |||
Update upgrade and installation guides ahead of 1.0. |
@@ -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 | |||
@@ -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. | |||