diff options
| -rw-r--r-- | develop/upgrading/index.html | 1260 | ||||
| -rw-r--r-- | latest/upgrading/index.html | 1260 | ||||
| -rw-r--r-- | v1.37/upgrading/index.html | 1260 |
3 files changed, 0 insertions, 3780 deletions
diff --git a/develop/upgrading/index.html b/develop/upgrading/index.html deleted file mode 100644 index fe9879895a..0000000000 --- a/develop/upgrading/index.html +++ /dev/null @@ -1,1260 +0,0 @@ -<!DOCTYPE HTML> -<html lang="en" class="sidebar-visible no-js light"> - <head> - <!-- Book generated using mdBook --> - <meta charset="UTF-8"> - <title>Upgrading between Synapse Versions - Synapse</title> - - - - - <!-- Custom HTML head --> - - - - <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> - <meta name="description" content=""> - <meta name="viewport" content="width=device-width, initial-scale=1"> - <meta name="theme-color" content="#ffffff" /> - - - <link rel="icon" href="../favicon.svg"> - - - <link rel="shortcut icon" href="../favicon.png"> - - <link rel="stylesheet" href="../css/variables.css"> - <link rel="stylesheet" href="../css/general.css"> - <link rel="stylesheet" href="../css/chrome.css"> - - <link rel="stylesheet" href="../css/print.css" media="print"> - - - <!-- Fonts --> - <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css"> - - <link rel="stylesheet" href="../fonts/fonts.css"> - - - <!-- Highlight.js Stylesheets --> - <link rel="stylesheet" href="../highlight.css"> - <link rel="stylesheet" href="../tomorrow-night.css"> - <link rel="stylesheet" href="../ayu-highlight.css"> - - <!-- Custom theme stylesheets --> - - <link rel="stylesheet" href="../docs/website_files/table-of-contents.css"> - - <link rel="stylesheet" href="../docs/website_files/remove-nav-buttons.css"> - - <link rel="stylesheet" href="../docs/website_files/indent-section-headers.css"> - - - - </head> - <body> - <!-- Provide site root to javascript --> - <script type="text/javascript"> - var path_to_root = "../"; - var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light"; - </script> - - <!-- Work around some values being stored in localStorage wrapped in quotes --> - <script type="text/javascript"> - try { - var theme = localStorage.getItem('mdbook-theme'); - var sidebar = localStorage.getItem('mdbook-sidebar'); - if (theme.startsWith('"') && theme.endsWith('"')) { - localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); - } - if (sidebar.startsWith('"') && sidebar.endsWith('"')) { - localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); - } - } catch (e) { } - </script> - - <!-- Set the theme before any content is loaded, prevents flash --> - <script type="text/javascript"> - var theme; - try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } - if (theme === null || theme === undefined) { theme = default_theme; } - var html = document.querySelector('html'); - html.classList.remove('no-js') - html.classList.remove('light') - html.classList.add(theme); - html.classList.add('js'); - </script> - - <!-- Hide / unhide sidebar before it is displayed --> - <script type="text/javascript"> - var html = document.querySelector('html'); - var sidebar = 'hidden'; - if (document.body.clientWidth >= 1080) { - try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } - sidebar = sidebar || 'visible'; - } - html.classList.remove('sidebar-visible'); - html.classList.add("sidebar-" + sidebar); - </script> - - <nav id="sidebar" class="sidebar" aria-label="Table of contents"> - <div class="sidebar-scrollbox"> - <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="../welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="../setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="../postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="../reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="../turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="../delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="../upgrading/index.html" class="active">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="../MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="../federate.html">Federation</a></li><li class="chapter-item expanded "><a href="../usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="../usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="../structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="../usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="../sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="../password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="../jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="../CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="../application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="../server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="../url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="../user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="../message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="../modules.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="../spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="../presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="../workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="../systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="../usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="../admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="../admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="../admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="../admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="../admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="../admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="../admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="../admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="../admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../admin_api/shutdown_room.html">Shutdown Room</a></li><li class="chapter-item expanded "><a href="../admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="../admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="../admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="../manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="../metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="../usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="../development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="../code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="../dev/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="../opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="../development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="../replication.html">Replication</a></li><li class="chapter-item expanded "><a href="../tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="../development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../dev/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="../dev/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="../media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="../room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="../deprecation_policy.html">Dependency Deprecation Policy</a></li></ol> - </div> - <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div> - </nav> - - <div id="page-wrapper" class="page-wrapper"> - - <div class="page"> - - <div id="menu-bar-hover-placeholder"></div> - <div id="menu-bar" class="menu-bar sticky bordered"> - <div class="left-buttons"> - <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> - <i class="fa fa-bars"></i> - </button> - <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list"> - <i class="fa fa-paint-brush"></i> - </button> - <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> - <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li> - <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> - <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> - <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> - <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> - </ul> - - <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar"> - <i class="fa fa-search"></i> - </button> - - </div> - - <h1 class="menu-title">Synapse</h1> - - <div class="right-buttons"> - - <a href="../print.html" title="Print this book" aria-label="Print this book"> - <i id="print-button" class="fa fa-print"></i> - </a> - - - <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository"> - <i id="git-repository-button" class="fa fa-github"></i> - </a> - - - <a href="https://github.com/matrix-org/synapse/edit/develop/docs/upgrading/README.md" title="Suggest an edit" aria-label="Suggest an edit"> - <i id="git-edit-button" class="fa fa-edit"></i> - </a> - - - </div> - </div> - - - <div id="search-wrapper" class="hidden"> - <form id="searchbar-outer" class="searchbar-outer"> - <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> - </form> - <div id="searchresults-outer" class="searchresults-outer hidden"> - <div id="searchresults-header" class="searchresults-header"></div> - <ul id="searchresults"> - </ul> - </div> - </div> - - - <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> - <script type="text/javascript"> - document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); - document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); - Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { - link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); - }); - </script> - - <div id="content" class="content"> - <main> - <!-- Page table of contents --> - <div class="sidetoc"> - <nav class="pagetoc"></nav> - </div> - - <!-- - Include the contents of UPGRADE.rst from the project root without moving it, which may - break links around the internet. Additionally, note that SUMMARY.md is unable to - directly link to content outside of the docs/ directory. So we use this file as a - redirection. ---> -<h1 id="upgrading-synapse"><a class="header" href="#upgrading-synapse">Upgrading Synapse</a></h1> -<p>Before upgrading check if any special steps are required to upgrade from the -version you currently have installed to the current version of Synapse. The extra -instructions that may be required are listed later in this document.</p> -<ul> -<li> -<p>Check that your versions of Python and PostgreSQL are still supported.</p> -<p>Synapse follows upstream lifecycles for <code>Python</code>_ and <code>PostgreSQL</code>_, and -removes support for versions which are no longer maintained.</p> -<p>The website https://endoflife.date also offers convenient summaries.</p> -<p>.. _Python: https://devguide.python.org/devcycle/#end-of-life-branches -.. _PostgreSQL: https://www.postgresql.org/support/versioning/</p> -</li> -<li> -<p>If Synapse was installed using <code>prebuilt packages <INSTALL.md#prebuilt-packages></code>_, you will need to follow the normal process -for upgrading those packages.</p> -</li> -<li> -<p>If Synapse was installed from source, then:</p> -<ol> -<li> -<p>Activate the virtualenv before upgrading. For example, if Synapse is -installed in a virtualenv in <code>~/synapse/env</code> then run:</p> -<p>.. code:: bash</p> -<p>source ~/synapse/env/bin/activate</p> -</li> -<li> -<p>If Synapse was installed using pip then upgrade to the latest version by -running:</p> -<p>.. code:: bash</p> -<p>pip install --upgrade matrix-synapse</p> -<p>If Synapse was installed using git then upgrade to the latest version by -running:</p> -<p>.. code:: bash</p> -<p>git pull -pip install --upgrade .</p> -</li> -<li> -<p>Restart Synapse:</p> -<p>.. code:: bash</p> -<p>./synctl restart</p> -</li> -</ol> -</li> -</ul> -<p>To check whether your update was successful, you can check the running server -version with:</p> -<p>.. code:: bash</p> -<pre><code># you may need to replace 'localhost:8008' if synapse is not configured -# to listen on port 8008. - -curl http://localhost:8008/_synapse/admin/v1/server_version -</code></pre> -<h2 id="rolling-back-to-older-versions"><a class="header" href="#rolling-back-to-older-versions">Rolling back to older versions</a></h2> -<p>Rolling back to previous releases can be difficult, due to database schema -changes between releases. Where we have been able to test the rollback process, -this will be noted below.</p> -<p>In general, you will need to undo any changes made during the upgrade process, -for example:</p> -<ul> -<li> -<p>pip:</p> -<p>.. code:: bash</p> -<p>source env/bin/activate</p> -<h1 id="replace-130-accordingly"><a class="header" href="#replace-130-accordingly">replace <code>1.3.0</code> accordingly:</a></h1> -<p>pip install matrix-synapse==1.3.0</p> -</li> -<li> -<p>Debian:</p> -<p>.. code:: bash</p> -<h1 id="replace-130-and-stretch-accordingly"><a class="header" href="#replace-130-and-stretch-accordingly">replace <code>1.3.0</code> and <code>stretch</code> accordingly:</a></h1> -<p>wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb -dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb</p> -</li> -</ul> -<h1 id="upgrading-to-v1370"><a class="header" href="#upgrading-to-v1370">Upgrading to v1.37.0</a></h1> -<h2 id="deprecation-of-the-current-spam-checker-interface"><a class="header" href="#deprecation-of-the-current-spam-checker-interface">Deprecation of the current spam checker interface</a></h2> -<p>The current spam checker interface is deprecated in favour of a new generic modules system. -Authors of spam checker modules can refer to <code>this documentation <https://matrix-org.github.io/synapse/develop/modules.html#porting-an-existing-module-that-uses-the-old-interface></code>_ -to update their modules. Synapse administrators can refer to <code>this documentation <https://matrix-org.github.io/synapse/develop/modules.html#using-modules></code>_ -to update their configuration once the modules they are using have been updated.</p> -<p>We plan to remove support for the current spam checker interface in August 2021.</p> -<p>More module interfaces will be ported over to this new generic system in future versions -of Synapse.</p> -<h1 id="upgrading-to-v1340"><a class="header" href="#upgrading-to-v1340">Upgrading to v1.34.0</a></h1> -<h2 id="room_invite_state_types-configuration-setting"><a class="header" href="#room_invite_state_types-configuration-setting"><code>room_invite_state_types</code> configuration setting</a></h2> -<p>The <code>room_invite_state_types</code> configuration setting has been deprecated and -replaced with <code>room_prejoin_state</code>. See the <code>sample configuration file <https://github.com/matrix-org/synapse/blob/v1.34.0/docs/sample_config.yaml#L1515></code>_.</p> -<p>If you have set <code>room_invite_state_types</code> to the default value you should simply -remove it from your configuration file. The default value used to be:</p> -<p>.. code:: yaml</p> -<p>room_invite_state_types: -- "m.room.join_rules" -- "m.room.canonical_alias" -- "m.room.avatar" -- "m.room.encryption" -- "m.room.name"</p> -<p>If you have customised this value, you should remove <code>room_invite_state_types</code> and -configure <code>room_prejoin_state</code> instead.</p> -<h1 id="upgrading-to-v1330"><a class="header" href="#upgrading-to-v1330">Upgrading to v1.33.0</a></h1> -<h2 id="account-validity-html-templates-can-now-display-a-users-expiration-date"><a class="header" href="#account-validity-html-templates-can-now-display-a-users-expiration-date">Account Validity HTML templates can now display a user's expiration date</a></h2> -<p>This may affect you if you have enabled the account validity feature, and have made use of a -custom HTML template specified by the <code>account_validity.template_dir</code> or <code>account_validity.account_renewed_html_path</code> -Synapse config options.</p> -<p>The template can now accept an <code>expiration_ts</code> variable, which represents the unix timestamp in milliseconds for the -future date of which their account has been renewed until. See the -<code>default template <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_renewed.html></code>_ -for an example of usage.</p> -<p>ALso note that a new HTML template, <code>account_previously_renewed.html</code>, has been added. This is is shown to users -when they attempt to renew their account with a valid renewal token that has already been used before. The default -template contents can been found -<code>here <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_previously_renewed.html></code>_, -and can also accept an <code>expiration_ts</code> variable. This template replaces the error message users would previously see -upon attempting to use a valid renewal token more than once.</p> -<h1 id="upgrading-to-v1320"><a class="header" href="#upgrading-to-v1320">Upgrading to v1.32.0</a></h1> -<h2 id="regression-causing-connected-prometheus-instances-to-become-overwhelmed"><a class="header" href="#regression-causing-connected-prometheus-instances-to-become-overwhelmed">Regression causing connected Prometheus instances to become overwhelmed</a></h2> -<p>This release introduces <code>a regression <https://github.com/matrix-org/synapse/issues/9853></code>_ -that can overwhelm connected Prometheus instances. This issue is not present in -Synapse v1.32.0rc1.</p> -<p>If you have been affected, please downgrade to 1.31.0. You then may need to -remove excess writeahead logs in order for Prometheus to recover. Instructions -for doing so are provided -<code>here <https://github.com/matrix-org/synapse/pull/9854#issuecomment-823472183></code>_.</p> -<h2 id="dropping-support-for-old-python-postgres-and-sqlite-versions"><a class="header" href="#dropping-support-for-old-python-postgres-and-sqlite-versions">Dropping support for old Python, Postgres and SQLite versions</a></h2> -<p>In line with our <code>deprecation policy <https://github.com/matrix-org/synapse/blob/release-v1.32.0/docs/deprecation_policy.md></code>_, -we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no longer supported upstream.</p> -<p>This release of Synapse requires Python 3.6+ and PostgresSQL 9.6+ or SQLite 3.22+.</p> -<h2 id="removal-of-old-list-accounts-admin-api"><a class="header" href="#removal-of-old-list-accounts-admin-api">Removal of old List Accounts Admin API</a></h2> -<p>The deprecated v1 "list accounts" admin API (<code>GET /_synapse/admin/v1/users/<user_id></code>) has been removed in this version.</p> -<p>The <code>v2 list accounts API <https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#list-accounts></code>_ -has been available since Synapse 1.7.0 (2019-12-13), and is accessible under <code>GET /_synapse/admin/v2/users</code>.</p> -<p>The deprecation of the old endpoint was announced with Synapse 1.28.0 (released on 2021-02-25).</p> -<h2 id="application-services-must-use-type-mloginapplication_service-when-registering-users"><a class="header" href="#application-services-must-use-type-mloginapplication_service-when-registering-users">Application Services must use type <code>m.login.application_service</code> when registering users</a></h2> -<p>In compliance with the -<code>Application Service spec <https://matrix.org/docs/spec/application_service/r0.1.2#server-admin-style-permissions></code>_, -Application Services are now required to use the <code>m.login.application_service</code> type when registering users via the -<code>/_matrix/client/r0/register</code> endpoint. This behaviour was deprecated in Synapse v1.30.0.</p> -<p>Please ensure your Application Services are up to date.</p> -<h1 id="upgrading-to-v1290"><a class="header" href="#upgrading-to-v1290">Upgrading to v1.29.0</a></h1> -<h2 id="requirement-for-x-forwarded-proto-header"><a class="header" href="#requirement-for-x-forwarded-proto-header">Requirement for X-Forwarded-Proto header</a></h2> -<p>When using Synapse with a reverse proxy (in particular, when using the -<code>x_forwarded</code> option on an HTTP listener), Synapse now expects to receive an -<code>X-Forwarded-Proto</code> header on incoming HTTP requests. If it is not set, Synapse -will log a warning on each received request.</p> -<p>To avoid the warning, administrators using a reverse proxy should ensure that -the reverse proxy sets <code>X-Forwarded-Proto</code> header to <code>https</code> or <code>http</code> to -indicate the protocol used by the client.</p> -<p>Synapse also requires the <code>Host</code> header to be preserved.</p> -<p>See the <code>reverse proxy documentation <docs/reverse_proxy.md></code>_, where the -example configurations have been updated to show how to set these headers.</p> -<p>(Users of <code>Caddy <https://caddyserver.com/></code>_ are unaffected, since we believe it -sets <code>X-Forwarded-Proto</code> by default.)</p> -<h1 id="upgrading-to-v1270"><a class="header" href="#upgrading-to-v1270">Upgrading to v1.27.0</a></h1> -<h2 id="changes-to-callback-uri-for-oauth2--openid-connect-and-saml2"><a class="header" href="#changes-to-callback-uri-for-oauth2--openid-connect-and-saml2">Changes to callback URI for OAuth2 / OpenID Connect and SAML2</a></h2> -<p>This version changes the URI used for callbacks from OAuth2 and SAML2 identity providers:</p> -<ul> -<li> -<p>If your server is configured for single sign-on via an OpenID Connect or OAuth2 identity -provider, you will need to add <code>[synapse public baseurl]/_synapse/client/oidc/callback</code> -to the list of permitted "redirect URIs" at the identity provider.</p> -<p>See <code>docs/openid.md <docs/openid.md></code>_ for more information on setting up OpenID -Connect.</p> -</li> -<li> -<p>If your server is configured for single sign-on via a SAML2 identity provider, you will -need to add <code>[synapse public baseurl]/_synapse/client/saml2/authn_response</code> as a permitted -"ACS location" (also known as "allowed callback URLs") at the identity provider.</p> -<p>The "Issuer" in the "AuthnRequest" to the SAML2 identity provider is also updated to -<code>[synapse public baseurl]/_synapse/client/saml2/metadata.xml</code>. If your SAML2 identity -provider uses this property to validate or otherwise identify Synapse, its configuration -will need to be updated to use the new URL. Alternatively you could create a new, separate -"EntityDescriptor" in your SAML2 identity provider with the new URLs and leave the URLs in -the existing "EntityDescriptor" as they were.</p> -</li> -</ul> -<h2 id="changes-to-html-templates"><a class="header" href="#changes-to-html-templates">Changes to HTML templates</a></h2> -<p>The HTML templates for SSO and email notifications now have <code>Jinja2's autoescape <https://jinja.palletsprojects.com/en/2.11.x/api/#autoescaping></code>_ -enabled for files ending in <code>.html</code>, <code>.htm</code>, and <code>.xml</code>. If you have customised -these templates and see issues when viewing them you might need to update them. -It is expected that most configurations will need no changes.</p> -<p>If you have customised the templates <em>names</em> for these templates, it is recommended -to verify they end in <code>.html</code> to ensure autoescape is enabled.</p> -<p>The above applies to the following templates:</p> -<ul> -<li><code>add_threepid.html</code></li> -<li><code>add_threepid_failure.html</code></li> -<li><code>add_threepid_success.html</code></li> -<li><code>notice_expiry.html</code></li> -<li><code>notice_expiry.html</code></li> -<li><code>notif_mail.html</code> (which, by default, includes <code>room.html</code> and <code>notif.html</code>)</li> -<li><code>password_reset.html</code></li> -<li><code>password_reset_confirmation.html</code></li> -<li><code>password_reset_failure.html</code></li> -<li><code>password_reset_success.html</code></li> -<li><code>registration.html</code></li> -<li><code>registration_failure.html</code></li> -<li><code>registration_success.html</code></li> -<li><code>sso_account_deactivated.html</code></li> -<li><code>sso_auth_bad_user.html</code></li> -<li><code>sso_auth_confirm.html</code></li> -<li><code>sso_auth_success.html</code></li> -<li><code>sso_error.html</code></li> -<li><code>sso_login_idp_picker.html</code></li> -<li><code>sso_redirect_confirm.html</code></li> -</ul> -<h1 id="upgrading-to-v1260"><a class="header" href="#upgrading-to-v1260">Upgrading to v1.26.0</a></h1> -<h2 id="rolling-back-to-v1250-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1250-after-a-failed-upgrade">Rolling back to v1.25.0 after a failed upgrade</a></h2> -<p>v1.26.0 includes a lot of large changes. If something problematic occurs, you -may want to roll-back to a previous version of Synapse. Because v1.26.0 also -includes a new database schema version, reverting that version is also required -alongside the generic rollback instructions mentioned above. In short, to roll -back to v1.25.0 you need to:</p> -<ol> -<li> -<p>Stop the server</p> -</li> -<li> -<p>Decrease the schema version in the database:</p> -<p>.. code:: sql</p> -<p>UPDATE schema_version SET version = 58;</p> -</li> -<li> -<p>Delete the ignored users & chain cover data:</p> -<p>.. code:: sql</p> -<p>DROP TABLE IF EXISTS ignored_users; -UPDATE rooms SET has_auth_chain_index = false;</p> -<p>For PostgreSQL run:</p> -<p>.. code:: sql</p> -<p>TRUNCATE event_auth_chain_links; -TRUNCATE event_auth_chains;</p> -<p>For SQLite run:</p> -<p>.. code:: sql</p> -<p>DELETE FROM event_auth_chain_links; -DELETE FROM event_auth_chains;</p> -</li> -<li> -<p>Mark the deltas as not run (so they will re-run on upgrade).</p> -<p>.. code:: sql</p> -<p>DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/01ignored_user.py"; -DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/06chain_cover_index.sql";</p> -</li> -<li> -<p>Downgrade Synapse by following the instructions for your installation method -in the "Rolling back to older versions" section above.</p> -</li> -</ol> -<h1 id="upgrading-to-v1250"><a class="header" href="#upgrading-to-v1250">Upgrading to v1.25.0</a></h1> -<h2 id="last-release-supporting-python-35"><a class="header" href="#last-release-supporting-python-35">Last release supporting Python 3.5</a></h2> -<p>This is the last release of Synapse which guarantees support with Python 3.5, -which passed its upstream End of Life date several months ago.</p> -<p>We will attempt to maintain support through March 2021, but without guarantees.</p> -<p>In the future, Synapse will follow upstream schedules for ending support of -older versions of Python and PostgreSQL. Please upgrade to at least Python 3.6 -and PostgreSQL 9.6 as soon as possible.</p> -<h2 id="blacklisting-ip-ranges"><a class="header" href="#blacklisting-ip-ranges">Blacklisting IP ranges</a></h2> -<p>Synapse v1.25.0 includes new settings, <code>ip_range_blacklist</code> and -<code>ip_range_whitelist</code>, for controlling outgoing requests from Synapse for federation, -identity servers, push, and for checking key validity for third-party invite events. -The previous setting, <code>federation_ip_range_blacklist</code>, is deprecated. The new -<code>ip_range_blacklist</code> defaults to private IP ranges if it is not defined.</p> -<p>If you have never customised <code>federation_ip_range_blacklist</code> it is recommended -that you remove that setting.</p> -<p>If you have customised <code>federation_ip_range_blacklist</code> you should update the -setting name to <code>ip_range_blacklist</code>.</p> -<p>If you have a custom push server that is reached via private IP space you may -need to customise <code>ip_range_blacklist</code> or <code>ip_range_whitelist</code>.</p> -<h1 id="upgrading-to-v1240"><a class="header" href="#upgrading-to-v1240">Upgrading to v1.24.0</a></h1> -<h2 id="custom-openid-connect-mapping-provider-breaking-change"><a class="header" href="#custom-openid-connect-mapping-provider-breaking-change">Custom OpenID Connect mapping provider breaking change</a></h2> -<p>This release allows the OpenID Connect mapping provider to perform normalisation -of the localpart of the Matrix ID. This allows for the mapping provider to -specify different algorithms, instead of the <a href="https://matrix.org/docs/spec/appendices#mapping-from-other-character-sets">default way</a>.</p> -<p>If your Synapse configuration uses a custom mapping provider -(<code>oidc_config.user_mapping_provider.module</code> is specified and not equal to -<code>synapse.handlers.oidc_handler.JinjaOidcMappingProvider</code>) then you <em>must</em> ensure -that <code>map_user_attributes</code> of the mapping provider performs some normalisation -of the <code>localpart</code> returned. To match previous behaviour you can use the -<code>map_username_to_mxid_localpart</code> function provided by Synapse. An example is -shown below:</p> -<p>.. code-block:: python</p> -<p>from synapse.types import map_username_to_mxid_localpart</p> -<p>class MyMappingProvider: -def map_user_attributes(self, userinfo, token): -# ... your custom logic ... -sso_user_id = ... -localpart = map_username_to_mxid_localpart(sso_user_id)</p> -<pre><code> return {"localpart": localpart} -</code></pre> -<h2 id="removal-historical-synapse-admin-api"><a class="header" href="#removal-historical-synapse-admin-api">Removal historical Synapse Admin API</a></h2> -<p>Historically, the Synapse Admin API has been accessible under:</p> -<ul> -<li><code>/_matrix/client/api/v1/admin</code></li> -<li><code>/_matrix/client/unstable/admin</code></li> -<li><code>/_matrix/client/r0/admin</code></li> -<li><code>/_synapse/admin/v1</code></li> -</ul> -<p>The endpoints with <code>/_matrix/client/*</code> prefixes have been removed as of v1.24.0. -The Admin API is now only accessible under:</p> -<ul> -<li><code>/_synapse/admin/v1</code></li> -</ul> -<p>The only exception is the <code>/admin/whois</code> endpoint, which is -<code>also available via the client-server API <https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid></code>_.</p> -<p>The deprecation of the old endpoints was announced with Synapse 1.20.0 (released -on 2020-09-22) and makes it easier for homeserver admins to lock down external -access to the Admin API endpoints.</p> -<h1 id="upgrading-to-v1230"><a class="header" href="#upgrading-to-v1230">Upgrading to v1.23.0</a></h1> -<h2 id="structured-logging-configuration-breaking-changes"><a class="header" href="#structured-logging-configuration-breaking-changes">Structured logging configuration breaking changes</a></h2> -<p>This release deprecates use of the <code>structured: true</code> logging configuration for -structured logging. If your logging configuration contains <code>structured: true</code> -then it should be modified based on the <code>structured logging documentation <https://github.com/matrix-org/synapse/blob/master/docs/structured_logging.md></code>_.</p> -<p>The <code>structured</code> and <code>drains</code> logging options are now deprecated and should -be replaced by standard logging configuration of <code>handlers</code> and <code>formatters</code>.</p> -<p>A future will release of Synapse will make using <code>structured: true</code> an error.</p> -<h1 id="upgrading-to-v1220"><a class="header" href="#upgrading-to-v1220">Upgrading to v1.22.0</a></h1> -<h2 id="thirdpartyeventrules-breaking-changes"><a class="header" href="#thirdpartyeventrules-breaking-changes">ThirdPartyEventRules breaking changes</a></h2> -<p>This release introduces a backwards-incompatible change to modules making use of -<code>ThirdPartyEventRules</code> in Synapse. If you make use of a module defined under the -<code>third_party_event_rules</code> config option, please make sure it is updated to handle -the below change:</p> -<p>The <code>http_client</code> argument is no longer passed to modules as they are initialised. Instead, -modules are expected to make use of the <code>http_client</code> property on the <code>ModuleApi</code> class. -Modules are now passed a <code>module_api</code> argument during initialisation, which is an instance of -<code>ModuleApi</code>. <code>ModuleApi</code> instances have a <code>http_client</code> property which acts the same as -the <code>http_client</code> argument previously passed to <code>ThirdPartyEventRules</code> modules.</p> -<h1 id="upgrading-to-v1210"><a class="header" href="#upgrading-to-v1210">Upgrading to v1.21.0</a></h1> -<h2 id="forwarding-_synapseclient-through-your-reverse-proxy"><a class="header" href="#forwarding-_synapseclient-through-your-reverse-proxy">Forwarding <code>/_synapse/client</code> through your reverse proxy</a></h2> -<p>The <code>reverse proxy documentation <https://github.com/matrix-org/synapse/blob/develop/docs/reverse_proxy.md></code>_ has been updated -to include reverse proxy directives for <code>/_synapse/client/*</code> endpoints. As the user password -reset flow now uses endpoints under this prefix, <strong>you must update your reverse proxy -configurations for user password reset to work</strong>.</p> -<p>Additionally, note that the <code>Synapse worker documentation <https://github.com/matrix-org/synapse/blob/develop/docs/workers.md></code>_ has been updated to -state that the <code>/_synapse/client/password_reset/email/submit_token</code> endpoint can be handled -by all workers. If you make use of Synapse's worker feature, please update your reverse proxy -configuration to reflect this change.</p> -<h2 id="new-html-templates"><a class="header" href="#new-html-templates">New HTML templates</a></h2> -<p>A new HTML template, -<code>password_reset_confirmation.html <https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html></code>_, -has been added to the <code>synapse/res/templates</code> directory. If you are using a -custom template directory, you may want to copy the template over and modify it.</p> -<p>Note that as of v1.20.0, templates do not need to be included in custom template -directories for Synapse to start. The default templates will be used if a custom -template cannot be found.</p> -<p>This page will appear to the user after clicking a password reset link that has -been emailed to them.</p> -<p>To complete password reset, the page must include a way to make a <code>POST</code> -request to -<code>/_synapse/client/password_reset/{medium}/submit_token</code> -with the query parameters from the original link, presented as a URL-encoded form. See the file -itself for more details.</p> -<h2 id="updated-single-sign-on-html-templates"><a class="header" href="#updated-single-sign-on-html-templates">Updated Single Sign-on HTML Templates</a></h2> -<p>The <code>saml_error.html</code> template was removed from Synapse and replaced with the -<code>sso_error.html</code> template. If your Synapse is configured to use SAML and a -custom <code>sso_redirect_confirm_template_dir</code> configuration then any customisations -of the <code>saml_error.html</code> template will need to be merged into the <code>sso_error.html</code> -template. These templates are similar, but the parameters are slightly different:</p> -<ul> -<li>The <code>msg</code> parameter should be renamed to <code>error_description</code>.</li> -<li>There is no longer a <code>code</code> parameter for the response code.</li> -<li>A string <code>error</code> parameter is available that includes a short hint of why a -user is seeing the error page.</li> -</ul> -<h1 id="upgrading-to-v1180"><a class="header" href="#upgrading-to-v1180">Upgrading to v1.18.0</a></h1> -<h2 id="docker--py3-suffix-will-be-removed-in-future-versions"><a class="header" href="#docker--py3-suffix-will-be-removed-in-future-versions">Docker <code>-py3</code> suffix will be removed in future versions</a></h2> -<p>From 10th August 2020, we will no longer publish Docker images with the <code>-py3</code> tag suffix. The images tagged with the <code>-py3</code> suffix have been identical to the non-suffixed tags since release 0.99.0, and the suffix is obsolete.</p> -<p>On 10th August, we will remove the <code>latest-py3</code> tag. Existing per-release tags (such as <code>v1.18.0-py3</code>) will not be removed, but no new <code>-py3</code> tags will be added.</p> -<p>Scripts relying on the <code>-py3</code> suffix will need to be updated.</p> -<h2 id="redis-replication-is-now-recommended-in-lieu-of-tcp-replication"><a class="header" href="#redis-replication-is-now-recommended-in-lieu-of-tcp-replication">Redis replication is now recommended in lieu of TCP replication</a></h2> -<p>When setting up worker processes, we now recommend the use of a Redis server for replication. <strong>The old direct TCP connection method is deprecated and will be removed in a future release.</strong> -See <code>docs/workers.md <docs/workers.md></code>_ for more details.</p> -<h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1> -<p>This version includes a database update which is run as part of the upgrade, -and which may take a couple of minutes in the case of a large server. Synapse -will not respond to HTTP requests while this update is taking place.</p> -<h1 id="upgrading-to-v1130"><a class="header" href="#upgrading-to-v1130">Upgrading to v1.13.0</a></h1> -<h2 id="incorrect-database-migration-in-old-synapse-versions"><a class="header" href="#incorrect-database-migration-in-old-synapse-versions">Incorrect database migration in old synapse versions</a></h2> -<p>A bug was introduced in Synapse 1.4.0 which could cause the room directory to -be incomplete or empty if Synapse was upgraded directly from v1.2.1 or -earlier, to versions between v1.4.0 and v1.12.x.</p> -<p>This will <em>not</em> be a problem for Synapse installations which were:</p> -<ul> -<li>created at v1.4.0 or later,</li> -<li>upgraded via v1.3.x, or</li> -<li>upgraded straight from v1.2.1 or earlier to v1.13.0 or later.</li> -</ul> -<p>If completeness of the room directory is a concern, installations which are -affected can be repaired as follows:</p> -<ol> -<li> -<p>Run the following sql from a <code>psql</code> or <code>sqlite3</code> console:</p> -<p>.. code:: sql</p> -<p>INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES -('populate_stats_process_rooms', '{}', 'current_state_events_membership');</p> -<p>INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES -('populate_stats_process_users', '{}', 'populate_stats_process_rooms');</p> -</li> -<li> -<p>Restart synapse.</p> -</li> -</ol> -<h2 id="new-single-sign-on-html-templates"><a class="header" href="#new-single-sign-on-html-templates">New Single Sign-on HTML Templates</a></h2> -<p>New templates (<code>sso_auth_confirm.html</code>, <code>sso_auth_success.html</code>, and -<code>sso_account_deactivated.html</code>) were added to Synapse. If your Synapse is -configured to use SSO and a custom <code>sso_redirect_confirm_template_dir</code> -configuration then these templates will need to be copied from -<code>synapse/res/templates <synapse/res/templates></code>_ into that directory.</p> -<h2 id="synapse-sso-plugins-method-deprecation"><a class="header" href="#synapse-sso-plugins-method-deprecation">Synapse SSO Plugins Method Deprecation</a></h2> -<p>Plugins using the <code>complete_sso_login</code> method of -<code>synapse.module_api.ModuleApi</code> should update to using the async/await -version <code>complete_sso_login_async</code> which includes additional checks. The -non-async version is considered deprecated.</p> -<h2 id="rolling-back-to-v1124-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1124-after-a-failed-upgrade">Rolling back to v1.12.4 after a failed upgrade</a></h2> -<p>v1.13.0 includes a lot of large changes. If something problematic occurs, you -may want to roll-back to a previous version of Synapse. Because v1.13.0 also -includes a new database schema version, reverting that version is also required -alongside the generic rollback instructions mentioned above. In short, to roll -back to v1.12.4 you need to:</p> -<ol> -<li> -<p>Stop the server</p> -</li> -<li> -<p>Decrease the schema version in the database:</p> -<p>.. code:: sql</p> -<p>UPDATE schema_version SET version = 57;</p> -</li> -<li> -<p>Downgrade Synapse by following the instructions for your installation method -in the "Rolling back to older versions" section above.</p> -</li> -</ol> -<h1 id="upgrading-to-v1120"><a class="header" href="#upgrading-to-v1120">Upgrading to v1.12.0</a></h1> -<p>This version includes a database update which is run as part of the upgrade, -and which may take some time (several hours in the case of a large -server). Synapse will not respond to HTTP requests while this update is taking -place.</p> -<p>This is only likely to be a problem in the case of a server which is -participating in many rooms.</p> -<ol start="0"> -<li> -<p>As with all upgrades, it is recommended that you have a recent backup of -your database which can be used for recovery in the event of any problems.</p> -</li> -<li> -<p>As an initial check to see if you will be affected, you can try running the -following query from the <code>psql</code> or <code>sqlite3</code> console. It is safe to run it -while Synapse is still running.</p> -<p>.. code:: sql</p> -<p>SELECT MAX(q.v) FROM ( -SELECT ( -SELECT ej.json AS v -FROM state_events se INNER JOIN event_json ej USING (event_id) -WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key='' -LIMIT 1 -) FROM rooms WHERE rooms.room_version IS NULL -) q;</p> -<p>This query will take about the same amount of time as the upgrade process: ie, -if it takes 5 minutes, then it is likely that Synapse will be unresponsive for -5 minutes during the upgrade.</p> -<p>If you consider an outage of this duration to be acceptable, no further -action is necessary and you can simply start Synapse 1.12.0.</p> -<p>If you would prefer to reduce the downtime, continue with the steps below.</p> -</li> -<li> -<p>The easiest workaround for this issue is to manually -create a new index before upgrading. On PostgreSQL, his can be done as follows:</p> -<p>.. code:: sql</p> -<p>CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index -ON state_events(room_id) WHERE type = 'm.room.create';</p> -<p>The above query may take some time, but is also safe to run while Synapse is -running.</p> -<p>We assume that no SQLite users have databases large enough to be -affected. If you <em>are</em> affected, you can run a similar query, omitting the -<code>CONCURRENTLY</code> keyword. Note however that this operation may in itself cause -Synapse to stop running for some time. Synapse admins are reminded that -<code>SQLite is not recommended for use outside a test environment <https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql></code>_.</p> -</li> -<li> -<p>Once the index has been created, the <code>SELECT</code> query in step 1 above should -complete quickly. It is therefore safe to upgrade to Synapse 1.12.0.</p> -</li> -<li> -<p>Once Synapse 1.12.0 has successfully started and is responding to HTTP -requests, the temporary index can be removed:</p> -<p>.. code:: sql</p> -<p>DROP INDEX tmp_upgrade_1_12_0_index;</p> -</li> -</ol> -<h1 id="upgrading-to-v1100"><a class="header" href="#upgrading-to-v1100">Upgrading to v1.10.0</a></h1> -<p>Synapse will now log a warning on start up if used with a PostgreSQL database -that has a non-recommended locale set.</p> -<p>See <code>docs/postgres.md <docs/postgres.md></code>_ for details.</p> -<h1 id="upgrading-to-v180"><a class="header" href="#upgrading-to-v180">Upgrading to v1.8.0</a></h1> -<p>Specifying a <code>log_file</code> config option will now cause Synapse to refuse to -start, and should be replaced by with the <code>log_config</code> option. Support for -the <code>log_file</code> option was removed in v1.3.0 and has since had no effect.</p> -<h1 id="upgrading-to-v170"><a class="header" href="#upgrading-to-v170">Upgrading to v1.7.0</a></h1> -<p>In an attempt to configure Synapse in a privacy preserving way, the default -behaviours of <code>allow_public_rooms_without_auth</code> and -<code>allow_public_rooms_over_federation</code> have been inverted. This means that by -default, only authenticated users querying the Client/Server API will be able -to query the room directory, and relatedly that the server will not share -room directory information with other servers over federation.</p> -<p>If your installation does not explicitly set these settings one way or the other -and you want either setting to be <code>true</code> then it will necessary to update -your homeserver configuration file accordingly.</p> -<p>For more details on the surrounding context see our <code>explainer <https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers></code>_.</p> -<h1 id="upgrading-to-v150"><a class="header" href="#upgrading-to-v150">Upgrading to v1.5.0</a></h1> -<p>This release includes a database migration which may take several minutes to -complete if there are a large number (more than a million or so) of entries in -the <code>devices</code> table. This is only likely to a be a problem on very large -installations.</p> -<h1 id="upgrading-to-v140"><a class="header" href="#upgrading-to-v140">Upgrading to v1.4.0</a></h1> -<h2 id="new-custom-templates"><a class="header" href="#new-custom-templates">New custom templates</a></h2> -<p>If you have configured a custom template directory with the -<code>email.template_dir</code> option, be aware that there are new templates regarding -registration and threepid management (see below) that must be included.</p> -<ul> -<li><code>registration.html</code> and <code>registration.txt</code></li> -<li><code>registration_success.html</code> and <code>registration_failure.html</code></li> -<li><code>add_threepid.html</code> and <code>add_threepid.txt</code></li> -<li><code>add_threepid_failure.html</code> and <code>add_threepid_success.html</code></li> -</ul> -<p>Synapse will expect these files to exist inside the configured template -directory, and <strong>will fail to start</strong> if they are absent. -To view the default templates, see <code>synapse/res/templates <https://github.com/matrix-org/synapse/tree/master/synapse/res/templates></code>_.</p> -<h2 id="3pid-verification-changes"><a class="header" href="#3pid-verification-changes">3pid verification changes</a></h2> -<p><strong>Note: As of this release, users will be unable to add phone numbers or email -addresses to their accounts, without changes to the Synapse configuration. This -includes adding an email address during registration.</strong></p> -<p>It is possible for a user to associate an email address or phone number -with their account, for a number of reasons:</p> -<ul> -<li>for use when logging in, as an alternative to the user id.</li> -<li>in the case of email, as an alternative contact to help with account recovery.</li> -<li>in the case of email, to receive notifications of missed messages.</li> -</ul> -<p>Before an email address or phone number can be added to a user's account, -or before such an address is used to carry out a password-reset, Synapse must -confirm the operation with the owner of the email address or phone number. -It does this by sending an email or text giving the user a link or token to confirm -receipt. This process is known as '3pid verification'. ('3pid', or 'threepid', -stands for third-party identifier, and we use it to refer to external -identifiers such as email addresses and phone numbers.)</p> -<p>Previous versions of Synapse delegated the task of 3pid verification to an -identity server by default. In most cases this server is <code>vector.im</code> or -<code>matrix.org</code>.</p> -<p>In Synapse 1.4.0, for security and privacy reasons, the homeserver will no -longer delegate this task to an identity server by default. Instead, -the server administrator will need to explicitly decide how they would like the -verification messages to be sent.</p> -<p>In the medium term, the <code>vector.im</code> and <code>matrix.org</code> identity servers will -disable support for delegated 3pid verification entirely. However, in order to -ease the transition, they will retain the capability for a limited -period. Delegated email verification will be disabled on Monday 2nd December -2019 (giving roughly 2 months notice). Disabling delegated SMS verification -will follow some time after that once SMS verification support lands in -Synapse.</p> -<p>Once delegated 3pid verification support has been disabled in the <code>vector.im</code> and -<code>matrix.org</code> identity servers, all Synapse versions that depend on those -instances will be unable to verify email and phone numbers through them. There -are no imminent plans to remove delegated 3pid verification from Sydent -generally. (Sydent is the identity server project that backs the <code>vector.im</code> and -<code>matrix.org</code> instances).</p> -<p>Email</p> -<pre><code>Following upgrade, to continue verifying email (e.g. as part of the -registration process), admins can either:- - -* Configure Synapse to use an email server. -* Run or choose an identity server which allows delegated email verification - and delegate to it. - -Configure SMTP in Synapse -+++++++++++++++++++++++++ - -To configure an SMTP server for Synapse, modify the configuration section -headed ``email``, and be sure to have at least the ``smtp_host, smtp_port`` -and ``notif_from`` fields filled out. - -You may also need to set ``smtp_user``, ``smtp_pass``, and -``require_transport_security``. - -See the `sample configuration file <docs/sample_config.yaml>`_ for more details -on these settings. - -Delegate email to an identity server -++++++++++++++++++++++++++++++++++++ - -Some admins will wish to continue using email verification as part of the -registration process, but will not immediately have an appropriate SMTP server -at hand. - -To this end, we will continue to support email verification delegation via the -``vector.im`` and ``matrix.org`` identity servers for two months. Support for -delegated email verification will be disabled on Monday 2nd December. - -The ``account_threepid_delegates`` dictionary defines whether the homeserver -should delegate an external server (typically an `identity server -<https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending -confirmation messages via email and SMS. - -So to delegate email verification, in ``homeserver.yaml``, set -``account_threepid_delegates.email`` to the base URL of an identity server. For -example: - -.. code:: yaml - - account_threepid_delegates: - email: https://example.com # Delegate email sending to example.com - -Note that ``account_threepid_delegates.email`` replaces the deprecated -``email.trust_identity_server_for_password_resets``: if -``email.trust_identity_server_for_password_resets`` is set to ``true``, and -``account_threepid_delegates.email`` is not set, then the first entry in -``trusted_third_party_id_servers`` will be used as the -``account_threepid_delegate`` for email. This is to ensure compatibility with -existing Synapse installs that set up external server handling for these tasks -before v1.4.0. If ``email.trust_identity_server_for_password_resets`` is -``true`` and no trusted identity server domains are configured, Synapse will -report an error and refuse to start. - -If ``email.trust_identity_server_for_password_resets`` is ``false`` or absent -and no ``email`` delegate is configured in ``account_threepid_delegates``, -then Synapse will send email verification messages itself, using the configured -SMTP server (see above). -that type. - -Phone numbers -</code></pre> -<p>Synapse does not support phone-number verification itself, so the only way to -maintain the ability for users to add phone numbers to their accounts will be -by continuing to delegate phone number verification to the <code>matrix.org</code> and -<code>vector.im</code> identity servers (or another identity server that supports SMS -sending).</p> -<p>The <code>account_threepid_delegates</code> dictionary defines whether the homeserver -should delegate an external server (typically an <code>identity server <https://matrix.org/docs/spec/identity_service/r0.2.1></code>_) to handle sending -confirmation messages via email and SMS.</p> -<p>So to delegate phone number verification, in <code>homeserver.yaml</code>, set -<code>account_threepid_delegates.msisdn</code> to the base URL of an identity -server. For example:</p> -<p>.. code:: yaml</p> -<p>account_threepid_delegates: -msisdn: https://example.com # Delegate sms sending to example.com</p> -<p>The <code>matrix.org</code> and <code>vector.im</code> identity servers will continue to support -delegated phone number verification via SMS until such time as it is possible -for admins to configure their servers to perform phone number verification -directly. More details will follow in a future release.</p> -<h2 id="rolling-back-to-v131"><a class="header" href="#rolling-back-to-v131">Rolling back to v1.3.1</a></h2> -<p>If you encounter problems with v1.4.0, it should be possible to roll back to -v1.3.1, subject to the following:</p> -<ul> -<li> -<p>The 'room statistics' engine was heavily reworked in this release (see -<code>#5971 <https://github.com/matrix-org/synapse/pull/5971></code>_), including -significant changes to the database schema, which are not easily -reverted. This will cause the room statistics engine to stop updating when -you downgrade.</p> -<p>The room statistics are essentially unused in v1.3.1 (in future versions of -Synapse, they will be used to populate the room directory), so there should -be no loss of functionality. However, the statistics engine will write errors -to the logs, which can be avoided by setting the following in -<code>homeserver.yaml</code>:</p> -<p>.. code:: yaml</p> -<p>stats: -enabled: false</p> -<p>Don't forget to re-enable it when you upgrade again, in preparation for its -use in the room directory!</p> -</li> -</ul> -<h1 id="upgrading-to-v120"><a class="header" href="#upgrading-to-v120">Upgrading to v1.2.0</a></h1> -<p>Some counter metrics have been renamed, with the old names deprecated. See -<code>the metrics documentation <docs/metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12></code>_ -for details.</p> -<h1 id="upgrading-to-v110"><a class="header" href="#upgrading-to-v110">Upgrading to v1.1.0</a></h1> -<p>Synapse v1.1.0 removes support for older Python and PostgreSQL versions, as -outlined in <code>our deprecation notice <https://matrix.org/blog/2019/04/08/synapse-deprecating-postgres-9-4-and-python-2-x></code>_.</p> -<h2 id="minimum-python-version"><a class="header" href="#minimum-python-version">Minimum Python Version</a></h2> -<p>Synapse v1.1.0 has a minimum Python requirement of Python 3.5. Python 3.6 or -Python 3.7 are recommended as they have improved internal string handling, -significantly reducing memory usage.</p> -<p>If you use current versions of the Matrix.org-distributed Debian packages or -Docker images, action is not required.</p> -<p>If you install Synapse in a Python virtual environment, please see "Upgrading to -v0.34.0" for notes on setting up a new virtualenv under Python 3.</p> -<h2 id="minimum-postgresql-version"><a class="header" href="#minimum-postgresql-version">Minimum PostgreSQL Version</a></h2> -<p>If using PostgreSQL under Synapse, you will need to use PostgreSQL 9.5 or above. -Please see the -<code>PostgreSQL documentation <https://www.postgresql.org/docs/11/upgrading.html></code>_ -for more details on upgrading your database.</p> -<h1 id="upgrading-to-v10"><a class="header" href="#upgrading-to-v10">Upgrading to v1.0</a></h1> -<h2 id="validation-of-tls-certificates"><a class="header" href="#validation-of-tls-certificates">Validation of TLS certificates</a></h2> -<p>Synapse v1.0 is the first release to enforce -validation of TLS certificates for the federation API. It is therefore -essential that your certificates are correctly configured. See the <code>FAQ <docs/MSC1711_certificates_FAQ.md></code>_ for more information.</p> -<p>Note, v1.0 installations will also no longer be able to federate with servers -that have not correctly configured their certificates.</p> -<p>In rare cases, it may be desirable to disable certificate checking: for -example, it might be essential to be able to federate with a given legacy -server in a closed federation. This can be done in one of two ways:-</p> -<ul> -<li>Configure the global switch <code>federation_verify_certificates</code> to <code>false</code>.</li> -<li>Configure a whitelist of server domains to trust via <code>federation_certificate_verification_whitelist</code>.</li> -</ul> -<p>See the <code>sample configuration file <docs/sample_config.yaml></code>_ -for more details on these settings.</p> -<h2 id="email"><a class="header" href="#email">Email</a></h2> -<p>When a user requests a password reset, Synapse will send an email to the -user to confirm the request.</p> -<p>Previous versions of Synapse delegated the job of sending this email to an -identity server. If the identity server was somehow malicious or became -compromised, it would be theoretically possible to hijack an account through -this means.</p> -<p>Therefore, by default, Synapse v1.0 will send the confirmation email itself. If -Synapse is not configured with an SMTP server, password reset via email will be -disabled.</p> -<p>To configure an SMTP server for Synapse, modify the configuration section -headed <code>email</code>, and be sure to have at least the <code>smtp_host</code>, <code>smtp_port</code> -and <code>notif_from</code> fields filled out. You may also need to set <code>smtp_user</code>, -<code>smtp_pass</code>, and <code>require_transport_security</code>.</p> -<p>If you are absolutely certain that you wish to continue using an identity -server for password resets, set <code>trust_identity_server_for_password_resets</code> to <code>true</code>.</p> -<p>See the <code>sample configuration file <docs/sample_config.yaml></code>_ -for more details on these settings.</p> -<h2 id="new-email-templates"><a class="header" href="#new-email-templates">New email templates</a></h2> -<p>Some new templates have been added to the default template directory for the purpose of the -homeserver sending its own password reset emails. If you have configured a custom -<code>template_dir</code> in your Synapse config, these files will need to be added.</p> -<p><code>password_reset.html</code> and <code>password_reset.txt</code> are HTML and plain text templates -respectively that contain the contents of what will be emailed to the user upon attempting to -reset their password via email. <code>password_reset_success.html</code> and -<code>password_reset_failure.html</code> are HTML files that the content of which (assuming no redirect -URL is set) will be shown to the user after they attempt to click the link in the email sent -to them.</p> -<h1 id="upgrading-to-v0990"><a class="header" href="#upgrading-to-v0990">Upgrading to v0.99.0</a></h1> -<p>Please be aware that, before Synapse v1.0 is released around March 2019, you -will need to replace any self-signed certificates with those verified by a -root CA. Information on how to do so can be found at <code>the ACME docs <docs/ACME.md></code>_.</p> -<p>For more information on configuring TLS certificates see the <code>FAQ <docs/MSC1711_certificates_FAQ.md></code>_.</p> -<h1 id="upgrading-to-v0340"><a class="header" href="#upgrading-to-v0340">Upgrading to v0.34.0</a></h1> -<ol> -<li> -<p>This release is the first to fully support Python 3. Synapse will now run on -Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to -Python 3, as it has been shown to give performance improvements.</p> -<p>For users who have installed Synapse into a virtualenv, we recommend doing -this by creating a new virtualenv. For example::</p> -<pre><code>virtualenv -p python3 ~/synapse/env3 -source ~/synapse/env3/bin/activate -pip install matrix-synapse -</code></pre> -<p>You can then start synapse as normal, having activated the new virtualenv::</p> -<pre><code>cd ~/synapse -source env3/bin/activate -synctl start -</code></pre> -<p>Users who have installed from distribution packages should see the relevant -package documentation. See below for notes on Debian packages.</p> -<ul> -<li> -<p>When upgrading to Python 3, you <strong>must</strong> make sure that your log files are -configured as UTF-8, by adding <code>encoding: utf8</code> to the -<code>RotatingFileHandler</code> configuration (if you have one) in your -<code><server>.log.config</code> file. For example, if your <code>log.config</code> file -contains::</p> -<p>handlers: -file: -class: logging.handlers.RotatingFileHandler -formatter: precise -filename: homeserver.log -maxBytes: 104857600 -backupCount: 10 -filters: [context] -console: -class: logging.StreamHandler -formatter: precise -filters: [context]</p> -<p>Then you should update this to be::</p> -<p>handlers: -file: -class: logging.handlers.RotatingFileHandler -formatter: precise -filename: homeserver.log -maxBytes: 104857600 -backupCount: 10 -filters: [context] -encoding: utf8 -console: -class: logging.StreamHandler -formatter: precise -filters: [context]</p> -<p>There is no need to revert this change if downgrading to Python 2.</p> -</li> -</ul> -<p>We are also making available Debian packages which will run Synapse on -Python 3. You can switch to these packages with <code>apt-get install matrix-synapse-py3</code>, however, please read <code>debian/NEWS <https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS></code>_ -before doing so. The existing <code>matrix-synapse</code> packages will continue to -use Python 2 for the time being.</p> -</li> -<li> -<p>This release removes the <code>riot.im</code> from the default list of trusted -identity servers.</p> -<p>If <code>riot.im</code> is in your homeserver's list of -<code>trusted_third_party_id_servers</code>, you should remove it. It was added in -case a hypothetical future identity server was put there. If you don't -remove it, users may be unable to deactivate their accounts.</p> -</li> -<li> -<p>This release no longer installs the (unmaintained) Matrix Console web client -as part of the default installation. It is possible to re-enable it by -installing it separately and setting the <code>web_client_location</code> config -option, but please consider switching to another client.</p> -</li> -</ol> -<h1 id="upgrading-to-v0337"><a class="header" href="#upgrading-to-v0337">Upgrading to v0.33.7</a></h1> -<p>This release removes the example email notification templates from -<code>res/templates</code> (they are now internal to the python package). This should -only affect you if you (a) deploy your Synapse instance from a git checkout or -a github snapshot URL, and (b) have email notifications enabled.</p> -<p>If you have email notifications enabled, you should ensure that -<code>email.template_dir</code> is either configured to point at a directory where you -have installed customised templates, or leave it unset to use the default -templates.</p> -<h1 id="upgrading-to-v0273"><a class="header" href="#upgrading-to-v0273">Upgrading to v0.27.3</a></h1> -<p>This release expands the anonymous usage stats sent if the opt-in -<code>report_stats</code> configuration is set to <code>true</code>. We now capture RSS memory -and cpu use at a very coarse level. This requires administrators to install -the optional <code>psutil</code> python module.</p> -<p>We would appreciate it if you could assist by ensuring this module is available -and <code>report_stats</code> is enabled. This will let us see if performance changes to -synapse are having an impact to the general community.</p> -<h1 id="upgrading-to-v0150"><a class="header" href="#upgrading-to-v0150">Upgrading to v0.15.0</a></h1> -<p>If you want to use the new URL previewing API (/_matrix/media/r0/preview_url) -then you have to explicitly enable it in the config and update your dependencies -dependencies. See README.rst for details.</p> -<h1 id="upgrading-to-v0110"><a class="header" href="#upgrading-to-v0110">Upgrading to v0.11.0</a></h1> -<p>This release includes the option to send anonymous usage stats to matrix.org, -and requires that administrators explictly opt in or out by setting the -<code>report_stats</code> option to either <code>true</code> or <code>false</code>.</p> -<p>We would really appreciate it if you could help our project out by reporting -anonymized usage statistics from your homeserver. Only very basic aggregate -data (e.g. number of users) will be reported, but it helps us to track the -growth of the Matrix community, and helps us to make Matrix a success, as well -as to convince other networks that they should peer with us.</p> -<h1 id="upgrading-to-v090"><a class="header" href="#upgrading-to-v090">Upgrading to v0.9.0</a></h1> -<p>Application services have had a breaking API change in this version.</p> -<p>They can no longer register themselves with a home server using the AS HTTP API. This -decision was made because a compromised application service with free reign to register -any regex in effect grants full read/write access to the home server if a regex of <code>.*</code> -is used. An attack where a compromised AS re-registers itself with <code>.*</code> was deemed too -big of a security risk to ignore, and so the ability to register with the HS remotely has -been removed.</p> -<p>It has been replaced by specifying a list of application service registrations in -<code>homeserver.yaml</code>::</p> -<p>app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]</p> -<p>Where <code>registration-01.yaml</code> looks like::</p> -<p>url: <String> # e.g. "https://my.application.service.com" -as_token: <String> -hs_token: <String> -sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token -namespaces: -users: -- exclusive: <Boolean> -regex: <String> # e.g. "@prefix_.*" -aliases: -- exclusive: <Boolean> -regex: <String> -rooms: -- exclusive: <Boolean> -regex: <String></p> -<h1 id="upgrading-to-v080"><a class="header" href="#upgrading-to-v080">Upgrading to v0.8.0</a></h1> -<p>Servers which use captchas will need to add their public key to::</p> -<p>static/client/register/register_config.js</p> -<pre><code>window.matrixRegistrationConfig = { - recaptcha_public_key: "YOUR_PUBLIC_KEY" -}; -</code></pre> -<p>This is required in order to support registration fallback (typically used on -mobile devices).</p> -<h1 id="upgrading-to-v070"><a class="header" href="#upgrading-to-v070">Upgrading to v0.7.0</a></h1> -<p>New dependencies are:</p> -<ul> -<li>pydenticon</li> -<li>simplejson</li> -<li>syutil</li> -<li>matrix-angular-sdk</li> -</ul> -<p>To pull in these dependencies in a virtual env, run::</p> -<pre><code>python synapse/python_dependencies.py | xargs -n 1 pip install -</code></pre> -<h1 id="upgrading-to-v060"><a class="header" href="#upgrading-to-v060">Upgrading to v0.6.0</a></h1> -<p>To pull in new dependencies, run::</p> -<pre><code>python setup.py develop --user -</code></pre> -<p>This update includes a change to the database schema. To upgrade you first need -to upgrade the database by running::</p> -<pre><code>python scripts/upgrade_db_to_v0.6.0.py <db> <server_name> <signing_key> -</code></pre> -<p>Where <code><db></code> is the location of the database, <code><server_name></code> is the -server name as specified in the synapse configuration, and <code><signing_key></code> is -the location of the signing key as specified in the synapse configuration.</p> -<p>This may take some time to complete. Failures of signatures and content hashes -can safely be ignored.</p> -<h1 id="upgrading-to-v051"><a class="header" href="#upgrading-to-v051">Upgrading to v0.5.1</a></h1> -<p>Depending on precisely when you installed v0.5.0 you may have ended up with -a stale release of the reference matrix webclient installed as a python module. -To uninstall it and ensure you are depending on the latest module, please run::</p> -<pre><code>$ pip uninstall syweb -</code></pre> -<h1 id="upgrading-to-v050"><a class="header" href="#upgrading-to-v050">Upgrading to v0.5.0</a></h1> -<p>The webclient has been split out into a seperate repository/pacakage in this -release. Before you restart your homeserver you will need to pull in the -webclient package by running::</p> -<p>python setup.py develop --user</p> -<p>This release completely changes the database schema and so requires upgrading -it before starting the new version of the homeserver.</p> -<p>The script "database-prepare-for-0.5.0.sh" should be used to upgrade the -database. This will save all user information, such as logins and profiles, -but will otherwise purge the database. This includes messages, which -rooms the home server was a member of and room alias mappings.</p> -<p>If you would like to keep your history, please take a copy of your database -file and ask for help in #matrix:matrix.org. The upgrade process is, -unfortunately, non trivial and requires human intervention to resolve any -resulting conflicts during the upgrade process.</p> -<p>Before running the command the homeserver should be first completely -shutdown. To run it, simply specify the location of the database, e.g.:</p> -<p>./scripts/database-prepare-for-0.5.0.sh "homeserver.db"</p> -<p>Once this has successfully completed it will be safe to restart the -homeserver. You may notice that the homeserver takes a few seconds longer to -restart than usual as it reinitializes the database.</p> -<p>On startup of the new version, users can either rejoin remote rooms using room -aliases or by being reinvited. Alternatively, if any other homeserver sends a -message to a room that the homeserver was previously in the local HS will -automatically rejoin the room.</p> -<h1 id="upgrading-to-v040"><a class="header" href="#upgrading-to-v040">Upgrading to v0.4.0</a></h1> -<p>This release needs an updated syutil version. Run::</p> -<pre><code>python setup.py develop -</code></pre> -<p>You will also need to upgrade your configuration as the signing key format has -changed. Run::</p> -<pre><code>python -m synapse.app.homeserver --config-path <CONFIG> --generate-config -</code></pre> -<h1 id="upgrading-to-v030"><a class="header" href="#upgrading-to-v030">Upgrading to v0.3.0</a></h1> -<p>This registration API now closely matches the login API. This introduces a bit -more backwards and forwards between the HS and the client, but this improves -the overall flexibility of the API. You can now GET on /register to retrieve a list -of valid registration flows. Upon choosing one, they are submitted in the same -way as login, e.g::</p> -<p>{ -type: m.login.password, -user: foo, -password: bar -}</p> -<p>The default HS supports 2 flows, with and without Identity Server email -authentication. Enabling captcha on the HS will add in an extra step to all -flows: <code>m.login.recaptcha</code> which must be completed before you can transition -to the next stage. There is a new login type: <code>m.login.email.identity</code> which -contains the <code>threepidCreds</code> key which were previously sent in the original -register request. For more information on this, see the specification.</p> -<h2 id="web-client"><a class="header" href="#web-client">Web Client</a></h2> -<p>The VoIP specification has changed between v0.2.0 and v0.3.0. Users should -refresh any browser tabs to get the latest web client code. Users on -v0.2.0 of the web client will not be able to call those on v0.3.0 and -vice versa.</p> -<h1 id="upgrading-to-v020"><a class="header" href="#upgrading-to-v020">Upgrading to v0.2.0</a></h1> -<p>The home server now requires setting up of SSL config before it can run. To -automatically generate default config use::</p> -<pre><code>$ python synapse/app/homeserver.py \ - --server-name machine.my.domain.name \ - --bind-port 8448 \ - --config-path homeserver.config \ - --generate-config -</code></pre> -<p>This config can be edited if desired, for example to specify a different SSL -certificate to use. Once done you can run the home server using::</p> -<pre><code>$ python synapse/app/homeserver.py --config-path homeserver.config -</code></pre> -<p>See the README.rst for more information.</p> -<p>Also note that some config options have been renamed, including:</p> -<ul> -<li>"host" to "server-name"</li> -<li>"database" to "database-path"</li> -<li>"port" to "bind-port" and "unsecure-port"</li> -</ul> -<h1 id="upgrading-to-v001"><a class="header" href="#upgrading-to-v001">Upgrading to v0.0.1</a></h1> -<p>This release completely changes the database schema and so requires upgrading -it before starting the new version of the homeserver.</p> -<p>The script "database-prepare-for-0.0.1.sh" should be used to upgrade the -database. This will save all user information, such as logins and profiles, -but will otherwise purge the database. This includes messages, which -rooms the home server was a member of and room alias mappings.</p> -<p>Before running the command the homeserver should be first completely -shutdown. To run it, simply specify the location of the database, e.g.:</p> -<p>./scripts/database-prepare-for-0.0.1.sh "homeserver.db"</p> -<p>Once this has successfully completed it will be safe to restart the -homeserver. You may notice that the homeserver takes a few seconds longer to -restart than usual as it reinitializes the database.</p> -<p>On startup of the new version, users can either rejoin remote rooms using room -aliases or by being reinvited. Alternatively, if any other homeserver sends a -message to a room that the homeserver was previously in the local HS will -automatically rejoin the room.</p> - - </main> - - <nav class="nav-wrapper" aria-label="Page navigation"> - <!-- Mobile navigation buttons --> - - <a rel="prev" href="../delegate.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> - <i class="fa fa-angle-left"></i> - </a> - - - - <a rel="next" href="../MSC1711_certificates_FAQ.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> - <i class="fa fa-angle-right"></i> - </a> - - - <div style="clear: both"></div> - </nav> - </div> - </div> - - <nav class="nav-wide-wrapper" aria-label="Page navigation"> - - <a rel="prev" href="../delegate.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> - <i class="fa fa-angle-left"></i> - </a> - - - - <a rel="next" href="../MSC1711_certificates_FAQ.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> - <i class="fa fa-angle-right"></i> - </a> - - </nav> - - </div> - - - - - - - - - <script type="text/javascript"> - window.playground_copyable = true; - </script> - - - - - - <script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../mark.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../searcher.js" type="text/javascript" charset="utf-8"></script> - - - <script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../highlight.js" type="text/javascript" charset="utf-8"></script> - <script src="../book.js" type="text/javascript" charset="utf-8"></script> - - <!-- Custom JS scripts --> - - <script type="text/javascript" src="../docs/website_files/table-of-contents.js"></script> - - - - - </body> -</html> \ No newline at end of file diff --git a/latest/upgrading/index.html b/latest/upgrading/index.html deleted file mode 100644 index fe9879895a..0000000000 --- a/latest/upgrading/index.html +++ /dev/null @@ -1,1260 +0,0 @@ -<!DOCTYPE HTML> -<html lang="en" class="sidebar-visible no-js light"> - <head> - <!-- Book generated using mdBook --> - <meta charset="UTF-8"> - <title>Upgrading between Synapse Versions - Synapse</title> - - - - - <!-- Custom HTML head --> - - - - <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> - <meta name="description" content=""> - <meta name="viewport" content="width=device-width, initial-scale=1"> - <meta name="theme-color" content="#ffffff" /> - - - <link rel="icon" href="../favicon.svg"> - - - <link rel="shortcut icon" href="../favicon.png"> - - <link rel="stylesheet" href="../css/variables.css"> - <link rel="stylesheet" href="../css/general.css"> - <link rel="stylesheet" href="../css/chrome.css"> - - <link rel="stylesheet" href="../css/print.css" media="print"> - - - <!-- Fonts --> - <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css"> - - <link rel="stylesheet" href="../fonts/fonts.css"> - - - <!-- Highlight.js Stylesheets --> - <link rel="stylesheet" href="../highlight.css"> - <link rel="stylesheet" href="../tomorrow-night.css"> - <link rel="stylesheet" href="../ayu-highlight.css"> - - <!-- Custom theme stylesheets --> - - <link rel="stylesheet" href="../docs/website_files/table-of-contents.css"> - - <link rel="stylesheet" href="../docs/website_files/remove-nav-buttons.css"> - - <link rel="stylesheet" href="../docs/website_files/indent-section-headers.css"> - - - - </head> - <body> - <!-- Provide site root to javascript --> - <script type="text/javascript"> - var path_to_root = "../"; - var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light"; - </script> - - <!-- Work around some values being stored in localStorage wrapped in quotes --> - <script type="text/javascript"> - try { - var theme = localStorage.getItem('mdbook-theme'); - var sidebar = localStorage.getItem('mdbook-sidebar'); - if (theme.startsWith('"') && theme.endsWith('"')) { - localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); - } - if (sidebar.startsWith('"') && sidebar.endsWith('"')) { - localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); - } - } catch (e) { } - </script> - - <!-- Set the theme before any content is loaded, prevents flash --> - <script type="text/javascript"> - var theme; - try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } - if (theme === null || theme === undefined) { theme = default_theme; } - var html = document.querySelector('html'); - html.classList.remove('no-js') - html.classList.remove('light') - html.classList.add(theme); - html.classList.add('js'); - </script> - - <!-- Hide / unhide sidebar before it is displayed --> - <script type="text/javascript"> - var html = document.querySelector('html'); - var sidebar = 'hidden'; - if (document.body.clientWidth >= 1080) { - try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } - sidebar = sidebar || 'visible'; - } - html.classList.remove('sidebar-visible'); - html.classList.add("sidebar-" + sidebar); - </script> - - <nav id="sidebar" class="sidebar" aria-label="Table of contents"> - <div class="sidebar-scrollbox"> - <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="../welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="../setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="../postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="../reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="../turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="../delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="../upgrading/index.html" class="active">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="../MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="../federate.html">Federation</a></li><li class="chapter-item expanded "><a href="../usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="../usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="../structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="../usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="../sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="../password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="../jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="../CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="../application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="../server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="../url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="../user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="../message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="../modules.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="../spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="../presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="../workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="../systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="../usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="../admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="../admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="../admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="../admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="../admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="../admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="../admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="../admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="../admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../admin_api/shutdown_room.html">Shutdown Room</a></li><li class="chapter-item expanded "><a href="../admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="../admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="../admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="../manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="../metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="../usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="../development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="../code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="../dev/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="../opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="../development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="../replication.html">Replication</a></li><li class="chapter-item expanded "><a href="../tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="../development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../dev/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="../dev/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="../media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="../room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="../deprecation_policy.html">Dependency Deprecation Policy</a></li></ol> - </div> - <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div> - </nav> - - <div id="page-wrapper" class="page-wrapper"> - - <div class="page"> - - <div id="menu-bar-hover-placeholder"></div> - <div id="menu-bar" class="menu-bar sticky bordered"> - <div class="left-buttons"> - <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> - <i class="fa fa-bars"></i> - </button> - <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list"> - <i class="fa fa-paint-brush"></i> - </button> - <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> - <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li> - <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> - <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> - <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> - <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> - </ul> - - <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar"> - <i class="fa fa-search"></i> - </button> - - </div> - - <h1 class="menu-title">Synapse</h1> - - <div class="right-buttons"> - - <a href="../print.html" title="Print this book" aria-label="Print this book"> - <i id="print-button" class="fa fa-print"></i> - </a> - - - <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository"> - <i id="git-repository-button" class="fa fa-github"></i> - </a> - - - <a href="https://github.com/matrix-org/synapse/edit/develop/docs/upgrading/README.md" title="Suggest an edit" aria-label="Suggest an edit"> - <i id="git-edit-button" class="fa fa-edit"></i> - </a> - - - </div> - </div> - - - <div id="search-wrapper" class="hidden"> - <form id="searchbar-outer" class="searchbar-outer"> - <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> - </form> - <div id="searchresults-outer" class="searchresults-outer hidden"> - <div id="searchresults-header" class="searchresults-header"></div> - <ul id="searchresults"> - </ul> - </div> - </div> - - - <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> - <script type="text/javascript"> - document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); - document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); - Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { - link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); - }); - </script> - - <div id="content" class="content"> - <main> - <!-- Page table of contents --> - <div class="sidetoc"> - <nav class="pagetoc"></nav> - </div> - - <!-- - Include the contents of UPGRADE.rst from the project root without moving it, which may - break links around the internet. Additionally, note that SUMMARY.md is unable to - directly link to content outside of the docs/ directory. So we use this file as a - redirection. ---> -<h1 id="upgrading-synapse"><a class="header" href="#upgrading-synapse">Upgrading Synapse</a></h1> -<p>Before upgrading check if any special steps are required to upgrade from the -version you currently have installed to the current version of Synapse. The extra -instructions that may be required are listed later in this document.</p> -<ul> -<li> -<p>Check that your versions of Python and PostgreSQL are still supported.</p> -<p>Synapse follows upstream lifecycles for <code>Python</code>_ and <code>PostgreSQL</code>_, and -removes support for versions which are no longer maintained.</p> -<p>The website https://endoflife.date also offers convenient summaries.</p> -<p>.. _Python: https://devguide.python.org/devcycle/#end-of-life-branches -.. _PostgreSQL: https://www.postgresql.org/support/versioning/</p> -</li> -<li> -<p>If Synapse was installed using <code>prebuilt packages <INSTALL.md#prebuilt-packages></code>_, you will need to follow the normal process -for upgrading those packages.</p> -</li> -<li> -<p>If Synapse was installed from source, then:</p> -<ol> -<li> -<p>Activate the virtualenv before upgrading. For example, if Synapse is -installed in a virtualenv in <code>~/synapse/env</code> then run:</p> -<p>.. code:: bash</p> -<p>source ~/synapse/env/bin/activate</p> -</li> -<li> -<p>If Synapse was installed using pip then upgrade to the latest version by -running:</p> -<p>.. code:: bash</p> -<p>pip install --upgrade matrix-synapse</p> -<p>If Synapse was installed using git then upgrade to the latest version by -running:</p> -<p>.. code:: bash</p> -<p>git pull -pip install --upgrade .</p> -</li> -<li> -<p>Restart Synapse:</p> -<p>.. code:: bash</p> -<p>./synctl restart</p> -</li> -</ol> -</li> -</ul> -<p>To check whether your update was successful, you can check the running server -version with:</p> -<p>.. code:: bash</p> -<pre><code># you may need to replace 'localhost:8008' if synapse is not configured -# to listen on port 8008. - -curl http://localhost:8008/_synapse/admin/v1/server_version -</code></pre> -<h2 id="rolling-back-to-older-versions"><a class="header" href="#rolling-back-to-older-versions">Rolling back to older versions</a></h2> -<p>Rolling back to previous releases can be difficult, due to database schema -changes between releases. Where we have been able to test the rollback process, -this will be noted below.</p> -<p>In general, you will need to undo any changes made during the upgrade process, -for example:</p> -<ul> -<li> -<p>pip:</p> -<p>.. code:: bash</p> -<p>source env/bin/activate</p> -<h1 id="replace-130-accordingly"><a class="header" href="#replace-130-accordingly">replace <code>1.3.0</code> accordingly:</a></h1> -<p>pip install matrix-synapse==1.3.0</p> -</li> -<li> -<p>Debian:</p> -<p>.. code:: bash</p> -<h1 id="replace-130-and-stretch-accordingly"><a class="header" href="#replace-130-and-stretch-accordingly">replace <code>1.3.0</code> and <code>stretch</code> accordingly:</a></h1> -<p>wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb -dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb</p> -</li> -</ul> -<h1 id="upgrading-to-v1370"><a class="header" href="#upgrading-to-v1370">Upgrading to v1.37.0</a></h1> -<h2 id="deprecation-of-the-current-spam-checker-interface"><a class="header" href="#deprecation-of-the-current-spam-checker-interface">Deprecation of the current spam checker interface</a></h2> -<p>The current spam checker interface is deprecated in favour of a new generic modules system. -Authors of spam checker modules can refer to <code>this documentation <https://matrix-org.github.io/synapse/develop/modules.html#porting-an-existing-module-that-uses-the-old-interface></code>_ -to update their modules. Synapse administrators can refer to <code>this documentation <https://matrix-org.github.io/synapse/develop/modules.html#using-modules></code>_ -to update their configuration once the modules they are using have been updated.</p> -<p>We plan to remove support for the current spam checker interface in August 2021.</p> -<p>More module interfaces will be ported over to this new generic system in future versions -of Synapse.</p> -<h1 id="upgrading-to-v1340"><a class="header" href="#upgrading-to-v1340">Upgrading to v1.34.0</a></h1> -<h2 id="room_invite_state_types-configuration-setting"><a class="header" href="#room_invite_state_types-configuration-setting"><code>room_invite_state_types</code> configuration setting</a></h2> -<p>The <code>room_invite_state_types</code> configuration setting has been deprecated and -replaced with <code>room_prejoin_state</code>. See the <code>sample configuration file <https://github.com/matrix-org/synapse/blob/v1.34.0/docs/sample_config.yaml#L1515></code>_.</p> -<p>If you have set <code>room_invite_state_types</code> to the default value you should simply -remove it from your configuration file. The default value used to be:</p> -<p>.. code:: yaml</p> -<p>room_invite_state_types: -- "m.room.join_rules" -- "m.room.canonical_alias" -- "m.room.avatar" -- "m.room.encryption" -- "m.room.name"</p> -<p>If you have customised this value, you should remove <code>room_invite_state_types</code> and -configure <code>room_prejoin_state</code> instead.</p> -<h1 id="upgrading-to-v1330"><a class="header" href="#upgrading-to-v1330">Upgrading to v1.33.0</a></h1> -<h2 id="account-validity-html-templates-can-now-display-a-users-expiration-date"><a class="header" href="#account-validity-html-templates-can-now-display-a-users-expiration-date">Account Validity HTML templates can now display a user's expiration date</a></h2> -<p>This may affect you if you have enabled the account validity feature, and have made use of a -custom HTML template specified by the <code>account_validity.template_dir</code> or <code>account_validity.account_renewed_html_path</code> -Synapse config options.</p> -<p>The template can now accept an <code>expiration_ts</code> variable, which represents the unix timestamp in milliseconds for the -future date of which their account has been renewed until. See the -<code>default template <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_renewed.html></code>_ -for an example of usage.</p> -<p>ALso note that a new HTML template, <code>account_previously_renewed.html</code>, has been added. This is is shown to users -when they attempt to renew their account with a valid renewal token that has already been used before. The default -template contents can been found -<code>here <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_previously_renewed.html></code>_, -and can also accept an <code>expiration_ts</code> variable. This template replaces the error message users would previously see -upon attempting to use a valid renewal token more than once.</p> -<h1 id="upgrading-to-v1320"><a class="header" href="#upgrading-to-v1320">Upgrading to v1.32.0</a></h1> -<h2 id="regression-causing-connected-prometheus-instances-to-become-overwhelmed"><a class="header" href="#regression-causing-connected-prometheus-instances-to-become-overwhelmed">Regression causing connected Prometheus instances to become overwhelmed</a></h2> -<p>This release introduces <code>a regression <https://github.com/matrix-org/synapse/issues/9853></code>_ -that can overwhelm connected Prometheus instances. This issue is not present in -Synapse v1.32.0rc1.</p> -<p>If you have been affected, please downgrade to 1.31.0. You then may need to -remove excess writeahead logs in order for Prometheus to recover. Instructions -for doing so are provided -<code>here <https://github.com/matrix-org/synapse/pull/9854#issuecomment-823472183></code>_.</p> -<h2 id="dropping-support-for-old-python-postgres-and-sqlite-versions"><a class="header" href="#dropping-support-for-old-python-postgres-and-sqlite-versions">Dropping support for old Python, Postgres and SQLite versions</a></h2> -<p>In line with our <code>deprecation policy <https://github.com/matrix-org/synapse/blob/release-v1.32.0/docs/deprecation_policy.md></code>_, -we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no longer supported upstream.</p> -<p>This release of Synapse requires Python 3.6+ and PostgresSQL 9.6+ or SQLite 3.22+.</p> -<h2 id="removal-of-old-list-accounts-admin-api"><a class="header" href="#removal-of-old-list-accounts-admin-api">Removal of old List Accounts Admin API</a></h2> -<p>The deprecated v1 "list accounts" admin API (<code>GET /_synapse/admin/v1/users/<user_id></code>) has been removed in this version.</p> -<p>The <code>v2 list accounts API <https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#list-accounts></code>_ -has been available since Synapse 1.7.0 (2019-12-13), and is accessible under <code>GET /_synapse/admin/v2/users</code>.</p> -<p>The deprecation of the old endpoint was announced with Synapse 1.28.0 (released on 2021-02-25).</p> -<h2 id="application-services-must-use-type-mloginapplication_service-when-registering-users"><a class="header" href="#application-services-must-use-type-mloginapplication_service-when-registering-users">Application Services must use type <code>m.login.application_service</code> when registering users</a></h2> -<p>In compliance with the -<code>Application Service spec <https://matrix.org/docs/spec/application_service/r0.1.2#server-admin-style-permissions></code>_, -Application Services are now required to use the <code>m.login.application_service</code> type when registering users via the -<code>/_matrix/client/r0/register</code> endpoint. This behaviour was deprecated in Synapse v1.30.0.</p> -<p>Please ensure your Application Services are up to date.</p> -<h1 id="upgrading-to-v1290"><a class="header" href="#upgrading-to-v1290">Upgrading to v1.29.0</a></h1> -<h2 id="requirement-for-x-forwarded-proto-header"><a class="header" href="#requirement-for-x-forwarded-proto-header">Requirement for X-Forwarded-Proto header</a></h2> -<p>When using Synapse with a reverse proxy (in particular, when using the -<code>x_forwarded</code> option on an HTTP listener), Synapse now expects to receive an -<code>X-Forwarded-Proto</code> header on incoming HTTP requests. If it is not set, Synapse -will log a warning on each received request.</p> -<p>To avoid the warning, administrators using a reverse proxy should ensure that -the reverse proxy sets <code>X-Forwarded-Proto</code> header to <code>https</code> or <code>http</code> to -indicate the protocol used by the client.</p> -<p>Synapse also requires the <code>Host</code> header to be preserved.</p> -<p>See the <code>reverse proxy documentation <docs/reverse_proxy.md></code>_, where the -example configurations have been updated to show how to set these headers.</p> -<p>(Users of <code>Caddy <https://caddyserver.com/></code>_ are unaffected, since we believe it -sets <code>X-Forwarded-Proto</code> by default.)</p> -<h1 id="upgrading-to-v1270"><a class="header" href="#upgrading-to-v1270">Upgrading to v1.27.0</a></h1> -<h2 id="changes-to-callback-uri-for-oauth2--openid-connect-and-saml2"><a class="header" href="#changes-to-callback-uri-for-oauth2--openid-connect-and-saml2">Changes to callback URI for OAuth2 / OpenID Connect and SAML2</a></h2> -<p>This version changes the URI used for callbacks from OAuth2 and SAML2 identity providers:</p> -<ul> -<li> -<p>If your server is configured for single sign-on via an OpenID Connect or OAuth2 identity -provider, you will need to add <code>[synapse public baseurl]/_synapse/client/oidc/callback</code> -to the list of permitted "redirect URIs" at the identity provider.</p> -<p>See <code>docs/openid.md <docs/openid.md></code>_ for more information on setting up OpenID -Connect.</p> -</li> -<li> -<p>If your server is configured for single sign-on via a SAML2 identity provider, you will -need to add <code>[synapse public baseurl]/_synapse/client/saml2/authn_response</code> as a permitted -"ACS location" (also known as "allowed callback URLs") at the identity provider.</p> -<p>The "Issuer" in the "AuthnRequest" to the SAML2 identity provider is also updated to -<code>[synapse public baseurl]/_synapse/client/saml2/metadata.xml</code>. If your SAML2 identity -provider uses this property to validate or otherwise identify Synapse, its configuration -will need to be updated to use the new URL. Alternatively you could create a new, separate -"EntityDescriptor" in your SAML2 identity provider with the new URLs and leave the URLs in -the existing "EntityDescriptor" as they were.</p> -</li> -</ul> -<h2 id="changes-to-html-templates"><a class="header" href="#changes-to-html-templates">Changes to HTML templates</a></h2> -<p>The HTML templates for SSO and email notifications now have <code>Jinja2's autoescape <https://jinja.palletsprojects.com/en/2.11.x/api/#autoescaping></code>_ -enabled for files ending in <code>.html</code>, <code>.htm</code>, and <code>.xml</code>. If you have customised -these templates and see issues when viewing them you might need to update them. -It is expected that most configurations will need no changes.</p> -<p>If you have customised the templates <em>names</em> for these templates, it is recommended -to verify they end in <code>.html</code> to ensure autoescape is enabled.</p> -<p>The above applies to the following templates:</p> -<ul> -<li><code>add_threepid.html</code></li> -<li><code>add_threepid_failure.html</code></li> -<li><code>add_threepid_success.html</code></li> -<li><code>notice_expiry.html</code></li> -<li><code>notice_expiry.html</code></li> -<li><code>notif_mail.html</code> (which, by default, includes <code>room.html</code> and <code>notif.html</code>)</li> -<li><code>password_reset.html</code></li> -<li><code>password_reset_confirmation.html</code></li> -<li><code>password_reset_failure.html</code></li> -<li><code>password_reset_success.html</code></li> -<li><code>registration.html</code></li> -<li><code>registration_failure.html</code></li> -<li><code>registration_success.html</code></li> -<li><code>sso_account_deactivated.html</code></li> -<li><code>sso_auth_bad_user.html</code></li> -<li><code>sso_auth_confirm.html</code></li> -<li><code>sso_auth_success.html</code></li> -<li><code>sso_error.html</code></li> -<li><code>sso_login_idp_picker.html</code></li> -<li><code>sso_redirect_confirm.html</code></li> -</ul> -<h1 id="upgrading-to-v1260"><a class="header" href="#upgrading-to-v1260">Upgrading to v1.26.0</a></h1> -<h2 id="rolling-back-to-v1250-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1250-after-a-failed-upgrade">Rolling back to v1.25.0 after a failed upgrade</a></h2> -<p>v1.26.0 includes a lot of large changes. If something problematic occurs, you -may want to roll-back to a previous version of Synapse. Because v1.26.0 also -includes a new database schema version, reverting that version is also required -alongside the generic rollback instructions mentioned above. In short, to roll -back to v1.25.0 you need to:</p> -<ol> -<li> -<p>Stop the server</p> -</li> -<li> -<p>Decrease the schema version in the database:</p> -<p>.. code:: sql</p> -<p>UPDATE schema_version SET version = 58;</p> -</li> -<li> -<p>Delete the ignored users & chain cover data:</p> -<p>.. code:: sql</p> -<p>DROP TABLE IF EXISTS ignored_users; -UPDATE rooms SET has_auth_chain_index = false;</p> -<p>For PostgreSQL run:</p> -<p>.. code:: sql</p> -<p>TRUNCATE event_auth_chain_links; -TRUNCATE event_auth_chains;</p> -<p>For SQLite run:</p> -<p>.. code:: sql</p> -<p>DELETE FROM event_auth_chain_links; -DELETE FROM event_auth_chains;</p> -</li> -<li> -<p>Mark the deltas as not run (so they will re-run on upgrade).</p> -<p>.. code:: sql</p> -<p>DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/01ignored_user.py"; -DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/06chain_cover_index.sql";</p> -</li> -<li> -<p>Downgrade Synapse by following the instructions for your installation method -in the "Rolling back to older versions" section above.</p> -</li> -</ol> -<h1 id="upgrading-to-v1250"><a class="header" href="#upgrading-to-v1250">Upgrading to v1.25.0</a></h1> -<h2 id="last-release-supporting-python-35"><a class="header" href="#last-release-supporting-python-35">Last release supporting Python 3.5</a></h2> -<p>This is the last release of Synapse which guarantees support with Python 3.5, -which passed its upstream End of Life date several months ago.</p> -<p>We will attempt to maintain support through March 2021, but without guarantees.</p> -<p>In the future, Synapse will follow upstream schedules for ending support of -older versions of Python and PostgreSQL. Please upgrade to at least Python 3.6 -and PostgreSQL 9.6 as soon as possible.</p> -<h2 id="blacklisting-ip-ranges"><a class="header" href="#blacklisting-ip-ranges">Blacklisting IP ranges</a></h2> -<p>Synapse v1.25.0 includes new settings, <code>ip_range_blacklist</code> and -<code>ip_range_whitelist</code>, for controlling outgoing requests from Synapse for federation, -identity servers, push, and for checking key validity for third-party invite events. -The previous setting, <code>federation_ip_range_blacklist</code>, is deprecated. The new -<code>ip_range_blacklist</code> defaults to private IP ranges if it is not defined.</p> -<p>If you have never customised <code>federation_ip_range_blacklist</code> it is recommended -that you remove that setting.</p> -<p>If you have customised <code>federation_ip_range_blacklist</code> you should update the -setting name to <code>ip_range_blacklist</code>.</p> -<p>If you have a custom push server that is reached via private IP space you may -need to customise <code>ip_range_blacklist</code> or <code>ip_range_whitelist</code>.</p> -<h1 id="upgrading-to-v1240"><a class="header" href="#upgrading-to-v1240">Upgrading to v1.24.0</a></h1> -<h2 id="custom-openid-connect-mapping-provider-breaking-change"><a class="header" href="#custom-openid-connect-mapping-provider-breaking-change">Custom OpenID Connect mapping provider breaking change</a></h2> -<p>This release allows the OpenID Connect mapping provider to perform normalisation -of the localpart of the Matrix ID. This allows for the mapping provider to -specify different algorithms, instead of the <a href="https://matrix.org/docs/spec/appendices#mapping-from-other-character-sets">default way</a>.</p> -<p>If your Synapse configuration uses a custom mapping provider -(<code>oidc_config.user_mapping_provider.module</code> is specified and not equal to -<code>synapse.handlers.oidc_handler.JinjaOidcMappingProvider</code>) then you <em>must</em> ensure -that <code>map_user_attributes</code> of the mapping provider performs some normalisation -of the <code>localpart</code> returned. To match previous behaviour you can use the -<code>map_username_to_mxid_localpart</code> function provided by Synapse. An example is -shown below:</p> -<p>.. code-block:: python</p> -<p>from synapse.types import map_username_to_mxid_localpart</p> -<p>class MyMappingProvider: -def map_user_attributes(self, userinfo, token): -# ... your custom logic ... -sso_user_id = ... -localpart = map_username_to_mxid_localpart(sso_user_id)</p> -<pre><code> return {"localpart": localpart} -</code></pre> -<h2 id="removal-historical-synapse-admin-api"><a class="header" href="#removal-historical-synapse-admin-api">Removal historical Synapse Admin API</a></h2> -<p>Historically, the Synapse Admin API has been accessible under:</p> -<ul> -<li><code>/_matrix/client/api/v1/admin</code></li> -<li><code>/_matrix/client/unstable/admin</code></li> -<li><code>/_matrix/client/r0/admin</code></li> -<li><code>/_synapse/admin/v1</code></li> -</ul> -<p>The endpoints with <code>/_matrix/client/*</code> prefixes have been removed as of v1.24.0. -The Admin API is now only accessible under:</p> -<ul> -<li><code>/_synapse/admin/v1</code></li> -</ul> -<p>The only exception is the <code>/admin/whois</code> endpoint, which is -<code>also available via the client-server API <https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid></code>_.</p> -<p>The deprecation of the old endpoints was announced with Synapse 1.20.0 (released -on 2020-09-22) and makes it easier for homeserver admins to lock down external -access to the Admin API endpoints.</p> -<h1 id="upgrading-to-v1230"><a class="header" href="#upgrading-to-v1230">Upgrading to v1.23.0</a></h1> -<h2 id="structured-logging-configuration-breaking-changes"><a class="header" href="#structured-logging-configuration-breaking-changes">Structured logging configuration breaking changes</a></h2> -<p>This release deprecates use of the <code>structured: true</code> logging configuration for -structured logging. If your logging configuration contains <code>structured: true</code> -then it should be modified based on the <code>structured logging documentation <https://github.com/matrix-org/synapse/blob/master/docs/structured_logging.md></code>_.</p> -<p>The <code>structured</code> and <code>drains</code> logging options are now deprecated and should -be replaced by standard logging configuration of <code>handlers</code> and <code>formatters</code>.</p> -<p>A future will release of Synapse will make using <code>structured: true</code> an error.</p> -<h1 id="upgrading-to-v1220"><a class="header" href="#upgrading-to-v1220">Upgrading to v1.22.0</a></h1> -<h2 id="thirdpartyeventrules-breaking-changes"><a class="header" href="#thirdpartyeventrules-breaking-changes">ThirdPartyEventRules breaking changes</a></h2> -<p>This release introduces a backwards-incompatible change to modules making use of -<code>ThirdPartyEventRules</code> in Synapse. If you make use of a module defined under the -<code>third_party_event_rules</code> config option, please make sure it is updated to handle -the below change:</p> -<p>The <code>http_client</code> argument is no longer passed to modules as they are initialised. Instead, -modules are expected to make use of the <code>http_client</code> property on the <code>ModuleApi</code> class. -Modules are now passed a <code>module_api</code> argument during initialisation, which is an instance of -<code>ModuleApi</code>. <code>ModuleApi</code> instances have a <code>http_client</code> property which acts the same as -the <code>http_client</code> argument previously passed to <code>ThirdPartyEventRules</code> modules.</p> -<h1 id="upgrading-to-v1210"><a class="header" href="#upgrading-to-v1210">Upgrading to v1.21.0</a></h1> -<h2 id="forwarding-_synapseclient-through-your-reverse-proxy"><a class="header" href="#forwarding-_synapseclient-through-your-reverse-proxy">Forwarding <code>/_synapse/client</code> through your reverse proxy</a></h2> -<p>The <code>reverse proxy documentation <https://github.com/matrix-org/synapse/blob/develop/docs/reverse_proxy.md></code>_ has been updated -to include reverse proxy directives for <code>/_synapse/client/*</code> endpoints. As the user password -reset flow now uses endpoints under this prefix, <strong>you must update your reverse proxy -configurations for user password reset to work</strong>.</p> -<p>Additionally, note that the <code>Synapse worker documentation <https://github.com/matrix-org/synapse/blob/develop/docs/workers.md></code>_ has been updated to -state that the <code>/_synapse/client/password_reset/email/submit_token</code> endpoint can be handled -by all workers. If you make use of Synapse's worker feature, please update your reverse proxy -configuration to reflect this change.</p> -<h2 id="new-html-templates"><a class="header" href="#new-html-templates">New HTML templates</a></h2> -<p>A new HTML template, -<code>password_reset_confirmation.html <https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html></code>_, -has been added to the <code>synapse/res/templates</code> directory. If you are using a -custom template directory, you may want to copy the template over and modify it.</p> -<p>Note that as of v1.20.0, templates do not need to be included in custom template -directories for Synapse to start. The default templates will be used if a custom -template cannot be found.</p> -<p>This page will appear to the user after clicking a password reset link that has -been emailed to them.</p> -<p>To complete password reset, the page must include a way to make a <code>POST</code> -request to -<code>/_synapse/client/password_reset/{medium}/submit_token</code> -with the query parameters from the original link, presented as a URL-encoded form. See the file -itself for more details.</p> -<h2 id="updated-single-sign-on-html-templates"><a class="header" href="#updated-single-sign-on-html-templates">Updated Single Sign-on HTML Templates</a></h2> -<p>The <code>saml_error.html</code> template was removed from Synapse and replaced with the -<code>sso_error.html</code> template. If your Synapse is configured to use SAML and a -custom <code>sso_redirect_confirm_template_dir</code> configuration then any customisations -of the <code>saml_error.html</code> template will need to be merged into the <code>sso_error.html</code> -template. These templates are similar, but the parameters are slightly different:</p> -<ul> -<li>The <code>msg</code> parameter should be renamed to <code>error_description</code>.</li> -<li>There is no longer a <code>code</code> parameter for the response code.</li> -<li>A string <code>error</code> parameter is available that includes a short hint of why a -user is seeing the error page.</li> -</ul> -<h1 id="upgrading-to-v1180"><a class="header" href="#upgrading-to-v1180">Upgrading to v1.18.0</a></h1> -<h2 id="docker--py3-suffix-will-be-removed-in-future-versions"><a class="header" href="#docker--py3-suffix-will-be-removed-in-future-versions">Docker <code>-py3</code> suffix will be removed in future versions</a></h2> -<p>From 10th August 2020, we will no longer publish Docker images with the <code>-py3</code> tag suffix. The images tagged with the <code>-py3</code> suffix have been identical to the non-suffixed tags since release 0.99.0, and the suffix is obsolete.</p> -<p>On 10th August, we will remove the <code>latest-py3</code> tag. Existing per-release tags (such as <code>v1.18.0-py3</code>) will not be removed, but no new <code>-py3</code> tags will be added.</p> -<p>Scripts relying on the <code>-py3</code> suffix will need to be updated.</p> -<h2 id="redis-replication-is-now-recommended-in-lieu-of-tcp-replication"><a class="header" href="#redis-replication-is-now-recommended-in-lieu-of-tcp-replication">Redis replication is now recommended in lieu of TCP replication</a></h2> -<p>When setting up worker processes, we now recommend the use of a Redis server for replication. <strong>The old direct TCP connection method is deprecated and will be removed in a future release.</strong> -See <code>docs/workers.md <docs/workers.md></code>_ for more details.</p> -<h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1> -<p>This version includes a database update which is run as part of the upgrade, -and which may take a couple of minutes in the case of a large server. Synapse -will not respond to HTTP requests while this update is taking place.</p> -<h1 id="upgrading-to-v1130"><a class="header" href="#upgrading-to-v1130">Upgrading to v1.13.0</a></h1> -<h2 id="incorrect-database-migration-in-old-synapse-versions"><a class="header" href="#incorrect-database-migration-in-old-synapse-versions">Incorrect database migration in old synapse versions</a></h2> -<p>A bug was introduced in Synapse 1.4.0 which could cause the room directory to -be incomplete or empty if Synapse was upgraded directly from v1.2.1 or -earlier, to versions between v1.4.0 and v1.12.x.</p> -<p>This will <em>not</em> be a problem for Synapse installations which were:</p> -<ul> -<li>created at v1.4.0 or later,</li> -<li>upgraded via v1.3.x, or</li> -<li>upgraded straight from v1.2.1 or earlier to v1.13.0 or later.</li> -</ul> -<p>If completeness of the room directory is a concern, installations which are -affected can be repaired as follows:</p> -<ol> -<li> -<p>Run the following sql from a <code>psql</code> or <code>sqlite3</code> console:</p> -<p>.. code:: sql</p> -<p>INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES -('populate_stats_process_rooms', '{}', 'current_state_events_membership');</p> -<p>INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES -('populate_stats_process_users', '{}', 'populate_stats_process_rooms');</p> -</li> -<li> -<p>Restart synapse.</p> -</li> -</ol> -<h2 id="new-single-sign-on-html-templates"><a class="header" href="#new-single-sign-on-html-templates">New Single Sign-on HTML Templates</a></h2> -<p>New templates (<code>sso_auth_confirm.html</code>, <code>sso_auth_success.html</code>, and -<code>sso_account_deactivated.html</code>) were added to Synapse. If your Synapse is -configured to use SSO and a custom <code>sso_redirect_confirm_template_dir</code> -configuration then these templates will need to be copied from -<code>synapse/res/templates <synapse/res/templates></code>_ into that directory.</p> -<h2 id="synapse-sso-plugins-method-deprecation"><a class="header" href="#synapse-sso-plugins-method-deprecation">Synapse SSO Plugins Method Deprecation</a></h2> -<p>Plugins using the <code>complete_sso_login</code> method of -<code>synapse.module_api.ModuleApi</code> should update to using the async/await -version <code>complete_sso_login_async</code> which includes additional checks. The -non-async version is considered deprecated.</p> -<h2 id="rolling-back-to-v1124-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1124-after-a-failed-upgrade">Rolling back to v1.12.4 after a failed upgrade</a></h2> -<p>v1.13.0 includes a lot of large changes. If something problematic occurs, you -may want to roll-back to a previous version of Synapse. Because v1.13.0 also -includes a new database schema version, reverting that version is also required -alongside the generic rollback instructions mentioned above. In short, to roll -back to v1.12.4 you need to:</p> -<ol> -<li> -<p>Stop the server</p> -</li> -<li> -<p>Decrease the schema version in the database:</p> -<p>.. code:: sql</p> -<p>UPDATE schema_version SET version = 57;</p> -</li> -<li> -<p>Downgrade Synapse by following the instructions for your installation method -in the "Rolling back to older versions" section above.</p> -</li> -</ol> -<h1 id="upgrading-to-v1120"><a class="header" href="#upgrading-to-v1120">Upgrading to v1.12.0</a></h1> -<p>This version includes a database update which is run as part of the upgrade, -and which may take some time (several hours in the case of a large -server). Synapse will not respond to HTTP requests while this update is taking -place.</p> -<p>This is only likely to be a problem in the case of a server which is -participating in many rooms.</p> -<ol start="0"> -<li> -<p>As with all upgrades, it is recommended that you have a recent backup of -your database which can be used for recovery in the event of any problems.</p> -</li> -<li> -<p>As an initial check to see if you will be affected, you can try running the -following query from the <code>psql</code> or <code>sqlite3</code> console. It is safe to run it -while Synapse is still running.</p> -<p>.. code:: sql</p> -<p>SELECT MAX(q.v) FROM ( -SELECT ( -SELECT ej.json AS v -FROM state_events se INNER JOIN event_json ej USING (event_id) -WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key='' -LIMIT 1 -) FROM rooms WHERE rooms.room_version IS NULL -) q;</p> -<p>This query will take about the same amount of time as the upgrade process: ie, -if it takes 5 minutes, then it is likely that Synapse will be unresponsive for -5 minutes during the upgrade.</p> -<p>If you consider an outage of this duration to be acceptable, no further -action is necessary and you can simply start Synapse 1.12.0.</p> -<p>If you would prefer to reduce the downtime, continue with the steps below.</p> -</li> -<li> -<p>The easiest workaround for this issue is to manually -create a new index before upgrading. On PostgreSQL, his can be done as follows:</p> -<p>.. code:: sql</p> -<p>CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index -ON state_events(room_id) WHERE type = 'm.room.create';</p> -<p>The above query may take some time, but is also safe to run while Synapse is -running.</p> -<p>We assume that no SQLite users have databases large enough to be -affected. If you <em>are</em> affected, you can run a similar query, omitting the -<code>CONCURRENTLY</code> keyword. Note however that this operation may in itself cause -Synapse to stop running for some time. Synapse admins are reminded that -<code>SQLite is not recommended for use outside a test environment <https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql></code>_.</p> -</li> -<li> -<p>Once the index has been created, the <code>SELECT</code> query in step 1 above should -complete quickly. It is therefore safe to upgrade to Synapse 1.12.0.</p> -</li> -<li> -<p>Once Synapse 1.12.0 has successfully started and is responding to HTTP -requests, the temporary index can be removed:</p> -<p>.. code:: sql</p> -<p>DROP INDEX tmp_upgrade_1_12_0_index;</p> -</li> -</ol> -<h1 id="upgrading-to-v1100"><a class="header" href="#upgrading-to-v1100">Upgrading to v1.10.0</a></h1> -<p>Synapse will now log a warning on start up if used with a PostgreSQL database -that has a non-recommended locale set.</p> -<p>See <code>docs/postgres.md <docs/postgres.md></code>_ for details.</p> -<h1 id="upgrading-to-v180"><a class="header" href="#upgrading-to-v180">Upgrading to v1.8.0</a></h1> -<p>Specifying a <code>log_file</code> config option will now cause Synapse to refuse to -start, and should be replaced by with the <code>log_config</code> option. Support for -the <code>log_file</code> option was removed in v1.3.0 and has since had no effect.</p> -<h1 id="upgrading-to-v170"><a class="header" href="#upgrading-to-v170">Upgrading to v1.7.0</a></h1> -<p>In an attempt to configure Synapse in a privacy preserving way, the default -behaviours of <code>allow_public_rooms_without_auth</code> and -<code>allow_public_rooms_over_federation</code> have been inverted. This means that by -default, only authenticated users querying the Client/Server API will be able -to query the room directory, and relatedly that the server will not share -room directory information with other servers over federation.</p> -<p>If your installation does not explicitly set these settings one way or the other -and you want either setting to be <code>true</code> then it will necessary to update -your homeserver configuration file accordingly.</p> -<p>For more details on the surrounding context see our <code>explainer <https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers></code>_.</p> -<h1 id="upgrading-to-v150"><a class="header" href="#upgrading-to-v150">Upgrading to v1.5.0</a></h1> -<p>This release includes a database migration which may take several minutes to -complete if there are a large number (more than a million or so) of entries in -the <code>devices</code> table. This is only likely to a be a problem on very large -installations.</p> -<h1 id="upgrading-to-v140"><a class="header" href="#upgrading-to-v140">Upgrading to v1.4.0</a></h1> -<h2 id="new-custom-templates"><a class="header" href="#new-custom-templates">New custom templates</a></h2> -<p>If you have configured a custom template directory with the -<code>email.template_dir</code> option, be aware that there are new templates regarding -registration and threepid management (see below) that must be included.</p> -<ul> -<li><code>registration.html</code> and <code>registration.txt</code></li> -<li><code>registration_success.html</code> and <code>registration_failure.html</code></li> -<li><code>add_threepid.html</code> and <code>add_threepid.txt</code></li> -<li><code>add_threepid_failure.html</code> and <code>add_threepid_success.html</code></li> -</ul> -<p>Synapse will expect these files to exist inside the configured template -directory, and <strong>will fail to start</strong> if they are absent. -To view the default templates, see <code>synapse/res/templates <https://github.com/matrix-org/synapse/tree/master/synapse/res/templates></code>_.</p> -<h2 id="3pid-verification-changes"><a class="header" href="#3pid-verification-changes">3pid verification changes</a></h2> -<p><strong>Note: As of this release, users will be unable to add phone numbers or email -addresses to their accounts, without changes to the Synapse configuration. This -includes adding an email address during registration.</strong></p> -<p>It is possible for a user to associate an email address or phone number -with their account, for a number of reasons:</p> -<ul> -<li>for use when logging in, as an alternative to the user id.</li> -<li>in the case of email, as an alternative contact to help with account recovery.</li> -<li>in the case of email, to receive notifications of missed messages.</li> -</ul> -<p>Before an email address or phone number can be added to a user's account, -or before such an address is used to carry out a password-reset, Synapse must -confirm the operation with the owner of the email address or phone number. -It does this by sending an email or text giving the user a link or token to confirm -receipt. This process is known as '3pid verification'. ('3pid', or 'threepid', -stands for third-party identifier, and we use it to refer to external -identifiers such as email addresses and phone numbers.)</p> -<p>Previous versions of Synapse delegated the task of 3pid verification to an -identity server by default. In most cases this server is <code>vector.im</code> or -<code>matrix.org</code>.</p> -<p>In Synapse 1.4.0, for security and privacy reasons, the homeserver will no -longer delegate this task to an identity server by default. Instead, -the server administrator will need to explicitly decide how they would like the -verification messages to be sent.</p> -<p>In the medium term, the <code>vector.im</code> and <code>matrix.org</code> identity servers will -disable support for delegated 3pid verification entirely. However, in order to -ease the transition, they will retain the capability for a limited -period. Delegated email verification will be disabled on Monday 2nd December -2019 (giving roughly 2 months notice). Disabling delegated SMS verification -will follow some time after that once SMS verification support lands in -Synapse.</p> -<p>Once delegated 3pid verification support has been disabled in the <code>vector.im</code> and -<code>matrix.org</code> identity servers, all Synapse versions that depend on those -instances will be unable to verify email and phone numbers through them. There -are no imminent plans to remove delegated 3pid verification from Sydent -generally. (Sydent is the identity server project that backs the <code>vector.im</code> and -<code>matrix.org</code> instances).</p> -<p>Email</p> -<pre><code>Following upgrade, to continue verifying email (e.g. as part of the -registration process), admins can either:- - -* Configure Synapse to use an email server. -* Run or choose an identity server which allows delegated email verification - and delegate to it. - -Configure SMTP in Synapse -+++++++++++++++++++++++++ - -To configure an SMTP server for Synapse, modify the configuration section -headed ``email``, and be sure to have at least the ``smtp_host, smtp_port`` -and ``notif_from`` fields filled out. - -You may also need to set ``smtp_user``, ``smtp_pass``, and -``require_transport_security``. - -See the `sample configuration file <docs/sample_config.yaml>`_ for more details -on these settings. - -Delegate email to an identity server -++++++++++++++++++++++++++++++++++++ - -Some admins will wish to continue using email verification as part of the -registration process, but will not immediately have an appropriate SMTP server -at hand. - -To this end, we will continue to support email verification delegation via the -``vector.im`` and ``matrix.org`` identity servers for two months. Support for -delegated email verification will be disabled on Monday 2nd December. - -The ``account_threepid_delegates`` dictionary defines whether the homeserver -should delegate an external server (typically an `identity server -<https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending -confirmation messages via email and SMS. - -So to delegate email verification, in ``homeserver.yaml``, set -``account_threepid_delegates.email`` to the base URL of an identity server. For -example: - -.. code:: yaml - - account_threepid_delegates: - email: https://example.com # Delegate email sending to example.com - -Note that ``account_threepid_delegates.email`` replaces the deprecated -``email.trust_identity_server_for_password_resets``: if -``email.trust_identity_server_for_password_resets`` is set to ``true``, and -``account_threepid_delegates.email`` is not set, then the first entry in -``trusted_third_party_id_servers`` will be used as the -``account_threepid_delegate`` for email. This is to ensure compatibility with -existing Synapse installs that set up external server handling for these tasks -before v1.4.0. If ``email.trust_identity_server_for_password_resets`` is -``true`` and no trusted identity server domains are configured, Synapse will -report an error and refuse to start. - -If ``email.trust_identity_server_for_password_resets`` is ``false`` or absent -and no ``email`` delegate is configured in ``account_threepid_delegates``, -then Synapse will send email verification messages itself, using the configured -SMTP server (see above). -that type. - -Phone numbers -</code></pre> -<p>Synapse does not support phone-number verification itself, so the only way to -maintain the ability for users to add phone numbers to their accounts will be -by continuing to delegate phone number verification to the <code>matrix.org</code> and -<code>vector.im</code> identity servers (or another identity server that supports SMS -sending).</p> -<p>The <code>account_threepid_delegates</code> dictionary defines whether the homeserver -should delegate an external server (typically an <code>identity server <https://matrix.org/docs/spec/identity_service/r0.2.1></code>_) to handle sending -confirmation messages via email and SMS.</p> -<p>So to delegate phone number verification, in <code>homeserver.yaml</code>, set -<code>account_threepid_delegates.msisdn</code> to the base URL of an identity -server. For example:</p> -<p>.. code:: yaml</p> -<p>account_threepid_delegates: -msisdn: https://example.com # Delegate sms sending to example.com</p> -<p>The <code>matrix.org</code> and <code>vector.im</code> identity servers will continue to support -delegated phone number verification via SMS until such time as it is possible -for admins to configure their servers to perform phone number verification -directly. More details will follow in a future release.</p> -<h2 id="rolling-back-to-v131"><a class="header" href="#rolling-back-to-v131">Rolling back to v1.3.1</a></h2> -<p>If you encounter problems with v1.4.0, it should be possible to roll back to -v1.3.1, subject to the following:</p> -<ul> -<li> -<p>The 'room statistics' engine was heavily reworked in this release (see -<code>#5971 <https://github.com/matrix-org/synapse/pull/5971></code>_), including -significant changes to the database schema, which are not easily -reverted. This will cause the room statistics engine to stop updating when -you downgrade.</p> -<p>The room statistics are essentially unused in v1.3.1 (in future versions of -Synapse, they will be used to populate the room directory), so there should -be no loss of functionality. However, the statistics engine will write errors -to the logs, which can be avoided by setting the following in -<code>homeserver.yaml</code>:</p> -<p>.. code:: yaml</p> -<p>stats: -enabled: false</p> -<p>Don't forget to re-enable it when you upgrade again, in preparation for its -use in the room directory!</p> -</li> -</ul> -<h1 id="upgrading-to-v120"><a class="header" href="#upgrading-to-v120">Upgrading to v1.2.0</a></h1> -<p>Some counter metrics have been renamed, with the old names deprecated. See -<code>the metrics documentation <docs/metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12></code>_ -for details.</p> -<h1 id="upgrading-to-v110"><a class="header" href="#upgrading-to-v110">Upgrading to v1.1.0</a></h1> -<p>Synapse v1.1.0 removes support for older Python and PostgreSQL versions, as -outlined in <code>our deprecation notice <https://matrix.org/blog/2019/04/08/synapse-deprecating-postgres-9-4-and-python-2-x></code>_.</p> -<h2 id="minimum-python-version"><a class="header" href="#minimum-python-version">Minimum Python Version</a></h2> -<p>Synapse v1.1.0 has a minimum Python requirement of Python 3.5. Python 3.6 or -Python 3.7 are recommended as they have improved internal string handling, -significantly reducing memory usage.</p> -<p>If you use current versions of the Matrix.org-distributed Debian packages or -Docker images, action is not required.</p> -<p>If you install Synapse in a Python virtual environment, please see "Upgrading to -v0.34.0" for notes on setting up a new virtualenv under Python 3.</p> -<h2 id="minimum-postgresql-version"><a class="header" href="#minimum-postgresql-version">Minimum PostgreSQL Version</a></h2> -<p>If using PostgreSQL under Synapse, you will need to use PostgreSQL 9.5 or above. -Please see the -<code>PostgreSQL documentation <https://www.postgresql.org/docs/11/upgrading.html></code>_ -for more details on upgrading your database.</p> -<h1 id="upgrading-to-v10"><a class="header" href="#upgrading-to-v10">Upgrading to v1.0</a></h1> -<h2 id="validation-of-tls-certificates"><a class="header" href="#validation-of-tls-certificates">Validation of TLS certificates</a></h2> -<p>Synapse v1.0 is the first release to enforce -validation of TLS certificates for the federation API. It is therefore -essential that your certificates are correctly configured. See the <code>FAQ <docs/MSC1711_certificates_FAQ.md></code>_ for more information.</p> -<p>Note, v1.0 installations will also no longer be able to federate with servers -that have not correctly configured their certificates.</p> -<p>In rare cases, it may be desirable to disable certificate checking: for -example, it might be essential to be able to federate with a given legacy -server in a closed federation. This can be done in one of two ways:-</p> -<ul> -<li>Configure the global switch <code>federation_verify_certificates</code> to <code>false</code>.</li> -<li>Configure a whitelist of server domains to trust via <code>federation_certificate_verification_whitelist</code>.</li> -</ul> -<p>See the <code>sample configuration file <docs/sample_config.yaml></code>_ -for more details on these settings.</p> -<h2 id="email"><a class="header" href="#email">Email</a></h2> -<p>When a user requests a password reset, Synapse will send an email to the -user to confirm the request.</p> -<p>Previous versions of Synapse delegated the job of sending this email to an -identity server. If the identity server was somehow malicious or became -compromised, it would be theoretically possible to hijack an account through -this means.</p> -<p>Therefore, by default, Synapse v1.0 will send the confirmation email itself. If -Synapse is not configured with an SMTP server, password reset via email will be -disabled.</p> -<p>To configure an SMTP server for Synapse, modify the configuration section -headed <code>email</code>, and be sure to have at least the <code>smtp_host</code>, <code>smtp_port</code> -and <code>notif_from</code> fields filled out. You may also need to set <code>smtp_user</code>, -<code>smtp_pass</code>, and <code>require_transport_security</code>.</p> -<p>If you are absolutely certain that you wish to continue using an identity -server for password resets, set <code>trust_identity_server_for_password_resets</code> to <code>true</code>.</p> -<p>See the <code>sample configuration file <docs/sample_config.yaml></code>_ -for more details on these settings.</p> -<h2 id="new-email-templates"><a class="header" href="#new-email-templates">New email templates</a></h2> -<p>Some new templates have been added to the default template directory for the purpose of the -homeserver sending its own password reset emails. If you have configured a custom -<code>template_dir</code> in your Synapse config, these files will need to be added.</p> -<p><code>password_reset.html</code> and <code>password_reset.txt</code> are HTML and plain text templates -respectively that contain the contents of what will be emailed to the user upon attempting to -reset their password via email. <code>password_reset_success.html</code> and -<code>password_reset_failure.html</code> are HTML files that the content of which (assuming no redirect -URL is set) will be shown to the user after they attempt to click the link in the email sent -to them.</p> -<h1 id="upgrading-to-v0990"><a class="header" href="#upgrading-to-v0990">Upgrading to v0.99.0</a></h1> -<p>Please be aware that, before Synapse v1.0 is released around March 2019, you -will need to replace any self-signed certificates with those verified by a -root CA. Information on how to do so can be found at <code>the ACME docs <docs/ACME.md></code>_.</p> -<p>For more information on configuring TLS certificates see the <code>FAQ <docs/MSC1711_certificates_FAQ.md></code>_.</p> -<h1 id="upgrading-to-v0340"><a class="header" href="#upgrading-to-v0340">Upgrading to v0.34.0</a></h1> -<ol> -<li> -<p>This release is the first to fully support Python 3. Synapse will now run on -Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to -Python 3, as it has been shown to give performance improvements.</p> -<p>For users who have installed Synapse into a virtualenv, we recommend doing -this by creating a new virtualenv. For example::</p> -<pre><code>virtualenv -p python3 ~/synapse/env3 -source ~/synapse/env3/bin/activate -pip install matrix-synapse -</code></pre> -<p>You can then start synapse as normal, having activated the new virtualenv::</p> -<pre><code>cd ~/synapse -source env3/bin/activate -synctl start -</code></pre> -<p>Users who have installed from distribution packages should see the relevant -package documentation. See below for notes on Debian packages.</p> -<ul> -<li> -<p>When upgrading to Python 3, you <strong>must</strong> make sure that your log files are -configured as UTF-8, by adding <code>encoding: utf8</code> to the -<code>RotatingFileHandler</code> configuration (if you have one) in your -<code><server>.log.config</code> file. For example, if your <code>log.config</code> file -contains::</p> -<p>handlers: -file: -class: logging.handlers.RotatingFileHandler -formatter: precise -filename: homeserver.log -maxBytes: 104857600 -backupCount: 10 -filters: [context] -console: -class: logging.StreamHandler -formatter: precise -filters: [context]</p> -<p>Then you should update this to be::</p> -<p>handlers: -file: -class: logging.handlers.RotatingFileHandler -formatter: precise -filename: homeserver.log -maxBytes: 104857600 -backupCount: 10 -filters: [context] -encoding: utf8 -console: -class: logging.StreamHandler -formatter: precise -filters: [context]</p> -<p>There is no need to revert this change if downgrading to Python 2.</p> -</li> -</ul> -<p>We are also making available Debian packages which will run Synapse on -Python 3. You can switch to these packages with <code>apt-get install matrix-synapse-py3</code>, however, please read <code>debian/NEWS <https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS></code>_ -before doing so. The existing <code>matrix-synapse</code> packages will continue to -use Python 2 for the time being.</p> -</li> -<li> -<p>This release removes the <code>riot.im</code> from the default list of trusted -identity servers.</p> -<p>If <code>riot.im</code> is in your homeserver's list of -<code>trusted_third_party_id_servers</code>, you should remove it. It was added in -case a hypothetical future identity server was put there. If you don't -remove it, users may be unable to deactivate their accounts.</p> -</li> -<li> -<p>This release no longer installs the (unmaintained) Matrix Console web client -as part of the default installation. It is possible to re-enable it by -installing it separately and setting the <code>web_client_location</code> config -option, but please consider switching to another client.</p> -</li> -</ol> -<h1 id="upgrading-to-v0337"><a class="header" href="#upgrading-to-v0337">Upgrading to v0.33.7</a></h1> -<p>This release removes the example email notification templates from -<code>res/templates</code> (they are now internal to the python package). This should -only affect you if you (a) deploy your Synapse instance from a git checkout or -a github snapshot URL, and (b) have email notifications enabled.</p> -<p>If you have email notifications enabled, you should ensure that -<code>email.template_dir</code> is either configured to point at a directory where you -have installed customised templates, or leave it unset to use the default -templates.</p> -<h1 id="upgrading-to-v0273"><a class="header" href="#upgrading-to-v0273">Upgrading to v0.27.3</a></h1> -<p>This release expands the anonymous usage stats sent if the opt-in -<code>report_stats</code> configuration is set to <code>true</code>. We now capture RSS memory -and cpu use at a very coarse level. This requires administrators to install -the optional <code>psutil</code> python module.</p> -<p>We would appreciate it if you could assist by ensuring this module is available -and <code>report_stats</code> is enabled. This will let us see if performance changes to -synapse are having an impact to the general community.</p> -<h1 id="upgrading-to-v0150"><a class="header" href="#upgrading-to-v0150">Upgrading to v0.15.0</a></h1> -<p>If you want to use the new URL previewing API (/_matrix/media/r0/preview_url) -then you have to explicitly enable it in the config and update your dependencies -dependencies. See README.rst for details.</p> -<h1 id="upgrading-to-v0110"><a class="header" href="#upgrading-to-v0110">Upgrading to v0.11.0</a></h1> -<p>This release includes the option to send anonymous usage stats to matrix.org, -and requires that administrators explictly opt in or out by setting the -<code>report_stats</code> option to either <code>true</code> or <code>false</code>.</p> -<p>We would really appreciate it if you could help our project out by reporting -anonymized usage statistics from your homeserver. Only very basic aggregate -data (e.g. number of users) will be reported, but it helps us to track the -growth of the Matrix community, and helps us to make Matrix a success, as well -as to convince other networks that they should peer with us.</p> -<h1 id="upgrading-to-v090"><a class="header" href="#upgrading-to-v090">Upgrading to v0.9.0</a></h1> -<p>Application services have had a breaking API change in this version.</p> -<p>They can no longer register themselves with a home server using the AS HTTP API. This -decision was made because a compromised application service with free reign to register -any regex in effect grants full read/write access to the home server if a regex of <code>.*</code> -is used. An attack where a compromised AS re-registers itself with <code>.*</code> was deemed too -big of a security risk to ignore, and so the ability to register with the HS remotely has -been removed.</p> -<p>It has been replaced by specifying a list of application service registrations in -<code>homeserver.yaml</code>::</p> -<p>app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]</p> -<p>Where <code>registration-01.yaml</code> looks like::</p> -<p>url: <String> # e.g. "https://my.application.service.com" -as_token: <String> -hs_token: <String> -sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token -namespaces: -users: -- exclusive: <Boolean> -regex: <String> # e.g. "@prefix_.*" -aliases: -- exclusive: <Boolean> -regex: <String> -rooms: -- exclusive: <Boolean> -regex: <String></p> -<h1 id="upgrading-to-v080"><a class="header" href="#upgrading-to-v080">Upgrading to v0.8.0</a></h1> -<p>Servers which use captchas will need to add their public key to::</p> -<p>static/client/register/register_config.js</p> -<pre><code>window.matrixRegistrationConfig = { - recaptcha_public_key: "YOUR_PUBLIC_KEY" -}; -</code></pre> -<p>This is required in order to support registration fallback (typically used on -mobile devices).</p> -<h1 id="upgrading-to-v070"><a class="header" href="#upgrading-to-v070">Upgrading to v0.7.0</a></h1> -<p>New dependencies are:</p> -<ul> -<li>pydenticon</li> -<li>simplejson</li> -<li>syutil</li> -<li>matrix-angular-sdk</li> -</ul> -<p>To pull in these dependencies in a virtual env, run::</p> -<pre><code>python synapse/python_dependencies.py | xargs -n 1 pip install -</code></pre> -<h1 id="upgrading-to-v060"><a class="header" href="#upgrading-to-v060">Upgrading to v0.6.0</a></h1> -<p>To pull in new dependencies, run::</p> -<pre><code>python setup.py develop --user -</code></pre> -<p>This update includes a change to the database schema. To upgrade you first need -to upgrade the database by running::</p> -<pre><code>python scripts/upgrade_db_to_v0.6.0.py <db> <server_name> <signing_key> -</code></pre> -<p>Where <code><db></code> is the location of the database, <code><server_name></code> is the -server name as specified in the synapse configuration, and <code><signing_key></code> is -the location of the signing key as specified in the synapse configuration.</p> -<p>This may take some time to complete. Failures of signatures and content hashes -can safely be ignored.</p> -<h1 id="upgrading-to-v051"><a class="header" href="#upgrading-to-v051">Upgrading to v0.5.1</a></h1> -<p>Depending on precisely when you installed v0.5.0 you may have ended up with -a stale release of the reference matrix webclient installed as a python module. -To uninstall it and ensure you are depending on the latest module, please run::</p> -<pre><code>$ pip uninstall syweb -</code></pre> -<h1 id="upgrading-to-v050"><a class="header" href="#upgrading-to-v050">Upgrading to v0.5.0</a></h1> -<p>The webclient has been split out into a seperate repository/pacakage in this -release. Before you restart your homeserver you will need to pull in the -webclient package by running::</p> -<p>python setup.py develop --user</p> -<p>This release completely changes the database schema and so requires upgrading -it before starting the new version of the homeserver.</p> -<p>The script "database-prepare-for-0.5.0.sh" should be used to upgrade the -database. This will save all user information, such as logins and profiles, -but will otherwise purge the database. This includes messages, which -rooms the home server was a member of and room alias mappings.</p> -<p>If you would like to keep your history, please take a copy of your database -file and ask for help in #matrix:matrix.org. The upgrade process is, -unfortunately, non trivial and requires human intervention to resolve any -resulting conflicts during the upgrade process.</p> -<p>Before running the command the homeserver should be first completely -shutdown. To run it, simply specify the location of the database, e.g.:</p> -<p>./scripts/database-prepare-for-0.5.0.sh "homeserver.db"</p> -<p>Once this has successfully completed it will be safe to restart the -homeserver. You may notice that the homeserver takes a few seconds longer to -restart than usual as it reinitializes the database.</p> -<p>On startup of the new version, users can either rejoin remote rooms using room -aliases or by being reinvited. Alternatively, if any other homeserver sends a -message to a room that the homeserver was previously in the local HS will -automatically rejoin the room.</p> -<h1 id="upgrading-to-v040"><a class="header" href="#upgrading-to-v040">Upgrading to v0.4.0</a></h1> -<p>This release needs an updated syutil version. Run::</p> -<pre><code>python setup.py develop -</code></pre> -<p>You will also need to upgrade your configuration as the signing key format has -changed. Run::</p> -<pre><code>python -m synapse.app.homeserver --config-path <CONFIG> --generate-config -</code></pre> -<h1 id="upgrading-to-v030"><a class="header" href="#upgrading-to-v030">Upgrading to v0.3.0</a></h1> -<p>This registration API now closely matches the login API. This introduces a bit -more backwards and forwards between the HS and the client, but this improves -the overall flexibility of the API. You can now GET on /register to retrieve a list -of valid registration flows. Upon choosing one, they are submitted in the same -way as login, e.g::</p> -<p>{ -type: m.login.password, -user: foo, -password: bar -}</p> -<p>The default HS supports 2 flows, with and without Identity Server email -authentication. Enabling captcha on the HS will add in an extra step to all -flows: <code>m.login.recaptcha</code> which must be completed before you can transition -to the next stage. There is a new login type: <code>m.login.email.identity</code> which -contains the <code>threepidCreds</code> key which were previously sent in the original -register request. For more information on this, see the specification.</p> -<h2 id="web-client"><a class="header" href="#web-client">Web Client</a></h2> -<p>The VoIP specification has changed between v0.2.0 and v0.3.0. Users should -refresh any browser tabs to get the latest web client code. Users on -v0.2.0 of the web client will not be able to call those on v0.3.0 and -vice versa.</p> -<h1 id="upgrading-to-v020"><a class="header" href="#upgrading-to-v020">Upgrading to v0.2.0</a></h1> -<p>The home server now requires setting up of SSL config before it can run. To -automatically generate default config use::</p> -<pre><code>$ python synapse/app/homeserver.py \ - --server-name machine.my.domain.name \ - --bind-port 8448 \ - --config-path homeserver.config \ - --generate-config -</code></pre> -<p>This config can be edited if desired, for example to specify a different SSL -certificate to use. Once done you can run the home server using::</p> -<pre><code>$ python synapse/app/homeserver.py --config-path homeserver.config -</code></pre> -<p>See the README.rst for more information.</p> -<p>Also note that some config options have been renamed, including:</p> -<ul> -<li>"host" to "server-name"</li> -<li>"database" to "database-path"</li> -<li>"port" to "bind-port" and "unsecure-port"</li> -</ul> -<h1 id="upgrading-to-v001"><a class="header" href="#upgrading-to-v001">Upgrading to v0.0.1</a></h1> -<p>This release completely changes the database schema and so requires upgrading -it before starting the new version of the homeserver.</p> -<p>The script "database-prepare-for-0.0.1.sh" should be used to upgrade the -database. This will save all user information, such as logins and profiles, -but will otherwise purge the database. This includes messages, which -rooms the home server was a member of and room alias mappings.</p> -<p>Before running the command the homeserver should be first completely -shutdown. To run it, simply specify the location of the database, e.g.:</p> -<p>./scripts/database-prepare-for-0.0.1.sh "homeserver.db"</p> -<p>Once this has successfully completed it will be safe to restart the -homeserver. You may notice that the homeserver takes a few seconds longer to -restart than usual as it reinitializes the database.</p> -<p>On startup of the new version, users can either rejoin remote rooms using room -aliases or by being reinvited. Alternatively, if any other homeserver sends a -message to a room that the homeserver was previously in the local HS will -automatically rejoin the room.</p> - - </main> - - <nav class="nav-wrapper" aria-label="Page navigation"> - <!-- Mobile navigation buttons --> - - <a rel="prev" href="../delegate.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> - <i class="fa fa-angle-left"></i> - </a> - - - - <a rel="next" href="../MSC1711_certificates_FAQ.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> - <i class="fa fa-angle-right"></i> - </a> - - - <div style="clear: both"></div> - </nav> - </div> - </div> - - <nav class="nav-wide-wrapper" aria-label="Page navigation"> - - <a rel="prev" href="../delegate.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> - <i class="fa fa-angle-left"></i> - </a> - - - - <a rel="next" href="../MSC1711_certificates_FAQ.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> - <i class="fa fa-angle-right"></i> - </a> - - </nav> - - </div> - - - - - - - - - <script type="text/javascript"> - window.playground_copyable = true; - </script> - - - - - - <script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../mark.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../searcher.js" type="text/javascript" charset="utf-8"></script> - - - <script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../highlight.js" type="text/javascript" charset="utf-8"></script> - <script src="../book.js" type="text/javascript" charset="utf-8"></script> - - <!-- Custom JS scripts --> - - <script type="text/javascript" src="../docs/website_files/table-of-contents.js"></script> - - - - - </body> -</html> \ No newline at end of file diff --git a/v1.37/upgrading/index.html b/v1.37/upgrading/index.html deleted file mode 100644 index fe9879895a..0000000000 --- a/v1.37/upgrading/index.html +++ /dev/null @@ -1,1260 +0,0 @@ -<!DOCTYPE HTML> -<html lang="en" class="sidebar-visible no-js light"> - <head> - <!-- Book generated using mdBook --> - <meta charset="UTF-8"> - <title>Upgrading between Synapse Versions - Synapse</title> - - - - - <!-- Custom HTML head --> - - - - <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> - <meta name="description" content=""> - <meta name="viewport" content="width=device-width, initial-scale=1"> - <meta name="theme-color" content="#ffffff" /> - - - <link rel="icon" href="../favicon.svg"> - - - <link rel="shortcut icon" href="../favicon.png"> - - <link rel="stylesheet" href="../css/variables.css"> - <link rel="stylesheet" href="../css/general.css"> - <link rel="stylesheet" href="../css/chrome.css"> - - <link rel="stylesheet" href="../css/print.css" media="print"> - - - <!-- Fonts --> - <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css"> - - <link rel="stylesheet" href="../fonts/fonts.css"> - - - <!-- Highlight.js Stylesheets --> - <link rel="stylesheet" href="../highlight.css"> - <link rel="stylesheet" href="../tomorrow-night.css"> - <link rel="stylesheet" href="../ayu-highlight.css"> - - <!-- Custom theme stylesheets --> - - <link rel="stylesheet" href="../docs/website_files/table-of-contents.css"> - - <link rel="stylesheet" href="../docs/website_files/remove-nav-buttons.css"> - - <link rel="stylesheet" href="../docs/website_files/indent-section-headers.css"> - - - - </head> - <body> - <!-- Provide site root to javascript --> - <script type="text/javascript"> - var path_to_root = "../"; - var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light"; - </script> - - <!-- Work around some values being stored in localStorage wrapped in quotes --> - <script type="text/javascript"> - try { - var theme = localStorage.getItem('mdbook-theme'); - var sidebar = localStorage.getItem('mdbook-sidebar'); - if (theme.startsWith('"') && theme.endsWith('"')) { - localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); - } - if (sidebar.startsWith('"') && sidebar.endsWith('"')) { - localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); - } - } catch (e) { } - </script> - - <!-- Set the theme before any content is loaded, prevents flash --> - <script type="text/javascript"> - var theme; - try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } - if (theme === null || theme === undefined) { theme = default_theme; } - var html = document.querySelector('html'); - html.classList.remove('no-js') - html.classList.remove('light') - html.classList.add(theme); - html.classList.add('js'); - </script> - - <!-- Hide / unhide sidebar before it is displayed --> - <script type="text/javascript"> - var html = document.querySelector('html'); - var sidebar = 'hidden'; - if (document.body.clientWidth >= 1080) { - try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } - sidebar = sidebar || 'visible'; - } - html.classList.remove('sidebar-visible'); - html.classList.add("sidebar-" + sidebar); - </script> - - <nav id="sidebar" class="sidebar" aria-label="Table of contents"> - <div class="sidebar-scrollbox"> - <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="../welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="../setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="../postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="../reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="../turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="../delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="../upgrading/index.html" class="active">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="../MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="../federate.html">Federation</a></li><li class="chapter-item expanded "><a href="../usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="../usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="../structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="../usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="../sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="../password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="../jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="../CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="../application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="../server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="../url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="../user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="../message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="../modules.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="../spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="../presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="../workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="../systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="../usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="../admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="../admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="../admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="../admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="../admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="../admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="../admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="../admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="../admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="../admin_api/shutdown_room.html">Shutdown Room</a></li><li class="chapter-item expanded "><a href="../admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="../admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="../admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="../manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="../metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="../usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="../development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="../code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="../dev/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="../opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="../development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="../replication.html">Replication</a></li><li class="chapter-item expanded "><a href="../tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="../development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../dev/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="../dev/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="../media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="../room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="../deprecation_policy.html">Dependency Deprecation Policy</a></li></ol> - </div> - <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div> - </nav> - - <div id="page-wrapper" class="page-wrapper"> - - <div class="page"> - - <div id="menu-bar-hover-placeholder"></div> - <div id="menu-bar" class="menu-bar sticky bordered"> - <div class="left-buttons"> - <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> - <i class="fa fa-bars"></i> - </button> - <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list"> - <i class="fa fa-paint-brush"></i> - </button> - <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> - <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li> - <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> - <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> - <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> - <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> - </ul> - - <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar"> - <i class="fa fa-search"></i> - </button> - - </div> - - <h1 class="menu-title">Synapse</h1> - - <div class="right-buttons"> - - <a href="../print.html" title="Print this book" aria-label="Print this book"> - <i id="print-button" class="fa fa-print"></i> - </a> - - - <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository"> - <i id="git-repository-button" class="fa fa-github"></i> - </a> - - - <a href="https://github.com/matrix-org/synapse/edit/develop/docs/upgrading/README.md" title="Suggest an edit" aria-label="Suggest an edit"> - <i id="git-edit-button" class="fa fa-edit"></i> - </a> - - - </div> - </div> - - - <div id="search-wrapper" class="hidden"> - <form id="searchbar-outer" class="searchbar-outer"> - <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> - </form> - <div id="searchresults-outer" class="searchresults-outer hidden"> - <div id="searchresults-header" class="searchresults-header"></div> - <ul id="searchresults"> - </ul> - </div> - </div> - - - <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> - <script type="text/javascript"> - document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); - document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); - Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { - link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); - }); - </script> - - <div id="content" class="content"> - <main> - <!-- Page table of contents --> - <div class="sidetoc"> - <nav class="pagetoc"></nav> - </div> - - <!-- - Include the contents of UPGRADE.rst from the project root without moving it, which may - break links around the internet. Additionally, note that SUMMARY.md is unable to - directly link to content outside of the docs/ directory. So we use this file as a - redirection. ---> -<h1 id="upgrading-synapse"><a class="header" href="#upgrading-synapse">Upgrading Synapse</a></h1> -<p>Before upgrading check if any special steps are required to upgrade from the -version you currently have installed to the current version of Synapse. The extra -instructions that may be required are listed later in this document.</p> -<ul> -<li> -<p>Check that your versions of Python and PostgreSQL are still supported.</p> -<p>Synapse follows upstream lifecycles for <code>Python</code>_ and <code>PostgreSQL</code>_, and -removes support for versions which are no longer maintained.</p> -<p>The website https://endoflife.date also offers convenient summaries.</p> -<p>.. _Python: https://devguide.python.org/devcycle/#end-of-life-branches -.. _PostgreSQL: https://www.postgresql.org/support/versioning/</p> -</li> -<li> -<p>If Synapse was installed using <code>prebuilt packages <INSTALL.md#prebuilt-packages></code>_, you will need to follow the normal process -for upgrading those packages.</p> -</li> -<li> -<p>If Synapse was installed from source, then:</p> -<ol> -<li> -<p>Activate the virtualenv before upgrading. For example, if Synapse is -installed in a virtualenv in <code>~/synapse/env</code> then run:</p> -<p>.. code:: bash</p> -<p>source ~/synapse/env/bin/activate</p> -</li> -<li> -<p>If Synapse was installed using pip then upgrade to the latest version by -running:</p> -<p>.. code:: bash</p> -<p>pip install --upgrade matrix-synapse</p> -<p>If Synapse was installed using git then upgrade to the latest version by -running:</p> -<p>.. code:: bash</p> -<p>git pull -pip install --upgrade .</p> -</li> -<li> -<p>Restart Synapse:</p> -<p>.. code:: bash</p> -<p>./synctl restart</p> -</li> -</ol> -</li> -</ul> -<p>To check whether your update was successful, you can check the running server -version with:</p> -<p>.. code:: bash</p> -<pre><code># you may need to replace 'localhost:8008' if synapse is not configured -# to listen on port 8008. - -curl http://localhost:8008/_synapse/admin/v1/server_version -</code></pre> -<h2 id="rolling-back-to-older-versions"><a class="header" href="#rolling-back-to-older-versions">Rolling back to older versions</a></h2> -<p>Rolling back to previous releases can be difficult, due to database schema -changes between releases. Where we have been able to test the rollback process, -this will be noted below.</p> -<p>In general, you will need to undo any changes made during the upgrade process, -for example:</p> -<ul> -<li> -<p>pip:</p> -<p>.. code:: bash</p> -<p>source env/bin/activate</p> -<h1 id="replace-130-accordingly"><a class="header" href="#replace-130-accordingly">replace <code>1.3.0</code> accordingly:</a></h1> -<p>pip install matrix-synapse==1.3.0</p> -</li> -<li> -<p>Debian:</p> -<p>.. code:: bash</p> -<h1 id="replace-130-and-stretch-accordingly"><a class="header" href="#replace-130-and-stretch-accordingly">replace <code>1.3.0</code> and <code>stretch</code> accordingly:</a></h1> -<p>wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb -dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb</p> -</li> -</ul> -<h1 id="upgrading-to-v1370"><a class="header" href="#upgrading-to-v1370">Upgrading to v1.37.0</a></h1> -<h2 id="deprecation-of-the-current-spam-checker-interface"><a class="header" href="#deprecation-of-the-current-spam-checker-interface">Deprecation of the current spam checker interface</a></h2> -<p>The current spam checker interface is deprecated in favour of a new generic modules system. -Authors of spam checker modules can refer to <code>this documentation <https://matrix-org.github.io/synapse/develop/modules.html#porting-an-existing-module-that-uses-the-old-interface></code>_ -to update their modules. Synapse administrators can refer to <code>this documentation <https://matrix-org.github.io/synapse/develop/modules.html#using-modules></code>_ -to update their configuration once the modules they are using have been updated.</p> -<p>We plan to remove support for the current spam checker interface in August 2021.</p> -<p>More module interfaces will be ported over to this new generic system in future versions -of Synapse.</p> -<h1 id="upgrading-to-v1340"><a class="header" href="#upgrading-to-v1340">Upgrading to v1.34.0</a></h1> -<h2 id="room_invite_state_types-configuration-setting"><a class="header" href="#room_invite_state_types-configuration-setting"><code>room_invite_state_types</code> configuration setting</a></h2> -<p>The <code>room_invite_state_types</code> configuration setting has been deprecated and -replaced with <code>room_prejoin_state</code>. See the <code>sample configuration file <https://github.com/matrix-org/synapse/blob/v1.34.0/docs/sample_config.yaml#L1515></code>_.</p> -<p>If you have set <code>room_invite_state_types</code> to the default value you should simply -remove it from your configuration file. The default value used to be:</p> -<p>.. code:: yaml</p> -<p>room_invite_state_types: -- "m.room.join_rules" -- "m.room.canonical_alias" -- "m.room.avatar" -- "m.room.encryption" -- "m.room.name"</p> -<p>If you have customised this value, you should remove <code>room_invite_state_types</code> and -configure <code>room_prejoin_state</code> instead.</p> -<h1 id="upgrading-to-v1330"><a class="header" href="#upgrading-to-v1330">Upgrading to v1.33.0</a></h1> -<h2 id="account-validity-html-templates-can-now-display-a-users-expiration-date"><a class="header" href="#account-validity-html-templates-can-now-display-a-users-expiration-date">Account Validity HTML templates can now display a user's expiration date</a></h2> -<p>This may affect you if you have enabled the account validity feature, and have made use of a -custom HTML template specified by the <code>account_validity.template_dir</code> or <code>account_validity.account_renewed_html_path</code> -Synapse config options.</p> -<p>The template can now accept an <code>expiration_ts</code> variable, which represents the unix timestamp in milliseconds for the -future date of which their account has been renewed until. See the -<code>default template <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_renewed.html></code>_ -for an example of usage.</p> -<p>ALso note that a new HTML template, <code>account_previously_renewed.html</code>, has been added. This is is shown to users -when they attempt to renew their account with a valid renewal token that has already been used before. The default -template contents can been found -<code>here <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_previously_renewed.html></code>_, -and can also accept an <code>expiration_ts</code> variable. This template replaces the error message users would previously see -upon attempting to use a valid renewal token more than once.</p> -<h1 id="upgrading-to-v1320"><a class="header" href="#upgrading-to-v1320">Upgrading to v1.32.0</a></h1> -<h2 id="regression-causing-connected-prometheus-instances-to-become-overwhelmed"><a class="header" href="#regression-causing-connected-prometheus-instances-to-become-overwhelmed">Regression causing connected Prometheus instances to become overwhelmed</a></h2> -<p>This release introduces <code>a regression <https://github.com/matrix-org/synapse/issues/9853></code>_ -that can overwhelm connected Prometheus instances. This issue is not present in -Synapse v1.32.0rc1.</p> -<p>If you have been affected, please downgrade to 1.31.0. You then may need to -remove excess writeahead logs in order for Prometheus to recover. Instructions -for doing so are provided -<code>here <https://github.com/matrix-org/synapse/pull/9854#issuecomment-823472183></code>_.</p> -<h2 id="dropping-support-for-old-python-postgres-and-sqlite-versions"><a class="header" href="#dropping-support-for-old-python-postgres-and-sqlite-versions">Dropping support for old Python, Postgres and SQLite versions</a></h2> -<p>In line with our <code>deprecation policy <https://github.com/matrix-org/synapse/blob/release-v1.32.0/docs/deprecation_policy.md></code>_, -we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no longer supported upstream.</p> -<p>This release of Synapse requires Python 3.6+ and PostgresSQL 9.6+ or SQLite 3.22+.</p> -<h2 id="removal-of-old-list-accounts-admin-api"><a class="header" href="#removal-of-old-list-accounts-admin-api">Removal of old List Accounts Admin API</a></h2> -<p>The deprecated v1 "list accounts" admin API (<code>GET /_synapse/admin/v1/users/<user_id></code>) has been removed in this version.</p> -<p>The <code>v2 list accounts API <https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#list-accounts></code>_ -has been available since Synapse 1.7.0 (2019-12-13), and is accessible under <code>GET /_synapse/admin/v2/users</code>.</p> -<p>The deprecation of the old endpoint was announced with Synapse 1.28.0 (released on 2021-02-25).</p> -<h2 id="application-services-must-use-type-mloginapplication_service-when-registering-users"><a class="header" href="#application-services-must-use-type-mloginapplication_service-when-registering-users">Application Services must use type <code>m.login.application_service</code> when registering users</a></h2> -<p>In compliance with the -<code>Application Service spec <https://matrix.org/docs/spec/application_service/r0.1.2#server-admin-style-permissions></code>_, -Application Services are now required to use the <code>m.login.application_service</code> type when registering users via the -<code>/_matrix/client/r0/register</code> endpoint. This behaviour was deprecated in Synapse v1.30.0.</p> -<p>Please ensure your Application Services are up to date.</p> -<h1 id="upgrading-to-v1290"><a class="header" href="#upgrading-to-v1290">Upgrading to v1.29.0</a></h1> -<h2 id="requirement-for-x-forwarded-proto-header"><a class="header" href="#requirement-for-x-forwarded-proto-header">Requirement for X-Forwarded-Proto header</a></h2> -<p>When using Synapse with a reverse proxy (in particular, when using the -<code>x_forwarded</code> option on an HTTP listener), Synapse now expects to receive an -<code>X-Forwarded-Proto</code> header on incoming HTTP requests. If it is not set, Synapse -will log a warning on each received request.</p> -<p>To avoid the warning, administrators using a reverse proxy should ensure that -the reverse proxy sets <code>X-Forwarded-Proto</code> header to <code>https</code> or <code>http</code> to -indicate the protocol used by the client.</p> -<p>Synapse also requires the <code>Host</code> header to be preserved.</p> -<p>See the <code>reverse proxy documentation <docs/reverse_proxy.md></code>_, where the -example configurations have been updated to show how to set these headers.</p> -<p>(Users of <code>Caddy <https://caddyserver.com/></code>_ are unaffected, since we believe it -sets <code>X-Forwarded-Proto</code> by default.)</p> -<h1 id="upgrading-to-v1270"><a class="header" href="#upgrading-to-v1270">Upgrading to v1.27.0</a></h1> -<h2 id="changes-to-callback-uri-for-oauth2--openid-connect-and-saml2"><a class="header" href="#changes-to-callback-uri-for-oauth2--openid-connect-and-saml2">Changes to callback URI for OAuth2 / OpenID Connect and SAML2</a></h2> -<p>This version changes the URI used for callbacks from OAuth2 and SAML2 identity providers:</p> -<ul> -<li> -<p>If your server is configured for single sign-on via an OpenID Connect or OAuth2 identity -provider, you will need to add <code>[synapse public baseurl]/_synapse/client/oidc/callback</code> -to the list of permitted "redirect URIs" at the identity provider.</p> -<p>See <code>docs/openid.md <docs/openid.md></code>_ for more information on setting up OpenID -Connect.</p> -</li> -<li> -<p>If your server is configured for single sign-on via a SAML2 identity provider, you will -need to add <code>[synapse public baseurl]/_synapse/client/saml2/authn_response</code> as a permitted -"ACS location" (also known as "allowed callback URLs") at the identity provider.</p> -<p>The "Issuer" in the "AuthnRequest" to the SAML2 identity provider is also updated to -<code>[synapse public baseurl]/_synapse/client/saml2/metadata.xml</code>. If your SAML2 identity -provider uses this property to validate or otherwise identify Synapse, its configuration -will need to be updated to use the new URL. Alternatively you could create a new, separate -"EntityDescriptor" in your SAML2 identity provider with the new URLs and leave the URLs in -the existing "EntityDescriptor" as they were.</p> -</li> -</ul> -<h2 id="changes-to-html-templates"><a class="header" href="#changes-to-html-templates">Changes to HTML templates</a></h2> -<p>The HTML templates for SSO and email notifications now have <code>Jinja2's autoescape <https://jinja.palletsprojects.com/en/2.11.x/api/#autoescaping></code>_ -enabled for files ending in <code>.html</code>, <code>.htm</code>, and <code>.xml</code>. If you have customised -these templates and see issues when viewing them you might need to update them. -It is expected that most configurations will need no changes.</p> -<p>If you have customised the templates <em>names</em> for these templates, it is recommended -to verify they end in <code>.html</code> to ensure autoescape is enabled.</p> -<p>The above applies to the following templates:</p> -<ul> -<li><code>add_threepid.html</code></li> -<li><code>add_threepid_failure.html</code></li> -<li><code>add_threepid_success.html</code></li> -<li><code>notice_expiry.html</code></li> -<li><code>notice_expiry.html</code></li> -<li><code>notif_mail.html</code> (which, by default, includes <code>room.html</code> and <code>notif.html</code>)</li> -<li><code>password_reset.html</code></li> -<li><code>password_reset_confirmation.html</code></li> -<li><code>password_reset_failure.html</code></li> -<li><code>password_reset_success.html</code></li> -<li><code>registration.html</code></li> -<li><code>registration_failure.html</code></li> -<li><code>registration_success.html</code></li> -<li><code>sso_account_deactivated.html</code></li> -<li><code>sso_auth_bad_user.html</code></li> -<li><code>sso_auth_confirm.html</code></li> -<li><code>sso_auth_success.html</code></li> -<li><code>sso_error.html</code></li> -<li><code>sso_login_idp_picker.html</code></li> -<li><code>sso_redirect_confirm.html</code></li> -</ul> -<h1 id="upgrading-to-v1260"><a class="header" href="#upgrading-to-v1260">Upgrading to v1.26.0</a></h1> -<h2 id="rolling-back-to-v1250-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1250-after-a-failed-upgrade">Rolling back to v1.25.0 after a failed upgrade</a></h2> -<p>v1.26.0 includes a lot of large changes. If something problematic occurs, you -may want to roll-back to a previous version of Synapse. Because v1.26.0 also -includes a new database schema version, reverting that version is also required -alongside the generic rollback instructions mentioned above. In short, to roll -back to v1.25.0 you need to:</p> -<ol> -<li> -<p>Stop the server</p> -</li> -<li> -<p>Decrease the schema version in the database:</p> -<p>.. code:: sql</p> -<p>UPDATE schema_version SET version = 58;</p> -</li> -<li> -<p>Delete the ignored users & chain cover data:</p> -<p>.. code:: sql</p> -<p>DROP TABLE IF EXISTS ignored_users; -UPDATE rooms SET has_auth_chain_index = false;</p> -<p>For PostgreSQL run:</p> -<p>.. code:: sql</p> -<p>TRUNCATE event_auth_chain_links; -TRUNCATE event_auth_chains;</p> -<p>For SQLite run:</p> -<p>.. code:: sql</p> -<p>DELETE FROM event_auth_chain_links; -DELETE FROM event_auth_chains;</p> -</li> -<li> -<p>Mark the deltas as not run (so they will re-run on upgrade).</p> -<p>.. code:: sql</p> -<p>DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/01ignored_user.py"; -DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/06chain_cover_index.sql";</p> -</li> -<li> -<p>Downgrade Synapse by following the instructions for your installation method -in the "Rolling back to older versions" section above.</p> -</li> -</ol> -<h1 id="upgrading-to-v1250"><a class="header" href="#upgrading-to-v1250">Upgrading to v1.25.0</a></h1> -<h2 id="last-release-supporting-python-35"><a class="header" href="#last-release-supporting-python-35">Last release supporting Python 3.5</a></h2> -<p>This is the last release of Synapse which guarantees support with Python 3.5, -which passed its upstream End of Life date several months ago.</p> -<p>We will attempt to maintain support through March 2021, but without guarantees.</p> -<p>In the future, Synapse will follow upstream schedules for ending support of -older versions of Python and PostgreSQL. Please upgrade to at least Python 3.6 -and PostgreSQL 9.6 as soon as possible.</p> -<h2 id="blacklisting-ip-ranges"><a class="header" href="#blacklisting-ip-ranges">Blacklisting IP ranges</a></h2> -<p>Synapse v1.25.0 includes new settings, <code>ip_range_blacklist</code> and -<code>ip_range_whitelist</code>, for controlling outgoing requests from Synapse for federation, -identity servers, push, and for checking key validity for third-party invite events. -The previous setting, <code>federation_ip_range_blacklist</code>, is deprecated. The new -<code>ip_range_blacklist</code> defaults to private IP ranges if it is not defined.</p> -<p>If you have never customised <code>federation_ip_range_blacklist</code> it is recommended -that you remove that setting.</p> -<p>If you have customised <code>federation_ip_range_blacklist</code> you should update the -setting name to <code>ip_range_blacklist</code>.</p> -<p>If you have a custom push server that is reached via private IP space you may -need to customise <code>ip_range_blacklist</code> or <code>ip_range_whitelist</code>.</p> -<h1 id="upgrading-to-v1240"><a class="header" href="#upgrading-to-v1240">Upgrading to v1.24.0</a></h1> -<h2 id="custom-openid-connect-mapping-provider-breaking-change"><a class="header" href="#custom-openid-connect-mapping-provider-breaking-change">Custom OpenID Connect mapping provider breaking change</a></h2> -<p>This release allows the OpenID Connect mapping provider to perform normalisation -of the localpart of the Matrix ID. This allows for the mapping provider to -specify different algorithms, instead of the <a href="https://matrix.org/docs/spec/appendices#mapping-from-other-character-sets">default way</a>.</p> -<p>If your Synapse configuration uses a custom mapping provider -(<code>oidc_config.user_mapping_provider.module</code> is specified and not equal to -<code>synapse.handlers.oidc_handler.JinjaOidcMappingProvider</code>) then you <em>must</em> ensure -that <code>map_user_attributes</code> of the mapping provider performs some normalisation -of the <code>localpart</code> returned. To match previous behaviour you can use the -<code>map_username_to_mxid_localpart</code> function provided by Synapse. An example is -shown below:</p> -<p>.. code-block:: python</p> -<p>from synapse.types import map_username_to_mxid_localpart</p> -<p>class MyMappingProvider: -def map_user_attributes(self, userinfo, token): -# ... your custom logic ... -sso_user_id = ... -localpart = map_username_to_mxid_localpart(sso_user_id)</p> -<pre><code> return {"localpart": localpart} -</code></pre> -<h2 id="removal-historical-synapse-admin-api"><a class="header" href="#removal-historical-synapse-admin-api">Removal historical Synapse Admin API</a></h2> -<p>Historically, the Synapse Admin API has been accessible under:</p> -<ul> -<li><code>/_matrix/client/api/v1/admin</code></li> -<li><code>/_matrix/client/unstable/admin</code></li> -<li><code>/_matrix/client/r0/admin</code></li> -<li><code>/_synapse/admin/v1</code></li> -</ul> -<p>The endpoints with <code>/_matrix/client/*</code> prefixes have been removed as of v1.24.0. -The Admin API is now only accessible under:</p> -<ul> -<li><code>/_synapse/admin/v1</code></li> -</ul> -<p>The only exception is the <code>/admin/whois</code> endpoint, which is -<code>also available via the client-server API <https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid></code>_.</p> -<p>The deprecation of the old endpoints was announced with Synapse 1.20.0 (released -on 2020-09-22) and makes it easier for homeserver admins to lock down external -access to the Admin API endpoints.</p> -<h1 id="upgrading-to-v1230"><a class="header" href="#upgrading-to-v1230">Upgrading to v1.23.0</a></h1> -<h2 id="structured-logging-configuration-breaking-changes"><a class="header" href="#structured-logging-configuration-breaking-changes">Structured logging configuration breaking changes</a></h2> -<p>This release deprecates use of the <code>structured: true</code> logging configuration for -structured logging. If your logging configuration contains <code>structured: true</code> -then it should be modified based on the <code>structured logging documentation <https://github.com/matrix-org/synapse/blob/master/docs/structured_logging.md></code>_.</p> -<p>The <code>structured</code> and <code>drains</code> logging options are now deprecated and should -be replaced by standard logging configuration of <code>handlers</code> and <code>formatters</code>.</p> -<p>A future will release of Synapse will make using <code>structured: true</code> an error.</p> -<h1 id="upgrading-to-v1220"><a class="header" href="#upgrading-to-v1220">Upgrading to v1.22.0</a></h1> -<h2 id="thirdpartyeventrules-breaking-changes"><a class="header" href="#thirdpartyeventrules-breaking-changes">ThirdPartyEventRules breaking changes</a></h2> -<p>This release introduces a backwards-incompatible change to modules making use of -<code>ThirdPartyEventRules</code> in Synapse. If you make use of a module defined under the -<code>third_party_event_rules</code> config option, please make sure it is updated to handle -the below change:</p> -<p>The <code>http_client</code> argument is no longer passed to modules as they are initialised. Instead, -modules are expected to make use of the <code>http_client</code> property on the <code>ModuleApi</code> class. -Modules are now passed a <code>module_api</code> argument during initialisation, which is an instance of -<code>ModuleApi</code>. <code>ModuleApi</code> instances have a <code>http_client</code> property which acts the same as -the <code>http_client</code> argument previously passed to <code>ThirdPartyEventRules</code> modules.</p> -<h1 id="upgrading-to-v1210"><a class="header" href="#upgrading-to-v1210">Upgrading to v1.21.0</a></h1> -<h2 id="forwarding-_synapseclient-through-your-reverse-proxy"><a class="header" href="#forwarding-_synapseclient-through-your-reverse-proxy">Forwarding <code>/_synapse/client</code> through your reverse proxy</a></h2> -<p>The <code>reverse proxy documentation <https://github.com/matrix-org/synapse/blob/develop/docs/reverse_proxy.md></code>_ has been updated -to include reverse proxy directives for <code>/_synapse/client/*</code> endpoints. As the user password -reset flow now uses endpoints under this prefix, <strong>you must update your reverse proxy -configurations for user password reset to work</strong>.</p> -<p>Additionally, note that the <code>Synapse worker documentation <https://github.com/matrix-org/synapse/blob/develop/docs/workers.md></code>_ has been updated to -state that the <code>/_synapse/client/password_reset/email/submit_token</code> endpoint can be handled -by all workers. If you make use of Synapse's worker feature, please update your reverse proxy -configuration to reflect this change.</p> -<h2 id="new-html-templates"><a class="header" href="#new-html-templates">New HTML templates</a></h2> -<p>A new HTML template, -<code>password_reset_confirmation.html <https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html></code>_, -has been added to the <code>synapse/res/templates</code> directory. If you are using a -custom template directory, you may want to copy the template over and modify it.</p> -<p>Note that as of v1.20.0, templates do not need to be included in custom template -directories for Synapse to start. The default templates will be used if a custom -template cannot be found.</p> -<p>This page will appear to the user after clicking a password reset link that has -been emailed to them.</p> -<p>To complete password reset, the page must include a way to make a <code>POST</code> -request to -<code>/_synapse/client/password_reset/{medium}/submit_token</code> -with the query parameters from the original link, presented as a URL-encoded form. See the file -itself for more details.</p> -<h2 id="updated-single-sign-on-html-templates"><a class="header" href="#updated-single-sign-on-html-templates">Updated Single Sign-on HTML Templates</a></h2> -<p>The <code>saml_error.html</code> template was removed from Synapse and replaced with the -<code>sso_error.html</code> template. If your Synapse is configured to use SAML and a -custom <code>sso_redirect_confirm_template_dir</code> configuration then any customisations -of the <code>saml_error.html</code> template will need to be merged into the <code>sso_error.html</code> -template. These templates are similar, but the parameters are slightly different:</p> -<ul> -<li>The <code>msg</code> parameter should be renamed to <code>error_description</code>.</li> -<li>There is no longer a <code>code</code> parameter for the response code.</li> -<li>A string <code>error</code> parameter is available that includes a short hint of why a -user is seeing the error page.</li> -</ul> -<h1 id="upgrading-to-v1180"><a class="header" href="#upgrading-to-v1180">Upgrading to v1.18.0</a></h1> -<h2 id="docker--py3-suffix-will-be-removed-in-future-versions"><a class="header" href="#docker--py3-suffix-will-be-removed-in-future-versions">Docker <code>-py3</code> suffix will be removed in future versions</a></h2> -<p>From 10th August 2020, we will no longer publish Docker images with the <code>-py3</code> tag suffix. The images tagged with the <code>-py3</code> suffix have been identical to the non-suffixed tags since release 0.99.0, and the suffix is obsolete.</p> -<p>On 10th August, we will remove the <code>latest-py3</code> tag. Existing per-release tags (such as <code>v1.18.0-py3</code>) will not be removed, but no new <code>-py3</code> tags will be added.</p> -<p>Scripts relying on the <code>-py3</code> suffix will need to be updated.</p> -<h2 id="redis-replication-is-now-recommended-in-lieu-of-tcp-replication"><a class="header" href="#redis-replication-is-now-recommended-in-lieu-of-tcp-replication">Redis replication is now recommended in lieu of TCP replication</a></h2> -<p>When setting up worker processes, we now recommend the use of a Redis server for replication. <strong>The old direct TCP connection method is deprecated and will be removed in a future release.</strong> -See <code>docs/workers.md <docs/workers.md></code>_ for more details.</p> -<h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1> -<p>This version includes a database update which is run as part of the upgrade, -and which may take a couple of minutes in the case of a large server. Synapse -will not respond to HTTP requests while this update is taking place.</p> -<h1 id="upgrading-to-v1130"><a class="header" href="#upgrading-to-v1130">Upgrading to v1.13.0</a></h1> -<h2 id="incorrect-database-migration-in-old-synapse-versions"><a class="header" href="#incorrect-database-migration-in-old-synapse-versions">Incorrect database migration in old synapse versions</a></h2> -<p>A bug was introduced in Synapse 1.4.0 which could cause the room directory to -be incomplete or empty if Synapse was upgraded directly from v1.2.1 or -earlier, to versions between v1.4.0 and v1.12.x.</p> -<p>This will <em>not</em> be a problem for Synapse installations which were:</p> -<ul> -<li>created at v1.4.0 or later,</li> -<li>upgraded via v1.3.x, or</li> -<li>upgraded straight from v1.2.1 or earlier to v1.13.0 or later.</li> -</ul> -<p>If completeness of the room directory is a concern, installations which are -affected can be repaired as follows:</p> -<ol> -<li> -<p>Run the following sql from a <code>psql</code> or <code>sqlite3</code> console:</p> -<p>.. code:: sql</p> -<p>INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES -('populate_stats_process_rooms', '{}', 'current_state_events_membership');</p> -<p>INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES -('populate_stats_process_users', '{}', 'populate_stats_process_rooms');</p> -</li> -<li> -<p>Restart synapse.</p> -</li> -</ol> -<h2 id="new-single-sign-on-html-templates"><a class="header" href="#new-single-sign-on-html-templates">New Single Sign-on HTML Templates</a></h2> -<p>New templates (<code>sso_auth_confirm.html</code>, <code>sso_auth_success.html</code>, and -<code>sso_account_deactivated.html</code>) were added to Synapse. If your Synapse is -configured to use SSO and a custom <code>sso_redirect_confirm_template_dir</code> -configuration then these templates will need to be copied from -<code>synapse/res/templates <synapse/res/templates></code>_ into that directory.</p> -<h2 id="synapse-sso-plugins-method-deprecation"><a class="header" href="#synapse-sso-plugins-method-deprecation">Synapse SSO Plugins Method Deprecation</a></h2> -<p>Plugins using the <code>complete_sso_login</code> method of -<code>synapse.module_api.ModuleApi</code> should update to using the async/await -version <code>complete_sso_login_async</code> which includes additional checks. The -non-async version is considered deprecated.</p> -<h2 id="rolling-back-to-v1124-after-a-failed-upgrade"><a class="header" href="#rolling-back-to-v1124-after-a-failed-upgrade">Rolling back to v1.12.4 after a failed upgrade</a></h2> -<p>v1.13.0 includes a lot of large changes. If something problematic occurs, you -may want to roll-back to a previous version of Synapse. Because v1.13.0 also -includes a new database schema version, reverting that version is also required -alongside the generic rollback instructions mentioned above. In short, to roll -back to v1.12.4 you need to:</p> -<ol> -<li> -<p>Stop the server</p> -</li> -<li> -<p>Decrease the schema version in the database:</p> -<p>.. code:: sql</p> -<p>UPDATE schema_version SET version = 57;</p> -</li> -<li> -<p>Downgrade Synapse by following the instructions for your installation method -in the "Rolling back to older versions" section above.</p> -</li> -</ol> -<h1 id="upgrading-to-v1120"><a class="header" href="#upgrading-to-v1120">Upgrading to v1.12.0</a></h1> -<p>This version includes a database update which is run as part of the upgrade, -and which may take some time (several hours in the case of a large -server). Synapse will not respond to HTTP requests while this update is taking -place.</p> -<p>This is only likely to be a problem in the case of a server which is -participating in many rooms.</p> -<ol start="0"> -<li> -<p>As with all upgrades, it is recommended that you have a recent backup of -your database which can be used for recovery in the event of any problems.</p> -</li> -<li> -<p>As an initial check to see if you will be affected, you can try running the -following query from the <code>psql</code> or <code>sqlite3</code> console. It is safe to run it -while Synapse is still running.</p> -<p>.. code:: sql</p> -<p>SELECT MAX(q.v) FROM ( -SELECT ( -SELECT ej.json AS v -FROM state_events se INNER JOIN event_json ej USING (event_id) -WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key='' -LIMIT 1 -) FROM rooms WHERE rooms.room_version IS NULL -) q;</p> -<p>This query will take about the same amount of time as the upgrade process: ie, -if it takes 5 minutes, then it is likely that Synapse will be unresponsive for -5 minutes during the upgrade.</p> -<p>If you consider an outage of this duration to be acceptable, no further -action is necessary and you can simply start Synapse 1.12.0.</p> -<p>If you would prefer to reduce the downtime, continue with the steps below.</p> -</li> -<li> -<p>The easiest workaround for this issue is to manually -create a new index before upgrading. On PostgreSQL, his can be done as follows:</p> -<p>.. code:: sql</p> -<p>CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index -ON state_events(room_id) WHERE type = 'm.room.create';</p> -<p>The above query may take some time, but is also safe to run while Synapse is -running.</p> -<p>We assume that no SQLite users have databases large enough to be -affected. If you <em>are</em> affected, you can run a similar query, omitting the -<code>CONCURRENTLY</code> keyword. Note however that this operation may in itself cause -Synapse to stop running for some time. Synapse admins are reminded that -<code>SQLite is not recommended for use outside a test environment <https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql></code>_.</p> -</li> -<li> -<p>Once the index has been created, the <code>SELECT</code> query in step 1 above should -complete quickly. It is therefore safe to upgrade to Synapse 1.12.0.</p> -</li> -<li> -<p>Once Synapse 1.12.0 has successfully started and is responding to HTTP -requests, the temporary index can be removed:</p> -<p>.. code:: sql</p> -<p>DROP INDEX tmp_upgrade_1_12_0_index;</p> -</li> -</ol> -<h1 id="upgrading-to-v1100"><a class="header" href="#upgrading-to-v1100">Upgrading to v1.10.0</a></h1> -<p>Synapse will now log a warning on start up if used with a PostgreSQL database -that has a non-recommended locale set.</p> -<p>See <code>docs/postgres.md <docs/postgres.md></code>_ for details.</p> -<h1 id="upgrading-to-v180"><a class="header" href="#upgrading-to-v180">Upgrading to v1.8.0</a></h1> -<p>Specifying a <code>log_file</code> config option will now cause Synapse to refuse to -start, and should be replaced by with the <code>log_config</code> option. Support for -the <code>log_file</code> option was removed in v1.3.0 and has since had no effect.</p> -<h1 id="upgrading-to-v170"><a class="header" href="#upgrading-to-v170">Upgrading to v1.7.0</a></h1> -<p>In an attempt to configure Synapse in a privacy preserving way, the default -behaviours of <code>allow_public_rooms_without_auth</code> and -<code>allow_public_rooms_over_federation</code> have been inverted. This means that by -default, only authenticated users querying the Client/Server API will be able -to query the room directory, and relatedly that the server will not share -room directory information with other servers over federation.</p> -<p>If your installation does not explicitly set these settings one way or the other -and you want either setting to be <code>true</code> then it will necessary to update -your homeserver configuration file accordingly.</p> -<p>For more details on the surrounding context see our <code>explainer <https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers></code>_.</p> -<h1 id="upgrading-to-v150"><a class="header" href="#upgrading-to-v150">Upgrading to v1.5.0</a></h1> -<p>This release includes a database migration which may take several minutes to -complete if there are a large number (more than a million or so) of entries in -the <code>devices</code> table. This is only likely to a be a problem on very large -installations.</p> -<h1 id="upgrading-to-v140"><a class="header" href="#upgrading-to-v140">Upgrading to v1.4.0</a></h1> -<h2 id="new-custom-templates"><a class="header" href="#new-custom-templates">New custom templates</a></h2> -<p>If you have configured a custom template directory with the -<code>email.template_dir</code> option, be aware that there are new templates regarding -registration and threepid management (see below) that must be included.</p> -<ul> -<li><code>registration.html</code> and <code>registration.txt</code></li> -<li><code>registration_success.html</code> and <code>registration_failure.html</code></li> -<li><code>add_threepid.html</code> and <code>add_threepid.txt</code></li> -<li><code>add_threepid_failure.html</code> and <code>add_threepid_success.html</code></li> -</ul> -<p>Synapse will expect these files to exist inside the configured template -directory, and <strong>will fail to start</strong> if they are absent. -To view the default templates, see <code>synapse/res/templates <https://github.com/matrix-org/synapse/tree/master/synapse/res/templates></code>_.</p> -<h2 id="3pid-verification-changes"><a class="header" href="#3pid-verification-changes">3pid verification changes</a></h2> -<p><strong>Note: As of this release, users will be unable to add phone numbers or email -addresses to their accounts, without changes to the Synapse configuration. This -includes adding an email address during registration.</strong></p> -<p>It is possible for a user to associate an email address or phone number -with their account, for a number of reasons:</p> -<ul> -<li>for use when logging in, as an alternative to the user id.</li> -<li>in the case of email, as an alternative contact to help with account recovery.</li> -<li>in the case of email, to receive notifications of missed messages.</li> -</ul> -<p>Before an email address or phone number can be added to a user's account, -or before such an address is used to carry out a password-reset, Synapse must -confirm the operation with the owner of the email address or phone number. -It does this by sending an email or text giving the user a link or token to confirm -receipt. This process is known as '3pid verification'. ('3pid', or 'threepid', -stands for third-party identifier, and we use it to refer to external -identifiers such as email addresses and phone numbers.)</p> -<p>Previous versions of Synapse delegated the task of 3pid verification to an -identity server by default. In most cases this server is <code>vector.im</code> or -<code>matrix.org</code>.</p> -<p>In Synapse 1.4.0, for security and privacy reasons, the homeserver will no -longer delegate this task to an identity server by default. Instead, -the server administrator will need to explicitly decide how they would like the -verification messages to be sent.</p> -<p>In the medium term, the <code>vector.im</code> and <code>matrix.org</code> identity servers will -disable support for delegated 3pid verification entirely. However, in order to -ease the transition, they will retain the capability for a limited -period. Delegated email verification will be disabled on Monday 2nd December -2019 (giving roughly 2 months notice). Disabling delegated SMS verification -will follow some time after that once SMS verification support lands in -Synapse.</p> -<p>Once delegated 3pid verification support has been disabled in the <code>vector.im</code> and -<code>matrix.org</code> identity servers, all Synapse versions that depend on those -instances will be unable to verify email and phone numbers through them. There -are no imminent plans to remove delegated 3pid verification from Sydent -generally. (Sydent is the identity server project that backs the <code>vector.im</code> and -<code>matrix.org</code> instances).</p> -<p>Email</p> -<pre><code>Following upgrade, to continue verifying email (e.g. as part of the -registration process), admins can either:- - -* Configure Synapse to use an email server. -* Run or choose an identity server which allows delegated email verification - and delegate to it. - -Configure SMTP in Synapse -+++++++++++++++++++++++++ - -To configure an SMTP server for Synapse, modify the configuration section -headed ``email``, and be sure to have at least the ``smtp_host, smtp_port`` -and ``notif_from`` fields filled out. - -You may also need to set ``smtp_user``, ``smtp_pass``, and -``require_transport_security``. - -See the `sample configuration file <docs/sample_config.yaml>`_ for more details -on these settings. - -Delegate email to an identity server -++++++++++++++++++++++++++++++++++++ - -Some admins will wish to continue using email verification as part of the -registration process, but will not immediately have an appropriate SMTP server -at hand. - -To this end, we will continue to support email verification delegation via the -``vector.im`` and ``matrix.org`` identity servers for two months. Support for -delegated email verification will be disabled on Monday 2nd December. - -The ``account_threepid_delegates`` dictionary defines whether the homeserver -should delegate an external server (typically an `identity server -<https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending -confirmation messages via email and SMS. - -So to delegate email verification, in ``homeserver.yaml``, set -``account_threepid_delegates.email`` to the base URL of an identity server. For -example: - -.. code:: yaml - - account_threepid_delegates: - email: https://example.com # Delegate email sending to example.com - -Note that ``account_threepid_delegates.email`` replaces the deprecated -``email.trust_identity_server_for_password_resets``: if -``email.trust_identity_server_for_password_resets`` is set to ``true``, and -``account_threepid_delegates.email`` is not set, then the first entry in -``trusted_third_party_id_servers`` will be used as the -``account_threepid_delegate`` for email. This is to ensure compatibility with -existing Synapse installs that set up external server handling for these tasks -before v1.4.0. If ``email.trust_identity_server_for_password_resets`` is -``true`` and no trusted identity server domains are configured, Synapse will -report an error and refuse to start. - -If ``email.trust_identity_server_for_password_resets`` is ``false`` or absent -and no ``email`` delegate is configured in ``account_threepid_delegates``, -then Synapse will send email verification messages itself, using the configured -SMTP server (see above). -that type. - -Phone numbers -</code></pre> -<p>Synapse does not support phone-number verification itself, so the only way to -maintain the ability for users to add phone numbers to their accounts will be -by continuing to delegate phone number verification to the <code>matrix.org</code> and -<code>vector.im</code> identity servers (or another identity server that supports SMS -sending).</p> -<p>The <code>account_threepid_delegates</code> dictionary defines whether the homeserver -should delegate an external server (typically an <code>identity server <https://matrix.org/docs/spec/identity_service/r0.2.1></code>_) to handle sending -confirmation messages via email and SMS.</p> -<p>So to delegate phone number verification, in <code>homeserver.yaml</code>, set -<code>account_threepid_delegates.msisdn</code> to the base URL of an identity -server. For example:</p> -<p>.. code:: yaml</p> -<p>account_threepid_delegates: -msisdn: https://example.com # Delegate sms sending to example.com</p> -<p>The <code>matrix.org</code> and <code>vector.im</code> identity servers will continue to support -delegated phone number verification via SMS until such time as it is possible -for admins to configure their servers to perform phone number verification -directly. More details will follow in a future release.</p> -<h2 id="rolling-back-to-v131"><a class="header" href="#rolling-back-to-v131">Rolling back to v1.3.1</a></h2> -<p>If you encounter problems with v1.4.0, it should be possible to roll back to -v1.3.1, subject to the following:</p> -<ul> -<li> -<p>The 'room statistics' engine was heavily reworked in this release (see -<code>#5971 <https://github.com/matrix-org/synapse/pull/5971></code>_), including -significant changes to the database schema, which are not easily -reverted. This will cause the room statistics engine to stop updating when -you downgrade.</p> -<p>The room statistics are essentially unused in v1.3.1 (in future versions of -Synapse, they will be used to populate the room directory), so there should -be no loss of functionality. However, the statistics engine will write errors -to the logs, which can be avoided by setting the following in -<code>homeserver.yaml</code>:</p> -<p>.. code:: yaml</p> -<p>stats: -enabled: false</p> -<p>Don't forget to re-enable it when you upgrade again, in preparation for its -use in the room directory!</p> -</li> -</ul> -<h1 id="upgrading-to-v120"><a class="header" href="#upgrading-to-v120">Upgrading to v1.2.0</a></h1> -<p>Some counter metrics have been renamed, with the old names deprecated. See -<code>the metrics documentation <docs/metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12></code>_ -for details.</p> -<h1 id="upgrading-to-v110"><a class="header" href="#upgrading-to-v110">Upgrading to v1.1.0</a></h1> -<p>Synapse v1.1.0 removes support for older Python and PostgreSQL versions, as -outlined in <code>our deprecation notice <https://matrix.org/blog/2019/04/08/synapse-deprecating-postgres-9-4-and-python-2-x></code>_.</p> -<h2 id="minimum-python-version"><a class="header" href="#minimum-python-version">Minimum Python Version</a></h2> -<p>Synapse v1.1.0 has a minimum Python requirement of Python 3.5. Python 3.6 or -Python 3.7 are recommended as they have improved internal string handling, -significantly reducing memory usage.</p> -<p>If you use current versions of the Matrix.org-distributed Debian packages or -Docker images, action is not required.</p> -<p>If you install Synapse in a Python virtual environment, please see "Upgrading to -v0.34.0" for notes on setting up a new virtualenv under Python 3.</p> -<h2 id="minimum-postgresql-version"><a class="header" href="#minimum-postgresql-version">Minimum PostgreSQL Version</a></h2> -<p>If using PostgreSQL under Synapse, you will need to use PostgreSQL 9.5 or above. -Please see the -<code>PostgreSQL documentation <https://www.postgresql.org/docs/11/upgrading.html></code>_ -for more details on upgrading your database.</p> -<h1 id="upgrading-to-v10"><a class="header" href="#upgrading-to-v10">Upgrading to v1.0</a></h1> -<h2 id="validation-of-tls-certificates"><a class="header" href="#validation-of-tls-certificates">Validation of TLS certificates</a></h2> -<p>Synapse v1.0 is the first release to enforce -validation of TLS certificates for the federation API. It is therefore -essential that your certificates are correctly configured. See the <code>FAQ <docs/MSC1711_certificates_FAQ.md></code>_ for more information.</p> -<p>Note, v1.0 installations will also no longer be able to federate with servers -that have not correctly configured their certificates.</p> -<p>In rare cases, it may be desirable to disable certificate checking: for -example, it might be essential to be able to federate with a given legacy -server in a closed federation. This can be done in one of two ways:-</p> -<ul> -<li>Configure the global switch <code>federation_verify_certificates</code> to <code>false</code>.</li> -<li>Configure a whitelist of server domains to trust via <code>federation_certificate_verification_whitelist</code>.</li> -</ul> -<p>See the <code>sample configuration file <docs/sample_config.yaml></code>_ -for more details on these settings.</p> -<h2 id="email"><a class="header" href="#email">Email</a></h2> -<p>When a user requests a password reset, Synapse will send an email to the -user to confirm the request.</p> -<p>Previous versions of Synapse delegated the job of sending this email to an -identity server. If the identity server was somehow malicious or became -compromised, it would be theoretically possible to hijack an account through -this means.</p> -<p>Therefore, by default, Synapse v1.0 will send the confirmation email itself. If -Synapse is not configured with an SMTP server, password reset via email will be -disabled.</p> -<p>To configure an SMTP server for Synapse, modify the configuration section -headed <code>email</code>, and be sure to have at least the <code>smtp_host</code>, <code>smtp_port</code> -and <code>notif_from</code> fields filled out. You may also need to set <code>smtp_user</code>, -<code>smtp_pass</code>, and <code>require_transport_security</code>.</p> -<p>If you are absolutely certain that you wish to continue using an identity -server for password resets, set <code>trust_identity_server_for_password_resets</code> to <code>true</code>.</p> -<p>See the <code>sample configuration file <docs/sample_config.yaml></code>_ -for more details on these settings.</p> -<h2 id="new-email-templates"><a class="header" href="#new-email-templates">New email templates</a></h2> -<p>Some new templates have been added to the default template directory for the purpose of the -homeserver sending its own password reset emails. If you have configured a custom -<code>template_dir</code> in your Synapse config, these files will need to be added.</p> -<p><code>password_reset.html</code> and <code>password_reset.txt</code> are HTML and plain text templates -respectively that contain the contents of what will be emailed to the user upon attempting to -reset their password via email. <code>password_reset_success.html</code> and -<code>password_reset_failure.html</code> are HTML files that the content of which (assuming no redirect -URL is set) will be shown to the user after they attempt to click the link in the email sent -to them.</p> -<h1 id="upgrading-to-v0990"><a class="header" href="#upgrading-to-v0990">Upgrading to v0.99.0</a></h1> -<p>Please be aware that, before Synapse v1.0 is released around March 2019, you -will need to replace any self-signed certificates with those verified by a -root CA. Information on how to do so can be found at <code>the ACME docs <docs/ACME.md></code>_.</p> -<p>For more information on configuring TLS certificates see the <code>FAQ <docs/MSC1711_certificates_FAQ.md></code>_.</p> -<h1 id="upgrading-to-v0340"><a class="header" href="#upgrading-to-v0340">Upgrading to v0.34.0</a></h1> -<ol> -<li> -<p>This release is the first to fully support Python 3. Synapse will now run on -Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to -Python 3, as it has been shown to give performance improvements.</p> -<p>For users who have installed Synapse into a virtualenv, we recommend doing -this by creating a new virtualenv. For example::</p> -<pre><code>virtualenv -p python3 ~/synapse/env3 -source ~/synapse/env3/bin/activate -pip install matrix-synapse -</code></pre> -<p>You can then start synapse as normal, having activated the new virtualenv::</p> -<pre><code>cd ~/synapse -source env3/bin/activate -synctl start -</code></pre> -<p>Users who have installed from distribution packages should see the relevant -package documentation. See below for notes on Debian packages.</p> -<ul> -<li> -<p>When upgrading to Python 3, you <strong>must</strong> make sure that your log files are -configured as UTF-8, by adding <code>encoding: utf8</code> to the -<code>RotatingFileHandler</code> configuration (if you have one) in your -<code><server>.log.config</code> file. For example, if your <code>log.config</code> file -contains::</p> -<p>handlers: -file: -class: logging.handlers.RotatingFileHandler -formatter: precise -filename: homeserver.log -maxBytes: 104857600 -backupCount: 10 -filters: [context] -console: -class: logging.StreamHandler -formatter: precise -filters: [context]</p> -<p>Then you should update this to be::</p> -<p>handlers: -file: -class: logging.handlers.RotatingFileHandler -formatter: precise -filename: homeserver.log -maxBytes: 104857600 -backupCount: 10 -filters: [context] -encoding: utf8 -console: -class: logging.StreamHandler -formatter: precise -filters: [context]</p> -<p>There is no need to revert this change if downgrading to Python 2.</p> -</li> -</ul> -<p>We are also making available Debian packages which will run Synapse on -Python 3. You can switch to these packages with <code>apt-get install matrix-synapse-py3</code>, however, please read <code>debian/NEWS <https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS></code>_ -before doing so. The existing <code>matrix-synapse</code> packages will continue to -use Python 2 for the time being.</p> -</li> -<li> -<p>This release removes the <code>riot.im</code> from the default list of trusted -identity servers.</p> -<p>If <code>riot.im</code> is in your homeserver's list of -<code>trusted_third_party_id_servers</code>, you should remove it. It was added in -case a hypothetical future identity server was put there. If you don't -remove it, users may be unable to deactivate their accounts.</p> -</li> -<li> -<p>This release no longer installs the (unmaintained) Matrix Console web client -as part of the default installation. It is possible to re-enable it by -installing it separately and setting the <code>web_client_location</code> config -option, but please consider switching to another client.</p> -</li> -</ol> -<h1 id="upgrading-to-v0337"><a class="header" href="#upgrading-to-v0337">Upgrading to v0.33.7</a></h1> -<p>This release removes the example email notification templates from -<code>res/templates</code> (they are now internal to the python package). This should -only affect you if you (a) deploy your Synapse instance from a git checkout or -a github snapshot URL, and (b) have email notifications enabled.</p> -<p>If you have email notifications enabled, you should ensure that -<code>email.template_dir</code> is either configured to point at a directory where you -have installed customised templates, or leave it unset to use the default -templates.</p> -<h1 id="upgrading-to-v0273"><a class="header" href="#upgrading-to-v0273">Upgrading to v0.27.3</a></h1> -<p>This release expands the anonymous usage stats sent if the opt-in -<code>report_stats</code> configuration is set to <code>true</code>. We now capture RSS memory -and cpu use at a very coarse level. This requires administrators to install -the optional <code>psutil</code> python module.</p> -<p>We would appreciate it if you could assist by ensuring this module is available -and <code>report_stats</code> is enabled. This will let us see if performance changes to -synapse are having an impact to the general community.</p> -<h1 id="upgrading-to-v0150"><a class="header" href="#upgrading-to-v0150">Upgrading to v0.15.0</a></h1> -<p>If you want to use the new URL previewing API (/_matrix/media/r0/preview_url) -then you have to explicitly enable it in the config and update your dependencies -dependencies. See README.rst for details.</p> -<h1 id="upgrading-to-v0110"><a class="header" href="#upgrading-to-v0110">Upgrading to v0.11.0</a></h1> -<p>This release includes the option to send anonymous usage stats to matrix.org, -and requires that administrators explictly opt in or out by setting the -<code>report_stats</code> option to either <code>true</code> or <code>false</code>.</p> -<p>We would really appreciate it if you could help our project out by reporting -anonymized usage statistics from your homeserver. Only very basic aggregate -data (e.g. number of users) will be reported, but it helps us to track the -growth of the Matrix community, and helps us to make Matrix a success, as well -as to convince other networks that they should peer with us.</p> -<h1 id="upgrading-to-v090"><a class="header" href="#upgrading-to-v090">Upgrading to v0.9.0</a></h1> -<p>Application services have had a breaking API change in this version.</p> -<p>They can no longer register themselves with a home server using the AS HTTP API. This -decision was made because a compromised application service with free reign to register -any regex in effect grants full read/write access to the home server if a regex of <code>.*</code> -is used. An attack where a compromised AS re-registers itself with <code>.*</code> was deemed too -big of a security risk to ignore, and so the ability to register with the HS remotely has -been removed.</p> -<p>It has been replaced by specifying a list of application service registrations in -<code>homeserver.yaml</code>::</p> -<p>app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]</p> -<p>Where <code>registration-01.yaml</code> looks like::</p> -<p>url: <String> # e.g. "https://my.application.service.com" -as_token: <String> -hs_token: <String> -sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token -namespaces: -users: -- exclusive: <Boolean> -regex: <String> # e.g. "@prefix_.*" -aliases: -- exclusive: <Boolean> -regex: <String> -rooms: -- exclusive: <Boolean> -regex: <String></p> -<h1 id="upgrading-to-v080"><a class="header" href="#upgrading-to-v080">Upgrading to v0.8.0</a></h1> -<p>Servers which use captchas will need to add their public key to::</p> -<p>static/client/register/register_config.js</p> -<pre><code>window.matrixRegistrationConfig = { - recaptcha_public_key: "YOUR_PUBLIC_KEY" -}; -</code></pre> -<p>This is required in order to support registration fallback (typically used on -mobile devices).</p> -<h1 id="upgrading-to-v070"><a class="header" href="#upgrading-to-v070">Upgrading to v0.7.0</a></h1> -<p>New dependencies are:</p> -<ul> -<li>pydenticon</li> -<li>simplejson</li> -<li>syutil</li> -<li>matrix-angular-sdk</li> -</ul> -<p>To pull in these dependencies in a virtual env, run::</p> -<pre><code>python synapse/python_dependencies.py | xargs -n 1 pip install -</code></pre> -<h1 id="upgrading-to-v060"><a class="header" href="#upgrading-to-v060">Upgrading to v0.6.0</a></h1> -<p>To pull in new dependencies, run::</p> -<pre><code>python setup.py develop --user -</code></pre> -<p>This update includes a change to the database schema. To upgrade you first need -to upgrade the database by running::</p> -<pre><code>python scripts/upgrade_db_to_v0.6.0.py <db> <server_name> <signing_key> -</code></pre> -<p>Where <code><db></code> is the location of the database, <code><server_name></code> is the -server name as specified in the synapse configuration, and <code><signing_key></code> is -the location of the signing key as specified in the synapse configuration.</p> -<p>This may take some time to complete. Failures of signatures and content hashes -can safely be ignored.</p> -<h1 id="upgrading-to-v051"><a class="header" href="#upgrading-to-v051">Upgrading to v0.5.1</a></h1> -<p>Depending on precisely when you installed v0.5.0 you may have ended up with -a stale release of the reference matrix webclient installed as a python module. -To uninstall it and ensure you are depending on the latest module, please run::</p> -<pre><code>$ pip uninstall syweb -</code></pre> -<h1 id="upgrading-to-v050"><a class="header" href="#upgrading-to-v050">Upgrading to v0.5.0</a></h1> -<p>The webclient has been split out into a seperate repository/pacakage in this -release. Before you restart your homeserver you will need to pull in the -webclient package by running::</p> -<p>python setup.py develop --user</p> -<p>This release completely changes the database schema and so requires upgrading -it before starting the new version of the homeserver.</p> -<p>The script "database-prepare-for-0.5.0.sh" should be used to upgrade the -database. This will save all user information, such as logins and profiles, -but will otherwise purge the database. This includes messages, which -rooms the home server was a member of and room alias mappings.</p> -<p>If you would like to keep your history, please take a copy of your database -file and ask for help in #matrix:matrix.org. The upgrade process is, -unfortunately, non trivial and requires human intervention to resolve any -resulting conflicts during the upgrade process.</p> -<p>Before running the command the homeserver should be first completely -shutdown. To run it, simply specify the location of the database, e.g.:</p> -<p>./scripts/database-prepare-for-0.5.0.sh "homeserver.db"</p> -<p>Once this has successfully completed it will be safe to restart the -homeserver. You may notice that the homeserver takes a few seconds longer to -restart than usual as it reinitializes the database.</p> -<p>On startup of the new version, users can either rejoin remote rooms using room -aliases or by being reinvited. Alternatively, if any other homeserver sends a -message to a room that the homeserver was previously in the local HS will -automatically rejoin the room.</p> -<h1 id="upgrading-to-v040"><a class="header" href="#upgrading-to-v040">Upgrading to v0.4.0</a></h1> -<p>This release needs an updated syutil version. Run::</p> -<pre><code>python setup.py develop -</code></pre> -<p>You will also need to upgrade your configuration as the signing key format has -changed. Run::</p> -<pre><code>python -m synapse.app.homeserver --config-path <CONFIG> --generate-config -</code></pre> -<h1 id="upgrading-to-v030"><a class="header" href="#upgrading-to-v030">Upgrading to v0.3.0</a></h1> -<p>This registration API now closely matches the login API. This introduces a bit -more backwards and forwards between the HS and the client, but this improves -the overall flexibility of the API. You can now GET on /register to retrieve a list -of valid registration flows. Upon choosing one, they are submitted in the same -way as login, e.g::</p> -<p>{ -type: m.login.password, -user: foo, -password: bar -}</p> -<p>The default HS supports 2 flows, with and without Identity Server email -authentication. Enabling captcha on the HS will add in an extra step to all -flows: <code>m.login.recaptcha</code> which must be completed before you can transition -to the next stage. There is a new login type: <code>m.login.email.identity</code> which -contains the <code>threepidCreds</code> key which were previously sent in the original -register request. For more information on this, see the specification.</p> -<h2 id="web-client"><a class="header" href="#web-client">Web Client</a></h2> -<p>The VoIP specification has changed between v0.2.0 and v0.3.0. Users should -refresh any browser tabs to get the latest web client code. Users on -v0.2.0 of the web client will not be able to call those on v0.3.0 and -vice versa.</p> -<h1 id="upgrading-to-v020"><a class="header" href="#upgrading-to-v020">Upgrading to v0.2.0</a></h1> -<p>The home server now requires setting up of SSL config before it can run. To -automatically generate default config use::</p> -<pre><code>$ python synapse/app/homeserver.py \ - --server-name machine.my.domain.name \ - --bind-port 8448 \ - --config-path homeserver.config \ - --generate-config -</code></pre> -<p>This config can be edited if desired, for example to specify a different SSL -certificate to use. Once done you can run the home server using::</p> -<pre><code>$ python synapse/app/homeserver.py --config-path homeserver.config -</code></pre> -<p>See the README.rst for more information.</p> -<p>Also note that some config options have been renamed, including:</p> -<ul> -<li>"host" to "server-name"</li> -<li>"database" to "database-path"</li> -<li>"port" to "bind-port" and "unsecure-port"</li> -</ul> -<h1 id="upgrading-to-v001"><a class="header" href="#upgrading-to-v001">Upgrading to v0.0.1</a></h1> -<p>This release completely changes the database schema and so requires upgrading -it before starting the new version of the homeserver.</p> -<p>The script "database-prepare-for-0.0.1.sh" should be used to upgrade the -database. This will save all user information, such as logins and profiles, -but will otherwise purge the database. This includes messages, which -rooms the home server was a member of and room alias mappings.</p> -<p>Before running the command the homeserver should be first completely -shutdown. To run it, simply specify the location of the database, e.g.:</p> -<p>./scripts/database-prepare-for-0.0.1.sh "homeserver.db"</p> -<p>Once this has successfully completed it will be safe to restart the -homeserver. You may notice that the homeserver takes a few seconds longer to -restart than usual as it reinitializes the database.</p> -<p>On startup of the new version, users can either rejoin remote rooms using room -aliases or by being reinvited. Alternatively, if any other homeserver sends a -message to a room that the homeserver was previously in the local HS will -automatically rejoin the room.</p> - - </main> - - <nav class="nav-wrapper" aria-label="Page navigation"> - <!-- Mobile navigation buttons --> - - <a rel="prev" href="../delegate.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> - <i class="fa fa-angle-left"></i> - </a> - - - - <a rel="next" href="../MSC1711_certificates_FAQ.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> - <i class="fa fa-angle-right"></i> - </a> - - - <div style="clear: both"></div> - </nav> - </div> - </div> - - <nav class="nav-wide-wrapper" aria-label="Page navigation"> - - <a rel="prev" href="../delegate.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> - <i class="fa fa-angle-left"></i> - </a> - - - - <a rel="next" href="../MSC1711_certificates_FAQ.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> - <i class="fa fa-angle-right"></i> - </a> - - </nav> - - </div> - - - - - - - - - <script type="text/javascript"> - window.playground_copyable = true; - </script> - - - - - - <script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../mark.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../searcher.js" type="text/javascript" charset="utf-8"></script> - - - <script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script> - <script src="../highlight.js" type="text/javascript" charset="utf-8"></script> - <script src="../book.js" type="text/javascript" charset="utf-8"></script> - - <!-- Custom JS scripts --> - - <script type="text/javascript" src="../docs/website_files/table-of-contents.js"></script> - - - - - </body> -</html> \ No newline at end of file |