Compare commits
9 commits
develop
...
neilj/read
Author | SHA1 | Date | |
---|---|---|---|
|
a9ceb79f5a | ||
|
a9c14a2b66 | ||
|
d8e2077c3c | ||
|
de1c6cb736 | ||
|
992ae85ef6 | ||
|
b649d59332 | ||
|
b452b47a38 | ||
|
ccac22a3d8 | ||
|
a146ab4b0a |
|
@ -375,8 +375,12 @@ To configure Synapse to expose an HTTPS port, you will need to edit
|
|||
`tls_private_key_path` lines under the `TLS` section. You can either
|
||||
point these settings at an existing certificate and key, or you can
|
||||
enable Synapse's built-in ACME (Let's Encrypt) support. Instructions
|
||||
for having Synapse automatically provision and renew federation
|
||||
certificates through ACME can be found at [ACME.md](docs/ACME.md).
|
||||
for having Synapse automatically provision and renew federation
|
||||
certificates through ACME can be found at [ACME.md](docs/ACME.md). If,
|
||||
alternatively, you wish to delegate a TLS certificate from another domain
|
||||
see the .well-known guide at [well-known.md](docs/well-known.md).
|
||||
|
||||
|
||||
|
||||
## Registering a user
|
||||
|
||||
|
|
29
README.rst
29
README.rst
|
@ -93,13 +93,13 @@ Unless you are running a test instance of Synapse on your local machine, in
|
|||
general, you will need to enable TLS support before you can successfully
|
||||
connect from a client: see `<INSTALL.md#tls-certificates>`_.
|
||||
|
||||
An easy way to get started is to login or register via Riot at
|
||||
https://riot.im/app/#/login or https://riot.im/app/#/register respectively.
|
||||
An easy way to get started is to login or register via Riot at
|
||||
https://riot.im/app/#/login or https://riot.im/app/#/register respectively.
|
||||
You will need to change the server you are logging into from ``matrix.org``
|
||||
and instead specify a Homeserver URL of ``https://<server_name>:8448``
|
||||
(or just ``https://<server_name>`` if you are using a reverse proxy).
|
||||
(Leave the identity server as the default - see `Identity servers`_.)
|
||||
If you prefer to use another client, refer to our
|
||||
and instead specify a Homeserver URL of ``https://<server_name>:8448``
|
||||
(or just ``https://<server_name>`` if you are using a reverse proxy).
|
||||
(Leave the identity server as the default - see `Identity servers`_.)
|
||||
If you prefer to use another client, refer to our
|
||||
`client breakdown <https://matrix.org/docs/projects/clients-matrix>`_.
|
||||
|
||||
If all goes well you should at least be able to log in, create a room, and
|
||||
|
@ -134,6 +134,11 @@ ACME setup
|
|||
For details on having Synapse manage your federation TLS certificates
|
||||
automatically, please see `<docs/ACME.md>`_.
|
||||
|
||||
.well-known setup
|
||||
=================
|
||||
|
||||
For details on how to configure your TLS certificate such that one domain may
|
||||
delegate to another please see `<docs/well-known.md>`_.
|
||||
|
||||
Security Note
|
||||
=============
|
||||
|
@ -244,8 +249,16 @@ should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port>
|
|||
Note that the server hostname cannot be an alias (CNAME record): it has to point
|
||||
directly to the server hosting the synapse instance.
|
||||
|
||||
You can then configure your homeserver to use ``<yourdomain.com>`` as the domain in
|
||||
its user-ids, by setting ``server_name``::
|
||||
If it is not possible to acquire a certificate valid for your matrix domain,
|
||||
the correct method is create a .well-known file. For more details on how to
|
||||
configure .well-known `see <docs/well_known.md>`_.
|
||||
|
||||
For those of you upgrading your TLS certificate in readiness for Synapse 1.0,
|
||||
please take a look at `our guide <docs/MSC1711_certificates_FAQ.md#configuring-certificates-for-compatibility-with-synapse-100>`_.
|
||||
|
||||
Having created a valid TLS certificate you can then configure your homeserver
|
||||
to use ``<yourdomain.com>`` as the domain in its user-ids, by setting
|
||||
``server_name``::
|
||||
|
||||
python -m synapse.app.homeserver \
|
||||
--server-name <yourdomain.com> \
|
||||
|
|
1
changelog.d/4766.misc
Normal file
1
changelog.d/4766.misc
Normal file
|
@ -0,0 +1 @@
|
|||
Improved .well-known docs
|
49
docs/well-known.md
Normal file
49
docs/well-known.md
Normal file
|
@ -0,0 +1,49 @@
|
|||
# Well-Known
|
||||
|
||||
The mapping for a server name to a hostname for federation is done via
|
||||
`SRV` records. Synapse v1.0 mandates valid X.509 certificates for the
|
||||
federation endpoint where the certificate must match the server name.
|
||||
|
||||
This presents difficulties for hosted server offerings: ExampleCorp
|
||||
may want to delegate responsibility for running its Matrix homeserver to an
|
||||
outside supplier, but it may be difficult for that supplier to obtain a TLS
|
||||
certificate for `example.com` (and ExampleCorp may be reluctant to let them have
|
||||
one).
|
||||
|
||||
`.well-known` solves this problem by augmenting the current `SRV` record
|
||||
with a `.well-known` lookup.
|
||||
|
||||
## Configuring `.well-known`
|
||||
|
||||
1. Give synapse a certificate corresponding to the target domain
|
||||
(`customer.example.com`). 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`.
|
||||
|
||||
2. Restart Synapse to ensure the new certificate is loaded.
|
||||
|
||||
3. Arrange for a `.well-known` file at
|
||||
`https://<server_name>/.well-known/matrix/server` with contents:
|
||||
|
||||
```json
|
||||
{"m.server": "<target server name>"}
|
||||
```
|
||||
|
||||
where the target server name is resolved as usual (i.e. SRV lookup, falling
|
||||
back to talking to port 8448).
|
||||
|
||||
In the above `example.com` exmaple above, where synapse is listening on
|
||||
port 8000, `https://example.com/.well-known/matrix/server` should have
|
||||
`m.server` set to one of:
|
||||
|
||||
1. `customer.example.com` ─ with a SRV record on
|
||||
`_matrix._tcp.customer.example.com` pointing to port 8000, or:
|
||||
|
||||
2. `customer.example.com` ─ updating synapse to listen on the default port
|
||||
8448, or:
|
||||
|
||||
3. `customer.example.com:8000` ─ ensuring that if there is a reverse proxy
|
||||
on `customer.example.com:8000` it correctly handles HTTP requests with
|
||||
Host header set to `customer.example.com:8000`.
|
Loading…
Reference in a new issue