README.rst 11 KB

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