fork 0k-charms
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

99 lines
3.7 KiB

  1. Opiniated choice of this charm
  2. ==============================
  3. - As API is REST and compatible to be on same port, ``synapse`` server
  4. and client will be served on the same port 8008. This will allow
  5. one-port communication that can be reverse-proxified easily and is
  6. usually open even in tight controlled network environment.
  7. - for simplicity sake, one-responsibility and consistency, SSL support
  8. is delegated to ``web_proxy``. So any ACME support on synapse side
  9. is disabled.
  10. - Departing from standard ``8448`` port for federation support requires
  11. some delegation support to be implemented, either with DNS ``SRV``
  12. method, or with ``.well-known`` method. The second is chosen as the
  13. first was declared as temporary, and is flawed (see section talking
  14. of that). A third reason is that ``DNS`` charm is still not written
  15. so that is something we don't have control on yet easily whereas
  16. ``.well-known`` host might be easier to implement in existing ``web-proxy``
  17. charms (even if not trivial).
  18. Information
  19. ===========
  20. As it was difficult to gather information from synapse, here is a quick
  21. recap of most useful concepts and references::
  22. - Ansible recipe: https://github.com/spantaleev/matrix-docker-ansible-deploy
  23. Which is very complete on a fully featured deployment. With real code that
  24. is readable. This was a keypoint for a working example providing a
  25. ``.well-known`` delegation that actually works. But it also sports LDAP
  26. auth, mxid, or whatsapp and telegram bridges config that might become
  27. handy soon.
  28. Delegation
  29. ==========
  30. To enable federation and having a delegate server (ie:
  31. ``matrix.domain.com`` for the server managing ``domain.com``
  32. ids... for instance to use ``@user:domain.com`` for user id instead of
  33. ``@user:matrix.domain.com`` even if you matrix server is on
  34. ``matrix.domain.com``), there are 2 options, and only one is fully
  35. working as expected (spoiler alert, it is the ``.well-known``
  36. solution).
  37. The reference spec is there:
  38. https://matrix.org/docs/spec/server_server/r0.1.1.html#resolving-server-names
  39. DNS SRV method
  40. --------------
  41. This method uses the ``SRV`` DNS record. It is flawed in the way that
  42. if we provide the delegated hostname, the actual delegated hostname
  43. itself won't be used directly, it will be used only to resolv an IP,
  44. and then the HTTPS will set ``Host:`` header to the former hostname,
  45. not the delegate, (in our example, it'll contact ``matrix.domain.org``'s IP and
  46. will contact this IP asking ``Host: domain.org``).
  47. Which will mess with SSL certificate names of course if you are
  48. actually having 2 separated virtual hosts with separate SSL
  49. certificates.
  50. This is how to set up the DNS record according to synapse docs::
  51. > To use a SRV record, first create your SRV record and publish it in DNS.
  52. > This should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV
  53. > 10 0 <port> <synapse.server.name>``. The DNS record should then look
  54. > something like:
  55. >
  56. > $ dig -t srv _matrix._tcp.example.com
  57. > _matrix._tcp.example.com. 3600 IN SRV 10 0 8448 synapse.example.com.
  58. >
  59. > Note that the server hostname cannot be an alias (CNAME record): it has
  60. > to point directly to the server hosting the synapse instance.
  61. Note: DNS ``SRV`` method is said to be temporary.
  62. The rationale behind this "flaw" is laid down here:
  63. https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#interaction-with-srv-records
  64. .well-known method
  65. ------------------
  66. https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/matrix-base/templates/static-files/well-known/matrix-server.j2
  67. Troubleshooting
  68. ===============
  69. https://matrix.org/federationtester
  70. https://matrix.org/federationtester/api/report?server_name=DOMAIN