From cc83778686cab64f9c7b4803f1ef3615a98868d9 Mon Sep 17 00:00:00 2001 From: Valentin Lab Date: Mon, 17 Jan 2022 17:04:41 +0100 Subject: [PATCH] new: doc: [synapse] add a ``README.rst`` that was written at the time of the charm Signed-off-by: Valentin Lab --- synapse/README.rst | 100 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 synapse/README.rst diff --git a/synapse/README.rst b/synapse/README.rst new file mode 100644 index 0000000..0290f93 --- /dev/null +++ b/synapse/README.rst @@ -0,0 +1,100 @@ +Opiniated choice of this charm +============================== + +- As API is REST and compatible to be on same port, ``synapse`` server + and client will be served on the same port 8008. This will allow + one-port communication that can be reverse-proxified easily and is + usually open even in tight controlled network environment. + +- for simplicity sake, one-responsibility and consistency, SSL support + is delegated to ``web_proxy``. So any ACME support on synapse side + is disabled. + +- Departing from standard ``8448`` port for federation support requires + some delegation support to be implemented, either with DNS ``SRV`` + method, or with ``.well-known`` method. The second is chosen as the + first was declared as temporary, and is flawed (see section talking + of that). A third reason is that ``DNS`` charm is still not written + so that is something we don't have control on yet easily whereas + ``.well-known`` host might be easier to implement in existing ``web-proxy`` + charms (even if not trivial). + + +Information +=========== + +As it was difficult to gather information from synapse, here is a quick +recap of most useful concepts and references:: + +- Ansible recipe: https://github.com/spantaleev/matrix-docker-ansible-deploy + + Which is very complete on a fully featured deployment. With real code that + is readable. This was a keypoint for a working example providing a + ``.well-known`` delegation that actually works. But it also sports LDAP + auth, mxid, or whatsapp and telegram bridges config that might become + handy soon. + + + +Delegation +========== + +To enable federation and having a delegate server (ie: +``matrix.domain.com`` for the server managing ``domain.com`` +ids... for instance to use ``@user:domain.com`` for user id instead of +``@user:matrix.domain.com`` even if you matrix server is on +``matrix.domain.com``), there are 2 options, and only one is fully +working as expected (spoiler alert, it is the ``.well-known`` +solution). + +The reference spec is there: + +https://matrix.org/docs/spec/server_server/r0.1.1.html#resolving-server-names + + +DNS SRV method +-------------- + +This method uses the ``SRV`` DNS record. It is flawed in the way that +if we provide the delegated hostname, the actual delegated hostname +itself won't be used directly, it will be used only to resolv an IP, +and then the HTTPS will set ``Host:`` header to the former hostname, +not the delegate, (in our example, it'll contact ``matrix.domain.org``'s IP and +will contact this IP asking ``Host: domain.org``). + +Which will mess with SSL certificate names of course if you are +actually having 2 separated virtual hosts with separate SSL +certificates. + +This is how to set up the DNS record according to synapse docs:: + +> To use a SRV record, first create your SRV record and publish it in DNS. +> This should have the format ``_matrix._tcp. IN SRV +> 10 0 ``. The DNS record should then look +> something like: +> +> $ dig -t srv _matrix._tcp.example.com +> _matrix._tcp.example.com. 3600 IN SRV 10 0 8448 synapse.example.com. +> +> Note that the server hostname cannot be an alias (CNAME record): it has +> to point directly to the server hosting the synapse instance. + +Note: DNS ``SRV`` method is said to be temporary. + +The rationale behind this "flaw" is laid down here: +https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#interaction-with-srv-records + + +.well-known method +------------------ + + +https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/matrix-base/templates/static-files/well-known/matrix-server.j2 + +Troubleshooting +=============== + +https://matrix.org/federationtester + + +https://matrix.org/federationtester/api/report?server_name=DOMAIN \ No newline at end of file