tileradotorg/synapse
1
0
Fork 0
forked from MirrorHub/synapse
Code Pull requests Activity

Add notes on SRV and .well-known (#4573)

Browse source
This commit is contained in:
Richard van der Hoff 2019-02-05 18:11:26 +00:00 committed by GitHub
parent 61dc53abe9
commit 39bf0ea2e8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 116 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
docs/MSC1711_certificates_FAQ.md
View file

@ -19,19 +19,9 @@ certificate.** Admins will have 1 month to do so, after which 1.0.0 will be
released and those servers without a valid certificate will not longer be able released and those servers without a valid certificate will not longer be able
to federate with >= 1.0.0 servers. to federate with >= 1.0.0 servers.
If you are unable to generate a valid TLS certificate for your server (e.g. Full details on how to carry out this configuration change is given
because you run it on behalf of someone who doesn't want to give you a TLS [below](#configuring-certificates-for-compatibility-with-synapse-100). A
certificate for their domain, or simply because the matrix domain is hosted on timeline and some frequently asked questions are also given below.
a different server), then you can now create a /.well-known/matrix/server file
on the matrix domain in order to delegate Matrix hosting to another domain.
 Admins who currently use SRV records to delegate a domain **which they do not
control TLS for** will need to switch to using .well-known/matrix/server - though
they should retain their SRV record while the federation upgrades over the
course of the month.  Other SRV records are unaffected.
Full upgrade notes can be found in
[UPGRADE.rst](https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst).
What follows is a timeline and some frequently asked questions.
For more details and context on the release of the r0.1 Server/Server API and For more details and context on the release of the r0.1 Server/Server API and
imminent Matrix 1.0 release, you can also see our imminent Matrix 1.0 release, you can also see our
@ -39,25 +29,26 @@ imminent Matrix 1.0 release, you can also see our
## Contents ## Contents
* Timeline * Timeline
* Synapse 0.99.0 has just been released, what do I need to do right now? * Configuring certificates for compatibility with Synapse 1.0
* How do I upgrade? * FAQ
* What will happen if I do not set up a valid federation certificate * Synapse 0.99.0 has just been released, what do I need to do right now?
immediately? * How do I upgrade?
* What will happen if I do nothing at all? * What will happen if I do not set up a valid federation certificate
* When do I need a SRV record or .well-known URI? immediately?
* Can I still use an SRV record? * What will happen if I do nothing at all?
* I have created a .well-known URI. Do I still need an SRV record? * When do I need a SRV record or .well-known URI?
* It used to work just fine, why are you breaking everything? * Can I still use an SRV record?
* Can I manage my own certificates rather than having Synapse renew * I have created a .well-known URI. Do I still need an SRV record?
certificates itself? * It used to work just fine, why are you breaking everything?
* Do you still recommend against using a reverse-proxy on the federation port? * Can I manage my own certificates rather than having Synapse renew
* Do I still need to give my TLS certificates to Synapse if I am using a certificates itself?
reverse-proxy? * Do you still recommend against using a reverse-proxy on the federation port?
* Do I need the same certificate for the client and federation port? * Do I still need to give my TLS certificates to Synapse if I am using a
* How do I tell Synapse to reload my keys/certificates after I replace them? reverse-proxy?
* Do I need the same certificate for the client and federation port?
* How do I tell Synapse to reload my keys/certificates after I replace them?
## Timeline
### Timeline
**5th Feb 2019 - Synapse 0.99.0 is released.** **5th Feb 2019 - Synapse 0.99.0 is released.**
@ -82,10 +73,96 @@ alongside their .well-known record.
1.0.0 will land no sooner than 1 month after 0.99.0, leaving server admins one 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 month after 5th February to upgrade to 0.99.0 and deploy their certificates. In
accordance with the the [S2S spec](https://matrix.org/docs/spec/server_server/r0.1.0.html) accordance with the the [S2S spec](https://matrix.org/docs/spec/server_server/r0.1.0.html)
1.0.0 will enforce federation checks. This means that any homeserver without a 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 valid certificate after this point will no longer be able to federate with
1.0.0 servers. 1.0.0 servers.
## Configuring certificates for compatibility with Synapse 1.0.0
### If you do not currently have an SRV record
In this case, your `server_name` points to the host where your Synapse is
running. There is no need to create a `.well-known` URI or an SRV record, but
you will need to give Synapse a valid, signed, certificate.
The easiest way to do that is with Synapse's built-in ACME (Let's Encrypt)
support. Full details are in [ACME.md](./ACME.md) but, in a nutshell:
1. Allow Synapse to listen on port 80 with `authbind`, or forward it from a
reverse proxy.
2. Enable acme support in `homeserver.yaml`.
3. Move your old certificates out of the way.
4. Restart Synapse.
### If you do have an SRV record currently
If you are using an SRV record, your matrix domain (`server_name`) may not
point to the same host that your Synapse is running on (the 'target
domain'). (If it does, you can follow the recommendation above; otherwise, read
on.)
Let's assume that your `server_name` is `example.com`, and your Synapse is
hosted at a target domain of `customer.example.net`. Currently you should have
an SRV record which looks like:
```
_matrix._tcp.example.com. IN SRV 10 5 443 customer.example.net.
```
In this situation, you have two choices for how to proceed:
#### Option 1: give Synapse a certificate for your matrix domain
Synapse 1.0 will expect your server to present a TLS certificate for your
`server_name` (`example.com` in the above example). You can achieve this by
doing one of the following:
* Acquire a certificate for the `server_name` yourself (for example, using
`certbot`), and give it and the key to Synapse via `tls_certificate_path`
and `tls_private_key_path`, or:
* Use Synapse's [ACME support](./ACME.md), and forward port 80 on the
`server_name` domain to your Synapse instance, or:
* Set up a reverse-proxy on port 8448 on the `server_name` domain, which
forwards to Synapse. Once it is set up, you can remove the SRV record.
#### Option 2: add a .well-known file to delegate your matrix traffic
This will allow you to keep Synapse on a separate domain, without having to
give it a certificate for the matrix domain.
You can do this with a `.well-known` file as follows:
1. Keep the SRV record in place - it is needed for backwards compatibility
with Synapse 0.34 and earlier.
2. Give synapse a certificate corresponding to the target domain
(`customer.example.net` in the above example). Currently Synapse's ACME
support [does not support
this](https://github.com/matrix-org/synapse/issues/4552), so you will have
to 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.
4. Arrange for a `.well-known` file at
`https://<server_name>/.well-known/matrix/server` with contents:
```json
{"m.server": "<target domain>:<port>"}
```
In the above example, `https://example.com/.well-known/matrix/server`
should have the contents:
```json
{"m.server": "customer.example.net:443"}
```
## FAQ
### Synapse 0.99.0 has just been released, what do I need to do right now? ### Synapse 0.99.0 has just been released, what do I need to do right now?
Upgrade as soon as you can in preparation for Synapse 1.0.0. Upgrade as soon as you can in preparation for Synapse 1.0.0.
@ -126,14 +203,13 @@ other servers know how to find it.
The easiest way to do this is with a .well-known/matrix/server URI on the The easiest way to do this is with a .well-known/matrix/server URI on the
webroot of the domain to advertise your server. For instance, if you ran webroot of the domain to advertise your server. For instance, if you ran
"matrixhosting.com" and you were hosting a Matrix server for example.com, you "matrixhosting.com" and you were hosting a Matrix server for `example.com`, you
would ask example.com to create a file at: would ask `example.com` to create a file at
`https://example.com/.well-known/matrix/server` with contents:
`https://example.com/.well-known/matrix/server` ```json
{"m.server": "example.matrixhosting.com:8448"}
with contents: ```
`{"m.server": "example.matrixhosting.com:8448"}`
...which would tell servers trying to connect to example.com to instead connect ...which would tell servers trying to connect to example.com to instead connect
to example.matrixhosting.com on port 8448. You would then configure Synapse to example.matrixhosting.com on port 8448. You would then configure Synapse
@ -231,7 +307,7 @@ We no longer actively recommend against using a reverse proxy. Many admins will
find it easier to direct federation traffic to a reverse-proxy and manage their find it easier to direct federation traffic to a reverse-proxy and manage their
own TLS certificates, and this is a supported configuration. own TLS certificates, and this is a supported configuration.
### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy? ### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?
Practically speaking, this is no longer necessary. Practically speaking, this is no longer necessary.