<buttonid="sidebar-toggle"class="icon-button"type="button"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p>Welcome to the documentation repository for Synapse, a
<ahref="https://matrix.org">Matrix</a> homeserver implementation developed by the matrix.org core
team.</p>
<h2id="installing-and-using-synapse"><aclass="header"href="#installing-and-using-synapse">Installing and using Synapse</a></h2>
<p>This documentation covers topics for <strong>installation</strong>, <strong>configuration</strong> and
<strong>maintenance</strong> of your Synapse process:</p>
<ul>
<li>
<p>Learn how to <ahref="setup/installation.html">install</a> and
<ahref="usage/configuration/config_documentation.html">configure</a> your own instance, perhaps with <ahref="usage/configuration/user_authentication/index.html">Single
Sign-On</a>.</p>
</li>
<li>
<p>See how to <ahref="upgrade.html">upgrade</a> between Synapse versions.</p>
</li>
<li>
<p>Administer your instance using the <ahref="usage/administration/admin_api/index.html">Admin
<p>The quickest way to get up and running with ArchLinux is probably with the community package
<ahref="https://www.archlinux.org/packages/community/any/matrix-synapse/">https://www.archlinux.org/packages/community/any/matrix-synapse/</a>, which should pull in most of
the necessary dependencies.</p>
<p>pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):</p>
<h3id="installing-as-a-python-module-from-pypi"><aclass="header"href="#installing-as-a-python-module-from-pypi">Installing as a Python module from PyPI</a></h3>
<p>It's also possible to install Synapse as a Python module from PyPI.</p>
<p>When following this route please make sure that the <ahref="setup/installation.html#platform-specific-prerequisites">Platform-specific prerequisites</a> are already installed.</p>
<p>System requirements:</p>
<ul>
<li>POSIX-compliant system (tested on Linux & OS X)</li>
<li>Python 3.7 or later, up to Python 3.10.</li>
<li>At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org</li>
</ul>
<p>To install the Synapse homeserver run:</p>
<pre><codeclass="language-sh">mkdir -p ~/synapse
virtualenv -p python3 ~/synapse/env
source ~/synapse/env/bin/activate
pip install --upgrade pip
pip install --upgrade setuptools
pip install matrix-synapse
</code></pre>
<p>This will download Synapse from <ahref="https://pypi.org/project/matrix-synapse">PyPI</a>
and install it, along with the python libraries it uses, into a virtual environment
under <code>~/synapse/env</code>. Feel free to pick a different directory if you
prefer.</p>
<p>This Synapse installation can then be later upgraded by using pip again with the
<p>Before you can start Synapse, you will need to generate a configuration
file. To do this, run (in your virtualenv, as before):</p>
<pre><codeclass="language-sh">cd ~/synapse
python -m synapse.app.homeserver \
--server-name my.domain.name \
--config-path homeserver.yaml \
--generate-config \
--report-stats=[yes|no]
</code></pre>
<p>... substituting an appropriate value for <code>--server-name</code> and choosing whether
or not to report usage statistics (hostname, Synapse version, uptime, total
users, etc.) to the developers via the <code>--report-stats</code> argument.</p>
<p>This command will generate you a config file that you can then customise, but it will
also generate a set of keys for you. These keys will allow your homeserver to
identify itself to other homeserver, so don't lose or delete them. It would be
wise to back them up somewhere safe. (If, for whatever reason, you do need to
change your homeserver's keys, you may find that other homeserver have the
old key cached. If you update the signing key, you should change the name of the
key in the <code><server name>.signing.key</code> file (the second word) to something
different. See the <ahref="https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys">spec</a> for more information on key management).</p>
<p>To actually run your new homeserver, pick a working directory for Synapse to
<p>If you get an error along the lines of <code>FATAL: Ident authentication failed for user "synapse_user"</code>, you may need to use an authentication method other than
<code>ident</code>:</p>
<ul>
<li>
<p>If the <code>synapse_user</code> user has a password, add the password to the <code>database:</code>
section of <code>homeserver.yaml</code>. Then add the following to <code>pg_hba.conf</code>:</p>
<pre><code>host synapse synapse_user ::1/128 md5 # or `scram-sha-256` instead of `md5` if you use that
</code></pre>
</li>
<li>
<p>If the <code>synapse_user</code> user does not have a password, then a password doesn't
have to be added to <code>homeserver.yaml</code>. But the following does need to be added
<p>Note that line order matters in <code>pg_hba.conf</code>, so make sure that if you do add a
new line, it is inserted before:</p>
<pre><code>host all all ::1/128 ident
</code></pre>
<h3id="fixing-incorrect-collate-or-ctype"><aclass="header"href="#fixing-incorrect-collate-or-ctype">Fixing incorrect <code>COLLATE</code> or <code>CTYPE</code></a></h3>
<p>Synapse will refuse to set up a new database if it has the wrong values of
<code>COLLATE</code> and <code>CTYPE</code> set. Synapse will also refuse to start an existing database with incorrect values
of <code>COLLATE</code> and <code>CTYPE</code> unless the config flag <code>allow_unsafe_locale</code>, found in the
<code>database</code> section of the config, is set to true. Using different locales can cause issues if the locale library is updated from
underneath the database, or if a different version of the locale is used on any
replicas.</p>
<p>If you have a databse with an unsafe locale, the safest way to fix the issue is to dump the database and recreate it with
the correct locale parameter (as shown above). It is also possible to change the
parameters on a live database and run a <code>REINDEX</code> on the entire database,
however extreme care must be taken to avoid database corruption.</p>
<p>Note that the above may fail with an error about duplicate rows if corruption
has already occurred, and such duplicate rows will need to be manually removed.</p>
<p>Synapse uses Postgres sequences to generate IDs for various tables. A sequence
and associated table can get out of sync if, for example, Synapse has been
downgraded and then upgraded again.</p>
<p>To fix the issue shut down Synapse (including any and all workers) and run the
SQL command included in the error message. Once done Synapse should start
successfully.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="using-a-reverse-proxy-with-synapse"><aclass="header"href="#using-a-reverse-proxy-with-synapse">Using a reverse proxy with Synapse</a></h1>
<p>It is recommended to put a reverse proxy such as
<p><strong>NOTE</strong>: ensure the <code>nocanon</code> options are included.</p>
<p><strong>NOTE 2</strong>: It appears that Synapse is currently incompatible with the ModSecurity module for Apache (<code>mod_security2</code>). If you need it enabled for other services on your web server, you can disable it for Synapse's two VirtualHosts by including the following lines before each of the two <code></VirtualHost></code> above:</p>
<p>Endpoints for administering your Synapse instance are placed under
<code>/_synapse/admin</code>. These require authentication through an access token of an
admin user. However as access to these endpoints grants the caller a lot of power,
we do not recommend exposing them to the public internet without good reason.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="using-a-forward-proxy-with-synapse"><aclass="header"href="#using-a-forward-proxy-with-synapse">Using a forward proxy with Synapse</a></h1>
<p>You can use Synapse with a forward or outbound proxy. An example of when
this is necessary is in corporate environments behind a DMZ (demilitarized zone).
Synapse supports routing outbound HTTP(S) requests via a proxy. Only HTTP(S)
proxy is supported, not SOCKS proxy or anything else.</p>
<p>The <code>http_proxy</code>, <code>https_proxy</code>, <code>no_proxy</code> environment variables are used to
specify proxy settings. The environment variable is not case sensitive.</p>
<ul>
<li><code>http_proxy</code>: Proxy server to use for HTTP requests.</li>
<li><code>https_proxy</code>: Proxy server to use for HTTPS requests.</li>
<li><code>no_proxy</code>: Comma-separated list of hosts, IP addresses, or IP ranges in CIDR
format which should not use the proxy. Synapse will directly connect to these hosts.</li>
</ul>
<p>The <code>http_proxy</code> and <code>https_proxy</code> environment variables have the form: <code>[scheme://][<username>:<password>@]<host>[:<port>]</code></p>
<ul>
<li>
<p>Supported schemes are <code>http://</code> and <code>https://</code>. The default scheme is <code>http://</code>
for compatibility reasons; it is recommended to set a scheme. If scheme is set
to <code>https://</code> the connection uses TLS between Synapse and the proxy.</p>
<p><strong>NOTE</strong>: Synapse validates the certificates. If the certificate is not
valid, then the connection is dropped.</p>
</li>
<li>
<p>Default port if not given is <code>1080</code>.</p>
</li>
<li>
<p>Username and password are optional and will be used to authenticate against
<p>This document explains how to enable VoIP relaying on your homeserver with
TURN.</p>
<p>The synapse Matrix homeserver supports integration with TURN server via the
<ahref="https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00">TURN server REST API</a>. This
allows the homeserver to generate credentials that are valid for use on the
TURN server through the use of a secret shared between the homeserver and the
TURN server.</p>
<p>The following sections describe how to install <ahref="https://github.com/coturn/coturn">coturn</a> (which implements the TURN REST API) and integrate it with synapse.</p>
<p>Download the <ahref="https://github.com/coturn/coturn/releases/latest">latest release</a> from github. Unpack it and <code>cd</code> into the directory.</p>
</li>
<li>
<p>Configure it:</p>
<pre><codeclass="language-sh">./configure
</code></pre>
<p>You may need to install <code>libevent2</code>: if so, you should do so in
the way recommended by your operating system. You can ignore
warnings about lack of database support: a database is unnecessary
<p>Try removing any AAAA records for your TURN server, so that it is only
reachable over IPv4.</p>
</li>
<li>
<p>If your TURN server is behind NAT:</p>
<ul>
<li>
<p>double-check that your NAT gateway is correctly forwarding all TURN
ports (normally 3478 & 5349 for TCP & UDP TURN traffic, and 49152-65535 for the UDP
relay) to the NAT-internal address of your TURN server. If advertising
both IPv4 and IPv6 external addresses via the <code>external-ip</code> option, ensure
that the NAT is forwarding both IPv4 and IPv6 traffic to the IPv4 and IPv6
internal addresses of your TURN server. When in doubt, remove AAAA records
for your TURN server and specify only an IPv4 address as your <code>external-ip</code>.</p>
</li>
<li>
<p>ensure that your TURN server uses the NAT gateway as its default route.</p>
</li>
</ul>
</li>
<li>
<p>Enable more verbose logging in coturn via the <code>verbose</code> setting:</p>
<pre><code>verbose
</code></pre>
<p>... and then see if there are any clues in its logs.</p>
</li>
<li>
<p>If you are using a browser-based client under Chrome, check
<code>chrome://webrtc-internals/</code> for insights into the internals of the
negotiation. On Firefox, check the "Connection Log" on <code>about:webrtc</code>.</p>
<p>(Understanding the output is beyond the scope of this document!)</p>
</li>
<li>
<p>You can test your Matrix homeserver TURN setup with <ahref="https://test.voip.librepush.net/">https://test.voip.librepush.net/</a>.
Note that this test is not fully reliable yet, so don't be discouraged if
the test fails.
<ahref="https://github.com/matrix-org/voip-tester">Here</a> is the github repo of the
source of the tester, where you can file bug reports.</p>
</li>
<li>
<p>There is a WebRTC test tool at
<ahref="https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/">https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/</a>. To
use it, you will need a username/password for your TURN server. You can
either:</p>
<ul>
<li>
<p>look for the <code>GET /_matrix/client/r0/voip/turnServer</code> request made by a
matrix client to your homeserver in your browser's network inspector. In
the response you should see <code>username</code> and <code>password</code>. Or:</p>
<p>Note, specifying a port is optional. If no port is specified, then it defaults
to 8448.</p>
<h3id="serving-a-well-knownmatrixserver-file-with-synapse"><aclass="header"href="#serving-a-well-knownmatrixserver-file-with-synapse">Serving a <code>.well-known/matrix/server</code> file with Synapse</a></h3>
<p>If you are able to set up your domain so that <code>https://<server_name></code> is routed to
Synapse (i.e., the only change needed is to direct federation traffic to port 443
instead of port 8448), then it is possible to configure Synapse to serve a suitable
<code>.well-known/matrix/server</code> file. To do so, add the following to your <code>homeserver.yaml</code>
<h3id="when-do-i-need-delegation"><aclass="header"href="#when-do-i-need-delegation">When do I need delegation?</a></h3>
<p>If your homeserver's APIs are accessible on the default federation port (8448)
and the domain your <code>server_name</code> points to, you do not need any delegation.</p>
<p>For instance, if you registered <code>example.com</code> and pointed its DNS A record at a
fresh server, you could install Synapse on that host, giving it a <code>server_name</code>
of <code>example.com</code>, and once a reverse proxy has been set up to proxy all requests
sent to the port <code>8448</code> and serve TLS certificates for <code>example.com</code>, you
wouldn't need any delegation set up.</p>
<p><strong>However</strong>, if your homeserver's APIs aren't accessible on port 8448 and on the
domain <code>server_name</code> points to, you will need to let other servers know how to
find it using delegation.</p>
<h3id="should-i-use-a-reverse-proxy-for-federation-traffic"><aclass="header"href="#should-i-use-a-reverse-proxy-for-federation-traffic">Should I use a reverse proxy for federation traffic?</a></h3>
<p>Generally, using a reverse proxy for both the federation and client traffic is a good
idea, since it saves handling TLS traffic in Synapse. See
<ahref="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a
<h1id="upgrading-to-v1660"><aclass="header"href="#upgrading-to-v1660">Upgrading to v1.66.0</a></h1>
<h2id="delegation-of-email-validation-no-longer-supported"><aclass="header"href="#delegation-of-email-validation-no-longer-supported">Delegation of email validation no longer supported</a></h2>
<p>As of this version, Synapse no longer allows the tasks of verifying email address
ownership, and password reset confirmation, to be delegated to an identity server.
This removal was previously planned for Synapse 1.64.0, but was
<ahref="https://github.com/matrix-org/synapse/issues/13421">delayed</a> until now to give
homeserver administrators more notice of the change.</p>
<p>To continue to allow users to add email addresses to their homeserver accounts,
and perform password resets, make sure that Synapse is configured with a working
email server in the <ahref="https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email"><code>email</code> configuration
section</a>
(including, at a minimum, a <code>notif_from</code> setting.)</p>
<p>Specifying an <code>email</code> setting under <code>account_threepid_delegates</code> will now cause
<h1id="upgrading-to-v1640"><aclass="header"href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1>
<h2id="deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers"><aclass="header"href="#deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers">Deprecation of the ability to delegate e-mail verification to identity servers</a></h2>
<p>Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.</p>
<p>If you require your homeserver to verify e-mail addresses or to support password resets via e-mail, please configure your homeserver with SMTP access so that it can send e-mails on its own behalf.
<ahref="https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email">Consult the configuration documentation for more information.</a></p>
<p>The option that will be removed is <code>account_threepid_delegates.email</code>.</p>
<h2id="changes-to-the-event-replication-streams"><aclass="header"href="#changes-to-the-event-replication-streams">Changes to the event replication streams</a></h2>
<p>Synapse now includes a flag indicating if an event is an outlier when
replicating it to other workers. This is a forwards- and backwards-incompatible
change: v1.63 and workers cannot process events replicated by v1.64 workers, and
vice versa.</p>
<p>Once all workers are upgraded to v1.64 (or downgraded to v1.63), event
has recently been released, which fixes a memory leak that occurs during <code>/sync</code>
requests. We advise server administrators who installed Synapse via pip to upgrade
frozendict with <code>pip install --upgrade frozendict</code>. The Docker image
<code>matrixdotorg/synapse</code> and the Debian packages from <code>packages.matrix.org</code> already
include the updated library.</p>
<h1id="upgrading-to-v1620"><aclass="header"href="#upgrading-to-v1620">Upgrading to v1.62.0</a></h1>
<h2id="new-signatures-for-spam-checker-callbacks"><aclass="header"href="#new-signatures-for-spam-checker-callbacks">New signatures for spam checker callbacks</a></h2>
<p>As a followup to changes in v1.60.0, the following spam-checker callbacks have changed signature:</p>
<ul>
<li><code>user_may_join_room</code></li>
<li><code>user_may_invite</code></li>
<li><code>user_may_send_3pid_invite</code></li>
<li><code>user_may_create_room</code></li>
<li><code>user_may_create_room_alias</code></li>
<li><code>user_may_publish_room</code></li>
<li><code>check_media_file_for_spam</code></li>
</ul>
<p>For each of these methods, the previous callback signature has been deprecated.</p>
<p>Whereas callbacks used to return <code>bool</code>, they should now return <code>Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"]</code>.</p>
<p>For instance, if your module implements <code>user_may_join_room</code> as follows:</p>
# Request is spam, mark it as forbidden (you may use some more precise error
# code if it is useful).
return synapse.module_api.errors.Codes.FORBIDDEN
# Request is not spam, mark it as such.
return synapse.module_api.NOT_SPAM
</code></pre>
<h1id="upgrading-to-v1610"><aclass="header"href="#upgrading-to-v1610">Upgrading to v1.61.0</a></h1>
<h2id="removal-of-deprecated-communitygroups"><aclass="header"href="#removal-of-deprecated-communitygroups">Removal of deprecated community/groups</a></h2>
<p>This release of Synapse will remove deprecated community/groups from codebase.</p>
<h1id="upgrading-to-v1600"><aclass="header"href="#upgrading-to-v1600">Upgrading to v1.60.0</a></h1>
<h2id="adding-a-new-unique-index-to-state_group_edges-could-fail-if-your-database-is-corrupted"><aclass="header"href="#adding-a-new-unique-index-to-state_group_edges-could-fail-if-your-database-is-corrupted">Adding a new unique index to <code>state_group_edges</code> could fail if your database is corrupted</a></h2>
<p>This release of Synapse will add a unique index to the <code>state_group_edges</code> table, in order
to prevent accidentally introducing duplicate information (for example, because a database
backup was restored multiple times).</p>
<p>Duplicate rows being present in this table could cause drastic performance problems; see
<ahref="https://github.com/matrix-org/synapse/issues/11779">issue 11779</a> for more details.</p>
<p>If your Synapse database already has had duplicate rows introduced into this table,
this could fail, with either of these errors:</p>
<p><strong>On Postgres:</strong></p>
<pre><code>synapse.storage.background_updates - 623 - INFO - background_updates-0 - Adding index state_group_edges_unique_idx to state_group_edges
<p>At the command-line, use <code>sqlite3 path/to/your-homeserver-database.db</code>:</p>
<pre><codeclass="language-sql">BEGIN;
DELETE FROM state_group_edges WHERE (rowid, state_group, prev_state_group) IN (
SELECT row_id, state_group, prev_state_group
FROM (
SELECT
rowid AS row_id,
MIN(rowid) OVER (PARTITION BY state_group, prev_state_group) AS min_row_id,
state_group,
prev_state_group
FROM state_group_edges
)
WHERE row_id <> min_row_id
);
COMMIT;
</code></pre>
<h3id="for-more-details"><aclass="header"href="#for-more-details">For more details</a></h3>
<p><ahref="https://github.com/matrix-org/synapse/issues/11779#issuecomment-1131545970">This comment on issue 11779</a>
has queries that can be used to check a database for this problem in advance.</p>
</details>
<h2id="new-signature-for-the-spam-checker-callback-check_event_for_spam"><aclass="header"href="#new-signature-for-the-spam-checker-callback-check_event_for_spam">New signature for the spam checker callback <code>check_event_for_spam</code></a></h2>
<p>The previous signature has been deprecated.</p>
<p>Whereas <code>check_event_for_spam</code> callbacks used to return <code>Union[str, bool]</code>, they should now return <code>Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"]</code>.</p>
<p>This is part of an ongoing refactoring of the SpamChecker API to make it less ambiguous and more powerful.</p>
<p>If your module implements <code>check_event_for_spam</code> as follows:</p>
# Event is spam, mark it as forbidden (you may use some more precise error
# code if it is useful).
return synapse.module_api.errors.Codes.FORBIDDEN
# Event is not spam, mark it as such.
return synapse.module_api.NOT_SPAM
</code></pre>
<h1id="upgrading-to-v1590"><aclass="header"href="#upgrading-to-v1590">Upgrading to v1.59.0</a></h1>
<h2id="device-name-lookup-over-federation-has-been-disabled-by-default"><aclass="header"href="#device-name-lookup-over-federation-has-been-disabled-by-default">Device name lookup over federation has been disabled by default</a></h2>
<p>The names of user devices are no longer visible to users on other homeservers by default.
Device IDs are unaffected, as these are necessary to facilitate end-to-end encryption.</p>
homeserver config option to <code>true</code>.</p>
<h2id="deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types"><aclass="header"href="#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types">Deprecation of the <code>synapse.app.appservice</code> and <code>synapse.app.user_dir</code> worker application types</a></h2>
<p>The <code>synapse.app.appservice</code> worker application type allowed you to configure a
single worker to use to notify application services of new events, as long
as this functionality was disabled on the main process with <code>notify_appservices: False</code>.
Further, the <code>synapse.app.user_dir</code> worker application type allowed you to configure
a single worker to be responsible for updating the user directory, as long as this
was disabled on the main process with <code>update_user_directory: False</code>.</p>
<p>To unify Synapse's worker types, the <code>synapse.app.appservice</code> worker application
type and the <code>notify_appservices</code> configuration option have been deprecated.
The <code>synapse.app.user_dir</code> worker application type and <code>update_user_directory</code>
configuration option have also been deprecated.</p>
<p>To get the same functionality as was provided by the deprecated options, it's now recommended that the <code>synapse.app.generic_worker</code>
worker application type is used and that the <code>notify_appservices_from_worker</code> and/or
<code>update_user_directory_from_worker</code> options are set to the name of a worker.</p>
<p>For the time being, the old options can be used alongside the new options to make
it easier to transition between the two configurations, however please note that:</p>
<ul>
<li>the options must not contradict each other (otherwise Synapse won't start); and</li>
<li>the <code>notify_appservices</code> and <code>update_user_directory</code> options will be removed in a future release of Synapse.</li>
</ul>
<p>Please see the <ahref="workers.html#notifying-application-services"><em>Notifying Application Services</em></a> and
<ahref="workers.html#updating-the-user-directory"><em>Updating the User Directory</em></a> sections of the worker
documentation for more information.</p>
<h1id="upgrading-to-v1580"><aclass="header"href="#upgrading-to-v1580">Upgrading to v1.58.0</a></h1>
<h2id="groupscommunities-feature-has-been-disabled-by-default"><aclass="header"href="#groupscommunities-feature-has-been-disabled-by-default">Groups/communities feature has been disabled by default</a></h2>
<p>The non-standard groups/communities feature in Synapse has been disabled by default
and will be removed in Synapse v1.61.0.</p>
<h1id="upgrading-to-v1570"><aclass="header"href="#upgrading-to-v1570">Upgrading to v1.57.0</a></h1>
<h2id="changes-to-database-schema-for-application-services"><aclass="header"href="#changes-to-database-schema-for-application-services">Changes to database schema for application services</a></h2>
<p>Synapse v1.57.0 includes a <ahref="https://github.com/matrix-org/synapse/pull/12209">change</a> to the
way transaction IDs are managed for application services. If your deployment uses a dedicated
worker for application service traffic, <strong>it must be stopped</strong> when the database is upgraded
(which normally happens when the main process is upgraded), to ensure the change is made safely
without any risk of reusing transaction IDs.</p>
<p>Deployments which do not use separate worker processes can be upgraded as normal. Similarly,
deployments where no application services are in use can be upgraded as normal.</p>
<details>
<summary><b>Recovering from an incorrect upgrade</b></summary>
<p>If the database schema is upgraded <em>without</em> stopping the worker responsible
for AS traffic, then the following error may be given when attempting to start
<p>This error may also be seen if Synapse is <em>downgraded</em> to an earlier version,
and then upgraded again to v1.57.0 or later.</p>
<p>In either case:</p>
<ol>
<li>Ensure that the worker responsible for AS traffic is stopped.</li>
<li>Run the SQL command given in the error message via <code>psql</code>.</li>
</ol>
<p>Synapse should then start correctly.</p>
</details>
<h1id="upgrading-to-v1560"><aclass="header"href="#upgrading-to-v1560">Upgrading to v1.56.0</a></h1>
<h2id="open-registration-without-verification-is-now-disabled-by-default"><aclass="header"href="#open-registration-without-verification-is-now-disabled-by-default">Open registration without verification is now disabled by default</a></h2>
<p>Synapse will refuse to start if registration is enabled without email, captcha, or token-based verification unless the new config
flag <code>enable_registration_without_verification</code> is set to "true".</p>
<h2id="groupscommunities-feature-has-been-deprecated"><aclass="header"href="#groupscommunities-feature-has-been-deprecated">Groups/communities feature has been deprecated</a></h2>
<p>The non-standard groups/communities feature in Synapse has been deprecated and will
be disabled by default in Synapse v1.58.0.</p>
<p>You can test disabling it by adding the following to your homeserver configuration:</p>
<h2id="change-in-behaviour-for-postgresql-databases-with-unsafe-locale"><aclass="header"href="#change-in-behaviour-for-postgresql-databases-with-unsafe-locale">Change in behaviour for PostgreSQL databases with unsafe locale</a></h2>
<p>Synapse now refuses to start when using PostgreSQL with non-<code>C</code> values for <code>COLLATE</code> and
<code>CTYPE</code> unless the config flag <code>allow_unsafe_locale</code>, found in the database section of
the configuration file, is set to <code>true</code>. See the <ahref="https://matrix-org.github.io/synapse/latest/postgres.html#fixing-incorrect-collate-or-ctype">PostgreSQL documentation</a>
for more information and instructions on how to fix a database with incorrect values.</p>
<h1id="upgrading-to-v1550"><aclass="header"href="#upgrading-to-v1550">Upgrading to v1.55.0</a></h1>
<h2id="synctl-script-has-been-moved"><aclass="header"href="#synctl-script-has-been-moved"><code>synctl</code> script has been moved</a></h2>
<p>The <code>synctl</code> script
<ahref="https://github.com/matrix-org/synapse/pull/12140">has been made</a> an
<li>When installing from a wheel, sdist, or PyPI, a <code>synctl</code> executable is added
to your Python installation's <code>bin</code>. This should be on your <code>PATH</code>
automatically, though you might need to activate a virtual environment
depending on how you installed Synapse.</li>
</ul>
<h2id="compatibility-dropped-for-mjolnir-131-and-earlier"><aclass="header"href="#compatibility-dropped-for-mjolnir-131-and-earlier">Compatibility dropped for Mjolnir 1.3.1 and earlier</a></h2>
<p>Synapse v1.55.0 drops support for Mjolnir 1.3.1 and earlier.
If you use the Mjolnir module to moderate your homeserver,
please upgrade Mjolnir to version 1.3.2 or later before upgrading Synapse.</p>
<h1id="upgrading-to-v1540"><aclass="header"href="#upgrading-to-v1540">Upgrading to v1.54.0</a></h1>
<h1id="upgrading-to-v1530"><aclass="header"href="#upgrading-to-v1530">Upgrading to v1.53.0</a></h1>
<h2id="dropping-support-for-webclient-listeners-and-non-https-web_client_location"><aclass="header"href="#dropping-support-for-webclient-listeners-and-non-https-web_client_location">Dropping support for <code>webclient</code> listeners and non-HTTP(S) <code>web_client_location</code></a></h2>
<p>Per the deprecation notice in Synapse v1.51.0, listeners of type <code>webclient</code>
are no longer supported and configuring them is a now a configuration error.</p>
<p>Configuring a non-HTTP(S) <code>web_client_location</code> configuration is is now a
configuration error. Since the <code>webclient</code> listener is no longer supported, this
setting only applies to the root path <code>/</code> of Synapse's web server and no longer
the <code>/_matrix/client/</code> path.</p>
<h2id="stablisation-of-msc3231"><aclass="header"href="#stablisation-of-msc3231">Stablisation of MSC3231</a></h2>
<p>Please update any relevant reverse proxy or firewall configurations appropriately.</p>
<h2id="time-based-cache-expiry-is-now-enabled-by-default"><aclass="header"href="#time-based-cache-expiry-is-now-enabled-by-default">Time-based cache expiry is now enabled by default</a></h2>
<p>Formerly, entries in the cache were not evicted regardless of whether they were accessed after storing.
This behavior has now changed. By default entries in the cache are now evicted after 30m of not being accessed.
To change the default behavior, go to the <code>caches</code> section of the config and change the <code>expire_caches</code> and
<code>cache_entry_ttl</code> flags as necessary. Please note that these flags replace the <code>expiry_time</code> flag in the config.
The <code>expiry_time</code> flag will still continue to work, but it has been deprecated and will be removed in the future.</p>
<h2id="deprecation-of-capability-orgmatrixmsc3283"><aclass="header"href="#deprecation-of-capability-orgmatrixmsc3283">Deprecation of <code>capability</code><code>org.matrix.msc3283.*</code></a></h2>
<p>The <code>capabilities</code> of MSC3283 from the REST API <code>/_matrix/client/r0/capabilities</code>
<p>are deprecated and scheduled to be removed in Synapse v1.54.0.</p>
<p>The new <code>capabilities</code></p>
<ul>
<li><code>m.set_displayname</code>,</li>
<li><code>m.set_avatar_url</code> and</li>
<li><code>m.3pid_changes</code></li>
</ul>
<p>are now active by default.</p>
<h2id="removal-of-user_may_create_room_with_invites"><aclass="header"href="#removal-of-user_may_create_room_with_invites">Removal of <code>user_may_create_room_with_invites</code></a></h2>
<p>As announced with the release of <ahref="upgrade.html#deprecation-of-the-user_may_create_room_with_invites-module-callback">Synapse 1.47.0</a>,
the deprecated <code>user_may_create_room_with_invites</code> module callback has been removed.</p>
<p>Modules relying on it can instead implement <ahref="https://matrix-org.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite"><code>user_may_invite</code></a>
and use the <ahref="https://github.com/matrix-org/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876"><code>get_room_state</code></a>
module API to infer whether the invite is happening while creating a room (see <ahref="https://github.com/matrix-org/synapse-domain-rule-checker/blob/e7d092dd9f2a7f844928771dbfd9fd24c2332e48/synapse_domain_rule_checker/__init__.py#L56-L89">this function</a>
as an example). Alternately, modules can also implement <ahref="https://matrix-org.github.io/synapse/latest/modules/third_party_rules_callbacks.html#on_create_room"><code>on_create_room</code></a>.</p>
<h1id="upgrading-to-v1520"><aclass="header"href="#upgrading-to-v1520">Upgrading to v1.52.0</a></h1>
<p>Note that <ahref="https://github.com/twisted/twisted/releases/tag/twisted-22.1.0">Twisted 22.1.0</a>
has recently been released, which fixes a <ahref="https://github.com/twisted/twisted/security/advisories/GHSA-92x2-jw7w-xvvx">security issue</a>
within the Twisted library. We do not believe Synapse is affected by this vulnerability,
though we advise server administrators who installed Synapse via pip to upgrade Twisted
with <code>pip install --upgrade Twisted treq</code> as a matter of good practice. The Docker image
<code>matrixdotorg/synapse</code> and the Debian packages from <code>packages.matrix.org</code> are using the
updated library.</p>
<h1id="upgrading-to-v1510"><aclass="header"href="#upgrading-to-v1510">Upgrading to v1.51.0</a></h1>
<h2id="deprecation-of-webclient-listeners-and-non-https-web_client_location"><aclass="header"href="#deprecation-of-webclient-listeners-and-non-https-web_client_location">Deprecation of <code>webclient</code> listeners and non-HTTP(S) <code>web_client_location</code></a></h2>
<p>Listeners of type <code>webclient</code> are deprecated and scheduled to be removed in
Synapse v1.53.0.</p>
<p>Similarly, a non-HTTP(S) <code>web_client_location</code> configuration is deprecated and
will become a configuration error in Synapse v1.53.0.</p>
<h1id="upgrading-to-v1500"><aclass="header"href="#upgrading-to-v1500">Upgrading to v1.50.0</a></h1>
<h2id="dropping-support-for-old-python-and-postgres-versions"><aclass="header"href="#dropping-support-for-old-python-and-postgres-versions">Dropping support for old Python and Postgres versions</a></h2>
<p>In line with our <ahref="deprecation_policy.html">deprecation policy</a>,
we've dropped support for Python 3.6 and PostgreSQL 9.6, as they are no
longer supported upstream.</p>
<p>This release of Synapse requires Python 3.7+ and PostgreSQL 10+.</p>
<h1id="upgrading-to-v1470"><aclass="header"href="#upgrading-to-v1470">Upgrading to v1.47.0</a></h1>
<h2id="removal-of-old-room-admin-api"><aclass="header"href="#removal-of-old-room-admin-api">Removal of old Room Admin API</a></h2>
<p>The following admin APIs were deprecated in <ahref="https://github.com/matrix-org/synapse/blob/v1.34.0/CHANGES.md#deprecations-and-removals">Synapse 1.34</a>
(released on 2021-05-17) and have now been removed:</p>
<h2id="deprecation-of-the-user_may_create_room_with_invites-module-callback"><aclass="header"href="#deprecation-of-the-user_may_create_room_with_invites-module-callback">Deprecation of the <code>user_may_create_room_with_invites</code> module callback</a></h2>
<p>The <code>user_may_create_room_with_invites</code> is deprecated and will be removed in a future
version of Synapse. Modules implementing this callback can instead implement
and use the <ahref="https://github.com/matrix-org/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876"><code>get_room_state</code></a>
module API method to infer whether the invite is happening in the context of creating a
room.</p>
<p>We plan to remove this callback in January 2022.</p>
<h1id="upgrading-to-v1450"><aclass="header"href="#upgrading-to-v1450">Upgrading to v1.45.0</a></h1>
<h2id="changes-required-to-media-storage-provider-modules-when-reading-from-the-synapse-configuration-object"><aclass="header"href="#changes-required-to-media-storage-provider-modules-when-reading-from-the-synapse-configuration-object">Changes required to media storage provider modules when reading from the Synapse configuration object</a></h2>
<p>Media storage provider modules that read from the Synapse configuration object (i.e. that
read the value of <code>hs.config.[...]</code>) now need to specify the configuration section they're
reading from. This means that if a module reads the value of e.g. <code>hs.config.media_store_path</code>,
it needs to replace it with <code>hs.config.media.media_store_path</code>.</p>
<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
<p>The template is now provided an <code>error</code> variable if the authentication
process failed. See the default templates linked above for an example.</p>
<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
once, but not still, linked to their account.</p>
<h1id="upgrading-to-v1410"><aclass="header"href="#upgrading-to-v1410">Upgrading to v1.41.0</a></h1>
<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
details.</p>
<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>
has been updated to reflect that calls to <code>/_synapse/admin/v1/users/{userId}/media</code>
must now be handled by media repository workers. This is due to the new <code>DELETE</code> method
of this endpoint modifying the media store.</p>
<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/porting_legacy_module.html">this documentation</a>
to update their modules. Synapse administrators can refer to <ahref="modules/index.html">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>
<p>On this server, it would be wise to ensure that at least 1152MB are free.</p>
<p>The additional disk space will be freed once the migration completes.</p>
<p>SQLite databases are unaffected by this change.</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.
Authors of spam checker modules can refer to [this
documentation](modules/porting_legacy_module.md
to update their modules. Synapse administrators can refer to <ahref="modules/index.html">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 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>
<h1id="upgrading-to-v1340"><aclass="header"href="#upgrading-to-v1340">Upgrading to v1.34.0</a></h1>
<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>
<p>In line with our <ahref="deprecation_policy.html">deprecation policy</a>,
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
version.</p>
<p>The <ahref="admin_api/user_admin_api.html#list-accounts">v2 list accounts API</a>
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
<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 <ahref="reverse_proxy.html">reverse proxy documentation</a>, where the
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 <code>X-Forwarded-Proto</code> 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>
<p>See the <ahref="openid.html">OpenID docs</a> 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>
<h2id="changes-to-html-templates"><aclass="header"href="#changes-to-html-templates">Changes to HTML templates</a></h2>
<p>The HTML templates for SSO and email notifications now have <ahref="https://jinja.palletsprojects.com/en/2.11.x/api/#autoescaping">Jinja2's
autoescape</a>
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
<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
<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>
<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--py3-suffix-will-be-removed-in-future-versions"><aclass="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>
<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 <code>psql</code> or
<code>sqlite3</code> 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 <code>psql</code> or
<code>sqlite3</code> 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.
Synapse admins are reminded that <ahref="postgres.html">SQLite is not recommended for use
outside a test environment</a>.</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>
<pre><codeclass="language-sql">DROP INDEX tmp_upgrade_1_12_0_index;
</code></pre>
</li>
</ol>
<h1id="upgrading-to-v1100"><aclass="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 <ahref="postgres.html">Postgres</a> for details.</p>
<h1id="upgrading-to-v180"><aclass="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>
<h1id="upgrading-to-v170"><aclass="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
<p>Following upgrade, to continue verifying email (e.g. as part of the
registration process), admins can either:-</p>
<ul>
<li>Configure Synapse to use an email server.</li>
<li>Run or choose an identity server which allows delegated email
verification and delegate to it.</li>
</ul>
<h4id="configure-smtp-in-synapse"><aclass="header"href="#configure-smtp-in-synapse">Configure SMTP in Synapse</a></h4>
<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, smtp_port</code> and <code>notif_from</code> fields filled out.</p>
<p>You may also need to set <code>smtp_user</code>, <code>smtp_pass</code>, and
<code>require_transport_security</code>.</p>
<p>See the <ahref="usage/configuration/homeserver_sample_config.html">sample configuration file</a>
for more details on these settings.</p>
<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
<p><strong>HTTP <code>308 Permanent Redirect</code> redirects are not followed</strong>: Due to missing features
in the HTTP library used by Synapse, 308 redirects are currently not followed by
federating servers, which can cause <code>M_UNKNOWN</code> or <code>401 Unauthorized</code> errors. This
may affect users who are redirecting apex-to-www (e.g. <code>example.com</code> -><code>www.example.com</code>),
and especially users of the Kubernetes <em>Nginx Ingress</em> module, which uses 308 redirect
codes by default. For those Kubernetes users, <ahref="https://stackoverflow.com/a/52617528/5096871">this Stackoverflow post</a>
might be helpful. For other users, switching to a <code>301 Moved Permanently</code> code may be
an option. 308 redirect codes will be supported properly in a future
release of Synapse.</p>
<h2id="running-a-demo-federation-of-synapses"><aclass="header"href="#running-a-demo-federation-of-synapses">Running a demo federation of Synapses</a></h2>
<p>If you want to get up and running quickly with a trio of homeservers in a
private federation, there is a script in the <code>demo</code> directory. This is mainly
<p>This option allows server runners to add arbitrary key-value pairs to the <ahref="https://spec.matrix.org/latest/client-server-api/#well-known-uri">client-facing <code>.well-known</code> response</a>.
Note that the <code>public_baseurl</code> config option must be provided for Synapse to serve a response to <code>/.well-known/matrix/client</code> at all.</p>
<p>If this option is provided, it parses the given yaml to json and
serves it on <code>/.well-known/matrix/client</code> endpoint
<p><code>tls</code>: set to true to enable TLS for this listener. Will use the TLS key/cert specified in tls_private_key_path / tls_certificate_path.</p>
</li>
<li>
<p><code>x_forwarded</code>: Only valid for an 'http' listener. Set to true to use the X-Forwarded-For header as the client IP. Useful when Synapse is
behind a reverse-proxy.</p>
</li>
<li>
<p><code>resources</code>: Only valid for an 'http' listener. A list of resources to host
on this port. Sub-options for each resource are:</p>
<ul>
<li>
<p><code>names</code>: a list of names of HTTP resources. See below for a list of valid resource names.</p>
</li>
<li>
<p><code>compress</code>: set to true to enable gzip compression on HTTP bodies for this resource. This is currently only supported with the
<code>client</code>, <code>consent</code>, <code>metrics</code> and <code>federation</code> resources.</p>
</li>
</ul>
</li>
<li>
<p><code>additional_resources</code>: Only valid for an 'http' listener. A map of
additional endpoints which should be loaded via dynamic modules.</p>
</li>
</ul>
<p>Valid resource names are:</p>
<ul>
<li>
<p><code>client</code>: the client-server API (/_matrix/client), and the synapse admin API (/_synapse/admin). Also implies <code>media</code> and <code>static</code>.</p>
</li>
<li>
<p><code>consent</code>: user consent forms (/_matrix/consent). See <ahref="usage/configuration/../../consent_tracking.html">here</a> for more.</p>
</li>
<li>
<p><code>federation</code>: the server-server API (/_matrix/federation). Also implies <code>media</code>, <code>keys</code>, <code>openid</code></p>
</li>
<li>
<p><code>keys</code>: the key discovery API (/_matrix/key).</p>
</li>
<li>
<p><code>media</code>: the media API (/_matrix/media).</p>
</li>
<li>
<p><code>metrics</code>: the metrics interface. See <ahref="usage/configuration/../../metrics-howto.html">here</a>.</p>
</li>
<li>
<p><code>openid</code>: OpenID authentication. See <ahref="usage/configuration/../../openid.html">here</a>.</p>
</li>
<li>
<p><code>replication</code>: the HTTP replication API (/_synapse/replication). See <ahref="usage/configuration/../../workers.html">here</a>.</p>
</li>
<li>
<p><code>static</code>: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.)</p>
</li>
</ul>
<p>Example configuration #1:</p>
<pre><codeclass="language-yaml">listeners:
# TLS-enabled listener: for when matrix traffic is sent directly to synapse.
#
# (Note that you will also need to give Synapse a TLS key and certificate: see the TLS section
# below.)
#
- port: 8448
type: http
tls: true
resources:
- names: [client, federation]
</code></pre>
<p>Example configuration #2:</p>
<pre><codeclass="language-yaml">listeners:
# Unsecure HTTP listener: for when matrix traffic passes through a reverse proxy
<h3id="hs_disabled-and-hs_disabled_message"><aclass="header"href="#hs_disabled-and-hs_disabled_message"><code>hs_disabled</code> and <code>hs_disabled_message</code></a></h3>
<p>Blocks users from connecting to the homeserver and provides a human-readable reason
why the connection was blocked. Defaults to false.</p>
<p>Example configuration:</p>
<pre><codeclass="language-yaml">hs_disabled: true
hs_disabled_message: 'Reason for why the HS is blocked'
<h3id="templates-and-custom_template_directory"><aclass="header"href="#templates-and-custom_template_directory"><code>templates</code> and <code>custom_template_directory</code></a></h3>
<p>These options define templates to use when generating email or HTML page contents.
The <code>custom_template_directory</code> determines which directory Synapse will try to
find template files in to use to generate email or HTML page contents.
If not set, or a file is not found within the template directory, a default
template from within the Synapse package will be used.</p>
<p>See <ahref="usage/configuration/../../templates.html">here</a> for more
<p>Some caches have '*' and other characters that are not
alphanumeric or underscores. These caches can be named with or
without the special characters stripped. For example, to specify
the cache factor for <code>*stateGroupCache*</code> via an environment
variable would be <code>SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0</code>.</p>
</li>
<li>
<p><code>expire_caches</code>: Controls whether cache entries are evicted after a specified time
period. Defaults to true. Set to false to disable this feature. Note that never expiring
caches may result in excessive memory usage.</p>
</li>
<li>
<p><code>cache_entry_ttl</code>: If <code>expire_caches</code> is enabled, this flag controls how long an entry can
be in a cache without having been accessed before being evicted.
Defaults to 30m.</p>
</li>
<li>
<p><code>sync_response_cache_duration</code>: Controls how long the results of a /sync request are
cached for after a successful response is returned. A higher duration can help clients
with intermittent connections, at the cost of higher memory usage.
A value of zero means that sync responses are not cached.
Defaults to 2m.</p>
<p><em>Changed in Synapse 1.62.0</em>: The default was changed from 0 to 2m.</p>
</li>
<li>
<p><code>cache_autotuning</code> and its sub-options <code>max_cache_memory_usage</code>, <code>target_cache_memory_usage</code>, and
<code>min_cache_ttl</code> work in conjunction with each other to maintain a balance between cache memory
usage and cache entry availability. You must be using <ahref="https://github.com/matrix-org/synapse#help-synapse-is-slow-and-eats-all-my-ramcpu">jemalloc</a>
to utilize this option, and all three of the options must be specified for this feature to work. This option
defaults to off, enable it by providing values for the sub-options listed below. Please note that the feature will not work
and may cause unstable behavior (such as excessive emptying of caches or exceptions) if all of the values are not provided.
Please see the <ahref="usage/configuration/config_documentation.html#config-conventions">Config Conventions</a> for information on how to specify memory size and cache expiry
durations.</p>
<ul>
<li><code>max_cache_memory_usage</code> sets a ceiling on how much memory the cache can use before caches begin to be continuously evicted.
They will continue to be evicted until the memory usage drops below the <code>target_memory_usage</code>, set in
the setting below, or until the <code>min_cache_ttl</code> is hit. There is no default value for this option.</li>
<li><code>target_memory_usage</code> sets a rough target for the desired memory usage of the caches. There is no default value
for this option.</li>
<li><code>min_cache_ttl</code> sets a limit under which newer cache entries are not evicted and is only applied when
caches are actively being evicted/<code>max_cache_memory_usage</code> has been exceeded. This is to protect hot caches
from being emptied while Synapse is evicting due to memory. There is no default value for this option.</li>
<p>The <code>database</code> setting defines the database that synapse uses to store all of
its data.</p>
<p>Associated sub-options:</p>
<ul>
<li>
<p><code>name</code>: this option specifies the database engine to use: either <code>sqlite3</code> (for SQLite)
or <code>psycopg2</code> (for PostgreSQL). If no name is specified Synapse will default to SQLite.</p>
</li>
<li>
<p><code>txn_limit</code> gives the maximum number of transactions to run per connection
before reconnecting. Defaults to 0, which means no limit.</p>
</li>
<li>
<p><code>allow_unsafe_locale</code> is an option specific to Postgres. Under the default behavior, Synapse will refuse to
start if the postgres db is set to a non-C locale. You can override this behavior (which is <em>not</em> recommended)
by setting <code>allow_unsafe_locale</code> to true. Note that doing so may corrupt your database. You can find more information
<ahref="usage/configuration/../../postgres.html#fixing-incorrect-collate-or-ctype">here</a> and <ahref="https://wiki.postgresql.org/wiki/Locale_data_changes">here</a>.</p>
</li>
<li>
<p><code>args</code> gives options which are passed through to the database engine,
except for options starting with <code>cp_</code>, which are used to configure the Twisted
connection pool. For a reference to valid arguments, see:</p>
<p>This option specifies a yaml python logging config file as described <ahref="https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema">here</a>.</p>
<p>This option sets ratelimiting how often invites can be sent in a room or to a
specific user. <code>per_room</code> defaults to <code>per_second: 0.3</code>, <code>burst_count: 10</code> and
<code>per_user</code> defaults to <code>per_second: 0.003</code>, <code>burst_count: 5</code>.</p>
<p>Client requests that invite user(s) when <ahref="https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom">creating a
room</a>
will count against the <code>rc_invites.per_room</code> limit, whereas
client requests to <ahref="https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite">invite a single user to a
room</a>
will count against both the <code>rc_invites.per_user</code> and <code>rc_invites.per_room</code> limits.</p>
<p>Federation requests to invite a user will count against the <code>rc_invites.per_user</code>
limit only, as Synapse presumes ratelimiting by room will be done by the sending server.</p>
<p>The <code>rc_invites.per_user</code> limit applies to the <em>receiver</em> of the invite, rather than the
sender, meaning that a <code>rc_invite.per_user.burst_count</code> of 5 mandates that a single user
cannot <em>receive</em> more than a burst of 5 invites at a time.</p>
<p>In contrast, the <code>rc_invites.per_issuer</code> limit applies to the <em>issuer</em> of the invite, meaning that a <code>rc_invite.per_issuer.burst_count</code> of 5 mandates that single user cannot <em>send</em> more than a burst of 5 invites at a time.</p>
<p><em>Changed in version 1.63:</em> added the <code>per_issuer</code> limit.</p>
<h3id="turn_username-and-turn_password"><aclass="header"href="#turn_username-and-turn_password"><code>turn_username</code> and <code>turn_password</code></a></h3>
<p>The Username and password if the TURN server needs them and does not use a token.</p>
<p>Registration can be rate-limited using the parameters in the <ahref="usage/configuration/config_documentation.html#ratelimiting">Ratelimiting</a> section of this manual.</p>
<p>For detailed instructions on user consent configuration, see <ahref="usage/configuration/../../consent_tracking.html">here</a>.</p>
<p>Parts of this section are required if enabling the <code>consent</code> resource under
<ahref="usage/configuration/config_documentation.html#listeners"><code>listeners</code></a>, in particular <code>template_dir</code> and <code>version</code>.</p>
<ul>
<li>
<p><code>template_dir</code>: gives the location of the templates for the HTML forms.
This directory should contain one subdirectory per language (eg, <code>en</code>, <code>fr</code>),
and each language directory should contain the policy document (named as
<version>.html) and a success page (success.html).</p>
</li>
<li>
<p><code>version</code>: specifies the 'current' version of the policy document. It defines
the version to be served by the consent resource if there is no 'v'
parameter.</p>
</li>
<li>
<p><code>server_notice_content</code>: if enabled, will send a user a "Server Notice"
asking them to consent to the privacy policy. The <ahref="usage/configuration/config_documentation.html#server_notices"><code>server_notices</code> section</a>
must also be configured for this to work. Notices will <em>not</em> be sent to
guest users unless <code>send_server_notice_to_guests</code> is set to true.</p>
</li>
<li>
<p><code>block_events_error</code>, if set, will block any attempts to send events
until the user consents to the privacy policy. The value of the setting is
used as the text of the error.</p>
</li>
<li>
<p><code>require_at_registration</code>, if enabled, will add a step to the registration
process, similar to how captcha works. Users will be required to accept the
policy before their account is created.</p>
</li>
<li>
<p><code>policy_name</code> is the display name of the policy users will see when registering
for an account. Has no effect unless <code>require_at_registration</code> is enabled.
Defaults to "Privacy Policy".</p>
</li>
</ul>
<p>Example configuration:</p>
<pre><codeclass="language-yaml">user_consent:
template_dir: res/templates/privacy
version: 1.0
server_notice_content:
msgtype: m.text
body: >-
To continue using this homeserver you must review and agree to the
terms and conditions at %(consent_uri)s
send_server_notice_to_guests: true
block_events_error: >-
To continue using this homeserver you must review and agree to the
<p>Below are the templates Synapse will look for when generating the content of an email:</p>
<ul>
<li><code>notif_mail.html</code> and <code>notif_mail.txt</code>: The contents of email notifications of missed
events.
When rendering, this template is given the following variables:
<ul>
<li><code>user_display_name</code>: the display name for the user receiving the notification</li>
<li><code>unsubscribe_link</code>: the link users can click to unsubscribe from email notifications</li>
<li><code>summary_text</code>: a summary of the notification(s). The text used can be customised
by configuring the various settings in the <code>email.subjects</code> section of the
configuration file.</li>
<li><code>rooms</code>: a list of rooms containing events to include in the email. Each element is
an object with the following attributes:
<ul>
<li><code>title</code>: a human-readable name for the room</li>
<li><code>hash</code>: a hash of the ID of the room</li>
<li><code>invite</code>: a boolean, which is <code>True</code> if the room is an invite the user hasn't
accepted yet, <code>False</code> otherwise</li>
<li><code>notifs</code>: a list of events, or an empty list if <code>invite</code> is <code>True</code>. Each element
is an object with the following attributes:
<ul>
<li><code>link</code>: a <code>matrix.to</code> link to the event</li>
<li><code>ts</code>: the time in milliseconds at which the event was received</li>
<li><code>messages</code>: a list of messages containing one message before the event, the
message in the event, and one message after the event. Each element is an
object with the following attributes:
<ul>
<li><code>event_type</code>: the type of the event</li>
<li><code>is_historical</code>: a boolean, which is <code>False</code> if the message is the one
that triggered the notification, <code>True</code> otherwise</li>
<li><code>id</code>: the ID of the event</li>
<li><code>ts</code>: the time in milliseconds at which the event was sent</li>
<li><code>sender_name</code>: the display name for the event's sender</li>
<li><code>sender_avatar_url</code>: the avatar URL (as a <code>mxc://</code> URL) for the event's
sender</li>
<li><code>sender_hash</code>: a hash of the user ID of the sender</li>
<li><code>msgtype</code>: the type of the message</li>
<li><code>body_text_html</code>: html representation of the message</li>
<li><code>body_text_plain</code>: plaintext representation of the message</li>
<li><code>image_url</code>: mxc url of an image, when "msgtype" is "m.image"</li>
</ul>
</li>
</ul>
</li>
<li><code>link</code>: a <code>matrix.to</code> link to the room</li>
<li><code>avator_url</code>: url to the room's avator</li>
</ul>
</li>
<li><code>reason</code>: information on the event that triggered the email to be sent. It's an
object with the following attributes:
<ul>
<li><code>room_id</code>: the ID of the room the event was sent in</li>
<li><code>room_name</code>: a human-readable name for the room the event was sent in</li>
<li><code>now</code>: the current time in milliseconds</li>
<li><code>received_at</code>: the time in milliseconds at which the event was received</li>
<li><code>delay_before_mail_ms</code>: the amount of time in milliseconds Synapse always waits
before ever emailing about a notification (to give the user a chance to respond
to other push or notice the window)</li>
<li><code>last_sent_ts</code>: the time in milliseconds at which a notification was last sent
for an event in this room</li>
<li><code>throttle_ms</code>: the minimum amount of time in milliseconds between two
notifications can be sent for this room</li>
</ul>
</li>
</ul>
</li>
<li><code>password_reset.html</code> and <code>password_reset.txt</code>: The contents of password reset emails
sent by the homeserver.
When rendering, these templates are given a <code>link</code> variable which contains the link the
user must click in order to reset their password.</li>
<li><code>registration.html</code> and <code>registration.txt</code>: The contents of address verification emails
sent during registration.
When rendering, these templates are given a <code>link</code> variable which contains the link the
user must click in order to validate their email address.</li>
<li><code>add_threepid.html</code> and <code>add_threepid.txt</code>: The contents of address verification emails
sent when an address is added to a Matrix account.
When rendering, these templates are given a <code>link</code> variable which contains the link the
user must click in order to validate their email address.</li>
</ul>
<h2id="html-page-templates-for-registration-and-password-reset"><aclass="header"href="#html-page-templates-for-registration-and-password-reset">HTML page templates for registration and password reset</a></h2>
<p>Below are the templates Synapse will look for when generating pages related to
registration and password reset:</p>
<ul>
<li><code>password_reset_confirmation.html</code>: An HTML page that a user will see when they follow
the link in the password reset email. The user will be asked to confirm the action
before their password is reset.
When rendering, this template is given the following variables:
<ul>
<li><code>sid</code>: the session ID for the password reset</li>
<li><code>token</code>: the token for the password reset</li>
<li><code>client_secret</code>: the client secret for the password reset</li>
</ul>
</li>
<li><code>password_reset_success.html</code> and <code>password_reset_failure.html</code>: HTML pages for success
and failure that a user will see when they confirm the password reset flow using the
page above.
When rendering, <code>password_reset_success.html</code> is given no variable, and
<code>password_reset_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
for the password reset failure. </li>
<li><code>registration_success.html</code> and <code>registration_failure.html</code>: HTML pages for success and
failure that a user will see when they follow the link in an address verification email
sent during registration.
When rendering, <code>registration_success.html</code> is given no variable, and
<code>registration_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
for the registration failure.</li>
<li><code>add_threepid_success.html</code> and <code>add_threepid_failure.html</code>: HTML pages for success and
failure that a user will see when they follow the link in an address verification email
sent when an address is added to a Matrix account.
When rendering, <code>add_threepid_success.html</code> is given no variable, and
<code>add_threepid_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
for the registration failure.</li>
</ul>
<h2id="html-page-templates-for-single-sign-on-sso"><aclass="header"href="#html-page-templates-for-single-sign-on-sso">HTML page templates for Single Sign-On (SSO)</a></h2>
<p>Below are the templates Synapse will look for when generating pages related to SSO:</p>
<ul>
<li><code>sso_login_idp_picker.html</code>: HTML page to prompt the user to choose an
Identity Provider during login.
This is only used if multiple SSO Identity Providers are configured.
When rendering, this template is given the following variables:
<ul>
<li><code>redirect_url</code>: the URL that the user will be redirected to after
login.</li>
<li><code>server_name</code>: the homeserver's name.</li>
<li><code>providers</code>: a list of available Identity Providers. Each element is
an object with the following attributes:
<ul>
<li><code>idp_id</code>: unique identifier for the IdP</li>
<li><code>idp_name</code>: user-facing name for the IdP</li>
<li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
for the IdP</li>
<li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
for the brand of the IdP
The rendered HTML page should contain a form which submits its results
back as a GET request, with the following query parameters:</li>
</ul>
</li>
<li><code>redirectUrl</code>: the client redirect URI (ie, the <code>redirect_url</code> passed
to the template)</li>
<li><code>idp</code>: the 'idp_id' of the chosen IDP.</li>
</ul>
</li>
<li><code>sso_auth_account_details.html</code>: HTML page to prompt new users to enter a
userid and confirm other details. This is only shown if the
SSO implementation (with any <code>user_mapping_provider</code>) does not return
a localpart.
When rendering, this template is given the following variables:
<ul>
<li><code>server_name</code>: the homeserver's name.</li>
<li><code>idp</code>: details of the SSO Identity Provider that the user logged in
with: an object with the following attributes:
<ul>
<li><code>idp_id</code>: unique identifier for the IdP</li>
<li><code>idp_name</code>: user-facing name for the IdP</li>
<li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
for the IdP</li>
<li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
for the brand of the IdP</li>
</ul>
</li>
<li><code>user_attributes</code>: an object containing details about the user that
we received from the IdP. May have the following attributes:
<ul>
<li><code>display_name</code>: the user's display name</li>
<li><code>emails</code>: a list of email addresses</li>
<li><code>localpart</code>: the local part of the Matrix user ID to register,
if <code>localpart_template</code> is set in the mapping provider configuration (empty
string if not)
The template should render a form which submits the following fields:</li>
</ul>
</li>
<li><code>username</code>: the localpart of the user's chosen user id</li>
</ul>
</li>
<li><code>sso_new_user_consent.html</code>: HTML page allowing the user to consent to the
server's terms and conditions. This is only shown for new users, and only if
<code>user_consent.require_at_registration</code> is set.
When rendering, this template is given the following variables:
<ul>
<li><code>server_name</code>: the homeserver's name.</li>
<li><code>user_id</code>: the user's matrix proposed ID.</li>
<li><code>user_profile.display_name</code>: the user's proposed display name, if any.</li>
<li>consent_version: the version of the terms that the user will be
shown</li>
<li><code>terms_url</code>: a link to the page showing the terms.
The template should render a form which submits the following fields:</li>
<li><code>accepted_version</code>: the version of the terms accepted by the user
(ie, 'consent_version' from the input variables).</li>
</ul>
</li>
<li><code>sso_redirect_confirm.html</code>: HTML page for a confirmation step before redirecting back
to the client with the login token.
When rendering, this template is given the following variables:
<ul>
<li><code>redirect_url</code>: the URL the user is about to be redirected to.</li>
<li><code>display_url</code>: the same as <code>redirect_url</code>, but with the query
parameters stripped. The intention is to have a
human-readable URL to show to users, not to use it as
the final address to redirect to.</li>
<li><code>server_name</code>: the homeserver's name.</li>
<li><code>new_user</code>: a boolean indicating whether this is the user's first time
logging in.</li>
<li><code>user_id</code>: the user's matrix ID.</li>
<li><code>user_profile.avatar_url</code>: an MXC URI for the user's avatar, if any.
<code>None</code> if the user has not set an avatar.</li>
<li><code>user_profile.display_name</code>: the user's display name. <code>None</code> if the user
has not set a display name.</li>
</ul>
</li>
<li><code>sso_auth_confirm.html</code>: HTML page which notifies the user that they are authenticating
to confirm an operation on their account during the user interactive authentication
process.
When rendering, this template is given the following variables:
<ul>
<li><code>redirect_url</code>: the URL the user is about to be redirected to.</li>
<li><code>description</code>: the operation which the user is being asked to confirm</li>
<li><code>idp</code>: details of the Identity Provider that we will use to confirm
the user's identity: an object with the following attributes:
<ul>
<li><code>idp_id</code>: unique identifier for the IdP</li>
<li><code>idp_name</code>: user-facing name for the IdP</li>
<li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
for the IdP</li>
<li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
for the brand of the IdP</li>
</ul>
</li>
</ul>
</li>
<li><code>sso_auth_success.html</code>: HTML page shown after a successful user interactive
authentication session.
Note that this page must include the JavaScript which notifies of a successful
authentication (see https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
This template has no additional variables.</li>
<li><code>sso_auth_bad_user.html</code>: HTML page shown after a user-interactive authentication
session which does not map correctly onto the expected user.
When rendering, this template is given the following variables:
<ul>
<li><code>server_name</code>: the homeserver's name.</li>
<li><code>user_id_to_verify</code>: the MXID of the user that we are trying to
validate.</li>
</ul>
</li>
<li><code>sso_account_deactivated.html</code>: HTML page shown during single sign-on if a deactivated
user (according to Synapse's database) attempts to login.
This template has no additional variables.</li>
<li><code>sso_error.html</code>: HTML page to display to users if something goes wrong during the
OpenID Connect authentication process.
When rendering, this template is given two variables:
<ul>
<li><code>error</code>: the technical name of the error</li>
<li><code>error_description</code>: a human-readable message for the error</li>
<p>Synapse supports single sign-on through the SAML, Open ID Connect or CAS protocols.
LDAP and other login methods are supported through first and third-party password
auth provider modules.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="configuring-synapse-to-authenticate-against-an-openid-connect-provider"><aclass="header"href="#configuring-synapse-to-authenticate-against-an-openid-connect-provider">Configuring Synapse to authenticate against an OpenID Connect provider</a></h1>
<p>Synapse can be configured to use an OpenID Connect Provider (OP) for
authentication, instead of its own local password database.</p>
<p>Any OP should work with Synapse, as long as it supports the authorization code
flow. There are a few options for that:</p>
<ul>
<li>
<p>start a local OP. Synapse has been tested with <ahref="https://www.ory.sh/docs/hydra/">Hydra</a> and
<ahref="https://github.com/dexidp/dex">Dex</a>. Note that for an OP to work, it should be served under a
secure (HTTPS) origin. A certificate signed with a self-signed, locally
trusted CA should work. In that case, start Synapse with a <code>SSL_CERT_FILE</code>
environment variable set to the path of the CA.</p>
</li>
<li>
<p>set up a SaaS OP, like <ahref="https://developers.google.com/identity/protocols/oauth2/openid-connect">Google</a>, <ahref="https://auth0.com/">Auth0</a> or
<ahref="https://www.okta.com/">Okta</a>. Synapse has been tested with Auth0 and Google.</p>
</li>
</ul>
<p>It may also be possible to use other OAuth2 providers which provide the
<ahref="https://tools.ietf.org/html/rfc6749#section-4.1">authorization code grant type</a>,
such as <ahref="https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps">Github</a>.</p>
<ahref="https://pypi.org/project/Authlib/"><code>authlib</code></a> library, which must be installed
as follows:</p>
<ul>
<li>
<p>The relevant libraries are included in the Docker images and Debian packages
provided by <code>matrix.org</code> so no further action is needed.</p>
</li>
<li>
<p>If you installed Synapse into a virtualenv, run <code>/path/to/env/bin/pip install matrix-synapse[oidc]</code> to install the necessary dependencies.</p>
</li>
<li>
<p>For other installation mechanisms, see the documentation provided by the
maintainer.</p>
</li>
</ul>
<p>To enable the OpenID integration, you should then add a section to the <code>oidc_providers</code>
setting in your configuration file.
See the <ahref="usage/configuration/config_documentation.html#oidc_providers">configuration manual</a> for some sample settings, as well as
the text below for example configurations for specific providers.</p>
display_name_template: "{{ user.preferred_username|capitalize }}" # TO BE FILLED: If your users have names in Authentik and you want those in Synapse, this should be replaced with user.name|capitalize.
# TO BE FILLED: If your users have names in LemonLDAP::NG and you want those in Synapse, this should be replaced with user.name|capitalize or any valid filter.
<p><ahref="https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps">GitHub</a> is a bit special as it is not an OpenID Connect compliant provider, but
just a regular OAuth2 provider.</p>
<p>The <ahref="https://developer.github.com/v3/users/#get-the-authenticated-user"><code>/user</code> API endpoint</a>
can be used to retrieve information on the authenticated user. As the Synapse
login mechanism needs an attribute to uniquely identify users, and that endpoint
does not return a <code>sub</code> property, an alternative <code>subject_claim</code> has to be set.</p>
<ol>
<li>Create a new OAuth application: <ahref="https://github.com/settings/applications/new">https://github.com/settings/applications/new</a>.</li>
<li>Set the callback URL to <code>[synapse public baseurl]/_synapse/client/oidc/callback</code>.</li>
</ol>
<p>Synapse config:</p>
<pre><codeclass="language-yaml">oidc_providers:
- idp_id: github
idp_name: Github
idp_brand: "github" # optional: styling hint for clients
discover: false
issuer: "https://github.com/"
client_id: "your-client-id" # TO BE FILLED
client_secret: "your-client-secret" # TO BE FILLED
<p><ahref="https://developers.google.com/identity/protocols/oauth2/openid-connect">Google</a> is an OpenID certified authentication and authorisation provider.</p>
<ol>
<li>Set up a project in the Google API Console (see
<p>Install <ahref="https://extensions.xwiki.org/xwiki/bin/view/Extension/OpenID%20Connect/OpenID%20Connect%20Provider/">OpenID Connect Provider</a> extension in your <ahref="https://www.xwiki.org">XWiki</a> instance.</p>
<li><code>Authorization grant type</code>: <code>Authorization code</code></li>
<li><code>Algorithm</code>: <code>HMAC with SHA-2 256</code></li>
</ul>
<olstart="2">
<li>
<p>You can <ahref="https://django-oauth-toolkit.readthedocs.io/en/latest/oidc.html#customizing-the-oidc-responses">customize the claims</a> Django gives to synapse (optional):</p>
<p>Synapse supports authenticating users via the <ahref="https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language">Security Assertion
Markup Language</a>
(SAML) protocol natively.</p>
<p>Please see the <code>saml2_config</code> and <code>sso</code> sections of the <ahref="usage/configuration/user_authentication/single_sign_on/../../../configuration/homeserver_sample_config.html">Synapse configuration
<p>Synapse supports authenticating users via the <ahref="https://en.wikipedia.org/wiki/Central_Authentication_Service">Central Authentication
Service protocol</a>
(CAS) natively.</p>
<p>Please see the <ahref="usage/configuration/user_authentication/single_sign_on/../../../configuration/config_documentation.html#cas_config">cas_config</a> and <ahref="usage/configuration/user_authentication/single_sign_on/../../../configuration/config_documentation.html#sso">sso</a>
sections of the configuration manual for more details.</p>
<p>Synapse supports refresh tokens since version 1.49 (some earlier versions had support for an earlier, experimental draft of <ahref="https://github.com/matrix-org/matrix-doc/blob/main/proposals/2918-refreshtokens.md#msc2918-refresh-tokens">MSC2918</a> which is not compatible).</p>
<h2id="background-and-motivation"><aclass="header"href="#background-and-motivation">Background and motivation</a></h2>
<p>Synapse users' sessions are identified by <strong>access tokens</strong>; access tokens are
issued to users on login. Each session gets a unique access token which identifies
it; the access token must be kept secret as it grants access to the user's account.</p>
<p>Traditionally, these access tokens were eternally valid (at least until the user
explicitly chose to log out).</p>
<p>In some cases, it may be desirable for these access tokens to expire so that the
potential damage caused by leaking an access token is reduced.
On the other hand, forcing a user to re-authenticate (log in again) often might
be too much of an inconvenience.</p>
<p><strong>Refresh tokens</strong> are a mechanism to avoid some of this inconvenience whilst
still getting most of the benefits of short access token lifetimes.
Refresh tokens are also a concept present in OAuth 2 — further reading is available
<p>The following configuration options, in the <code>registration</code> section, are related:</p>
<ul>
<li><code>session_lifetime</code>: maximum length of a session, even if it's refreshed.
In other words, the client must log in again after this time period.
In most cases, this can be unset (infinite) or set to a long time (years or months).</li>
<li><code>refreshable_access_token_lifetime</code>: lifetime of access tokens that are created
by clients supporting refresh tokens.
This should be short; a good value might be 5 minutes (<code>5m</code>).</li>
<li><code>nonrefreshable_access_token_lifetime</code>: lifetime of access tokens that are created
by clients which don't support refresh tokens.
Make this short if you want to effectively force use of refresh tokens.
Make this long if you don't want to inconvenience users of clients which don't
support refresh tokens (by forcing them to frequently re-authenticate using
login credentials).</li>
<li><code>refresh_token_lifetime</code>: lifetime of refresh tokens.
In other words, the client must refresh within this time period to maintain its session.
Unless you want to log inactive sessions out, it is often fine to use a long
value here or even leave it unset (infinite).
Beware that making it too short will inconvenience clients that do not connect
very often, including mobile clients and clients of infrequent users (by making
it more difficult for them to refresh in time, which may force them to need to
re-authenticate using login credentials).</li>
</ul>
<p><strong>Note:</strong> All four options above only apply when tokens are created (by logging in or refreshing).
Changes to these settings do not apply retroactively.</p>
<h3id="using-refresh-token-expiry-to-log-out-inactive-sessions"><aclass="header"href="#using-refresh-token-expiry-to-log-out-inactive-sessions">Using refresh token expiry to log out inactive sessions</a></h3>
<p>If you'd like to force sessions to be logged out upon inactivity, you can enable
refreshable access token expiry and refresh token expiry.</p>
<p>This works because a client must refresh at least once within a period of
<code>refresh_token_lifetime</code> in order to maintain valid credentials to access the
account.</p>
<p>(It's suggested that <code>refresh_token_lifetime</code> should be longer than
<code>refreshable_access_token_lifetime</code> and this section assumes that to be the case
for simplicity.)</p>
<p>Note: this will only affect sessions using refresh tokens. You may wish to
set a short <code>nonrefreshable_access_token_lifetime</code> to prevent this being bypassed
by clients that do not support refresh tokens.</p>
<h4id="choosing-values-that-guarantee-permitting-some-inactivity"><aclass="header"href="#choosing-values-that-guarantee-permitting-some-inactivity">Choosing values that guarantee permitting some inactivity</a></h4>
<p>It may be desirable to permit some short periods of inactivity, for example to
accommodate brief outages in client connectivity.</p>
<p>The following model aims to provide guidance for choosing <code>refresh_token_lifetime</code>
and <code>refreshable_access_token_lifetime</code> to satisfy requirements of the form:</p>
<ol>
<li>inactivity longer than <code>L</code><strong>MUST</strong> cause the session to be logged out; and</li>
<li>inactivity shorter than <code>S</code><strong>MUST NOT</strong> cause the session to be logged out.</li>
</ol>
<p>This model makes the weakest assumption that all active clients will refresh as
needed to maintain an active access token, but no sooner.
<em>In reality, clients may refresh more often than this model assumes, but the
above requirements will still hold.</em></p>
<p>To satisfy the above model,</p>
<ul>
<li><code>refresh_token_lifetime</code> should be set to <code>L</code>; and</li>
<li><code>refreshable_access_token_lifetime</code> should be set to <code>L - S</code>.</li>
<p>The format of the AS configuration file is as follows:</p>
<pre><codeclass="language-yaml">url: <base url of AS>
as_token: <token AS will add to requests to HS>
hs_token: <token HS will add to requests to AS>
sender_localpart: <localpart of AS user>
namespaces:
users: # List of users we're interested in
- exclusive: <bool>
regex: <regex>
group_id: <group>
- ...
aliases: [] # List of aliases we're interested in
rooms: [] # List of room ids we're interested in
</code></pre>
<p><code>exclusive</code>: If enabled, only this application service is allowed to register users in its namespace(s).
<code>group_id</code>: All users of this application service are dynamically joined to this group. This is useful for e.g user organisation or flairs.</p>
<p>See the <ahref="https://matrix.org/docs/spec/application_service/unstable.html">spec</a> for further details on how application services work.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions"><aclass="header"href="#support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions">Support in Synapse for tracking agreement to server terms and conditions</a></h1>
<p>Synapse 0.30 introduces support for tracking whether users have agreed to the
terms and conditions set by the administrator of a server - and blocking access
to the server until they have.</p>
<p>There are several parts to this functionality; each requires some specific
configuration in <code>homeserver.yaml</code> to be enabled.</p>
<p>Note that various parts of the configuation and this document refer to the
"privacy policy": agreement with a privacy policy is one particular use of this
feature, but of course adminstrators can specify other terms and conditions
unrelated to "privacy" per se.</p>
<h2id="collecting-policy-agreement-from-a-user"><aclass="header"href="#collecting-policy-agreement-from-a-user">Collecting policy agreement from a user</a></h2>
<p>Synapse can be configured to serve the user a simple policy form with an
"accept" button. Clicking "Accept" records the user's acceptance in the
database and shows a success page.</p>
<p>To enable this, first create templates for the policy and success pages.
These should be stored on the local filesystem.</p>
<p>These templates use the <ahref="http://jinja.pocoo.org">Jinja2</a> templating language,
and <ahref="https://github.com/matrix-org/synapse/tree/develop/docs/privacy_policy_templates/">docs/privacy_policy_templates</a>
gives examples of the sort of thing that can be done.</p>
<p>Note that the templates must be stored under a name giving the language of the
template - currently this must always be <code>en</code> (for "English");
internationalisation support is intended for the future.</p>
<p>The template for the policy itself should be versioned and named according to
the version: for example <code>1.0.html</code>. The version of the policy which the user
has agreed to is stored in the database.</p>
<p>Once the templates are in place, make the following changes to <code>homeserver.yaml</code>:</p>
<ol>
<li>
<p>Add a <code>user_consent</code> section, which should look like:</p>
<pre><codeclass="language-yaml">user_consent:
template_dir: privacy_policy_templates
version: 1.0
</code></pre>
<p><code>template_dir</code> points to the directory containing the policy
templates. <code>version</code> defines the version of the policy which will be served
to the user. In the example above, Synapse will serve
<p>This should be set to an arbitrary secret string (try <code>pwgen -y 30</code> to
generate suitable secrets).</p>
<p>More on what this is used for below.</p>
</li>
<li>
<p>Add <code>consent</code> wherever the <code>client</code> resource is currently enabled in the
<code>listeners</code> configuration. For example:</p>
<pre><codeclass="language-yaml">listeners:
- port: 8008
resources:
- names:
- client
- consent
</code></pre>
</li>
</ol>
<p>Finally, ensure that <code>jinja2</code> is installed. If you are using a virtualenv, this
should be a matter of <code>pip install Jinja2</code>. On debian, try <code>apt-get install python-jinja2</code>.</p>
<p>Once this is complete, and the server has been restarted, try visiting
<code>https://<server>/_matrix/consent</code>. If correctly configured, this should give
an error "Missing string query parameter 'u'". It is now possible to manually
construct URIs where users can give their consent.</p>
<h3id="enabling-consent-tracking-at-registration"><aclass="header"href="#enabling-consent-tracking-at-registration">Enabling consent tracking at registration</a></h3>
<ol>
<li>
<p>Add the following to your configuration:</p>
<pre><codeclass="language-yaml">user_consent:
require_at_registration: true
policy_name: "Privacy Policy" # or whatever you'd like to call the policy
</code></pre>
</li>
<li>
<p>In your consent templates, make use of the <code>public_version</code> variable to
see if an unauthenticated user is viewing the page. This is typically
wrapped around the form that would be used to actually agree to the document:</p>
<pre><codeclass="language-html">{% if not public_version %}
<!-- The variables used here are only provided when the 'u' param is given to the homeserver -->
<p>Note that not providing a <code>u</code> parameter will be interpreted as wanting to view
the document from an unauthenticated perspective, such as prior to registration.
Therefore, the <code>h</code> parameter is not required in this scenario. To enable this
behaviour, set <code>require_at_registration</code> to <code>true</code> in your <code>user_consent</code> config.</p>
<h2id="sending-users-a-server-notice-asking-them-to-agree-to-the-policy"><aclass="header"href="#sending-users-a-server-notice-asking-them-to-agree-to-the-policy">Sending users a server notice asking them to agree to the policy</a></h2>
<p>It is possible to configure Synapse to send a <ahref="server_notices.html">server
notice</a> to anybody who has not yet agreed to the current
version of the policy. To do so:</p>
<ul>
<li>
<p>ensure that the consent resource is configured, as in the previous section</p>
</li>
<li>
<p>ensure that server notices are configured, as in <ahref="server_notices.html">the server notice documentation</a>.</p>
</li>
<li>
<p>Add <code>server_notice_content</code> under <code>user_consent</code> in <code>homeserver.yaml</code>. For
example:</p>
<pre><codeclass="language-yaml">user_consent:
server_notice_content:
msgtype: m.text
body: >-
Please give your consent to the privacy policy at %(consent_uri)s.
</code></pre>
<p>Synapse automatically replaces the placeholder <code>%(consent_uri)s</code> with the
consent uri for that user.</p>
</li>
<li>
<p>ensure that <code>public_baseurl</code> is set in <code>homeserver.yaml</code>, and gives the base
URI that clients use to connect to the server. (It is used to construct
<code>consent_uri</code> in the server notice.)</p>
</li>
</ul>
<h2id="blocking-users-from-using-the-server-until-they-agree-to-the-policy"><aclass="header"href="#blocking-users-from-using-the-server-until-they-agree-to-the-policy">Blocking users from using the server until they agree to the policy</a></h2>
<p>Synapse can be configured to block any attempts to join rooms or send messages
until the user has given their agreement to the policy. (Joining the server
notices room is exempted from this).</p>
<p>To enable this, add <code>block_events_error</code> under <code>user_consent</code>. For example:</p>
<pre><codeclass="language-yaml">user_consent:
block_events_error: >-
You can't send any messages until you consent to the privacy policy at
%(consent_uri)s.
</code></pre>
<p>Synapse automatically replaces the placeholder <code>%(consent_uri)s</code> with the
consent uri for that user.</p>
<p>ensure that <code>public_baseurl</code> is set in <code>homeserver.yaml</code>, and gives the base
URI that clients use to connect to the server. (It is used to construct
<code>consent_uri</code> in the error.)</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="user-directory-api-implementation"><aclass="header"href="#user-directory-api-implementation">User Directory API Implementation</a></h1>
<p>The user directory is currently maintained based on the 'visible' users
on this particular server - i.e. ones which your account shares a room with, or
who are present in a publicly viewable room present on the server.</p>
<p>The directory info is stored in various tables, which can (typically after
DB corruption) get stale or out of sync. If this happens, for now the
solution to fix it is to use the <ahref="usage/administration/admin_api/background_updates.html#run">admin API</a>
and execute the job <code>regenerate_directory</code>. This should then start a background task to
flush the current tables and regenerate the directory.</p>
<h2id="when-synapse-runs-with-several-modules-configured"><aclass="header"href="#when-synapse-runs-with-several-modules-configured">When Synapse runs with several modules configured</a></h2>
<p>If Synapse is running with other modules configured, the order each module appears in
within the <code>modules</code> section of the Synapse configuration file might restrict what it can
or cannot register. See <ahref="modules/index.html#using-multiple-modules">this section</a> for more
information.</p>
<p>On top of the rules listed in the link above, if a callback returns a value that should
cause the current operation to fail (e.g. if a callback checking an event returns with a
value that should cause the event to be denied), Synapse will fail the operation and
ignore any subsequent callbacks that should have been run after this one.</p>
<p>The documentation for each callback mentions how Synapse behaves when
multiple modules implement it.</p>
<h2id="handling-the-modules-configuration"><aclass="header"href="#handling-the-modules-configuration">Handling the module's configuration</a></h2>
<p>A module can implement the following static method:</p>
<pre><codeclass="language-python">@staticmethod
def parse_config(config: dict) -> Any
</code></pre>
<p>This method is given a dictionary resulting from parsing the YAML configuration for the
module. It may modify it (for example by parsing durations expressed as strings (e.g.
"5d") into milliseconds, etc.), and return the modified dictionary. It may also verify
that the configuration is correct, and raise an instance of
<code>synapse.module_api.errors.ConfigError</code> if not.</p>
<h2id="registering-a-web-resource"><aclass="header"href="#registering-a-web-resource">Registering a web resource</a></h2>
<p>Modules can register web resources onto Synapse's web server using the following module
<p>The path is the full absolute path to register the resource at. For example, if you
register a resource for the path <code>/_synapse/client/my_super_module/say_hello</code>, Synapse
will serve it at <code>http(s)://[HS_URL]/_synapse/client/my_super_module/say_hello</code>. Note
that Synapse does not allow registering resources for several sub-paths in the <code>/_matrix</code>
namespace (such as anything under <code>/_matrix/client</code> for example). It is strongly
recommended that modules register their web resources under the <code>/_synapse/client</code>
namespace.</p>
<p>The provided resource is a Python class that implements Twisted's <ahref="https://twistedmatrix.com/documents/current/api/twisted.web.resource.IResource.html">IResource</a>
interface (such as <ahref="https://twistedmatrix.com/documents/current/api/twisted.web.resource.Resource.html">Resource</a>).</p>
<p>Only one resource can be registered for a given path. If several modules attempt to
register a resource for the same path, the module that appears first in Synapse's
configuration file takes priority.</p>
<p>Modules <strong>must</strong> register their web resources in their <code>__init__</code> method.</p>
<h2id="registering-a-callback"><aclass="header"href="#registering-a-callback">Registering a callback</a></h2>
<p>Modules can use Synapse's module API to register callbacks. Callbacks are functions that
Synapse will call when performing specific actions. Callbacks must be asynchronous (unless
specified otherwise), and are split in categories. A single module may implement callbacks
from multiple categories, and is under no obligation to implement all callbacks from the
categories it registers callbacks for.</p>
<p>Modules can register callbacks using one of the module API's <code>register_[...]_callbacks</code>
methods. The callback functions are passed to these methods as keyword arguments, with
the callback name as the argument name and the function as its value. A
<code>register_[...]_callbacks</code> method exists for each category.</p>
<p>Callbacks for each category can be found on their respective page of the
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.60.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean or a string is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.61.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.62.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.45.0</em></p>
<p><em>Changed in Synapse v1.62.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.62.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.62.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.62.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p><em>First introduced in Synapse v1.37.0</em></p>
<p><em>Changed in Synapse v1.62.0: <code>synapse.module_api.NOT_SPAM</code> and <code>synapse.module_api.errors.Codes</code> can be returned by this callback. Returning a boolean is now deprecated.</em></p>
<p>Called when the deactivation of a user is requested. User deactivation can be
performed by an admin or the user themselves, so developers are encouraged to check the
requester when implementing this callback. The module must return a
boolean indicating whether the deactivation can go through. If the callback returns <code>False</code>,
the deactivation will not proceed and the caller will see a <code>M_FORBIDDEN</code> error.</p>
<p>The module is passed two parameters, <code>user_id</code> which is the ID of the user being deactivated, and <code>by_admin</code> which is <code>True</code> if the request is made by a serve admin, and <code>False</code> otherwise.</p>
<p>If multiple modules implement this callback, they will be considered in order. If a
callback returns <code>True</code>, Synapse falls through to the next one. The value of the first
callback that does not return <code>True</code> will be used. If this happens, Synapse will not call
any of the subsequent implementations of this callback.</p>
<p>Called when registering a new user. The module can return a username to set for the user
being registered by returning it as a string, or <code>None</code> if it doesn't wish to force a
username for this user. If a username is returned, it will be used as the local part of a
user's full Matrix ID (e.g. it's <code>alice</code> in <code>@alice:example.com</code>).</p>
<p>This callback is called once <ahref="https://spec.matrix.org/latest/client-server-api/#user-interactive-authentication-api">User-Interactive Authentication</a>
has been completed by the user. It is not called when registering a user via SSO. It is
passed two dictionaries, which include the information that the user has provided during
the registration process.</p>
<p>The first dictionary contains the results of the <ahref="https://spec.matrix.org/latest/client-server-api/#user-interactive-authentication-api">User-Interactive Authentication</a>
flow followed by the user. Its keys are the identifiers of every step involved in the flow,
associated with either a boolean value indicating whether the step was correctly completed,
or additional information (e.g. email address, phone number...). A list of most existing
identifiers can be found in the <ahref="https://spec.matrix.org/v1.1/client-server-api/#authentication-types">Matrix specification</a>.
Here's an example featuring all currently supported keys:</p>
"m.login.msisdn": { # User has provided and verified a phone number
"medium": "msisdn",
"address": "33123456789",
"validated_at": 1642701357084,
},
"m.login.registration_token": "sometoken", # User has registered through a registration token
}
</code></pre>
<p>The second dictionary contains the parameters provided by the user's client in the request
to <code>/_matrix/client/v3/register</code>. See the <ahref="https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3register">Matrix specification</a>
for a complete list of these parameters.</p>
<p>If the module cannot, or does not wish to, generate a username for this user, it must
return <code>None</code>.</p>
<p>If multiple modules implement this callback, they will be considered in order. If a
callback returns <code>None</code>, Synapse falls through to the next one. The value of the first
callback that does not return <code>None</code> will be used. If this happens, Synapse will not call
any of the subsequent implementations of this callback. If every callback returns <code>None</code>,
the username provided by the user is used, if any (otherwise one is automatically
<p>Called when registering a new user. The module can return a display name to set for the
user being registered by returning it as a string, or <code>None</code> if it doesn't wish to force a
display name for this user.</p>
<p>This callback is called once <ahref="https://spec.matrix.org/latest/client-server-api/#user-interactive-authentication-api">User-Interactive Authentication</a>
has been completed by the user. It is not called when registering a user via SSO. It is
passed two dictionaries, which include the information that the user has provided during
the registration process. These dictionaries are identical to the ones passed to
<ahref="modules/password_auth_provider_callbacks.html#get_username_for_registration"><code>get_username_for_registration</code></a>, so refer to the
documentation of this callback for more information about them.</p>
<p>If multiple modules implement this callback, they will be considered in order. If a
callback returns <code>None</code>, Synapse falls through to the next one. The value of the first
callback that does not return <code>None</code> will be used. If this happens, Synapse will not call
any of the subsequent implementations of this callback. If every callback returns <code>None</code>,
the username will be used (e.g. <code>alice</code> if the user being registered is <code>@alice:example.com</code>).</p>
raise ConfigError(f"'{param}' is required")
check_in_config("audit_room")
check_in_config("sender")
return CustomAccountDataConfig(
audit_room=config["audit_room"],
sender=config["sender"],
)
async def log_new_account_data(
self,
user_id: str,
room_id: Optional[str],
account_data_type: str,
content: JsonDict,
) -> None:
content_raw = json.dumps(content)
msg_content = f"{user_id} has changed their account data for type {account_data_type} to: {content_raw}"
if room_id is not None:
msg_content += f" (in room {room_id})"
await self.api.create_and_send_event_into_room(
{
"room_id": self.config.audit_room,
"sender": self.config.sender,
"type": "m.room.message",
"content": {
"msgtype": "m.text",
"body": msg_content
}
}
)
</code></pre>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="porting-an-existing-module-that-uses-the-old-interface"><aclass="header"href="#porting-an-existing-module-that-uses-the-old-interface">Porting an existing module that uses the old interface</a></h1>
<p>In order to port a module that uses Synapse's old module interface, its author needs to:</p>
<ul>
<li>ensure the module's callbacks are all asynchronous.</li>
<li>register their callbacks using one or more of the <code>register_[...]_callbacks</code> methods
from the <code>ModuleApi</code> class in the module's <code>__init__</code> method (see <ahref="modules/writing_a_module.html#registering-a-callback">this section</a>
for more info).</li>
</ul>
<p>Additionally, if the module is packaged with an additional web resource, the module
should register this resource in its <code>__init__</code> method using the <code>register_web_resource</code>
method from the <code>ModuleApi</code> class (see <ahref="modules/writing_a_module.html#registering-a-web-resource">this section</a> for
more info).</p>
<p>There is no longer a <code>get_db_schema_files</code> callback provided for password auth provider modules. Any
changes to the database should now be made by the module using the module API class.</p>
<p>The module's author should also update any example in the module's configuration to only
use the new <code>modules</code> section in Synapse's configuration file (see <ahref="modules/index.html#using-modules">this section</a>
for more info).</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="scaling-synapse-via-workers"><aclass="header"href="#scaling-synapse-via-workers">Scaling synapse via workers</a></h1>
<p>For small instances it is recommended to run Synapse in the default monolith mode.
For larger instances where performance is a concern it can be helpful to split
out functionality into multiple separate python processes. These processes are
called 'workers', and are (eventually) intended to scale horizontally
independently.</p>
<p>Synapse's worker support is under active development and subject to change as
we attempt to rapidly scale ever larger Synapse instances. However we are
documenting it here to help admins needing a highly scalable Synapse instance
similar to the one running <code>matrix.org</code>.</p>
<p>All processes continue to share the same database instance, and as such,
workers only work with PostgreSQL-based Synapse deployments. SQLite should only
be used for demo purposes and any admin considering workers should already be
running PostgreSQL.</p>
<p>See also <ahref="https://matrix.org/blog/2020/11/03/how-we-fixed-synapses-scalability">Matrix.org blog post</a>
<p>Note that these dependencies are included when synapse is installed with <code>pip install matrix-synapse[all]</code>. They are also included in the debian packages from
<code>matrix.org</code> and in the docker images at
<p><strong>Deprecated as of Synapse v1.59.</strong><ahref="workers.html#notifying-application-services">Use <code>synapse.app.generic_worker</code> with the
<p>Note that if a reverse proxy is used , then <code>/_matrix/media/</code> must be routed for both inbound client and federation requests (if they are handled separately).</p>
<p><strong>Deprecated as of Synapse v1.59.</strong><ahref="workers.html#updating-the-user-directory">Use <code>synapse.app.generic_worker</code> with the
<divstyle="break-before: page; page-break-before: always;"></div><h1id="setting-up-synapse-with-workers-and-systemd"><aclass="header"href="#setting-up-synapse-with-workers-and-systemd">Setting up Synapse with Workers and Systemd</a></h1>
<p>This is a setup for managing synapse with systemd, including support for
managing workers. It provides a <code>matrix-synapse</code> service for the master, as
well as a <code>matrix-synapse-worker@</code> service template for any workers you
require. Additionally, to group the required services, it sets up a
<code>matrix-synapse.target</code>.</p>
<p>See the folder <ahref="https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/">system</a>
<li>Adjust synapse configuration files as above.</li>
<li>Copy the <code>*.service</code> and <code>*.target</code> files in <ahref="https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/">system</a>
to <code>/etc/systemd/system</code>.</li>
<li>Run <code>systemctl daemon-reload</code> to tell systemd to load the new unit files.</li>
<li>Run <code>systemctl enable matrix-synapse.service</code>. This will configure the
synapse master process to be started as part of the <code>matrix-synapse.target</code>
target.</li>
<li>For each worker process to be enabled, run <code>systemctl enable matrix-synapse-worker@<worker_name>.service</code>. For each <code><worker_name></code>, there
<p>In order to see their effect, you may run <code>systemd-analyze security matrix-synapse.service</code> before and after applying the hardening options to see
<h2id="authenticate-as-a-server-admin"><aclass="header"href="#authenticate-as-a-server-admin">Authenticate as a server admin</a></h2>
<p>Many of the API calls in the admin api will require an <code>access_token</code> for a
server admin. (Note that a server admin is distinct from a room admin.)</p>
<p>An existing user can be marked as a server admin by updating the database directly.</p>
<p>Check your <ahref="usage/administration/admin_api/config_documentation.html#database">database settings</a> in the configuration file, connect to the correct database using either <code>psql [database name]</code> (if using PostgreSQL) or <code>sqlite3 path/to/your/database.db</code> (if using SQLite) and elevate the user <code>@foo:bar.com</code> to administrator.</p>
<pre><codeclass="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
</code></pre>
<p>A new server admin user can also be created using the <code>register_new_matrix_user</code>
command. This is a script that is distributed as part of synapse. It is possibly
already on your <code>$PATH</code> depending on how Synapse was installed.</p>
<p>Finding your user's <code>access_token</code> is client-dependent, but will usually be shown in the client's settings.</p>
<h2id="making-an-admin-api-request"><aclass="header"href="#making-an-admin-api-request">Making an Admin API request</a></h2>
<p>For security reasons, we <ahref="usage/administration/admin_api/reverse_proxy.html#synapse-administration-endpoints">recommend</a>
that the Admin API (<code>/_synapse/admin/...</code>) should be hidden from public view using a
reverse proxy. This means you should typically query the Admin API from a terminal on
the machine which runs Synapse.</p>
<p>Once you have your <code>access_token</code>, you will need to authenticate each request to an Admin API endpoint by
providing the token as either a query parameter or a request header. To add it as a request header in cURL:</p>
<p>The following JSON body parameters are available:</p>
<ul>
<li><code>job_name</code> - A string which job to run. Valid values are:
<ul>
<li><code>populate_stats_process_rooms</code> - Recalculate the stats for all rooms.</li>
<li><code>regenerate_directory</code> - Recalculate the <ahref="usage/administration/admin_api/../../../user_directory.html">user directory</a> if it is stale or out of sync.</li>
<p>To paginate, check for <code>next_token</code> and if present, call the endpoint again with <code>from</code>
set to the value of <code>next_token</code>. This will return a new page.</p>
<p>If the endpoint does not return a <code>next_token</code> then there are no more reports to
paginate through.</p>
<p><strong>URL parameters:</strong></p>
<ul>
<li><code>limit</code>: integer - Is optional but is used for pagination, denoting the maximum number
of items to return in this call. Defaults to <code>100</code>.</li>
<li><code>from</code>: integer - Is optional but used for pagination, denoting the offset in the
returned results. This should be treated as an opaque value and not explicitly set to
anything other than the return value of <code>next_token</code> from a previous call. Defaults to <code>0</code>.</li>
<li><code>dir</code>: string - Direction of event report order. Whether to fetch the most recent
first (<code>b</code>) or the oldest first (<code>f</code>). Defaults to <code>b</code>.</li>
<li><code>user_id</code>: string - Is optional and filters to only return users with user IDs that
contain this value. This is the user who reported the event and wrote the reason.</li>
<li><code>room_id</code>: string - Is optional and filters to only return rooms with room IDs that
contain this value.</li>
</ul>
<p><strong>Response</strong></p>
<p>The following fields are returned in the JSON response body:</p>
<ul>
<li><code>id</code>: integer - ID of event report.</li>
<li><code>received_ts</code>: integer - The timestamp (in milliseconds since the unix epoch) when this
report was sent.</li>
<li><code>room_id</code>: string - The ID of the room in which the event being reported is located.</li>
<li><code>name</code>: string - The name of the room.</li>
<li><code>event_id</code>: string - The ID of the reported event.</li>
<li><code>user_id</code>: string - This is the user who reported the event and wrote the reason.</li>
<li><code>reason</code>: string - Comment made by the <code>user_id</code> in this report. May be blank or <code>null</code>.</li>
<li><code>score</code>: integer - Content is reported based upon a negative score, where -100 is
"most offensive" and 0 is "inoffensive". May be <code>null</code>.</li>
<li><code>sender</code>: string - This is the ID of the user who sent the original message/event that
was reported.</li>
<li><code>canonical_alias</code>: string - The canonical alias of the room. <code>null</code> if the room does not
have a canonical alias set.</li>
<li><code>next_token</code>: integer - Indication for pagination. See above.</li>
<li><code>total</code>: integer - Total number of event reports related to the query
(<code>user_id</code> and <code>room_id</code>).</li>
</ul>
<h1id="show-details-of-a-specific-event-report"><aclass="header"href="#show-details-of-a-specific-event-report">Show details of a specific event report</a></h1>
<p>This API returns information about a specific event report.</p>
<li><code>user_id</code>: string - User ID in the form of <code>@bob:example.org</code></li>
</ul>
<p>Response:</p>
<pre><codeclass="language-json">{
"num_quarantined": 10
}
</code></pre>
<p>The following fields are returned in the JSON response body:</p>
<ul>
<li><code>num_quarantined</code>: integer - The number of media items successfully quarantined</li>
</ul>
<h2id="protecting-media-from-being-quarantined"><aclass="header"href="#protecting-media-from-being-quarantined">Protecting media from being quarantined</a></h2>
<p>This API protects a single piece of local media from being quarantined using the
above APIs. This is useful for sticker packs and other shared media which you do
not want to get quarantined, especially when
<ahref="admin_api/media_admin_api.html#quarantining-media-in-a-room">quarantining media in a room</a>.</p>
<p>Where <code>media_id</code> is in the form of <code>abcdefg12345...</code>.</p>
<p>Response:</p>
<pre><codeclass="language-json">{}
</code></pre>
<h2id="unprotecting-media-from-being-quarantined"><aclass="header"href="#unprotecting-media-from-being-quarantined">Unprotecting media from being quarantined</a></h2>
<p>This API reverts the protection of a media.</p>
<p>The List Room admin API allows server admins to get a list of rooms on their
server. There are various parameters available that allow for filtering and
sorting the returned list. This API supports pagination.</p>
<p>To use it, you will need to authenticate by providing an <code>access_token</code>
for a server admin: see <ahref="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
<p><strong>Parameters</strong></p>
<p>The following query parameters are available:</p>
<ul>
<li>
<p><code>from</code> - Offset in the returned list. Defaults to <code>0</code>.</p>
</li>
<li>
<p><code>limit</code> - Maximum amount of rooms to return. Defaults to <code>100</code>.</p>
</li>
<li>
<p><code>order_by</code> - The method in which to sort the returned list of rooms. Valid values are:</p>
<ul>
<li><code>alphabetical</code> - Same as <code>name</code>. This is deprecated.</li>
<li><code>size</code> - Same as <code>joined_members</code>. This is deprecated.</li>
<li><code>name</code> - Rooms are ordered alphabetically by room name. This is the default.</li>
<li><code>canonical_alias</code> - Rooms are ordered alphabetically by main alias address of the room.</li>
<li><code>joined_members</code> - Rooms are ordered by the number of members. Largest to smallest.</li>
<li><code>joined_local_members</code> - Rooms are ordered by the number of local members. Largest to smallest.</li>
<li><code>version</code> - Rooms are ordered by room version. Largest to smallest.</li>
<li><code>creator</code> - Rooms are ordered alphabetically by creator of the room.</li>
<li><code>encryption</code> - Rooms are ordered alphabetically by the end-to-end encryption algorithm.</li>
<li><code>federatable</code> - Rooms are ordered by whether the room is federatable.</li>
<li><code>public</code> - Rooms are ordered by visibility in room list.</li>
<li><code>join_rules</code> - Rooms are ordered alphabetically by join rules of the room.</li>
<li><code>guest_access</code> - Rooms are ordered alphabetically by guest access option of the room.</li>
<li><code>history_visibility</code> - Rooms are ordered alphabetically by visibility of history of the room.</li>
<li><code>state_events</code> - Rooms are ordered by number of state events. Largest to smallest.</li>
</ul>
</li>
<li>
<p><code>dir</code> - Direction of room order. Either <code>f</code> for forwards or <code>b</code> for backwards. Setting
this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</p>
</li>
<li>
<p><code>search_term</code> - Filter rooms by their room name, canonical alias and room id.
Specifically, rooms are selected if the search term is contained in</p>
<ul>
<li>the room's name,</li>
<li>the local part of the room's canonical alias, or</li>
<li>the complete (local and server part) room's id (case sensitive).</li>
</ul>
<p>Defaults to no filtering.</p>
</li>
</ul>
<p><strong>Response</strong></p>
<p>The following fields are possible in the JSON response body:</p>
<ul>
<li><code>rooms</code> - An array of objects, each containing information about a room.
<ul>
<li>Room objects contain the following fields:
<ul>
<li><code>room_id</code> - The ID of the room.</li>
<li><code>name</code> - The name of the room.</li>
<li><code>canonical_alias</code> - The canonical (main) alias address of the room.</li>
<li><code>joined_members</code> - How many users are currently in the room.</li>
<li><code>joined_local_members</code> - How many local users are currently in the room.</li>
<li><code>version</code> - The version of the room as a string.</li>
<li><code>creator</code> - The <code>user_id</code> of the room creator.</li>
<li><code>encryption</code> - Algorithm of end-to-end encryption of messages. Is <code>null</code> if encryption is not active.</li>
<li><code>federatable</code> - Whether users on other servers can join this room.</li>
<li><code>public</code> - Whether the room is visible in room directory.</li>
<li><code>join_rules</code> - The type of rules used for users wishing to join this room. One of: ["public", "knock", "invite", "private"].</li>
<li><code>guest_access</code> - Whether guests can join the room. One of: ["can_join", "forbidden"].</li>
<li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li>
<li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
<li><code>room_type</code> - The type of the room taken from the room's creation event; for example "m.space" if the room is a space. If the room does not define a type, the value will be <code>null</code>.</li>
</ul>
</li>
</ul>
</li>
<li><code>offset</code> - The current pagination offset in rooms. This parameter should be
used instead of <code>next_token</code> for room offset as <code>next_token</code> is
not intended to be parsed.</li>
<li><code>total_rooms</code> - The total number of rooms this query can return. Using this
and <code>offset</code>, you have enough information to know the current
progression through the list.</li>
<li><code>next_batch</code> - If this field is present, we know that there are potentially
more rooms on the server that did not all fit into this response.
We can use <code>next_batch</code> to get the "next page" of results. To do
so, simply repeat your request, setting the <code>from</code> parameter to
the value of <code>next_batch</code>.</li>
<li><code>prev_batch</code> - If this field is present, it is possible to paginate backwards.
Use <code>prev_batch</code> for the <code>from</code> value in the next request to
get the "previous page" of results.</li>
</ul>
<p>The API is:</p>
<p>A standard request with no filtering:</p>
<pre><code>GET /_synapse/admin/v1/rooms
</code></pre>
<p>A response body like the following is returned:</p>
<p>The Room Details admin API allows server admins to get all details of a room.</p>
<p>The following fields are possible in the JSON response body:</p>
<ul>
<li><code>room_id</code> - The ID of the room.</li>
<li><code>name</code> - The name of the room.</li>
<li><code>topic</code> - The topic of the room.</li>
<li><code>avatar</code> - The <code>mxc</code> URI to the avatar of the room.</li>
<li><code>canonical_alias</code> - The canonical (main) alias address of the room.</li>
<li><code>joined_members</code> - How many users are currently in the room.</li>
<li><code>joined_local_members</code> - How many local users are currently in the room.</li>
<li><code>joined_local_devices</code> - How many local devices are currently in the room.</li>
<li><code>version</code> - The version of the room as a string.</li>
<li><code>creator</code> - The <code>user_id</code> of the room creator.</li>
<li><code>encryption</code> - Algorithm of end-to-end encryption of messages. Is <code>null</code> if encryption is not active.</li>
<li><code>federatable</code> - Whether users on other servers can join this room.</li>
<li><code>public</code> - Whether the room is visible in room directory.</li>
<li><code>join_rules</code> - The type of rules used for users wishing to join this room. One of: ["public", "knock", "invite", "private"].</li>
<li><code>guest_access</code> - Whether guests can join the room. One of: ["can_join", "forbidden"].</li>
<li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li>
<li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
<li><code>room_type</code> - The type of the room taken from the room's creation event; for example "m.space" if the room is a space.
If the room does not define a type, the value will be <code>null</code>.</li>
<li><code>forgotten</code> - Whether all local users have
<ahref="https://spec.matrix.org/latest/client-server-api/#leaving-rooms">forgotten</a> the room.</li>
<p>The following parameters should be set in the URL:</p>
<ul>
<li><code>room_id</code> - The ID of the room.</li>
</ul>
<p>The following JSON body parameters are available:</p>
<ul>
<li><code>new_room_user_id</code> - Optional. If set, a new room will be created with this user ID
as the creator and admin, and all users in the old room will be moved into that
room. If not set, no new room will be created and the users will just be removed
from the old room. The user ID must be on the local server, but does not necessarily
have to belong to a registered user.</li>
<li><code>room_name</code> - Optional. A string representing the name of the room that new users will be
invited to. Defaults to <code>Content Violation Notification</code></li>
<li><code>message</code> - Optional. A string containing the first message that will be sent as
<code>new_room_user_id</code> in the new room. Ideally this will clearly convey why the
original room was shut down. Defaults to <code>Sharing illegal content on this server is not permitted and rooms in violation will be blocked.</code></li>
<li><code>block</code> - Optional. If set to <code>true</code>, this room will be added to a blocking list,
preventing future attempts to join the room. Rooms can be blocked
even if they're not yet known to the homeserver (only with
<ahref="admin_api/rooms.html#version-1-old-version">Version 1</a> of the API). Defaults to <code>false</code>.</li>
<li><code>purge</code> - Optional. If set to <code>true</code>, it will remove all traces of the room from your database.
Defaults to <code>true</code>.</li>
<li><code>force_purge</code> - Optional, and ignored unless <code>purge</code> is <code>true</code>. If set to <code>true</code>, it
will force a purge to go ahead even if there are local users still in the room. Do not
use this unless a regular <code>purge</code> operation fails, as it could leave those users'
clients in a confused state.</li>
</ul>
<p>The JSON body must not be empty. The body must be at least <code>{}</code>.</p>
<h2id="status-of-deleting-rooms"><aclass="header"href="#status-of-deleting-rooms">Status of deleting rooms</a></h2>
<p><strong>Note</strong>: This API is new, experimental and "subject to change".</p>
<p>It is possible to query the status of the background task for deleting rooms.
The status can be queried up to 24 hours after completion of the task,
or until Synapse is restarted (whichever happens first).</p>
<h3id="query-by-room_id"><aclass="header"href="#query-by-room_id">Query by <code>room_id</code></a></h3>
<p>With this API you can get the status of all active deletion tasks, and all those completed in the last 24h,
<p><em>Note</em>: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level,
the structure can and does change without notice.</p>
<p>First, it's important to understand that a room deletion is very destructive. Undoing a deletion is not as simple as pretending it
never happened - work has to be done to move forward instead of resetting the past. In fact, in some cases it might not be possible
to recover at all:</p>
<ul>
<li>If the room was invite-only, your users will need to be re-invited.</li>
<li>If the room no longer has any members at all, it'll be impossible to rejoin.</li>
<li>The first user to rejoin will have to do so via an alias on a different
server (or receive an invite from a user on a different server).</li>
</ul>
<p>With all that being said, if you still want to try and recover the room:</p>
<ol>
<li>
<p>If the room was <code>block</code>ed, you must unblock it on your server. This can be
accomplished as follows:</p>
<ol>
<li>For safety reasons, shut down Synapse.</li>
<li>In the database, run <code>DELETE FROM blocked_rooms WHERE room_id = '!example:example.org';</code>
<ul>
<li>For caution: it's recommended to run this in a transaction: <code>BEGIN; DELETE ...;</code>, verify you got 1 result, then <code>COMMIT;</code>.</li>
<li>The room ID is the same one supplied to the delete room API, not the Content Violation room.</li>
</ul>
</li>
<li>Restart Synapse.</li>
</ol>
<p>This step is unnecessary if <code>block</code> was not set.</p>
</li>
<li>
<p>Any room aliases on your server that pointed to the deleted room may have
been deleted, or redirected to the Content Violation room. These will need
to be restored manually.</p>
</li>
<li>
<p>Users on your server that were in the deleted room will have been kicked
from the room. Consider whether you want to update their membership
(possibly via the <ahref="admin_api/room_membership.html">Edit Room Membership API</a>) or let
them handle rejoining themselves.</p>
</li>
<li>
<p>If <code>new_room_user_id</code> was given, a 'Content Violation' will have been
created. Consider whether you want to delete that roomm.</p>
<p>This API mimmicks <ahref="https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-rooms-roomid-context-eventid">GET /_matrix/client/r0/rooms/{roomId}/context/{eventId}</a>. Please refer to the link for all details on parameters and reseponse.</p>
<p>Example response:</p>
<pre><codeclass="language-json">{
"end": "t29-57_2_0_2",
"events_after": [
{
"content": {
"body": "This is an example text message",
<li><code>medium</code> - string. Kind of third-party ID, either <code>email</code> or <code>msisdn</code>.</li>
<li><code>address</code> - string. Value of third-party ID.
belonging to a user.</li>
</ul>
</li>
<li><code>external_ids</code> - array, optional. Allow setting the identifier of the external identity
provider for SSO (Single sign-on). Details in the configuration manual under the
sections <ahref="admin_api/../usage/configuration/config_documentation.html#sso">sso</a> and <ahref="admin_api/../usage/configuration/config_documentation.html#oidc_providers">oidc_providers</a>.
<ul>
<li><code>auth_provider</code> - string. ID of the external identity provider. Value of <code>idp_id</code>
in the homeserver configuration. Note that no error is raised if the provided
value is not in the homeserver configuration.</li>
<li><code>external_id</code> - string, user ID in the external identity provider.</li>
</ul>
</li>
<li><code>avatar_url</code> - string, optional, must be a
<p>The parameter <code>new_password</code> is required.
The parameter <code>logout_devices</code> is optional and defaults to <code>true</code>.</p>
<h2id="get-whether-a-user-is-a-server-administrator-or-not"><aclass="header"href="#get-whether-a-user-is-a-server-administrator-or-not">Get whether a user is a server administrator or not</a></h2>
<p>A response body like the following is returned:</p>
<pre><codeclass="language-json">{
"admin": true
}
</code></pre>
<h2id="change-whether-a-user-is-a-server-administrator-or-not"><aclass="header"href="#change-whether-a-user-is-a-server-administrator-or-not">Change whether a user is a server administrator or not</a></h2>
<p>The following parameters should be set in the URL:</p>
<ul>
<li><code>user_id</code> - fully qualified: for example, <code>@user:server.com</code>.</li>
</ul>
<p><strong>Response</strong></p>
<p>The following fields are returned in the JSON response body:</p>
<ul>
<li>
<p><code>pushers</code> - An array containing the current pushers for the user</p>
<ul>
<li>
<p><code>app_display_name</code> - string - A string that will allow the user to identify
what application owns this pusher.</p>
</li>
<li>
<p><code>app_id</code> - string - This is a reverse-DNS style identifier for the application.
Max length, 64 chars.</p>
</li>
<li>
<p><code>data</code> - A dictionary of information for the pusher implementation itself.</p>
<ul>
<li>
<p><code>url</code> - string - Required if <code>kind</code> is <code>http</code>. The URL to use to send
notifications to.</p>
</li>
<li>
<p><code>format</code> - string - The format to use when sending notifications to the
Push Gateway.</p>
</li>
</ul>
</li>
<li>
<p><code>device_display_name</code> - string - A string that will allow the user to identify
what device owns this pusher.</p>
</li>
<li>
<p><code>profile_tag</code> - string - This string determines which set of device specific rules
this pusher executes.</p>
</li>
<li>
<p><code>kind</code> - string - The kind of pusher. "http" is a pusher that sends HTTP pokes.</p>
</li>
<li>
<p><code>lang</code> - string - The preferred language for receiving notifications
(e.g. 'en' or 'en-US')</p>
</li>
<li>
<p><code>profile_tag</code> - string - This string determines which set of device specific rules
this pusher executes.</p>
</li>
<li>
<p><code>pushkey</code> - string - This is a unique identifier for this pusher.
Max length, 512 bytes.</p>
</li>
</ul>
</li>
<li>
<p><code>total</code> - integer - Number of pushers.</p>
</li>
</ul>
<p>See also the
<ahref="https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-pushers">Client-Server API Spec on pushers</a>.</p>
<h2id="controlling-whether-a-user-is-shadow-banned"><aclass="header"href="#controlling-whether-a-user-is-shadow-banned">Controlling whether a user is shadow-banned</a></h2>
<p>Shadow-banning is a useful tool for moderating malicious or egregiously abusive users.
A shadow-banned users receives successful responses to their client-server API requests,
but the events are not propagated into rooms. This can be an effective tool as it
(hopefully) takes longer for the user to realise they are being moderated before
pivoting to another account.</p>
<p>Shadow-banning a user should be used as a tool of last resort and may lead to confusing
or broken behaviour for the client. A shadow-banned user will not receive any
notification and it is generally more appropriate to ban or kick abusive users.
A shadow-banned user will be unable to contact anyone on the server.</p>
<p>Checks to see if a username is available, and valid, for the server. See <ahref="https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available">the client-server
API</a>
for more information.</p>
<p>This endpoint will work even if registration is disabled on the server, unlike
<Deferred at 0x7ff253fc6998 current result: <FrozenEvent event_id='$1416420717069yeQaw:matrix.org', type='m.room.create', state_key=''>>
</code></pre>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="how-to-monitor-synapse-metrics-using-prometheus"><aclass="header"href="#how-to-monitor-synapse-metrics-using-prometheus">How to monitor Synapse metrics using Prometheus</a></h1>
<p>Labels (<code>instance</code>, <code>job</code>, <code>index</code>) can be defined as anything.
The labels are used to group graphs in grafana.</p>
<h2id="renaming-of-metrics--deprecation-of-old-names-in-12"><aclass="header"href="#renaming-of-metrics--deprecation-of-old-names-in-12">Renaming of metrics & deprecation of old names in 1.2</a></h2>
<p>Synapse 1.2 updates the Prometheus metrics to match the naming
convention of the upstream <code>prometheus_client</code>. The old names are
considered deprecated and will be removed in a future version of
<h2id="removal-of-deprecated-metrics--time-based-counters-becoming-histograms-in-0310"><aclass="header"href="#removal-of-deprecated-metrics--time-based-counters-becoming-histograms-in-0310">Removal of deprecated metrics & time based counters becoming histograms in 0.31.0</a></h2>
<p>The duplicated metrics deprecated in Synapse 0.27.0 have been removed.</p>
<p>All time duration-based metrics have been changed to be seconds. This
<h2id="block-and-response-metrics-renamed-for-0270"><aclass="header"href="#block-and-response-metrics-renamed-for-0270">Block and response metrics renamed for 0.27.0</a></h2>
<p>Synapse 0.27.0 begins the process of rationalising the duplicate
<code>*:count</code> metrics reported for the resource tracking for code blocks and
HTTP requests.</p>
<p>At the same time, the corresponding <code>*:total</code> metrics are being renamed,
as the <code>:total</code> suffix no longer makes sense in the absence of a
corresponding <code>:count</code> metric.</p>
<p>To enable a graceful migration path, this release just adds new names
for the metrics being renamed. A future release will remove the old
ones.</p>
<p>The following table shows the new metrics, and the old metrics which
<tr><td><code>homeserver</code></td><td>string</td><td>The homeserver's server name.</td></tr>
<tr><td><code>memory_rss</code></td><td>int</td><td>The memory usage of the process (in kilobytes on Unix-based systems, bytes on MacOS).</td></tr>
<tr><td><code>cpu_average</code></td><td>int</td><td>CPU time in % of a single core (not % of all cores).</td></tr>
<tr><td><code>server_context</code></td><td>string</td><td>An arbitrary string used to group statistics from a set of homeservers.</td></tr>
<tr><td><code>timestamp</code></td><td>int</td><td>The current time, represented as the number of seconds since the epoch.</td></tr>
<tr><td><code>uptime_seconds</code></td><td>int</td><td>The number of seconds since the homeserver was last started.</td></tr>
<tr><td><code>python_version</code></td><td>string</td><td>The Python version number in use (e.g "3.7.1"). Taken from <code>sys.version_info</code>.</td></tr>
<tr><td><code>total_users</code></td><td>int</td><td>The number of registered users on the homeserver.</td></tr>
<tr><td><code>total_nonbridged_users</code></td><td>int</td><td>The number of users, excluding those created by an Application Service.</td></tr>
<tr><td><code>daily_user_type_native</code></td><td>int</td><td>The number of native users created in the last 24 hours.</td></tr>
<tr><td><code>daily_user_type_guest</code></td><td>int</td><td>The number of guest users created in the last 24 hours.</td></tr>
<tr><td><code>daily_user_type_bridged</code></td><td>int</td><td>The number of users created by Application Services in the last 24 hours.</td></tr>
<tr><td><code>total_room_count</code></td><td>int</td><td>The total number of rooms present on the homeserver.</td></tr>
<tr><td><code>daily_active_users</code></td><td>int</td><td>The number of unique users<supclass="footnote-reference"><ahref="#1">1</a></sup> that have used the homeserver in the last 24 hours.</td></tr>
<tr><td><code>monthly_active_users</code></td><td>int</td><td>The number of unique users<supclass="footnote-reference"><ahref="#1">1</a></sup> that have used the homeserver in the last 30 days.</td></tr>
<tr><td><code>daily_active_rooms</code></td><td>int</td><td>The number of rooms that have had a (state) event with the type <code>m.room.message</code> sent in them in the last 24 hours.</td></tr>
<tr><td><code>daily_active_e2ee_rooms</code></td><td>int</td><td>The number of rooms that have had a (state) event with the type <code>m.room.encrypted</code> sent in them in the last 24 hours.</td></tr>
<tr><td><code>daily_messages</code></td><td>int</td><td>The number of (state) events with the type <code>m.room.message</code> seen in the last 24 hours.</td></tr>
<tr><td><code>daily_e2ee_messages</code></td><td>int</td><td>The number of (state) events with the type <code>m.room.encrypted</code> seen in the last 24 hours.</td></tr>
<tr><td><code>daily_sent_messages</code></td><td>int</td><td>The number of (state) events sent by a local user with the type <code>m.room.message</code> seen in the last 24 hours.</td></tr>
<tr><td><code>daily_sent_e2ee_messages</code></td><td>int</td><td>The number of (state) events sent by a local user with the type <code>m.room.encrypted</code> seen in the last 24 hours.</td></tr>
<tr><td><code>r30_users_all</code></td><td>int</td><td>The number of 30 day retained users, defined as users who have created their accounts more than 30 days ago, where they were last seen at most 30 days ago and where those two timestamps are over 30 days apart. Includes clients that do not fit into the below r30 client types.</td></tr>
<tr><td><code>r30_users_android</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "Android" in the user agent string.</td></tr>
<tr><td><code>r30_users_ios</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "iOS" in the user agent string.</td></tr>
<tr><td><code>r30_users_electron</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "Electron" in the user agent string.</td></tr>
<tr><td><code>r30_users_web</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "Mozilla" or "Gecko" in the user agent string.</td></tr>
<tr><td><code>r30v2_users_all</code></td><td>int</td><td>The number of 30 day retained users, with a revised algorithm. Defined as users that appear more than once in the past 60 days, and have more than 30 days between the most and least recent appearances in the past 60 days. Includes clients that do not fit into the below r30 client types.</td></tr>
<tr><td><code>r30v2_users_android</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "android" (case-insensitive) in the user agent string.</td></tr>
<tr><td><code>r30v2_users_ios</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "ios" (case-insensitive) in the user agent string.</td></tr>
<tr><td><code>r30v2_users_electron</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "electron" (case-insensitive) in the user agent string.</td></tr>
<tr><td><code>r30v2_users_web</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "mozilla" or "gecko" (case-insensitive) in the user agent string.</td></tr>
<tr><td><code>cache_factor</code></td><td>int</td><td>The configured <ahref="usage/administration/monitoring/../../configuration/config_documentation.html#caching"><code>global factor</code></a> value for caching.</td></tr>
<tr><td><code>event_cache_size</code></td><td>int</td><td>The configured <ahref="usage/administration/monitoring/../../configuration/config_documentation.html#caching"><code>event_cache_size</code></a> value for caching.</td></tr>
<tr><td><code>database_engine</code></td><td>string</td><td>The database engine that is in use. Either "psycopg2" meaning PostgreSQL is in use, or "sqlite3" for SQLite3.</td></tr>
<tr><td><code>database_server_version</code></td><td>string</td><td>The version of the database server. Examples being "10.10" for PostgreSQL server version 10.0, and "3.38.5" for SQLite 3.38.5 installed on the system.</td></tr>
<tr><td><code>log_level</code></td><td>string</td><td>The log level in use. Examples are "INFO", "WARNING", "ERROR", "DEBUG", etc.</td></tr>
<divstyle="break-before: page; page-break-before: always;"></div><h2id="understanding-synapse-through-grafana-graphs"><aclass="header"href="#understanding-synapse-through-grafana-graphs">Understanding Synapse through Grafana graphs</a></h2>
<p>It is possible to monitor much of the internal state of Synapse using <ahref="https://prometheus.io">Prometheus</a>
metrics and <ahref="https://grafana.com/">Grafana</a>.
A guide for configuring Synapse to provide metrics is available <ahref="usage/administration/../../metrics-howto.html">here</a>
and information on setting up Grafana is <ahref="https://github.com/matrix-org/synapse/tree/master/contrib/grafana">here</a>.
In this setup, Prometheus will periodically scrape the information Synapse provides and
store a record of it over time. Grafana is then used as an interface to query and
present this information through a series of pretty graphs.</p>
<p>Once you have grafana set up, and assuming you're using <ahref="https://github.com/matrix-org/synapse/blob/master/contrib/grafana/synapse.json">our grafana dashboard template</a>, look for the following graphs when debugging a slow/overloaded Synapse:</p>
<p>This, along with the CPU and Memory graphs, is a good way to check the general health of your Synapse instance. It represents how long it takes for a user on your homeserver to send a message.</p>
<h2id="transaction-count-and-transaction-duration"><aclass="header"href="#transaction-count-and-transaction-duration">Transaction Count and Transaction Duration</a></h2>
<p>These graphs show the database transactions that are occurring the most frequently, as well as those are that are taking the most amount of time to execute.</p>
<p>In the first graph, we can see obvious spikes corresponding to lots of <code>get_user_by_id</code> transactions. This would be useful information to figure out which part of the Synapse codebase is potentially creating a heavy load on the system. However, be sure to cross-reference this with Transaction Duration, which states that <code>get_users_by_id</code> is actually a very quick database transaction and isn't causing as much load as others, like <code>persist_events</code>:</p>
<p>Still, it's probably worth investigating why we're getting users from the database that often, and whether it's possible to reduce the amount of queries we make by adjusting our cache factor(s).</p>
<p>The <code>persist_events</code> transaction is responsible for saving new room events to the Synapse database, so can often show a high transaction duration.</p>
<p>The charts in the "Federation" section show information about incoming and outgoing federation requests. Federation data can be divided into two basic types:</p>
<ul>
<li>PDU (Persistent Data Unit) - room events: messages, state events (join/leave), etc. These are permanently stored in the database.</li>
<li>EDU (Ephemeral Data Unit) - other data, which need not be stored permanently, such as read receipts, typing notifications.</li>
</ul>
<p>The "Outgoing EDUs by type" chart shows the EDUs within outgoing federation requests by type: <code>m.device_list_update</code>, <code>m.direct_to_device</code>, <code>m.presence</code>, <code>m.receipt</code>, <code>m.typing</code>.</p>
<p>If you see a large number of <code>m.presence</code> EDUs and are having trouble with too much CPU load, you can disable <code>presence</code> in the Synapse config. See also <ahref="https://github.com/matrix-org/synapse/issues/3971">#3971</a>.</p>
<p>This is quite a useful graph. It shows how many times Synapse attempts to retrieve a piece of data from a cache which the cache did not contain, thus resulting in a call to the database. We can see here that the <code>_get_joined_profile_from_event_id</code> cache is being requested a lot, and often the data we're after is not cached.</p>
<p>Cross-referencing this with the Eviction Rate graph, which shows that entries are being evicted from <code>_get_joined_profile_from_event_id</code> quite often:</p>
<p>we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available <ahref="https://github.com/matrix-org/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642">here</a> (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage.</p>
<p>Forward extremities are the leaf events at the end of a DAG in a room, aka events that have no children. The more that exist in a room, the more <ahref="https://spec.matrix.org/v1.1/server-server-api/#room-state-resolution">state resolution</a> that Synapse needs to perform (hint: it's an expensive operation). While Synapse has code to prevent too many of these existing at one time in a room, bugs can sometimes make them crop up again.</p>
<p>If a room has >10 forward extremities, it's worth checking which room is the culprit and potentially removing them using the SQL queries mentioned in <ahref="https://github.com/matrix-org/synapse/issues/1760">#1760</a>.</p>
<h2id="show-top-20-larger-tables-by-row-count"><aclass="header"href="#show-top-20-larger-tables-by-row-count">Show top 20 larger tables by row count</a></h2>
<pre><codeclass="language-sql">SELECT relname, n_live_tup AS "rows"
FROM pg_stat_user_tables
ORDER BY n_live_tup DESC
LIMIT 20;
</code></pre>
<p>This query is quick, but may be very approximate, for exact number of rows use:</p>
<pre><codeclass="language-sql">SELECT COUNT(*) FROM <table_name>;
<h2id="show-top-20-larger-tables-by-storage-size"><aclass="header"href="#show-top-20-larger-tables-by-storage-size">Show top 20 larger tables by storage size</a></h2>
<pre><codeclass="language-sql">SELECT nspname || '.' || relname AS "relation",
pg_size_pretty(pg_total_relation_size(c.oid)) AS "total_size"
FROM pg_class c
LEFT JOIN pg_namespace n ON (n.oid = c.relnamespace)
WHERE nspname NOT IN ('pg_catalog', 'information_schema')
<h2id="show-top-20-larger-rooms-by-state-events-count"><aclass="header"href="#show-top-20-larger-rooms-by-state-events-count">Show top 20 larger rooms by state events count</a></h2>
<h2id="show-top-20-rooms-by-new-events-count-in-last-1-day"><aclass="header"href="#show-top-20-rooms-by-new-events-count-in-last-1-day">Show top 20 rooms by new events count in last 1 day:</a></h2>
<h2id="show-top-20-users-on-homeserver-by-sent-events-messages-at-last-month"><aclass="header"href="#show-top-20-users-on-homeserver-by-sent-events-messages-at-last-month">Show top 20 users on homeserver by sent events (messages) at last month:</a></h2>
<p>Caution. This query does not use any indexes, can be slow and create load on the database.</p>
<h2id="show-last-100-messages-from-needed-user-with-room-names"><aclass="header"href="#show-last-100-messages-from-needed-user-with-room-names">Show last 100 messages from needed user, with room names:</a></h2>
<h2id="show-rooms-with-names-sorted-by-events-in-this-rooms"><aclass="header"href="#show-rooms-with-names-sorted-by-events-in-this-rooms">Show rooms with names, sorted by events in this rooms</a></h2>
<p><strong>Sort and order with bash</strong></p>
<pre><codeclass="language-bash">echo "SELECT event_json.room_id, room_stats_state.name FROM event_json, room_stats_state \
<h2id="lookup-room-state-info-by-list-of-room_id"><aclass="header"href="#lookup-room-state-info-by-list-of-room_id">Lookup room state info by list of room_id</a></h2>
<h2id="show-users-and-devices-that-have-not-been-online-for-a-while"><aclass="header"href="#show-users-and-devices-that-have-not-been-online-for-a-while">Show users and devices that have not been online for a while</a></h2>
<pre><codeclass="language-sql">SELECT user_id, device_id, user_agent, TO_TIMESTAMP(last_seen / 1000) AS "last_seen"
<divstyle="break-before: page; page-break-before: always;"></div><p>This blog post by Victor Berger explains how to use many of the tools listed on this page: https://levans.fr/shrink-synapse-database.html</p>
<h1id="list-of-useful-tools-and-scripts-for-maintenance-synapse-database"><aclass="header"href="#list-of-useful-tools-and-scripts-for-maintenance-synapse-database">List of useful tools and scripts for maintenance Synapse database:</a></h1>
<h2id="purge-remote-media-api-1"><aclass="header"href="#purge-remote-media-api-1"><ahref="usage/administration/../../admin_api/media_admin_api.html#purge-remote-media-api">Purge Remote Media API</a></a></h2>
<p>The purge remote media API allows server admins to purge old cached remote media.</p>
<h2id="purge-local-media-api"><aclass="header"href="#purge-local-media-api"><ahref="usage/administration/../../admin_api/media_admin_api.html#delete-local-media">Purge Local Media API</a></a></h2>
<p>This API deletes the <em>local</em> media from the disk of your own server.</p>
<h2id="purge-history-api-1"><aclass="header"href="#purge-history-api-1"><ahref="usage/administration/../../admin_api/purge_history_api.html">Purge History API</a></a></h2>
<p>The purge history API allows server admins to purge historic events from their database, reclaiming disk space.</p>
<p>Tool for compressing (deduplicating) <code>state_groups_state</code> table.</p>
<h2id="sql-for-analyzing-synapse-postgresql-database-stats"><aclass="header"href="#sql-for-analyzing-synapse-postgresql-database-stats"><ahref="usage/administration/useful_sql_for_admins.html">SQL for analyzing Synapse PostgreSQL database stats</a></a></h2>
<p>Some easy SQL that reports useful stats about your Synapse database.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="how-do-state-groups-work"><aclass="header"href="#how-do-state-groups-work">How do State Groups work?</a></h1>
<p>As a general rule, I encourage people who want to understand the deepest darkest secrets of the database schema to drop by #synapse-dev:matrix.org and ask questions.</p>
<p>However, one question that comes up frequently is that of how "state groups" work, and why the <code>state_groups_state</code> table gets so big, so here's an attempt to answer that question.</p>
<p>We need to be able to relatively quickly calculate the state of a room at any point in that room's history. In other words, we need to know the state of the room at each event in that room. This is done as follows:</p>
<p>A sequence of events where the state is the same are grouped together into a <code>state_group</code>; the mapping is recorded in <code>event_to_state_groups</code>. (Technically speaking, since a state event usually changes the state in the room, we are recording the state of the room <em>after</em> the given event id: which is to say, to a handwavey simplification, the first event in a state group is normally a state event, and others in the same state group are normally non-state-events.)</p>
<p><code>state_groups</code> records, for each state group, the id of the room that we're looking at, and also the id of the first event in that group. (I'm not sure if that event id is used much in practice.) </p>
<p>Now, if we stored all the room state for each <code>state_group</code>, that would be a huge amount of data. Instead, for each state group, we normally store the difference between the state in that group and some other state group, and only occasionally (every 100 state changes or so) record the full state.</p>
<p>So, most state groups have an entry in <code>state_group_edges</code> (don't ask me why it's not a column in <code>state_groups</code>) which records the previous state group in the room, and <code>state_groups_state</code> records the differences in state since that previous state group.</p>
<p>A full state group just records the event id for each piece of state in the room at that point.</p>
<h2id="known-bugs-with-state-groups"><aclass="header"href="#known-bugs-with-state-groups">Known bugs with state groups</a></h2>
<p>There are various reasons that we can end up creating many more state groups than we need: see https://github.com/matrix-org/synapse/issues/3364 for more details.</p>
<p>There is a tool at https://github.com/matrix-org/rust-synapse-compress-state which can compress the <code>state_groups_state</code> on a room by-room basis (essentially, it reduces the number of "full" state groups). This can result in dramatic reductions of the storage used.</p>
<tr><td>AAAA</td><td>Timestamp request was logged (not recieved)</td></tr>
<tr><td>BBBB</td><td>Logger name (<code>synapse.access.(http\|https).<tag></code>, where 'tag' is defined in the <code>listeners</code> config section, normally the port)</td></tr>
<tr><td>CCCC</td><td>Line number in code</td></tr>
<tr><td>DDDD</td><td>Log Level</td></tr>
<tr><td>EEEE</td><td>Request Identifier (This identifier is shared by related log lines)</td></tr>
<tr><td>FFFF</td><td>Source IP (Or X-Forwarded-For if enabled)</td></tr>
<tr><td>GGGG</td><td>Server Port</td></tr>
<tr><td>HHHH</td><td>Federated Server or Local User making request (blank if unauthenticated or not supplied)</td></tr>
<tr><td>IIII</td><td>Total Time to process the request</td></tr>
<tr><td>JJJJ</td><td>Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)</td></tr>
<tr><td>KKKK</td><td>Userland CPU time</td></tr>
<tr><td>LLLL</td><td>System CPU time</td></tr>
<tr><td>MMMM</td><td>Total time waiting for a free DB connection from the pool across all parallel DB work from this request</td></tr>
<tr><td>NNNN</td><td>Total time waiting for response to DB queries across all parallel DB work from this request</td></tr>
<tr><td>OOOO</td><td>Count of DB transactions performed</td></tr>
<tr><td>PPPP</td><td>Response body size</td></tr>
<tr><td>QQQQ</td><td>Response status code<br/>Suffixed with <code>!</code> if the socket was closed before the response was generated.<br/>A <code>499!</code> status code indicates that Synapse also cancelled request processing after the socket was closed.<br/></td></tr>
<tr><td>RRRR</td><td>Request</td></tr>
<tr><td>SSSS</td><td>User-agent</td></tr>
<tr><td>TTTT</td><td>Events fetched from DB to service this request (note that this does not include events fetched from the cache)</td></tr>
</tbody></table>
<p>MMMM / NNNN can be greater than IIII if there are multiple slow database queries
running in parallel.</p>
<p>Some actions can result in multiple identical http requests, which will return
the same data, but only the first request will report time/transactions in
<code>KKKK</code>/<code>LLLL</code>/<code>MMMM</code>/<code>NNNN</code>/<code>OOOO</code> - the others will be awaiting the first query to return a
response and will simultaneously return with the first request, but with very
<h2id="how-do-i-become-a-server-admin"><aclass="header"href="#how-do-i-become-a-server-admin">How do I become a server admin?</a></h2>
<p>If your server already has an admin account you should use the <ahref="usage/administration/../../admin_api/user_admin_api.html#Change-whether-a-user-is-a-server-administrator-or-not">User Admin API</a> to promote other accounts to become admins.</p>
<p>If you don't have any admin accounts yet you won't be able to use the admin API, so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account: use the admin APIs to make further changes.</p>
<pre><codeclass="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
</code></pre>
<h2id="what-servers-are-my-server-talking-to"><aclass="header"href="#what-servers-are-my-server-talking-to">What servers are my server talking to?</a></h2>
<p>Run this sql query on your db:</p>
<pre><codeclass="language-sql">SELECT * FROM destinations;
</code></pre>
<h2id="what-servers-are-currently-participating-in-this-room"><aclass="header"href="#what-servers-are-currently-participating-in-this-room">What servers are currently participating in this room?</a></h2>
INNER JOIN room_memberships AS m USING (room_id, event_id)
WHERE room_id = '!cURbafjkfsMDVwdRDQ:matrix.org' AND membership = 'join';
</code></pre>
<h2id="what-users-are-registered-on-my-server"><aclass="header"href="#what-users-are-registered-on-my-server">What users are registered on my server?</a></h2>
<pre><codeclass="language-sql">SELECT NAME from users;
<p>Users can reset their password through their client. Alternatively, a server admin
can reset a user's password using the <ahref="usage/administration/../../admin_api/user_admin_api.html#reset-password">admin API</a>.</p>
<h2id="i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again"><aclass="header"href="#i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again">I have a problem with my server. Can I just delete my database and start again?</a></h2>
<p>Deleting your database is unlikely to make anything better. </p>
<p>It's easy to make the mistake of thinking that you can start again from a clean slate by dropping your database, but things don't work like that in a federated network: lots of other servers have information about your server.</p>
<p>For example: other servers might think that you are in a room, your server will think that you are not, and you'll probably be unable to interact with that room in a sensible way ever again.</p>
<p>In general, there are better solutions to any problem than dropping the database. Come and seek help in https://matrix.to/#/#synapse:matrix.org.</p>
<p>There are two exceptions when it might be sensible to delete your database and start again:</p>
<ul>
<li>You have <em>never</em> joined any rooms which are federated with other servers. For instance, a local deployment which the outside world can't talk to. </li>
<li>You are changing the <code>server_name</code> in the homeserver configuration. In effect this makes your server a completely new one from the point of view of the network, so in this case it makes sense to start with a clean database.
(In both cases you probably also want to clear out the media_store.)</li>
</ul>
<h2id="ive-stuffed-up-access-to-my-room-how-can-i-delete-it-to-free-up-the-alias"><aclass="header"href="#ive-stuffed-up-access-to-my-room-how-can-i-delete-it-to-free-up-the-alias">I've stuffed up access to my room, how can I delete it to free up the alias?</a></h2>
<p><code><access-token></code> - can be obtained in riot by looking in the riot settings, down the bottom is:
Access Token:<click to reveal></p>
<p><code><room-alias></code> - the room alias, eg. #my_room:matrix.org this possibly needs to be URL encoded also, for example %23my_room%3Amatrix.org</p>
<h2id="how-can-i-find-the-lines-corresponding-to-a-given-http-request-in-my-homeserver-log"><aclass="header"href="#how-can-i-find-the-lines-corresponding-to-a-given-http-request-in-my-homeserver-log">How can I find the lines corresponding to a given HTTP request in my homeserver log?</a></h2>
<p>Synapse tags each log line according to the HTTP request it is processing. When it finishes processing each request, it logs a line containing the words <code>Processed request: </code>. For example:</p>
<p>Here we can see that the request has been tagged with <code>GET-37</code>. (The tag depends on the method of the HTTP request, so might start with <code>GET-</code>, <code>PUT-</code>, <code>POST-</code>, <code>OPTIONS-</code> or <code>DELETE-</code>.) So to find all lines corresponding to this request, we can do:</p>
<pre><code>grep 'GET-37' homeserver.log
</code></pre>
<p>If you want to paste that output into a github issue or matrix room, please remember to surround it with triple-backticks (```) to make it legible (see https://help.github.com/en/articles/basic-writing-and-formatting-syntax#quoting-code).</p>
<h2id="what-do-all-those-fields-in-the-processed-line-mean"><aclass="header"href="#what-do-all-those-fields-in-the-processed-line-mean">What do all those fields in the 'Processed' line mean?</a></h2>
<h2id="what-are-the-biggest-rooms-on-my-server"><aclass="header"href="#what-are-the-biggest-rooms-on-my-server">What are the biggest rooms on my server?</a></h2>
<pre><codeclass="language-sql">SELECT s.canonical_alias, g.room_id, count(*) AS num_rows
FROM
state_groups_state AS g,
room_stats_state AS s
WHERE g.room_id = s.room_id
GROUP BY s.canonical_alias, g.room_id
ORDER BY num_rows desc
LIMIT 10;
</code></pre>
<p>You can also use the <ahref="usage/administration/../../admin_api/rooms.html#list-room-api">List Room API</a>
and <code>order_by</code><code>state_events</code>.</p>
<h2id="people-cant-accept-room-invitations-from-me"><aclass="header"href="#people-cant-accept-room-invitations-from-me">People can't accept room invitations from me</a></h2>
<p>The typical failure mode here is that you send an invitation to someone
to join a room or direct chat, but when they go to accept it, they get an
error (typically along the lines of "Invalid signature"). They might see
something like the following in their logs:</p>
<pre><code>2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server <server> with key ed25519:a_EqML: Unable to verify signature for <server>
</code></pre>
<p>This is normally caused by a misconfiguration in your reverse-proxy. See <ahref="usage/administration/docs/reverse_proxy.html">the reverse proxy docs</a> and double-check that your settings are correct.</p>
<h2id="help-synapse-is-slow-and-eats-all-my-ramcpu"><aclass="header"href="#help-synapse-is-slow-and-eats-all-my-ramcpu">Help!! Synapse is slow and eats all my RAM/CPU!</a></h2>
<p>First, ensure you are running the latest version of Synapse, using Python 3
with a <ahref="usage/administration/../../postgres.html">PostgreSQL database</a>.</p>
<p>Synapse's architecture is quite RAM hungry currently - we deliberately
cache a lot of recent room data and metadata in RAM in order to speed up
common requests. We'll improve this in the future, but for now the easiest
way to either reduce the RAM usage (at the risk of slowing things down)
is to set the almost-undocumented <code>SYNAPSE_CACHE_FACTOR</code> environment
variable. The default is 0.5, which can be decreased to reduce RAM usage
in memory constrained environments, or increased if performance starts to
degrade.</p>
<p>However, degraded performance due to a low cache factor, common on
machines with slow disks, often leads to explosions in memory use due
backlogged requests. In this case, reducing the cache factor will make
things worse. Instead, try increasing it drastically. 2.0 is a good
starting value.</p>
<p>Using <ahref="https://jemalloc.net">libjemalloc</a> can also yield a significant
improvement in overall memory use, and especially in terms of giving back
RAM to the OS. To use it, the library must simply be put in the
LD_PRELOAD environment variable when launching Synapse. On Debian, this
can be done by installing the <code>libjemalloc1</code> package and adding this
line to <code>/etc/default/matrix-synapse</code>:</p>
<p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <ahref="https://www.python.org/downloads/">a recent version of Python 3</a>. Your Python also needs support for <ahref="https://docs.python.org/3/library/venv.html">virtual environments</a>. This is usually built-in, but some Linux distributions like Debian and Ubuntu split it out into its own package. Running <code>sudo apt install python3-venv</code> should be enough.</p>
<p>Synapse can connect to PostgreSQL via the <ahref="https://pypi.org/project/psycopg2/">psycopg2</a> Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with <code>sudo apt install libpq-dev</code>.</p>
<p>The source code of Synapse is hosted on GitHub. You will also need <ahref="https://github.com/git-guides/install-git">a recent version of git</a>.</p>
<p>For some tests, you will need <ahref="https://docs.docker.com/get-docker/">a recent version of Docker</a>.</p>
<h1id="3-get-the-source"><aclass="header"href="#3-get-the-source">3. Get the source.</a></h1>
<p>The preferred and easiest way to contribute changes is to fork the relevant
project on GitHub, and then <ahref="https://help.github.com/articles/using-pull-requests/">create a pull request</a> to ask us to pull your
changes into our repo.</p>
<p>Please base your changes on the <code>develop</code> branch.</p>
<p>This will install the runtime and developer dependencies for the project.</p>
<h1id="5-get-in-touch"><aclass="header"href="#5-get-in-touch">5. Get in touch.</a></h1>
<p>Join our developer community on Matrix: <ahref="https://matrix.to/#/#synapse-dev:matrix.org">#synapse-dev:matrix.org</a>!</p>
<h1id="6-pick-an-issue"><aclass="header"href="#6-pick-an-issue">6. Pick an issue.</a></h1>
<p>Fix your favorite problem or perhaps find a <ahref="https://github.com/matrix-org/synapse/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22">Good First Issue</a>
to work on.</p>
<h1id="7-turn-coffee-into-code-and-documentation"><aclass="header"href="#7-turn-coffee-into-code-and-documentation">7. Turn coffee into code and documentation!</a></h1>
<p>There is a growing amount of documentation located in the
<p>While you're developing and before submitting a patch, you'll
want to test your code.</p>
<h2id="run-the-linters"><aclass="header"href="#run-the-linters">Run the linters.</a></h2>
<p>The linters look at your code and do two things:</p>
<ul>
<li>ensure that your code follows the coding style adopted by the project;</li>
<li>catch a number of errors in your code.</li>
</ul>
<p>The linter takes no time at all to run as soon as you've <ahref="development/contributing_guide.html#4-install-the-dependencies">downloaded the dependencies</a>.</p>
<pre><codeclass="language-sh">poetry run ./scripts-dev/lint.sh
</code></pre>
<p>Note that this script <em>will modify your files</em> to fix styling errors.
Make sure that you have saved all your files.</p>
<p>If you wish to restrict the linters to only the files changed since the last commit
(much faster!), you can instead run:</p>
<pre><codeclass="language-sh">poetry run ./scripts-dev/lint.sh -d
</code></pre>
<p>Or if you know exactly which files you wish to lint, you can instead run:</p>
<pre><codeclass="language-sh">poetry run ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
</code></pre>
<h2id="run-the-unit-tests-twisted-trial"><aclass="header"href="#run-the-unit-tests-twisted-trial">Run the unit tests (Twisted trial).</a></h2>
<p>The unit tests run parts of Synapse, including your changes, to see if anything
was broken. They are slower than the linters but will typically catch more errors.</p>
<pre><codeclass="language-sh">poetry run trial tests
</code></pre>
<p>If you wish to only run <em>some</em> unit tests, you may specify
another module instead of <code>tests</code> - or a test class or a method:</p>
<pre><codeclass="language-sh">poetry run trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
</code></pre>
<p>If your tests fail, you may wish to look at the logs (the default log level is <code>ERROR</code>):</p>
<pre><code>docker: Error response from daemon: driver failed programming external connectivity on endpoint nice_ride (b57bbe2e251b70015518d00c9981e8cb8346b5c785250341a6c53e3c899875f1): Error starting userland proxy: listen tcp4 0.0.0.0:5432: bind: address already in use.
</code></pre>
<p>then something is already bound to port 5432. You're probably already running postgres locally.</p>
<p>Once you have a postgres server running, invoke <code>trial</code> in a second terminal:</p>
<pre><codeclass="language-shell">SYNAPSE_POSTGRES=1 SYNAPSE_POSTGRES_HOST=127.0.0.1 SYNAPSE_POSTGRES_USER=postgres SYNAPSE_POSTGRES_PASSWORD=mysecretpassword poetry run trial tests
</code></pre>
<h4id="using-an-existing-postgres-installation"><aclass="header"href="#using-an-existing-postgres-installation">Using an existing Postgres installation</a></h4>
<p>If you have postgres already installed on your system, you can run <code>trial</code> with the
following environment variables matching your configuration:</p>
<ul>
<li><code>SYNAPSE_POSTGRES</code> to anything nonempty</li>
<li><code>SYNAPSE_POSTGRES_HOST</code> (optional if it's the default: UNIX socket)</li>
<li><code>SYNAPSE_POSTGRES_PORT</code> (optional if it's the default: 5432)</li>
<li><code>SYNAPSE_POSTGRES_USER</code> (optional if using a UNIX socket)</li>
<li><code>SYNAPSE_POSTGRES_PASSWORD</code> (optional if using a UNIX socket)</li>
<p>You don't need to specify the host, user, port or password if your Postgres
server is set to authenticate you over the UNIX socket (i.e. if the <code>psql</code> command
works without further arguments).</p>
<p>Your Postgres account needs to be able to create databases; see the postgres
docs for <ahref="https://www.postgresql.org/docs/current/sql-alterrole.html"><code>ALTER ROLE</code></a>.</p>
<h2id="run-the-integration-tests-sytest"><aclass="header"href="#run-the-integration-tests-sytest">Run the integration tests (<ahref="https://github.com/matrix-org/sytest">Sytest</a>).</a></h2>
<p>The integration tests are a more comprehensive suite of tests. They
run a full version of Synapse, including your changes, to check if
anything was broken. They are slower than the unit tests but will
typically catch more errors.</p>
<p>The following command will let you run the integration test with the most common
configuration:</p>
<pre><codeclass="language-sh">$ docker run --rm -it -v /path/where/you/have/cloned/the/repository\:/src:ro -v /path/to/where/you/want/logs\:/logs matrixdotorg/sytest-synapse:buster
</code></pre>
<p>(Note that the paths must be full paths! You could also write <code>$(realpath relative/path)</code> if needed.)</p>
<p>This configuration should generally cover your needs.</p>
<ul>
<li>To run with Postgres, supply the <code>-e POSTGRES=1 -e MULTI_POSTGRES=1</code> environment flags.</li>
<li>To run with Synapse in worker mode, supply the <code>-e WORKERS=1 -e REDIS=1</code> environment flags (in addition to the Postgres flags).</li>
</ul>
<p>For more details about other configurations, see the <ahref="https://github.com/matrix-org/sytest/blob/develop/docker/README.md">Docker-specific documentation in the SyTest repo</a>.</p>
<h2id="run-the-integration-tests-complement"><aclass="header"href="#run-the-integration-tests-complement">Run the integration tests (<ahref="https://github.com/matrix-org/complement">Complement</a>).</a></h2>
<p><ahref="https://github.com/matrix-org/complement">Complement</a> is a suite of black box tests that can be run on any homeserver implementation. It can also be thought of as end-to-end (e2e) tests.</p>
<p>It's often nice to develop on Synapse and write Complement tests at the same time.
Here is how to run your local Synapse checkout against your local Complement checkout.</p>
<p>(checkout <ahref="https://github.com/matrix-org/complement"><code>complement</code></a> alongside your <code>synapse</code> checkout)</p>
<p>To run a specific test file, you can pass the test name at the end of the command. The name passed comes from the naming structure in your Complement tests. If you're unsure of the name, you can do a full run and copy it from the test output:</p>
<h3id="prettier-formatting-with-gotestfmt"><aclass="header"href="#prettier-formatting-with-gotestfmt">Prettier formatting with <code>gotestfmt</code></a></h3>
<p>If you want to format the output of the tests the same way as it looks in CI,
<p>(Remove <code>-hide successful-tests</code> if you don't want to hide successful tests.)</p>
<h3id="access-database-for-homeserver-after-complement-test-runs"><aclass="header"href="#access-database-for-homeserver-after-complement-test-runs">Access database for homeserver after Complement test runs.</a></h3>
<p>If you're curious what the database looks like after you run some tests, here are some steps to get you going in Synapse:</p>
<ol>
<li>In your Complement test comment out <code>defer deployment.Destroy(t)</code> and replace with <code>defer time.Sleep(2 * time.Hour)</code> to keep the homeserver running after the tests complete</li>
<li>Start the Complement tests</li>
<li>Find the name of the container, <code>docker ps -f name=complement_</code> (this will filter for just the Compelement related Docker containers)</li>
<li>Access the container replacing the name with what you found in the previous step: <code>docker exec -it complement_1_hs_with_application_service.hs1_2 /bin/bash</code></li>
<li>Then run <code>sqlite3</code> and open the database <code>.open /conf/homeserver.db</code> (this db path comes from the Synapse homeserver.yaml)</li>
</ol>
<h1id="9-submit-your-patch"><aclass="header"href="#9-submit-your-patch">9. Submit your patch.</a></h1>
<p>Once you're happy with your patch, it's time to prepare a Pull Request.</p>
<p>To prepare a Pull Request, please:</p>
<ol>
<li>verify that <ahref="development/contributing_guide.html#test-test-test">all the tests pass</a>, including the coding style;</li>
<li><ahref="development/contributing_guide.html#sign-off">sign off</a> your contribution;</li>
<li><code>git push</code> your commit to your fork of Synapse;</li>
<li>on GitHub, <ahref="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request">create the Pull Request</a>;</li>
<li>add a <ahref="development/contributing_guide.html#changelog">changelog entry</a> and push it to your Pull Request;</li>
<li>that's it for now, a non-draft pull request will automatically request review from the team;</li>
<li>if you need to update your PR, please avoid rebasing and just add new commits to your branch.</li>
<p>This file will become part of our <ahref="https://github.com/matrix-org/synapse/blob/master/CHANGES.md">changelog</a> at the next
release, so the content of the file should be a short description of your
change in the same style as the rest of the changelog. The file can contain Markdown
formatting, and should end with a full stop (.) or an exclamation mark (!) for
consistency.</p>
<p>Adding credits to the changelog is encouraged, we value your
contributions and would like to have you shouted out in the release notes!</p>
<p>For example, a fix in PR #1234 would have its changelog entry in
<code>changelog.d/1234.bugfix</code>, and contain content like:</p>
<blockquote>
<p>The security levels of Florbs are now validated when received
via the <code>/federation/florb</code> endpoint. Contributed by Jane Matrix.</p>
</blockquote>
<p>If there are multiple pull requests involved in a single bugfix/feature/etc,
then the content for each <code>changelog.d</code> file should be the same. Towncrier will
merge the matching files together into a single changelog entry when we come to
release.</p>
<h3id="how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr"><aclass="header"href="#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr">How do I know what to call the changelog file before I create the PR?</a></h3>
<p>Obviously, you don't know if you should call your newsfile
<code>1234.bugfix</code> or <code>5678.bugfix</code> until you create the PR, which leads to a
chicken-and-egg problem.</p>
<p>There are two options for solving this:</p>
<ol>
<li>
<p>Open the PR without a changelog file, see what number you got, and <em>then</em>
add the changelog file to your branch (see <ahref="development/contributing_guide.html#updating-your-pull-request">Updating your pull
request</a>), or:</p>
</li>
<li>
<p>Look at the <ahref="https://github.com/matrix-org/synapse/issues?q=">list of all
issues/PRs</a>, add one to the
highest number you see, and quickly open the PR before somebody else claims
It helps to include "sign off" or similar in the subject line. You will then
be instructed further.</p>
<p>Once private sign off is complete, doing so for future contributions will not
be required.</p>
<h1id="10-turn-feedback-into-better-code"><aclass="header"href="#10-turn-feedback-into-better-code">10. Turn feedback into better code.</a></h1>
<p>Once the Pull Request is opened, you will see a few things:</p>
<ol>
<li>our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests and more;</li>
<li>one or more of the developers will take a look at your Pull Request and offer feedback.</li>
</ol>
<p>From this point, you should:</p>
<ol>
<li>Look at the results of the CI pipeline.
<ul>
<li>If there is any error, fix the error.</li>
</ul>
</li>
<li>If a developer has requested changes, make these changes and let us know if it is ready for a developer to review again.
<ul>
<li>A pull request is a conversation, if you disagree with the suggestions, please respond and discuss it.</li>
</ul>
</li>
<li>Create a new commit with the changes.
<ul>
<li>Please do NOT overwrite the history. New commits make the reviewer's life easier.</li>
<li>Push this commits to your Pull Request.</li>
</ul>
</li>
<li>Back to 1.</li>
<li>Once the pull request is ready for review again please re-request review from whichever developer did your initial
review (or leave a comment in the pull request that you believe all required changes have been done).</li>
</ol>
<p>Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly!</p>
<h1id="11-find-a-new-issue"><aclass="header"href="#11-find-a-new-issue">11. Find a new issue.</a></h1>
<p>By now, you know the drill!</p>
<h1id="notes-for-maintainers-on-merging-prs-etc"><aclass="header"href="#notes-for-maintainers-on-merging-prs-etc">Notes for maintainers on merging PRs etc</a></h1>
<p>There are some notes for those with commit access to the project on how we
<h2id="configuration-code-and-documentation-format"><aclass="header"href="#configuration-code-and-documentation-format">Configuration code and documentation format</a></h2>
<p>When adding a configuration option to the code, if several settings are grouped into a single dict, ensure that your code
correctly handles the top-level option being set to <code>None</code> (as it will be if no sub-options are enabled).</p>
<p>The <ahref="usage/configuration/config_documentation.html">configuration manual</a> acts as a
reference to Synapse's configuration options for server administrators.
Remember that many readers will be unfamiliar with YAML and server
administration in general, so it is important that when you add
a configuration option the documentation be as easy to understand as possible, which
includes following a consistent format.</p>
<p>Some guidelines follow:</p>
<ul>
<li>
<p>Each option should be listed in the config manual with the following format:</p>
<ul>
<li>
<p>The name of the option, prefixed by <code>###</code>. </p>
</li>
<li>
<p>A comment which describes the default behaviour (i.e. what
happens if the setting is omitted), as well as what the effect
will be if the setting is changed.</p>
</li>
<li>
<p>An example setting, using backticks to define the code block</p>
<p>For boolean (on/off) options, convention is that this example
should be the <em>opposite</em> to the default. For other options, the example should give
some non-default value which is likely to be useful to the reader.</p>
</li>
</ul>
</li>
<li>
<p>There should be a horizontal rule between each option, which can be achieved by adding <code>---</code> before and
after the option.</p>
</li>
<li>
<p><code>true</code> and <code>false</code> are spelt thus (as opposed to <code>True</code>, etc.)</p>
<p>Use the <code>module</code> sub-option to add a module under <code>modules</code> to extend functionality.
The <code>module</code> setting then has a sub-option, <code>config</code>, which can be used to define some configuration
for the <code>module</code>.</p>
<p>Defaults to none.</p>
<p>Example configuration:</p>
<pre><codeclass="language-yaml">modules:
- module: my_super_module.MySuperClass
config:
do_thing: true
- module: my_other_super_module.SomeClass
config: {}
</code></pre>
<hr/>
<p>Note that the sample configuration is generated from the synapse code
and is maintained by a script, <code>scripts-dev/generate_sample_config.sh</code>.
Making sure that the output from this script matches the desired format
is left as an exercise for the reader!</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="some-notes-on-how-we-do-reviews"><aclass="header"href="#some-notes-on-how-we-do-reviews">Some notes on how we do reviews</a></h1>
<p>The Synapse team works off a shared review queue -- any new pull requests for
Synapse (or related projects) has a review requested from the entire team. Team
members should process this queue using the following rules:</p>
<ul>
<li>Any high urgency pull requests (e.g. fixes for broken continuous integration
or fixes for release blockers);</li>
<li>Follow-up reviews for pull requests which have previously received reviews;</li>
<li>Any remaining pull requests.</li>
</ul>
<p>For the latter two categories above, older pull requests should be prioritised.</p>
<p>It is explicit that there is no priority given to pull requests from the team
(vs from the community). If a pull request requires a quick turn around, please
explicitly communicate this via <ahref="https://matrix.to/#/#synapse-dev:matrix.org">#synapse-dev:matrix.org</a>
or as a comment on the pull request.</p>
<p>Once an initial review has been completed and the author has made additional changes,
follow-up reviews should go back to the same reviewer. This helps build a shared
context and conversation between author and reviewer.</p>
<p>As a team we aim to keep the number of inflight pull requests to a minimum to ensure
that ongoing work is finished before starting new work.</p>
<h2id="performing-a-review"><aclass="header"href="#performing-a-review">Performing a review</a></h2>
<p>To communicate to the rest of the team the status of each pull request, team
members should do the following:</p>
<ul>
<li>Assign themselves to the pull request (they should be left assigned to the
pull request until it is merged, closed, or are no longer the reviewer);</li>
<li>Review the pull request by leaving comments, questions, and suggestions;</li>
<li>Mark the pull request appropriately (as needing changes or accepted).</li>
</ul>
<p>If you are unsure about a particular part of the pull request (or are not confident
in your understanding of part of the code) then ask questions or request review
from the team again. When requesting review from the team be sure to leave a comment
with the rationale on why you're putting it back in the queue.</p>
<p>Security will sometimes be backported to the previous version and released
immediately before the next release candidate. An example of this might be:</p>
<ul>
<li>Day 0: Synapse N - 1 is released.</li>
<li>Day 7: Synapse (N - 1).1 is released as Synapse N - 1 + the security fix.</li>
<li>Day 7: Synapse N release candidate 1 is released (including the security fix).</li>
</ul>
<p>Depending on the impact and complexity of security fixes, multiple fixes might
be held to be released together.</p>
<p>In some cases, a pre-disclosure of a security release will be issued as a notice
to Synapse operators that there is an upcoming security release. These can be
found in the <ahref="https://matrix.org/blog/category/security">security category of the Matrix blog</a>.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="some-notes-on-how-we-use-git"><aclass="header"href="#some-notes-on-how-we-use-git">Some notes on how we use git</a></h1>
<h2id="on-keeping-the-commit-history-clean"><aclass="header"href="#on-keeping-the-commit-history-clean">On keeping the commit history clean</a></h2>
<p>In an ideal world, our git commit history would be a linear progression of
commits each of which contains a single change building on what came
before. Here, by way of an arbitrary example, is the top of <code>git log --graph b2dba0607</code>:</p>
<ahref="https://github.com/matrix-org/synapse/commit/836358823">“typo”</a>, or <ahref="https://github.com/matrix-org/synapse/commit/707374d5d">“Who's
the president?”</a>.</p>
<p>There are a number of reasons why keeping a clean commit history is a good
thing:</p>
<ul>
<li>
<p>From time to time, after a change lands, it turns out to be necessary to
revert it, or to backport it to a release branch. Those operations are
<em>much</em> easier when the change is contained in a single commit.</p>
</li>
<li>
<p>Similarly, it's much easier to answer questions like “is the fix for
<code>/publicRooms</code> on the release branch?” if that change consists of a single
commit.</p>
</li>
<li>
<p>Likewise: “what has changed on this branch in the last week?” is much
clearer without merges and “pep8” commits everywhere.</p>
</li>
<li>
<p>Sometimes we need to figure out where a bug got introduced, or some
behaviour changed. One way of doing that is with <code>git bisect</code>: pick an
arbitrary commit between the known good point and the known bad point, and
see how the code behaves. However, that strategy fails if the commit you
chose is the middle of someone's epic branch in which they broke the world
before putting it back together again.</p>
</li>
</ul>
<p>One counterargument is that it is sometimes useful to see how a PR evolved as
it went through review cycles. This is true, but that information is always
available via the GitHub UI (or via the little-known <ahref="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally">refs/pull
namespace</a>).</p>
<p>Of course, in reality, things are more complicated than that. We have release
branches as well as <code>develop</code> and <code>master</code>, and we deliberately merge changes
between them. Bugs often slip through and have to be fixed later. That's all
fine: this not a cast-iron rule which must be obeyed, but an ideal to aim
<p><strong>DO NOT USE THESE DEMO SERVERS IN PRODUCTION</strong></p>
<p>Requires you to have a <ahref="https://matrix-org.github.io/synapse/develop/development/contributing_guide.html#4-install-the-dependencies">Synapse development environment setup</a>.</p>
<p>The demo setup allows running three federation Synapse servers, with server
names <code>localhost:8480</code>, <code>localhost:8481</code>, and <code>localhost:8482</code>.</p>
<p>You can access them via any Matrix client over HTTP at <code>localhost:8080</code>,
<code>localhost:8081</code>, and <code>localhost:8082</code> or over HTTPS at <code>localhost:8480</code>,
<code>localhost:8481</code>, and <code>localhost:8482</code>.</p>
<p>To enable the servers to communicate, self-signed SSL certificates are generated
and the servers are configured in a highly insecure way, including:</p>
<ul>
<li>Not checking certificates over federation.</li>
<li>Not verifying keys.</li>
</ul>
<p>The servers are configured to store their data under <code>demo/8080</code>, <code>demo/8081</code>, and
<code>demo/8082</code>. This includes configuration, logs, SQLite databases, and media.</p>
<p>Note that when joining a public room on a different homeserver via "#foo:bar.net",
then you are (in the current implementation) joining a room with room_id "foo".
This means that it won't work if your homeserver already has a room with that
name.</p>
<h2id="using-the-demo-scripts"><aclass="header"href="#using-the-demo-scripts">Using the demo scripts</a></h2>
<p>There's three main scripts with straightforward purposes:</p>
<ul>
<li><code>start.sh</code> will start the Synapse servers, generating any missing configuration.
<ul>
<li>This accepts a single parameter <code>--no-rate-limit</code> to "disable" rate limits
(they actually still exist, but are very high).</li>
</ul>
</li>
<li><code>stop.sh</code> will stop the Synapse servers.</li>
<li><code>clean.sh</code> will delete the configuration, databases, log files, etc.</li>
</ul>
<p>To start a completely new set of servers, run:</p>
<h2id="enable-opentracing-in-synapse"><aclass="header"href="#enable-opentracing-in-synapse">Enable OpenTracing in Synapse</a></h2>
<p>OpenTracing is not enabled by default. It must be enabled in the
homeserver config by adding the <code>opentracing</code> option to your config file. You can find
documentation about how to do this in the <ahref="usage/configuration/config_documentation.html#opentracing">config manual under the header 'Opentracing'</a>.
See below for an example Opentracing configuration: </p>
<p>These should be named <code>*.sql</code>, or — for changes which should only be applied for a
given database engine — <code>*.sql.posgres</code> or <code>*.sql.sqlite</code>. For example, a delta which
adds a new column to the <code>foo</code> table might be called <code>01add_bar_to_foo.sql</code>.</p>
<p>Note that our SQL parser is a bit simple - it understands comments (<code>--</code> and <code>/*...*/</code>),
but complex statements which require a <code>;</code> in the middle of them (such as <code>CREATE TRIGGER</code>) are beyond it and you'll have to use a Python delta file.</p>
<p>Boolean columns require special treatment, since SQLite treats booleans the
same as integers.</p>
<p>There are three separate aspects to this:</p>
<ul>
<li>
<p>Any new boolean column must be added to the <code>BOOLEAN_COLUMNS</code> list in
<code>synapse/_scripts/synapse_port_db.py</code>. This tells the port script to cast
the integer value from SQLite to a boolean before writing the value to the
postgres database.</p>
</li>
<li>
<p>Before SQLite 3.23, <code>TRUE</code> and <code>FALSE</code> were not recognised as constants by
SQLite, and the <code>IS [NOT] TRUE</code>/<code>IS [NOT] FALSE</code> operators were not
supported. This makes it necessary to avoid using <code>TRUE</code> and <code>FALSE</code>
constants in SQL commands.</p>
<p>For example, to insert a <code>TRUE</code> value into the database, write:</p>
<pre><codeclass="language-python">txn.execute("INSERT INTO tbl(col) VALUES (?)", (True, ))
</code></pre>
</li>
<li>
<p>Default values for new boolean columns present a particular
difficulty. Generally it is best to create separate schema files for
Postgres and SQLite. For example:</p>
<pre><codeclass="language-sql"># in 00delta.sql.postgres:
ALTER TABLE tbl ADD COLUMN col BOOLEAN DEFAULT FALSE;
</code></pre>
<pre><codeclass="language-sql"># in 00delta.sql.sqlite:
ALTER TABLE tbl ADD COLUMN col BOOLEAN DEFAULT 0;
</code></pre>
<p>Note that there is a particularly insidious failure mode here: the Postgres
flavour will be accepted by SQLite 3.22, but will give a column whose
default value is the <strong>string</strong><code>"FALSE"</code> - which, when cast back to a boolean
in Python, evaluates to <code>True</code>.</p>
</li>
</ul>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="implementing-experimental-features-in-synapse"><aclass="header"href="#implementing-experimental-features-in-synapse">Implementing experimental features in Synapse</a></h1>
<p>It can be desirable to implement "experimental" features which are disabled by
default and must be explicitly enabled via the Synapse configuration. This is
applicable for features which:</p>
<ul>
<li>Are unstable in the Matrix spec (e.g. those defined by an MSC that has not yet been merged).</li>
<li>Developers are not confident in their use by general Synapse administrators/users
(e.g. a feature is incomplete, buggy, performs poorly, or needs further testing).</li>
</ul>
<p>Note that this only really applies to features which are expected to be desirable
to a broad audience. The <ahref="development/../modules/index.html">module infrastructure</a> should
instead be investigated for non-standard features.</p>
<p>Guarding experimental features behind configuration flags should help with some
of the following scenarios:</p>
<ul>
<li>Ensure that clients do not assume that unstable features exist (failing
gracefully if they do not).</li>
<li>Unstable features do not become de-facto standards and can be removed
aggressively (since only those who have opted-in will be affected).</li>
<li>Ease finding the implementation of unstable features in Synapse (for future
removal or stabilization).</li>
<li>Ease testing a feature (or removal of feature) due to enabling/disabling without
code changes. It also becomes possible to ask for wider testing, if desired.</li>
</ul>
<p>Experimental configuration flags should be disabled by default (requiring Synapse
administrators to explicitly opt-in), although there are situations where it makes
sense (from a product point-of-view) to enable features by default. This is
expected and not an issue.</p>
<p>It is not a requirement for experimental features to be behind a configuration flag,
but one should be used if unsure.</p>
<p>New experimental configuration flags should be added under the <code>experimental</code>
configuration key (see the <code>synapse.config.experimental</code> file) and either explain
(briefly) what is being enabled, or include the MSC number.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="managing-dependencies-with-poetry"><aclass="header"href="#managing-dependencies-with-poetry">Managing dependencies with Poetry</a></h1>
<p>This is a quick cheat sheet for developers on how to use <ahref="https://python-poetry.org/"><code>poetry</code></a>.</p>
<p>The locked dependencies get included in our "self-contained" releases: namely,
our docker images and our debian packages. We also use the locked dependencies
in development and our continuous integration.</p>
<p>Separately, our "broad" dependencies—the version ranges specified in
<code>pyproject.toml</code>—are included as metadata in our "sdists" and "wheels"<ahref="https://pypi.org/project/matrix-synapse">uploaded
to PyPI</a>. Installing from PyPI or from
the Synapse source tree directly will <em>not</em> use the locked dependencies; instead,
they'll pull in the latest version of each package available at install time.</p>
<li>Teach direnv about poetry. The <ahref="https://github.com/direnv/direnv/wiki/Python#poetry">shell config here</a>
needs to be added to <code>~/.config/direnv/direnvrc</code> (or more generally <code>$XDG_CONFIG_HOME/direnv/direnvrc</code>).</li>
<li>Mark the synapse checkout as a poetry project: <code>echo layout poetry > .envrc</code>.</li>
<li>Convince yourself that you trust this <code>.envrc</code> configuration and project.
Then formally confirm this to <code>direnv</code> by running <code>direnv allow</code>.</li>
</ol>
<p>Then whenever you navigate to the synapse checkout, you should be able to run
e.g. <code>mypy</code> instead of <code>poetry run mypy</code>; <code>python</code> instead of
<code>poetry run python</code>; and your shell commands will automatically run in the
context of poetry's venv, without having to run <code>poetry shell</code> beforehand.</p>
<h1id="how-do-i"><aclass="header"href="#how-do-i">How do I...</a></h1>
<h2id="reset-my-venv-to-the-locked-environment"><aclass="header"href="#reset-my-venv-to-the-locked-environment">...reset my venv to the locked environment?</a></h2>
<pre><codeclass="language-shell">poetry install --extras all --remove-untracked
</code></pre>
<h2id="run-a-command-in-the-poetry-virtualenv"><aclass="header"href="#run-a-command-in-the-poetry-virtualenv">...run a command in the <code>poetry</code> virtualenv?</a></h2>
<p>Use <code>poetry run cmd args</code> when you need the python virtualenv context.
To avoid typing <code>poetry run</code> all the time, you can run <code>poetry shell</code>
to start a new shell in the poetry virtualenv context. Within <code>poetry shell</code>,
<code>python</code>, <code>pip</code>, <code>mypy</code>, <code>trial</code>, etc. are all run inside the project virtualenv
and isolated from the rest o the system.</p>
<p>Roughly speaking, the translation from a traditional virtualenv is:</p>
<li><code>deactivate</code> -> close the terminal (Ctrl-D, <code>exit</code>, etc.)</li>
</ul>
<p>See also the direnv recommendation above, which makes <code>poetry run</code> and
<code>poetry shell</code> unnecessary.</p>
<h2id="inspect-the-poetry-virtualenv"><aclass="header"href="#inspect-the-poetry-virtualenv">...inspect the <code>poetry</code> virtualenv?</a></h2>
<p>Some suggestions:</p>
<pre><codeclass="language-shell"># Current env only
poetry env info
# All envs: this allows you to have e.g. a poetry managed venv for Python 3.7,
# and another for Python 3.10.
poetry env list --full-path
poetry run pip list
</code></pre>
<p>Note that <code>poetry show</code> describes the abstract <em>lock file</em> rather than your
on-disk environment. With that said, <code>poetry show --tree</code> can sometimes be
useful.</p>
<h2id="add-a-new-dependency"><aclass="header"href="#add-a-new-dependency">...add a new dependency?</a></h2>
<p>Either:</p>
<ul>
<li>manually update <code>pyproject.toml</code>; then <code>poetry lock --no-update</code>; or else</li>
<li><code>poetry add packagename</code>. See <code>poetry add --help</code>; note the <code>--dev</code>,
<code>--extras</code> and <code>--optional</code> flags in particular.
<ul>
<li><strong>NB</strong>: this specifies the new package with a version given by a "caret bound". This won't get forced to its lowest version in the old deps CI job: see <ahref="https://github.com/matrix-org/synapse/blob/4e1374373857f2f7a911a31c50476342d9070681/.ci/scripts/test_old_deps.sh#L35-L39">this TODO</a>.</li>
</ul>
</li>
</ul>
<p>Include the updated <code>pyproject.toml</code> and <code>poetry.lock</code> files in your commit.</p>
<h2id="remove-a-dependency"><aclass="header"href="#remove-a-dependency">...remove a dependency?</a></h2>
<p>This is not done often and is untested, but</p>
<p>ought to do the trick. Alternatively, manually update <code>pyproject.toml</code> and
<code>poetry lock --no-update</code>. Include the updated <code>pyproject.toml</code> and poetry.lock`
files in your commit.</p>
<h2id="update-the-version-range-for-an-existing-dependency"><aclass="header"href="#update-the-version-range-for-an-existing-dependency">...update the version range for an existing dependency?</a></h2>
<p>Best done by manually editing <code>pyproject.toml</code>, then <code>poetry lock --no-update</code>.
Include the updated <code>pyproject.toml</code> and <code>poetry.lock</code> in your commit.</p>
<h2id="update-a-dependency-in-the-locked-environment"><aclass="header"href="#update-a-dependency-in-the-locked-environment">...update a dependency in the locked environment?</a></h2>
<h2id="check-the-version-of-poetry-with-poetry---version"><aclass="header"href="#check-the-version-of-poetry-with-poetry---version">Check the version of poetry with <code>poetry --version</code>.</a></h2>
<p>At the time of writing, the 1.2 series is beta only. We have seen some examples
where the lockfiles generated by 1.2 prereleasese aren't interpreted correctly
by poetry 1.1.x. For now, use poetry 1.1.14, which includes a critical
<ahref="https://github.com/python-poetry/poetry/pull/5973">change</a> needed to remain
<ahref="https://github.com/pypi/warehouse/pull/11775">compatible with PyPI</a>.</p>
<p>It can also be useful to check the version of <code>poetry-core</code> in use. If you've
installed <code>poetry</code> with <code>pipx</code>, try <code>pipx runpip poetry list | grep poetry-core</code>.</p>
<p>Poetry caches a bunch of information about packages that isn't readily available
from PyPI. (This is what makes poetry seem slow when doing the first
<code>poetry install</code>.) Try <code>poetry cache list</code> and <code>poetry cache clear --all <name of cache></code> to see if that fixes things.</p>
<h2id="try---verbose-or---dry-run-arguments"><aclass="header"href="#try---verbose-or---dry-run-arguments">Try <code>--verbose</code> or <code>--dry-run</code> arguments.</a></h2>
<p>Sometimes useful to see what poetry's internal logic is.</p>
<p>Sometimes, requests take a long time to service and clients disconnect
before Synapse produces a response. To avoid wasting resources, Synapse
can cancel request processing for select endpoints marked with the
<code>@cancellable</code> decorator.</p>
<p>Synapse makes use of Twisted's <code>Deferred.cancel()</code> feature to make
cancellation work. The <code>@cancellable</code> decorator does nothing by itself
and merely acts as a flag, signalling to developers and other code alike
that a method can be cancelled.</p>
<h2id="enabling-cancellation-for-an-endpoint"><aclass="header"href="#enabling-cancellation-for-an-endpoint">Enabling cancellation for an endpoint</a></h2>
<ol>
<li>Check that the endpoint method, and any <code>async</code> functions in its call
<h3id="creation-of-deferreds"><aclass="header"href="#creation-of-deferreds">Creation of <code>Deferred</code>s</a></h3>
<p>If a function creates a <code>Deferred</code>, the effect of cancelling it must be considered. <code>Deferred</code>s that get shared are likely to have unintended behaviour when cancelled.</p>
<h2id="logcontexts-without-asynchronous-code"><aclass="header"href="#logcontexts-without-asynchronous-code">Logcontexts without asynchronous code</a></h2>
<p>In the absence of any asynchronous voodoo, things are simple enough. As with
any code of this nature, the rule is that our function should leave
things as it found them:</p>
<pre><codeclass="language-python">from synapse.logging import context # omitted from future snippets
<p>Provided this pattern is followed all the way back up to the callchain
to where the logcontext was set, this will make things work out ok:
provided <code>do_some_stuff</code> and <code>more_stuff</code> follow the rules above, then
so will <code>fun</code>.</p>
<p>It's all too easy to forget to <code>await</code>: for instance if we forgot that
<code>do_some_stuff</code> returned an awaitable, we might plough on regardless. This
leads to a mess; it will probably work itself out eventually, but not
before a load of stuff has been logged against the wrong context.
(Normally, other things will break, more obviously, if you forget to
<code>await</code>, so this tends not to be a major problem in practice.)</p>
<p>Of course sometimes you need to do something a bit fancier with your
awaitable - not all code follows the linear A-then-B-then-C pattern.
Notes on implementing more complex patterns are in later sections.</p>
<h2id="where-you-create-a-new-awaitable-make-it-follow-the-rules"><aclass="header"href="#where-you-create-a-new-awaitable-make-it-follow-the-rules">Where you create a new awaitable, make it follow the rules</a></h2>
<p>Most of the time, an awaitable comes from another synapse function.
Sometimes, though, we need to make up a new awaitable, or we get an awaitable
back from external code. We need to make it follow our rules.</p>
<p>The easy way to do it is by using <code>context.make_deferred_yieldable</code>. Suppose we want to implement
<code>sleep</code>, which returns a deferred which will run its callbacks after a
given number of seconds. That might look like:</p>
<pre><codeclass="language-python"># not a logcontext-rules-compliant function
def get_sleep_deferred(seconds):
d = defer.Deferred()
reactor.callLater(seconds, d.callback, None)
return d
</code></pre>
<p>That doesn't follow the rules, but we can fix it by calling it through
<p>This is really a variation of the fire-and-forget problem above, in that
we are firing off <code>a1</code> and <code>a2</code> without awaiting on them. The difference
is that we now have third-party code attached to their callbacks. Anyway
either technique given in the <ahref="log_contexts.html#fire-and-forget">Fire-and-forget</a>
section will work.</p>
<p>Of course, the new awaitable returned by <code>gather</code> needs to be
wrapped in order to make it follow the logcontext rules before we can
yield it, as described in <ahref="log_contexts.html#where-you-create-a-new-awaitable-make-it-follow-the-rules">Where you create a new awaitable, make it
follow the
rules</a>.</p>
<p>So, option one: reset the logcontext before starting the operations to
result = await make_deferred_yieldable(defer.gatherResults([a1, a2]))
</code></pre>
<h2id="a-note-on-garbage-collection-of-awaitable-chains"><aclass="header"href="#a-note-on-garbage-collection-of-awaitable-chains">A note on garbage-collection of awaitable chains</a></h2>
<p>It turns out that our logcontext rules do not play nicely with awaitable
chains which get orphaned and garbage-collected.</p>
<p>Imagine we have some code that looks like this:</p>
<p>This section covers implementation documentation for various parts of Synapse.</p>
<p>If a developer is planning to make a change to a feature of Synapse, it can be useful for
general documentation of how that feature is implemented to be available. This saves the
developer time in place of needing to understand how the feature works by reading the
code.</p>
<p>Documentation that would be more useful for the perspective of a system administrator,
rather than a developer who's intending to change to code, should instead be placed
under the Usage section of the documentation.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="how-to-test-saml-as-a-developer-without-a-server"><aclass="header"href="#how-to-test-saml-as-a-developer-without-a-server">How to test SAML as a developer without a server</a></h1>
<p>https://fujifish.github.io/samling/samling.html (https://github.com/fujifish/samling) is a great resource for being able to tinker with the
SAML options within Synapse without needing to deploy and configure a complicated software stack.</p>
<p>To make Synapse (and therefore Element) use it:</p>
<ol>
<li>Use the samling.html URL above or deploy your own and visit the IdP Metadata tab.</li>
<li>Copy the XML to your clipboard.</li>
<li>On your Synapse server, create a new file <code>samling.xml</code> next to your <code>homeserver.yaml</code> with
the XML from step 2 as the contents.</li>
<li>Edit your <code>homeserver.yaml</code> to include:
<pre><codeclass="language-yaml">saml2_config:
sp_config:
allow_unknown_attributes: true # Works around a bug with AVA Hashes: https://github.com/IdentityPython/pysaml2/issues/388
metadata:
local: ["samling.xml"]
</code></pre>
</li>
<li>Ensure that your <code>homeserver.yaml</code> has a setting for <code>public_baseurl</code>:
<p>If you try and repeat this process, you may be automatically logged in using the information you
gave previously. To fix this, open your developer console (<code>F12</code> or <code>Ctrl+Shift+I</code>) while on the
samling page and clear the site data. In Chrome, this will be a button on the Application tab.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="how-to-test-cas-as-a-developer-without-a-server"><aclass="header"href="#how-to-test-cas-as-a-developer-without-a-server">How to test CAS as a developer without a server</a></h1>
<p>The <ahref="https://github.com/jbittel/django-mama-cas">django-mama-cas</a> project is an
easy to run CAS implementation built on top of Django.</p>
<p>You should now have a Django project configured to serve CAS authentication with
a single user created.</p>
<h2id="configure-synapse-and-element-to-use-cas"><aclass="header"href="#configure-synapse-and-element-to-use-cas">Configure Synapse (and Element) to use CAS</a></h2>
<ol>
<li>Modify your <code>homeserver.yaml</code> to enable CAS and point it to your locally
running Django test server:
<pre><codeclass="language-yaml">cas_config:
enabled: true
server_url: "http://localhost:8000"
service_url: "http://localhost:8081"
#displayname_attribute: name
#required_attributes:
# name: value
</code></pre>
</li>
<li>Restart Synapse.</li>
</ol>
<p>Note that the above configuration assumes the homeserver is running on port 8081
and that the CAS server is on port 8000, both on localhost.</p>
<h2id="testing-the-configuration"><aclass="header"href="#testing-the-configuration">Testing the configuration</a></h2>
<p>Then in Element:</p>
<ol>
<li>Visit the login page with a Element pointing at your homeserver.</li>
<li>Click the Single Sign-On button.</li>
<li>Login using the credentials created with <code>createsuperuser</code>.</li>
<li>You should be logged in.</li>
</ol>
<p>If you want to repeat this process you'll need to manually logout first:</p>
<ol>
<li>http://localhost:8000/admin/</li>
<li>Click "logout" in the top right.</li>
</ol>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="room-dag-concepts"><aclass="header"href="#room-dag-concepts">Room DAG concepts</a></h1>
<p>The word "edge" comes from graph theory lingo. An edge is just a connection
between two events. In Synapse, we connect events by specifying their
<code>prev_events</code>. A subsequent event points back at a previous event.</p>
<pre><code>A (oldest) <---- B <---- C (most recent)
</code></pre>
<h2id="depth-and-stream-ordering"><aclass="header"href="#depth-and-stream-ordering">Depth and stream ordering</a></h2>
<p>Events are normally sorted by <code>(topological_ordering, stream_ordering)</code> where
<code>topological_ordering</code> is just <code>depth</code>. In other words, we first sort by <code>depth</code>
and then tie-break based on <code>stream_ordering</code>. <code>depth</code> is incremented as new
messages are added to the DAG. Normally, <code>stream_ordering</code> is an auto
incrementing integer, but backfilled events start with <code>stream_ordering=-1</code> and decrement.</p>
<hr/>
<ul>
<li><code>/sync</code> returns things in the order they arrive at the server (<code>stream_ordering</code>).</li>
<li><code>/messages</code> (and <code>/backfill</code> in the federation API) return them in the order determined by the event graph <code>(topological_ordering, stream_ordering)</code>.</li>
</ul>
<p>The general idea is that, if you're following a room in real-time (i.e.
<code>/sync</code>), you probably want to see the messages as they arrive at your server,
rather than skipping any that arrived late; whereas if you're looking at a
historical section of timeline (i.e. <code>/messages</code>), you want to see the best
representation of the state of the room as others were seeing it at the time.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="room-and-user-statistics"><aclass="header"href="#room-and-user-statistics">Room and User Statistics</a></h1>
<p>Synapse maintains room and user statistics in various tables. These can be used
for administrative purposes but are also used when generating the public room
<p>It is important for system admins to have a clear understanding of the platform
requirements of Synapse and its deprecation policies so that they can
effectively plan upgrading their infrastructure ahead of time. This is
especially important in contexts where upgrading the infrastructure requires
auditing and approval from a security team, or where otherwise upgrading is a
long process.</p>
<p>By following the upstream support life cycles Synapse can ensure that its
dependencies continue to get security patches, while not requiring system admins
to constantly update their platform dependencies to the latest versions.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h2id="summary-of-performance-impact-of-running-on-resource-constrained-devices-such-as-sbcs"><aclass="header"href="#summary-of-performance-impact-of-running-on-resource-constrained-devices-such-as-sbcs">Summary of performance impact of running on resource constrained devices such as SBCs</a></h2>
<p>I've been running my homeserver on a cubietruck at home now for some time and am often replying to statements like "you need loads of ram to join large rooms" with "it works fine for me". I thought it might be useful to curate a summary of the issues you're likely to run into to help as a scaling-down guide, maybe highlight these for development work or end up as documentation. It seems that once you get up to about 4x1.5GHz arm64 4GiB these issues are no longer a problem.</p>
<p>This is the main reason people have a poor matrix experience on resource constrained homeservers. Element web will frequently be saying the server is offline while the python process will be pegged at 100% cpu. This feature is used to tell when other users are active (have a client app in the foreground) and therefore more likely to respond, but requires a lot of network activity to maintain even when nobody is talking in a room.</p>
<p>While synapse does have some performance issues with presence <ahref="https://github.com/matrix-org/synapse/issues/3971">#3971</a>, the fundamental problem is that this is an easy feature to implement for a centralised service at nearly no overhead, but federation makes it combinatorial <ahref="https://github.com/matrix-org/synapse/issues/8055">#8055</a>. There is also a client-side config option which disables the UI and idle tracking <ahref="https://github.com/vector-im/element-web/blob/v1.7.8/config.sample.json#L45">enable_presence_by_hs_url</a> to blacklist the largest instances but I didn't notice much difference, so I recommend disabling the feature entirely at the server level as well.</p>
<p>Joining a "large", federated room will initially fail with the below message in Element web, but waiting a while (10-60mins) and trying again will succeed without any issue. What counts as "large" is not message history, user count, connections to homeservers or even a simple count of the state events, it is instead how long the state resolution algorithm takes. However, each of those numbers are reasonable proxies, so we can use them as estimates since user count is one of the few things you see before joining.</p>
<p>This is <ahref="https://github.com/matrix-org/synapse/issues/1211">#1211</a> and will also hopefully be mitigated by peeking <ahref="https://github.com/matrix-org/matrix-doc/pull/2753">matrix-org/matrix-doc#2753</a> so at least you don't need to wait for a join to complete before finding out if it's the kind of room you want. Note that you should first disable presence, otherwise it'll just make the situation worse <ahref="https://github.com/matrix-org/synapse/issues/3120">#3120</a>. There is a lot of database interaction too, so make sure you've <ahref="other/../postgres.html">migrated your data</a> from the default sqlite to postgresql. Personally, I recommend patience - once the initial join is complete there's rarely any issues with actually interacting with the room, but if you like you can just block "large" rooms entirely.</p>
<p>Anything that requires modifying the device list <ahref="https://github.com/matrix-org/synapse/issues/7721">#7721</a> will take a while to propagate, again taking the client "Offline" until it's complete. This includes signing in and out, editing the public name and verifying e2ee. The main mitigation I recommend is to keep long-running sessions open e.g. by using Firefox SSB "Use this site in App mode" or Chromium PWA "Install Element".</p>
<p>Put the below in a new file at /etc/matrix-synapse/conf.d/sbc.yaml to override the defaults in homeserver.yaml.</p>
<pre><code># Disable presence tracking, which is currently fairly resource intensive
# More info: https://github.com/matrix-org/synapse/issues/9478
use_presence: false
# Set a small complexity limit, preventing users from joining large rooms
# which may be resource-intensive to remain a part of.
#
# Note that this will not prevent users from joining smaller rooms that
# eventually become complex.
limit_remote_rooms:
enabled: true
complexity: 3.0
# Database configuration
database:
# Use postgres for the best performance
name: psycopg2
args:
user: matrix-synapse
# Generate a long, secure password using a password manager
password: hunter2
database: matrix-synapse
host: localhost
</code></pre>
<p>Currently the complexity is measured by <ahref="https://github.com/matrix-org/synapse/blob/v1.20.1/synapse/storage/databases/main/events_worker.py#L986">current_state_events / 500</a>. You can find join times and your most complex rooms like this:</p>
admin@homeserver:~$ sudo --user postgres psql matrix-synapse --command 'select canonical_alias, joined_members, current_state_events from room_stats_state natural join room_stats_current where canonical_alias is not null order by current_state_events desc fetch first 5 rows only'
