1
0

UPGRADE.rst 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493
  1. Upgrading Synapse
  2. =================
  3. Before upgrading check if any special steps are required to upgrade from the
  4. what you currently have installed to current version of synapse. The extra
  5. instructions that may be required are listed later in this document.
  6. 1. If synapse was installed in a virtualenv then activate that virtualenv before
  7. upgrading. If synapse is installed in a virtualenv in ``~/synapse/env`` then
  8. run:
  9. .. code:: bash
  10. source ~/synapse/env/bin/activate
  11. 2. If synapse was installed using pip then upgrade to the latest version by
  12. running:
  13. .. code:: bash
  14. pip install --upgrade matrix-synapse[all]
  15. # restart synapse
  16. synctl restart
  17. If synapse was installed using git then upgrade to the latest version by
  18. running:
  19. .. code:: bash
  20. # Pull the latest version of the master branch.
  21. git pull
  22. # Update synapse and its python dependencies.
  23. pip install --upgrade .[all]
  24. # restart synapse
  25. ./synctl restart
  26. To check whether your update was successful, you can check the Server header
  27. returned by the Client-Server API:
  28. .. code:: bash
  29. # replace <host.name> with the hostname of your synapse homeserver.
  30. # You may need to specify a port (eg, :8448) if your server is not
  31. # configured on port 443.
  32. curl -kv https://<host.name>/_matrix/client/versions 2>&1 | grep "Server:"
  33. Upgrading to v1.2.0
  34. ===================
  35. Some counter metrics have been renamed, with the old names deprecated. See
  36. `the metrics documentation <docs/metrics-howto.rst#renaming-of-metrics--deprecation-of-old-names-in-12>`_
  37. for details.
  38. Upgrading to v1.1.0
  39. ===================
  40. Synapse v1.1.0 removes support for older Python and PostgreSQL versions, as
  41. outlined in `our deprecation notice <https://matrix.org/blog/2019/04/08/synapse-deprecating-postgres-9-4-and-python-2-x>`_.
  42. Minimum Python Version
  43. ----------------------
  44. Synapse v1.1.0 has a minimum Python requirement of Python 3.5. Python 3.6 or
  45. Python 3.7 are recommended as they have improved internal string handling,
  46. significantly reducing memory usage.
  47. If you use current versions of the Matrix.org-distributed Debian packages or
  48. Docker images, action is not required.
  49. If you install Synapse in a Python virtual environment, please see "Upgrading to
  50. v0.34.0" for notes on setting up a new virtualenv under Python 3.
  51. Minimum PostgreSQL Version
  52. --------------------------
  53. If using PostgreSQL under Synapse, you will need to use PostgreSQL 9.5 or above.
  54. Please see the
  55. `PostgreSQL documentation <https://www.postgresql.org/docs/11/upgrading.html>`_
  56. for more details on upgrading your database.
  57. Upgrading to v1.0
  58. =================
  59. Validation of TLS certificates
  60. ------------------------------
  61. Synapse v1.0 is the first release to enforce
  62. validation of TLS certificates for the federation API. It is therefore
  63. essential that your certificates are correctly configured. See the `FAQ
  64. <docs/MSC1711_certificates_FAQ.md>`_ for more information.
  65. Note, v1.0 installations will also no longer be able to federate with servers
  66. that have not correctly configured their certificates.
  67. In rare cases, it may be desirable to disable certificate checking: for
  68. example, it might be essential to be able to federate with a given legacy
  69. server in a closed federation. This can be done in one of two ways:-
  70. * Configure the global switch ``federation_verify_certificates`` to ``false``.
  71. * Configure a whitelist of server domains to trust via ``federation_certificate_verification_whitelist``.
  72. See the `sample configuration file <docs/sample_config.yaml>`_
  73. for more details on these settings.
  74. Email
  75. -----
  76. When a user requests a password reset, Synapse will send an email to the
  77. user to confirm the request.
  78. Previous versions of Synapse delegated the job of sending this email to an
  79. identity server. If the identity server was somehow malicious or became
  80. compromised, it would be theoretically possible to hijack an account through
  81. this means.
  82. Therefore, by default, Synapse v1.0 will send the confirmation email itself. If
  83. Synapse is not configured with an SMTP server, password reset via email will be
  84. disabled.
  85. To configure an SMTP server for Synapse, modify the configuration section
  86. headed ``email``, and be sure to have at least the ``smtp_host``, ``smtp_port``
  87. and ``notif_from`` fields filled out. You may also need to set ``smtp_user``,
  88. ``smtp_pass``, and ``require_transport_security``.
  89. If you are absolutely certain that you wish to continue using an identity
  90. server for password resets, set ``trust_identity_server_for_password_resets`` to ``true``.
  91. See the `sample configuration file <docs/sample_config.yaml>`_
  92. for more details on these settings.
  93. Upgrading to v0.99.0
  94. ====================
  95. Please be aware that, before Synapse v1.0 is released around March 2019, you
  96. will need to replace any self-signed certificates with those verified by a
  97. root CA. Information on how to do so can be found at `the ACME docs
  98. <docs/ACME.md>`_.
  99. For more information on configuring TLS certificates see the `FAQ <docs/MSC1711_certificates_FAQ.md>`_.
  100. Upgrading to v0.34.0
  101. ====================
  102. 1. This release is the first to fully support Python 3. Synapse will now run on
  103. Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to
  104. Python 3, as it has been shown to give performance improvements.
  105. For users who have installed Synapse into a virtualenv, we recommend doing
  106. this by creating a new virtualenv. For example::
  107. virtualenv -p python3 ~/synapse/env3
  108. source ~/synapse/env3/bin/activate
  109. pip install matrix-synapse
  110. You can then start synapse as normal, having activated the new virtualenv::
  111. cd ~/synapse
  112. source env3/bin/activate
  113. synctl start
  114. Users who have installed from distribution packages should see the relevant
  115. package documentation. See below for notes on Debian packages.
  116. * When upgrading to Python 3, you **must** make sure that your log files are
  117. configured as UTF-8, by adding ``encoding: utf8`` to the
  118. ``RotatingFileHandler`` configuration (if you have one) in your
  119. ``<server>.log.config`` file. For example, if your ``log.config`` file
  120. contains::
  121. handlers:
  122. file:
  123. class: logging.handlers.RotatingFileHandler
  124. formatter: precise
  125. filename: homeserver.log
  126. maxBytes: 104857600
  127. backupCount: 10
  128. filters: [context]
  129. console:
  130. class: logging.StreamHandler
  131. formatter: precise
  132. filters: [context]
  133. Then you should update this to be::
  134. handlers:
  135. file:
  136. class: logging.handlers.RotatingFileHandler
  137. formatter: precise
  138. filename: homeserver.log
  139. maxBytes: 104857600
  140. backupCount: 10
  141. filters: [context]
  142. encoding: utf8
  143. console:
  144. class: logging.StreamHandler
  145. formatter: precise
  146. filters: [context]
  147. There is no need to revert this change if downgrading to Python 2.
  148. We are also making available Debian packages which will run Synapse on
  149. Python 3. You can switch to these packages with ``apt-get install
  150. matrix-synapse-py3``, however, please read `debian/NEWS
  151. <https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS>`_
  152. before doing so. The existing ``matrix-synapse`` packages will continue to
  153. use Python 2 for the time being.
  154. 2. This release removes the ``riot.im`` from the default list of trusted
  155. identity servers.
  156. If ``riot.im`` is in your homeserver's list of
  157. ``trusted_third_party_id_servers``, you should remove it. It was added in
  158. case a hypothetical future identity server was put there. If you don't
  159. remove it, users may be unable to deactivate their accounts.
  160. 3. This release no longer installs the (unmaintained) Matrix Console web client
  161. as part of the default installation. It is possible to re-enable it by
  162. installing it separately and setting the ``web_client_location`` config
  163. option, but please consider switching to another client.
  164. Upgrading to v0.33.7
  165. ====================
  166. This release removes the example email notification templates from
  167. ``res/templates`` (they are now internal to the python package). This should
  168. only affect you if you (a) deploy your Synapse instance from a git checkout or
  169. a github snapshot URL, and (b) have email notifications enabled.
  170. If you have email notifications enabled, you should ensure that
  171. ``email.template_dir`` is either configured to point at a directory where you
  172. have installed customised templates, or leave it unset to use the default
  173. templates.
  174. Upgrading to v0.27.3
  175. ====================
  176. This release expands the anonymous usage stats sent if the opt-in
  177. ``report_stats`` configuration is set to ``true``. We now capture RSS memory
  178. and cpu use at a very coarse level. This requires administrators to install
  179. the optional ``psutil`` python module.
  180. We would appreciate it if you could assist by ensuring this module is available
  181. and ``report_stats`` is enabled. This will let us see if performance changes to
  182. synapse are having an impact to the general community.
  183. Upgrading to v0.15.0
  184. ====================
  185. If you want to use the new URL previewing API (/_matrix/media/r0/preview_url)
  186. then you have to explicitly enable it in the config and update your dependencies
  187. dependencies. See README.rst for details.
  188. Upgrading to v0.11.0
  189. ====================
  190. This release includes the option to send anonymous usage stats to matrix.org,
  191. and requires that administrators explictly opt in or out by setting the
  192. ``report_stats`` option to either ``true`` or ``false``.
  193. We would really appreciate it if you could help our project out by reporting
  194. anonymized usage statistics from your homeserver. Only very basic aggregate
  195. data (e.g. number of users) will be reported, but it helps us to track the
  196. growth of the Matrix community, and helps us to make Matrix a success, as well
  197. as to convince other networks that they should peer with us.
  198. Upgrading to v0.9.0
  199. ===================
  200. Application services have had a breaking API change in this version.
  201. They can no longer register themselves with a home server using the AS HTTP API. This
  202. decision was made because a compromised application service with free reign to register
  203. any regex in effect grants full read/write access to the home server if a regex of ``.*``
  204. is used. An attack where a compromised AS re-registers itself with ``.*`` was deemed too
  205. big of a security risk to ignore, and so the ability to register with the HS remotely has
  206. been removed.
  207. It has been replaced by specifying a list of application service registrations in
  208. ``homeserver.yaml``::
  209. app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]
  210. Where ``registration-01.yaml`` looks like::
  211. url: <String> # e.g. "https://my.application.service.com"
  212. as_token: <String>
  213. hs_token: <String>
  214. sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token
  215. namespaces:
  216. users:
  217. - exclusive: <Boolean>
  218. regex: <String> # e.g. "@prefix_.*"
  219. aliases:
  220. - exclusive: <Boolean>
  221. regex: <String>
  222. rooms:
  223. - exclusive: <Boolean>
  224. regex: <String>
  225. Upgrading to v0.8.0
  226. ===================
  227. Servers which use captchas will need to add their public key to::
  228. static/client/register/register_config.js
  229. window.matrixRegistrationConfig = {
  230. recaptcha_public_key: "YOUR_PUBLIC_KEY"
  231. };
  232. This is required in order to support registration fallback (typically used on
  233. mobile devices).
  234. Upgrading to v0.7.0
  235. ===================
  236. New dependencies are:
  237. - pydenticon
  238. - simplejson
  239. - syutil
  240. - matrix-angular-sdk
  241. To pull in these dependencies in a virtual env, run::
  242. python synapse/python_dependencies.py | xargs -n 1 pip install
  243. Upgrading to v0.6.0
  244. ===================
  245. To pull in new dependencies, run::
  246. python setup.py develop --user
  247. This update includes a change to the database schema. To upgrade you first need
  248. to upgrade the database by running::
  249. python scripts/upgrade_db_to_v0.6.0.py <db> <server_name> <signing_key>
  250. Where `<db>` is the location of the database, `<server_name>` is the
  251. server name as specified in the synapse configuration, and `<signing_key>` is
  252. the location of the signing key as specified in the synapse configuration.
  253. This may take some time to complete. Failures of signatures and content hashes
  254. can safely be ignored.
  255. Upgrading to v0.5.1
  256. ===================
  257. Depending on precisely when you installed v0.5.0 you may have ended up with
  258. a stale release of the reference matrix webclient installed as a python module.
  259. To uninstall it and ensure you are depending on the latest module, please run::
  260. $ pip uninstall syweb
  261. Upgrading to v0.5.0
  262. ===================
  263. The webclient has been split out into a seperate repository/pacakage in this
  264. release. Before you restart your homeserver you will need to pull in the
  265. webclient package by running::
  266. python setup.py develop --user
  267. This release completely changes the database schema and so requires upgrading
  268. it before starting the new version of the homeserver.
  269. The script "database-prepare-for-0.5.0.sh" should be used to upgrade the
  270. database. This will save all user information, such as logins and profiles,
  271. but will otherwise purge the database. This includes messages, which
  272. rooms the home server was a member of and room alias mappings.
  273. If you would like to keep your history, please take a copy of your database
  274. file and ask for help in #matrix:matrix.org. The upgrade process is,
  275. unfortunately, non trivial and requires human intervention to resolve any
  276. resulting conflicts during the upgrade process.
  277. Before running the command the homeserver should be first completely
  278. shutdown. To run it, simply specify the location of the database, e.g.:
  279. ./scripts/database-prepare-for-0.5.0.sh "homeserver.db"
  280. Once this has successfully completed it will be safe to restart the
  281. homeserver. You may notice that the homeserver takes a few seconds longer to
  282. restart than usual as it reinitializes the database.
  283. On startup of the new version, users can either rejoin remote rooms using room
  284. aliases or by being reinvited. Alternatively, if any other homeserver sends a
  285. message to a room that the homeserver was previously in the local HS will
  286. automatically rejoin the room.
  287. Upgrading to v0.4.0
  288. ===================
  289. This release needs an updated syutil version. Run::
  290. python setup.py develop
  291. You will also need to upgrade your configuration as the signing key format has
  292. changed. Run::
  293. python -m synapse.app.homeserver --config-path <CONFIG> --generate-config
  294. Upgrading to v0.3.0
  295. ===================
  296. This registration API now closely matches the login API. This introduces a bit
  297. more backwards and forwards between the HS and the client, but this improves
  298. the overall flexibility of the API. You can now GET on /register to retrieve a list
  299. of valid registration flows. Upon choosing one, they are submitted in the same
  300. way as login, e.g::
  301. {
  302. type: m.login.password,
  303. user: foo,
  304. password: bar
  305. }
  306. The default HS supports 2 flows, with and without Identity Server email
  307. authentication. Enabling captcha on the HS will add in an extra step to all
  308. flows: ``m.login.recaptcha`` which must be completed before you can transition
  309. to the next stage. There is a new login type: ``m.login.email.identity`` which
  310. contains the ``threepidCreds`` key which were previously sent in the original
  311. register request. For more information on this, see the specification.
  312. Web Client
  313. ----------
  314. The VoIP specification has changed between v0.2.0 and v0.3.0. Users should
  315. refresh any browser tabs to get the latest web client code. Users on
  316. v0.2.0 of the web client will not be able to call those on v0.3.0 and
  317. vice versa.
  318. Upgrading to v0.2.0
  319. ===================
  320. The home server now requires setting up of SSL config before it can run. To
  321. automatically generate default config use::
  322. $ python synapse/app/homeserver.py \
  323. --server-name machine.my.domain.name \
  324. --bind-port 8448 \
  325. --config-path homeserver.config \
  326. --generate-config
  327. This config can be edited if desired, for example to specify a different SSL
  328. certificate to use. Once done you can run the home server using::
  329. $ python synapse/app/homeserver.py --config-path homeserver.config
  330. See the README.rst for more information.
  331. Also note that some config options have been renamed, including:
  332. - "host" to "server-name"
  333. - "database" to "database-path"
  334. - "port" to "bind-port" and "unsecure-port"
  335. Upgrading to v0.0.1
  336. ===================
  337. This release completely changes the database schema and so requires upgrading
  338. it before starting the new version of the homeserver.
  339. The script "database-prepare-for-0.0.1.sh" should be used to upgrade the
  340. database. This will save all user information, such as logins and profiles,
  341. but will otherwise purge the database. This includes messages, which
  342. rooms the home server was a member of and room alias mappings.
  343. Before running the command the homeserver should be first completely
  344. shutdown. To run it, simply specify the location of the database, e.g.:
  345. ./scripts/database-prepare-for-0.0.1.sh "homeserver.db"
  346. Once this has successfully completed it will be safe to restart the
  347. homeserver. You may notice that the homeserver takes a few seconds longer to
  348. restart than usual as it reinitializes the database.
  349. On startup of the new version, users can either rejoin remote rooms using room
  350. aliases or by being reinvited. Alternatively, if any other homeserver sends a
  351. message to a room that the homeserver was previously in the local HS will
  352. automatically rejoin the room.