<buttonid="sidebar-toggle"class="icon-button"type="button"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<ahref="https://github.com/matrix-org/synapse/edit/develop/docs/upgrade.md"title="Suggest an edit"aria-label="Suggest an edit">
<iid="git-edit-button"class="fa fa-edit"></i>
</a>
</div>
</div>
<divid="search-wrapper"class="hidden">
<formid="searchbar-outer"class="searchbar-outer">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<h1id="upgrading-to-v1440"><aclass="header"href="#upgrading-to-v1440">Upgrading to v1.44.0</a></h1>
<h2id="the-url-preview-cache-is-no-longer-mirrored-to-storage-providers"><aclass="header"href="#the-url-preview-cache-is-no-longer-mirrored-to-storage-providers">The URL preview cache is no longer mirrored to storage providers</a></h2>
<p>The <code>url_cache/</code> and <code>url_cache_thumbnails/</code> directories in the media store are
no longer mirrored to storage providers. These two directories can be safely
deleted from any configured storage providers to reclaim space.</p>
<h1id="upgrading-to-v1430"><aclass="header"href="#upgrading-to-v1430">Upgrading to v1.43.0</a></h1>
<h2id="the-spaces-summary-apis-can-now-be-handled-by-workers"><aclass="header"href="#the-spaces-summary-apis-can-now-be-handled-by-workers">The spaces summary APIs can now be handled by workers</a></h2>
<h2id="user-interactive-authentication-fallback-templates-can-now-display-errors"><aclass="header"href="#user-interactive-authentication-fallback-templates-can-now-display-errors">User-interactive authentication fallback templates can now display errors</a></h2>
<p>This may affect you if you make use of custom HTML templates for the
<ahref="../synapse/res/templates/recaptcha.html">reCAPTCHA</a> or
<h2id="removal-of-out-of-date-email-pushers"><aclass="header"href="#removal-of-out-of-date-email-pushers">Removal of out-of-date email pushers</a></h2>
<p>Users will stop receiving message updates via email for addresses that were
<h2id="add-support-for-routing-outbound-http-requests-via-a-proxy-for-federation"><aclass="header"href="#add-support-for-routing-outbound-http-requests-via-a-proxy-for-federation">Add support for routing outbound HTTP requests via a proxy for federation</a></h2>
<p>Since Synapse 1.6.0 (2019-11-26) you can set a proxy for outbound HTTP requests via
http_proxy/https_proxy environment variables. This proxy was set for:</p>
<ul>
<li>push</li>
<li>url previews</li>
<li>phone-home stats</li>
<li>recaptcha validation</li>
<li>CAS auth validation</li>
<li>OpenID Connect</li>
<li>Federation (checking public key revocation)</li>
</ul>
<p>In this version we have added support for outbound requests for:</p>
<ul>
<li>Outbound federation</li>
<li>Downloading remote media</li>
<li>Fetching public keys of other servers</li>
</ul>
<p>These requests use the same proxy configuration. If you have a proxy configuration we
recommend to verify the configuration. It may be necessary to adjust the <code>no_proxy</code>
environment variable.</p>
<p>See <ahref="setup/forward_proxy.html">using a forward proxy with Synapse documentation</a> for
<h2id="deprecation-of-template_dir"><aclass="header"href="#deprecation-of-template_dir">Deprecation of <code>template_dir</code></a></h2>
<p>The <code>template_dir</code> settings in the <code>sso</code>, <code>account_validity</code> and <code>email</code> sections of the
configuration file are now deprecated. Server admins should use the new
<code>templates.custom_template_directory</code> setting in the configuration file and use one single
custom template directory for all aforementioned features. Template file names remain
unchanged. See <ahref="https://matrix-org.github.io/synapse/latest/templates.html">the related documentation</a>
for more information and examples.</p>
<p>We plan to remove support for these settings in October 2021.</p>
<h2id="_synapseadminv1usersuseridmedia-must-be-handled-by-media-workers"><aclass="header"href="#_synapseadminv1usersuseridmedia-must-be-handled-by-media-workers"><code>/_synapse/admin/v1/users/{userId}/media</code> must be handled by media workers</a></h2>
<h1id="upgrading-to-v1390"><aclass="header"href="#upgrading-to-v1390">Upgrading to v1.39.0</a></h1>
<h2id="deprecation-of-the-current-third-party-rules-module-interface"><aclass="header"href="#deprecation-of-the-current-third-party-rules-module-interface">Deprecation of the current third-party rules module interface</a></h2>
<p>The current third-party rules module interface is deprecated in favour of the new generic
modules system introduced in Synapse v1.37.0. Authors of third-party rules modules can refer
to <ahref="modules.html#porting-an-existing-module-that-uses-the-old-interface">this documentation</a>
to update their modules. Synapse administrators can refer to <ahref="modules.html#using-modules">this documentation</a>
to update their configuration once the modules they are using have been updated.</p>
<p>We plan to remove support for the current third-party rules interface in September 2021.</p>
<h1id="upgrading-to-v1380"><aclass="header"href="#upgrading-to-v1380">Upgrading to v1.38.0</a></h1>
<h2id="re-indexing-of-events-table-on-postgres-databases"><aclass="header"href="#re-indexing-of-events-table-on-postgres-databases">Re-indexing of <code>events</code> table on Postgres databases</a></h2>
<p>This release includes a database schema update which requires re-indexing one of
the larger tables in the database, <code>events</code>. This could result in increased
disk I/O for several hours or days after upgrading while the migration
completes. Furthermore, because we have to keep the old indexes until the new
indexes are ready, it could result in a significant, temporary, increase in
disk space.</p>
<p>To get a rough idea of the disk space required, check the current size of one
of the indexes. For example, from a <code>psql</code> shell, run the following sql:</p>
<h1id="upgrading-to-v1370"><aclass="header"href="#upgrading-to-v1370">Upgrading to v1.37.0</a></h1>
<h2id="deprecation-of-the-current-spam-checker-interface"><aclass="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.
<p>The <code>room_invite_state_types</code> configuration setting has been deprecated
and replaced with <code>room_prejoin_state</code>. See the <ahref="https://github.com/matrix-org/synapse/blob/v1.34.0/docs/sample_config.yaml#L1515">sample configuration
file</a>.</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
<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>
<h1id="upgrading-to-v1330"><aclass="header"href="#upgrading-to-v1330">Upgrading to v1.33.0</a></h1>
<h2id="account-validity-html-templates-can-now-display-a-users-expiration-date"><aclass="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
<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 <ahref="https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_renewed.html">default
template</a>
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
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>
<h1id="upgrading-to-v1320"><aclass="header"href="#upgrading-to-v1320">Upgrading to v1.32.0</a></h1>
<h2id="regression-causing-connected-prometheus-instances-to-become-overwhelmed"><aclass="header"href="#regression-causing-connected-prometheus-instances-to-become-overwhelmed">Regression causing connected Prometheus instances to become overwhelmed</a></h2>
<h2id="dropping-support-for-old-python-postgres-and-sqlite-versions"><aclass="header"href="#dropping-support-for-old-python-postgres-and-sqlite-versions">Dropping support for old Python, Postgres and SQLite versions</a></h2>
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>
<h2id="removal-of-old-list-accounts-admin-api"><aclass="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
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>
<h2id="application-services-must-use-type-mloginapplication_service-when-registering-users"><aclass="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 <ahref="https://matrix.org/docs/spec/application_service/r0.1.2#server-admin-style-permissions">Application Service
spec</a>,
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>
<h1id="upgrading-to-v1290"><aclass="header"href="#upgrading-to-v1290">Upgrading to v1.29.0</a></h1>
<h2id="requirement-for-x-forwarded-proto-header"><aclass="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
[x_forwarded]{.title-ref} option on an HTTP listener), Synapse now
expects to receive an [X-Forwarded-Proto]{.title-ref} 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 [X-Forwarded-Proto]{.title-ref} header to
[https]{.title-ref} or [http]{.title-ref} to indicate the protocol used
by the client.</p>
<p>Synapse also requires the [Host]{.title-ref} header to be preserved.</p>
example configurations have been updated to show how to set these
headers.</p>
<p>(Users of <ahref="https://caddyserver.com/">Caddy</a> are unaffected, since we
believe it sets [X-Forwarded-Proto]{.title-ref} by default.)</p>
<h1id="upgrading-to-v1270"><aclass="header"href="#upgrading-to-v1270">Upgrading to v1.27.0</a></h1>
<h2id="changes-to-callback-uri-for-oauth2--openid-connect-and-saml2"><aclass="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>
<h1id="upgrading-to-v1260"><aclass="header"href="#upgrading-to-v1260">Upgrading to v1.26.0</a></h1>
<h2id="rolling-back-to-v1250-after-a-failed-upgrade"><aclass="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>
<pre><codeclass="language-sql">UPDATE schema_version SET version = 58;
</code></pre>
</li>
<li>
<p>Delete the ignored users & chain cover data:</p>
<pre><codeclass="language-sql">DROP TABLE IF EXISTS ignored_users;
<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>
<h1id="upgrading-to-v1210"><aclass="header"href="#upgrading-to-v1210">Upgrading to v1.21.0</a></h1>
<h2id="forwarding-_synapseclient-through-your-reverse-proxy"><aclass="header"href="#forwarding-_synapseclient-through-your-reverse-proxy">Forwarding <code>/_synapse/client</code> through your reverse proxy</a></h2>
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
[POST]{.title-ref} 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>
<h2id="updated-single-sign-on-html-templates"><aclass="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>
<h1id="upgrading-to-v1180"><aclass="header"href="#upgrading-to-v1180">Upgrading to v1.18.0</a></h1>
<h2id="docker--py3title-ref-suffix-will-be-removed-in-future-versions"><aclass="header"href="#docker--py3title-ref-suffix-will-be-removed-in-future-versions">Docker [-py3]{.title-ref} suffix will be removed in future versions</a></h2>
<p>From 10th August 2020, we will no longer publish Docker images with the
[-py3]{.title-ref} tag suffix. The images tagged with the
[-py3]{.title-ref} 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 [latest-py3]{.title-ref} tag.
Existing per-release tags (such as [v1.18.0-py3]{.title-ref}) will not
be removed, but no new [-py3]{.title-ref} tags will be added.</p>
<p>Scripts relying on the [-py3]{.title-ref} suffix will need to be
updated.</p>
<h2id="redis-replication-is-now-recommended-in-lieu-of-tcp-replication"><aclass="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
<h1id="upgrading-to-v1140"><aclass="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>
<h1id="upgrading-to-v1130"><aclass="header"href="#upgrading-to-v1130">Upgrading to v1.13.0</a></h1>
<h2id="incorrect-database-migration-in-old-synapse-versions"><aclass="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>
<p>: - created at v1.4.0 or later,
- upgraded via v1.3.x, or
- upgraded straight from v1.2.1 or earlier to v1.13.0 or later.</p>
<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 [psql]{.title-ref} or
[sqlite3]{.title-ref} console:</p>
<pre><codeclass="language-sql">INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
<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>
<h2id="rolling-back-to-v1124-after-a-failed-upgrade"><aclass="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>
<pre><codeclass="language-sql">UPDATE schema_version SET version = 57;
</code></pre>
</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>
<h1id="upgrading-to-v1120"><aclass="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>
<olstart="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 [psql]{.title-ref} or
[sqlite3]{.title-ref} console. It is safe to run it while Synapse is
still running.</p>
<pre><codeclass="language-sql">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;
</code></pre>
<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>
<pre><codeclass="language-sql">CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index
ON state_events(room_id) WHERE type = 'm.room.create';
</code></pre>
<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.
<h4id="delegate-email-to-an-identity-server"><aclass="header"href="#delegate-email-to-an-identity-server">Delegate email to an identity server</a></h4>
<p>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.</p>
<p>To this end, we will continue to support email verification delegation
via the <code>vector.im</code> and <code>matrix.org</code> identity servers for two months.
Support for delegated email verification will be disabled on Monday 2nd
December.</p>
<p>The <code>account_threepid_delegates</code> dictionary defines whether the
homeserver should delegate an external server (typically an <ahref="https://matrix.org/docs/spec/identity_service/r0.2.1">identity
server</a>) to handle
sending confirmation messages via email and SMS.</p>
<p>So to delegate email verification, in <code>homeserver.yaml</code>, set
<code>account_threepid_delegates.email</code> to the base URL of an identity
