README.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259
  1. =========================================================================
  2. Synapse |support| |development| |documentation| |license| |pypi| |python|
  3. =========================================================================
  4. Synapse is now actively maintained at `element-hq/synapse <https://github.com/element-hq/synapse>`_
  5. =================================================================================================
  6. Synapse is an open-source `Matrix <https://matrix.org/>`_ homeserver developed
  7. from 2019 through 2023 as part of the Matrix.org Foundation. The Matrix.org
  8. Foundation is not able to resource maintenance of Synapse and it
  9. `continues to be developed by Element <https://github.com/element-hq/synapse>`_;
  10. additionally you have the choice of `other Matrix homeservers <https://matrix.org/ecosystem/servers/>`_.
  11. See `The future of Synapse and Dendrite <https://matrix.org/blog/2023/11/06/future-of-synapse-dendrite/>`_
  12. blog post for more information.
  13. =========================================================================
  14. Briefly, Matrix is an open standard for communications on the internet, supporting
  15. federation, encryption and VoIP. Matrix.org has more to say about the `goals of the
  16. Matrix project <https://matrix.org/docs/guides/introduction>`_, and the `formal specification
  17. <https://spec.matrix.org/>`_ describes the technical details.
  18. .. contents::
  19. Installing and configuration
  20. ============================
  21. The Synapse documentation describes `how to install Synapse <https://matrix-org.github.io/synapse/latest/setup/installation.html>`_. We recommend using
  22. `Docker images <https://matrix-org.github.io/synapse/latest/setup/installation.html#docker-images-and-ansible-playbooks>`_ or `Debian packages from Matrix.org
  23. <https://matrix-org.github.io/synapse/latest/setup/installation.html#matrixorg-packages>`_.
  24. .. _federation:
  25. Synapse has a variety of `config options
  26. <https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html>`_
  27. which can be used to customise its behaviour after installation.
  28. There are additional details on how to `configure Synapse for federation here
  29. <https://matrix-org.github.io/synapse/latest/federate.html>`_.
  30. .. _reverse-proxy:
  31. Using a reverse proxy with Synapse
  32. ----------------------------------
  33. It is recommended to put a reverse proxy such as
  34. `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`_,
  35. `Apache <https://httpd.apache.org/docs/current/mod/mod_proxy_http.html>`_,
  36. `Caddy <https://caddyserver.com/docs/quick-starts/reverse-proxy>`_,
  37. `HAProxy <https://www.haproxy.org/>`_ or
  38. `relayd <https://man.openbsd.org/relayd.8>`_ in front of Synapse. One advantage of
  39. doing so is that it means that you can expose the default https port (443) to
  40. Matrix clients without needing to run Synapse with root privileges.
  41. For information on configuring one, see `the reverse proxy docs
  42. <https://matrix-org.github.io/synapse/latest/reverse_proxy.html>`_.
  43. Upgrading an existing Synapse
  44. -----------------------------
  45. The instructions for upgrading Synapse are in `the upgrade notes`_.
  46. Please check these instructions as upgrading may require extra steps for some
  47. versions of Synapse.
  48. .. _the upgrade notes: https://matrix-org.github.io/synapse/develop/upgrade.html
  49. Platform dependencies
  50. ---------------------
  51. Synapse uses a number of platform dependencies such as Python and PostgreSQL,
  52. and aims to follow supported upstream versions. See the
  53. `deprecation policy <https://matrix-org.github.io/synapse/latest/deprecation_policy.html>`_
  54. for more details.
  55. Security note
  56. -------------
  57. Matrix serves raw, user-supplied data in some APIs -- specifically the `content
  58. repository endpoints`_.
  59. .. _content repository endpoints: https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid
  60. Whilst we make a reasonable effort to mitigate against XSS attacks (for
  61. instance, by using `CSP`_), a Matrix homeserver should not be hosted on a
  62. domain hosting other web applications. This especially applies to sharing
  63. the domain with Matrix web clients and other sensitive applications like
  64. webmail. See
  65. https://developer.github.com/changes/2014-04-25-user-content-security for more
  66. information.
  67. .. _CSP: https://github.com/matrix-org/synapse/pull/1021
  68. Ideally, the homeserver should not simply be on a different subdomain, but on
  69. a completely different `registered domain`_ (also known as top-level site or
  70. eTLD+1). This is because `some attacks`_ are still possible as long as the two
  71. applications share the same registered domain.
  72. .. _registered domain: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-2.3
  73. .. _some attacks: https://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cookie
  74. To illustrate this with an example, if your Element Web or other sensitive web
  75. application is hosted on ``A.example1.com``, you should ideally host Synapse on
  76. ``example2.com``. Some amount of protection is offered by hosting on
  77. ``B.example1.com`` instead, so this is also acceptable in some scenarios.
  78. However, you should *not* host your Synapse on ``A.example1.com``.
  79. Note that all of the above refers exclusively to the domain used in Synapse's
  80. ``public_baseurl`` setting. In particular, it has no bearing on the domain
  81. mentioned in MXIDs hosted on that server.
  82. Following this advice ensures that even if an XSS is found in Synapse, the
  83. impact to other applications will be minimal.
  84. Testing a new installation
  85. ==========================
  86. The easiest way to try out your new Synapse installation is by connecting to it
  87. from a web client.
  88. Unless you are running a test instance of Synapse on your local machine, in
  89. general, you will need to enable TLS support before you can successfully
  90. connect from a client: see
  91. `TLS certificates <https://matrix-org.github.io/synapse/latest/setup/installation.html#tls-certificates>`_.
  92. An easy way to get started is to login or register via Element at
  93. https://app.element.io/#/login or https://app.element.io/#/register respectively.
  94. You will need to change the server you are logging into from ``matrix.org``
  95. and instead specify a Homeserver URL of ``https://<server_name>:8448``
  96. (or just ``https://<server_name>`` if you are using a reverse proxy).
  97. If you prefer to use another client, refer to our
  98. `client breakdown <https://matrix.org/ecosystem/clients/>`_.
  99. If all goes well you should at least be able to log in, create a room, and
  100. start sending messages.
  101. .. _`client-user-reg`:
  102. Registering a new user from a client
  103. ------------------------------------
  104. By default, registration of new users via Matrix clients is disabled. To enable
  105. it:
  106. 1. In the
  107. `registration config section <https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#registration>`_
  108. set ``enable_registration: true`` in ``homeserver.yaml``.
  109. 2. Then **either**:
  110. a. set up a `CAPTCHA <https://matrix-org.github.io/synapse/latest/CAPTCHA_SETUP.html>`_, or
  111. b. set ``enable_registration_without_verification: true`` in ``homeserver.yaml``.
  112. We **strongly** recommend using a CAPTCHA, particularly if your homeserver is exposed to
  113. the public internet. Without it, anyone can freely register accounts on your homeserver.
  114. This can be exploited by attackers to create spambots targetting the rest of the Matrix
  115. federation.
  116. Your new user name will be formed partly from the ``server_name``, and partly
  117. from a localpart you specify when you create the account. Your name will take
  118. the form of::
  119. @localpart:my.domain.name
  120. (pronounced "at localpart on my dot domain dot name").
  121. As when logging in, you will need to specify a "Custom server". Specify your
  122. desired ``localpart`` in the 'User name' box.
  123. Troubleshooting and support
  124. ===========================
  125. The `Admin FAQ <https://matrix-org.github.io/synapse/latest/usage/administration/admin_faq.html>`_
  126. includes tips on dealing with some common problems. For more details, see
  127. `Synapse's wider documentation <https://matrix-org.github.io/synapse/latest/>`_.
  128. For additional support installing or managing Synapse, please ask in the community
  129. support room |room|_ (from a matrix.org account if necessary). We do not use GitHub
  130. issues for support requests, only for bug reports and feature requests.
  131. .. |room| replace:: ``#synapse:matrix.org``
  132. .. _room: https://matrix.to/#/#synapse:matrix.org
  133. .. |docs| replace:: ``docs``
  134. .. _docs: docs
  135. Identity Servers
  136. ================
  137. Identity servers have the job of mapping email addresses and other 3rd Party
  138. IDs (3PIDs) to Matrix user IDs, as well as verifying the ownership of 3PIDs
  139. before creating that mapping.
  140. **They are not where accounts or credentials are stored - these live on home
  141. servers. Identity Servers are just for mapping 3rd party IDs to matrix IDs.**
  142. This process is very security-sensitive, as there is obvious risk of spam if it
  143. is too easy to sign up for Matrix accounts or harvest 3PID data. In the longer
  144. term, we hope to create a decentralised system to manage it (`matrix-doc #712
  145. <https://github.com/matrix-org/matrix-doc/issues/712>`_), but in the meantime,
  146. the role of managing trusted identity in the Matrix ecosystem is farmed out to
  147. a cluster of known trusted ecosystem partners, who run 'Matrix Identity
  148. Servers' such as `Sydent <https://github.com/matrix-org/sydent>`_, whose role
  149. is purely to authenticate and track 3PID logins and publish end-user public
  150. keys.
  151. You can host your own copy of Sydent, but this will prevent you reaching other
  152. users in the Matrix ecosystem via their email address, and prevent them finding
  153. you. We therefore recommend that you use one of the centralised identity servers
  154. at ``https://matrix.org`` or ``https://vector.im`` for now.
  155. To reiterate: the Identity server will only be used if you choose to associate
  156. an email address with your account, or send an invite to another user via their
  157. email address.
  158. Development
  159. ===========
  160. We welcome contributions to Synapse from the community!
  161. The best place to get started is our
  162. `guide for contributors <https://matrix-org.github.io/synapse/latest/development/contributing_guide.html>`_.
  163. This is part of our larger `documentation <https://matrix-org.github.io/synapse/latest>`_, which includes
  164. information for Synapse developers as well as Synapse administrators.
  165. Developers might be particularly interested in:
  166. * `Synapse's database schema <https://matrix-org.github.io/synapse/latest/development/database_schema.html>`_,
  167. * `notes on Synapse's implementation details <https://matrix-org.github.io/synapse/latest/development/internal_documentation/index.html>`_, and
  168. * `how we use git <https://matrix-org.github.io/synapse/latest/development/git.html>`_.
  169. Alongside all that, join our developer community on Matrix:
  170. `#synapse-dev:matrix.org <https://matrix.to/#/#synapse-dev:matrix.org>`_, featuring real humans!
  171. .. |support| image:: https://img.shields.io/matrix/synapse:matrix.org?label=support&logo=matrix
  172. :alt: (get support on #synapse:matrix.org)
  173. :target: https://matrix.to/#/#synapse:matrix.org
  174. .. |development| image:: https://img.shields.io/matrix/synapse-dev:matrix.org?label=development&logo=matrix
  175. :alt: (discuss development on #synapse-dev:matrix.org)
  176. :target: https://matrix.to/#/#synapse-dev:matrix.org
  177. .. |documentation| image:: https://img.shields.io/badge/documentation-%E2%9C%93-success
  178. :alt: (Rendered documentation on GitHub Pages)
  179. :target: https://matrix-org.github.io/synapse/latest/
  180. .. |license| image:: https://img.shields.io/github/license/matrix-org/synapse
  181. :alt: (check license in LICENSE file)
  182. :target: LICENSE
  183. .. |pypi| image:: https://img.shields.io/pypi/v/matrix-synapse
  184. :alt: (latest version released on PyPi)
  185. :target: https://pypi.org/project/matrix-synapse
  186. .. |python| image:: https://img.shields.io/pypi/pyversions/matrix-synapse
  187. :alt: (supported python versions)
  188. :target: https://pypi.org/project/matrix-synapse