deploy: 2d44ee6868805d4ff23489a8dd6b4072ff358663

1 files changed, 391 insertions, 123 deletions

diff --git a/latest/print.html b/latest/print.html
index 0970b4bafd..982a0caad3 100644
--- a/latest/print.html
+++ b/latest/print.html
@@ -101,7 +101,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="development/url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="development/url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
@@ -1647,8 +1647,8 @@ of this endpoint modifying the media store.</p>
 <h2 id="deprecation-of-the-current-third-party-rules-module-interface"><a class="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 <a href="modules.html#porting-an-existing-module-that-uses-the-old-interface">this documentation</a>
-to update their modules. Synapse administrators can refer to <a href="modules.html#using-modules">this documentation</a>
+to <a href="modules/porting_legacy_module.html">this documentation</a>
+to update their modules. Synapse administrators can refer to <a href="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>
 <h1 id="upgrading-to-v1380"><a class="header" href="#upgrading-to-v1380">Upgrading to v1.38.0</a></h1>
@@ -1678,9 +1678,9 @@ particular server:</p>
 <h1 id="upgrading-to-v1370"><a class="header" href="#upgrading-to-v1370">Upgrading to v1.37.0</a></h1>
 <h2 id="deprecation-of-the-current-spam-checker-interface"><a class="header" href="#deprecation-of-the-current-spam-checker-interface">Deprecation of the current spam checker interface</a></h2>
 <p>The current spam checker interface is deprecated in favour of a new generic modules system.
-Authors of spam checker modules can refer to <a href="modules.html#porting-an-existing-module-that-uses-the-old-interface">this
-documentation</a>
-to update their modules. Synapse administrators can refer to <a href="modules.html#using-modules">this
+Authors of spam checker modules can refer to [this
+documentation](modules/porting_legacy_module.md
+to update their modules. Synapse administrators can refer to <a href="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>
@@ -1758,20 +1758,20 @@ Synapse v1.30.0.</p>
 <h1 id="upgrading-to-v1290"><a class="header" href="#upgrading-to-v1290">Upgrading to v1.29.0</a></h1>
 <h2 id="requirement-for-x-forwarded-proto-header"><a class="header" href="#requirement-for-x-forwarded-proto-header">Requirement for X-Forwarded-Proto header</a></h2>
 <p>When using Synapse with a reverse proxy (in particular, when using the
-[x_forwarded]{.title-ref} option on an HTTP listener), Synapse now
-expects to receive an [X-Forwarded-Proto]{.title-ref} header on incoming
+<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 [X-Forwarded-Proto]{.title-ref} header to
-[https]{.title-ref} or [http]{.title-ref} to indicate the protocol used
+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 [Host]{.title-ref} header to be preserved.</p>
+<p>Synapse also requires the <code>Host</code> header to be preserved.</p>
 <p>See the <a href="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 <a href="https://caddyserver.com/">Caddy</a> are unaffected, since we
-believe it sets [X-Forwarded-Proto]{.title-ref} by default.)</p>
+believe it sets <code>X-Forwarded-Proto</code> by default.)</p>
 <h1 id="upgrading-to-v1270"><a class="header" href="#upgrading-to-v1270">Upgrading to v1.27.0</a></h1>
 <h2 id="changes-to-callback-uri-for-oauth2--openid-connect-and-saml2"><a class="header" href="#changes-to-callback-uri-for-oauth2--openid-connect-and-saml2">Changes to callback URI for OAuth2 / OpenID Connect and SAML2</a></h2>
 <p>This version changes the URI used for callbacks from OAuth2 and SAML2
@@ -1909,13 +1909,13 @@ mapping provider to specify different algorithms, instead of the
 <a href="https://matrix.org/docs/spec/appendices#mapping-from-other-character-sets">default
 way</a>.</p>
 <p>If your Synapse configuration uses a custom mapping provider
-([oidc_config.user_mapping_provider.module]{.title-ref} is specified and
+(<code>oidc_config.user_mapping_provider.module</code> is specified and
 not equal to
-[synapse.handlers.oidc_handler.JinjaOidcMappingProvider]{.title-ref})
-then you <em>must</em> ensure that [map_user_attributes]{.title-ref} of the
+<code>synapse.handlers.oidc_handler.JinjaOidcMappingProvider</code>)
+then you <em>must</em> ensure that <code>map_user_attributes</code> of the
 mapping provider performs some normalisation of the
-[localpart]{.title-ref} returned. To match previous behaviour you can
-use the [map_username_to_mxid_localpart]{.title-ref} function provided
+<code>localpart</code> returned. To match previous behaviour you can
+use the <code>map_username_to_mxid_localpart</code> function provided
 by Synapse. An example is shown below:</p>
 <pre><code class="language-python">from synapse.types import map_username_to_mxid_localpart
 
@@ -1940,7 +1940,7 @@ v1.24.0. The Admin API is now only accessible under:</p>
 <ul>
 <li><code>/_synapse/admin/v1</code></li>
 </ul>
-<p>The only exception is the [/admin/whois]{.title-ref} endpoint, which is
+<p>The only exception is the <code>/admin/whois</code> endpoint, which is
 <a href="https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid">also available via the client-server
 API</a>.</p>
 <p>The deprecation of the old endpoints was announced with Synapse 1.20.0
@@ -1994,7 +1994,7 @@ used if a custom template cannot be found.</p>
 <p>This page will appear to the user after clicking a password reset link
 that has been emailed to them.</p>
 <p>To complete password reset, the page must include a way to make a
-[POST]{.title-ref} request to
+<code>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>
@@ -2012,15 +2012,15 @@ but the parameters are slightly different:</p>
 of why a user is seeing the error page.</li>
 </ul>
 <h1 id="upgrading-to-v1180"><a class="header" href="#upgrading-to-v1180">Upgrading to v1.18.0</a></h1>
-<h2 id="docker--py3title-ref-suffix-will-be-removed-in-future-versions"><a class="header" href="#docker--py3title-ref-suffix-will-be-removed-in-future-versions">Docker [-py3]{.title-ref} suffix will be removed in future versions</a></h2>
+<h2 id="docker--py3-suffix-will-be-removed-in-future-versions"><a class="header" href="#docker--py3-suffix-will-be-removed-in-future-versions">Docker <code>-py3</code> suffix will be removed in future versions</a></h2>
 <p>From 10th August 2020, we will no longer publish Docker images with the
-[-py3]{.title-ref} tag suffix. The images tagged with the
-[-py3]{.title-ref} suffix have been identical to the non-suffixed tags
+<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 [latest-py3]{.title-ref} tag.
-Existing per-release tags (such as [v1.18.0-py3]{.title-ref}) will not
-be removed, but no new [-py3]{.title-ref} tags will be added.</p>
-<p>Scripts relying on the [-py3]{.title-ref} suffix will need to be
+<p>On 10th August, we will remove the <code>latest-py3</code> tag.
+Existing per-release tags (such as <code>v1.18.0-py3</code> will not
+be removed, but no new <code>-py3</code> tags will be added.</p>
+<p>Scripts relying on the <code>-py3</code> suffix will need to be
 updated.</p>
 <h2 id="redis-replication-is-now-recommended-in-lieu-of-tcp-replication"><a class="header" href="#redis-replication-is-now-recommended-in-lieu-of-tcp-replication">Redis replication is now recommended in lieu of TCP replication</a></h2>
 <p>When setting up worker processes, we now recommend the use of a Redis
@@ -2045,8 +2045,8 @@ from v1.2.1 or earlier, to versions between v1.4.0 and v1.12.x.</p>
 are affected can be repaired as follows:</p>
 <ol>
 <li>
-<p>Run the following sql from a [psql]{.title-ref} or
-[sqlite3]{.title-ref} console:</p>
+<p>Run the following sql from a <code>psql</code> or
+<code>sqlite3</code> console:</p>
 <pre><code class="language-sql">INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
    ('populate_stats_process_rooms', '{}', 'current_state_events_membership');
 
@@ -2107,8 +2107,8 @@ of any problems.</p>
 </li>
 <li>
 <p>As an initial check to see if you will be affected, you can try
-running the following query from the [psql]{.title-ref} or
-[sqlite3]{.title-ref} console. It is safe to run it while Synapse is
+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><code class="language-sql">SELECT MAX(q.v) FROM (
   SELECT (
@@ -2586,9 +2586,9 @@ used on mobile devices).</p>
 first need to upgrade the database by running:</p>
 <pre><code>python scripts/upgrade_db_to_v0.6.0.py &lt;db&gt; &lt;server_name&gt; &lt;signing_key&gt;
 </code></pre>
-<p>Where [<db>]{.title-ref} is the location of the database,
-[&lt;server_name&gt;]{.title-ref} is the server name as specified in the
-synapse configuration, and [&lt;signing_key&gt;]{.title-ref} is the location
+<p>Where <code>&lt;db&gt;</code> is the location of the database,
+<code>&lt;server_name&gt;</code> is the server name as specified in the
+synapse configuration, and <code>&lt;signing_key&gt;</code> is the location
 of the signing key as specified in the synapse configuration.</p>
 <p>This may take some time to complete. Failures of signatures and content
 hashes can safely be ignored.</p>
@@ -3511,6 +3511,48 @@ limit_remote_rooms:
 #
 #user_ips_max_age: 14d
 
+# Inhibits the /requestToken endpoints from returning an error that might leak
+# information about whether an e-mail address is in use or not on this
+# homeserver.
+# Note that for some endpoints the error situation is the e-mail already being
+# used, and for others the error is entering the e-mail being unused.
+# If this option is enabled, instead of returning an error, these endpoints will
+# act as if no error happened and return a fake session ID ('sid') to clients.
+#
+#request_token_inhibit_3pid_errors: true
+
+# A list of domains that the domain portion of 'next_link' parameters
+# must match.
+#
+# This parameter is optionally provided by clients while requesting
+# validation of an email or phone number, and maps to a link that
+# users will be automatically redirected to after validation
+# succeeds. Clients can make use this parameter to aid the validation
+# process.
+#
+# The whitelist is applied whether the homeserver or an
+# identity server is handling validation.
+#
+# The default value is no whitelist functionality; all domains are
+# allowed. Setting this value to an empty list will instead disallow
+# all domains.
+#
+#next_link_domain_whitelist: [&quot;matrix.org&quot;]
+
+# Templates to use when generating email or HTML page contents.
+#
+templates:
+  # Directory in which Synapse will try to find template files 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.
+  #
+  # See https://matrix-org.github.io/synapse/latest/templates.html for more
+  # information about using custom templates.
+  #
+  #custom_template_directory: /path/to/custom/templates/
+
+
 # Message retention policy at the server level.
 #
 # Room admins and mods can define a retention period for their rooms using the
@@ -3580,47 +3622,6 @@ retention:
   #  - shortest_max_lifetime: 3d
   #    interval: 1d
 
-# Inhibits the /requestToken endpoints from returning an error that might leak
-# information about whether an e-mail address is in use or not on this
-# homeserver.
-# Note that for some endpoints the error situation is the e-mail already being
-# used, and for others the error is entering the e-mail being unused.
-# If this option is enabled, instead of returning an error, these endpoints will
-# act as if no error happened and return a fake session ID ('sid') to clients.
-#
-#request_token_inhibit_3pid_errors: true
-
-# A list of domains that the domain portion of 'next_link' parameters
-# must match.
-#
-# This parameter is optionally provided by clients while requesting
-# validation of an email or phone number, and maps to a link that
-# users will be automatically redirected to after validation
-# succeeds. Clients can make use this parameter to aid the validation
-# process.
-#
-# The whitelist is applied whether the homeserver or an
-# identity server is handling validation.
-#
-# The default value is no whitelist functionality; all domains are
-# allowed. Setting this value to an empty list will instead disallow
-# all domains.
-#
-#next_link_domain_whitelist: [&quot;matrix.org&quot;]
-
-# Templates to use when generating email or HTML page contents.
-#
-templates:
-  # Directory in which Synapse will try to find template files 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.
-  #
-  # See https://matrix-org.github.io/synapse/latest/templates.html for more
-  # information about using custom templates.
-  #
-  #custom_template_directory: /path/to/custom/templates/
-
 
 ## TLS ##
 
@@ -5299,34 +5300,6 @@ email:
     #email_validation: &quot;[%(server_name)s] Validate your email&quot;
 
 
-# Password providers allow homeserver administrators to integrate
-# their Synapse installation with existing authentication methods
-# ex. LDAP, external tokens, etc.
-#
-# For more information and known implementations, please see
-# https://matrix-org.github.io/synapse/latest/password_auth_providers.html
-#
-# Note: instances wishing to use SAML or CAS authentication should
-# instead use the `saml2_config` or `cas_config` options,
-# respectively.
-#
-password_providers:
-#    # Example config for an LDAP auth provider
-#    - module: &quot;ldap_auth_provider.LdapAuthProvider&quot;
-#      config:
-#        enabled: true
-#        uri: &quot;ldap://ldap.example.com:389&quot;
-#        start_tls: true
-#        base: &quot;ou=users,dc=example,dc=com&quot;
-#        attributes:
-#           uid: &quot;cn&quot;
-#           mail: &quot;email&quot;
-#           name: &quot;givenName&quot;
-#        #bind_dn:
-#        #bind_password:
-#        #filter: &quot;(objectClass=posixAccount)&quot;
-
-
 
 ## Push ##
 
@@ -5691,11 +5664,11 @@ redis:
 <div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="logging-sample-configuration-file"><a class="header" href="#logging-sample-configuration-file">Logging Sample Configuration File</a></h1>
 <p>Below is a sample logging configuration file. This file can be tweaked to control how your
 homeserver will output logs. A restart of the server is generally required to apply any
-changes made to this file.</p>
-<p>Note that the contents below are <em>not</em> intended to be copied and used as the basis for
-a real homeserver.yaml. Instead, if you are starting from scratch, please generate
-a fresh config using Synapse by following the instructions in
-<a href="usage/configuration/../../setup/installation.html">Installation</a>.</p>
+changes made to this file. The value of the <code>log_config</code> option in your homeserver
+config should be the path to this file.</p>
+<p>Note that a default logging configuration (shown below) is created automatically alongside
+the homeserver config when following the <a href="usage/configuration/../../setup/installation.html">installation instructions</a>.
+It should be named <code>&lt;SERVERNAME&gt;.log.config</code> by default.</p>
 <pre><code class="language-yaml"># Log configuration for Synapse.
 #
 # This is a YAML file containing a standard Python logging configuration
@@ -6903,7 +6876,12 @@ complete registration using methods from the <code>ModuleApi</code>.</p>
 <p>Synapse has a built-in SAML mapping provider if a custom provider isn't
 specified in the config. It is located at
 <a href="https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/saml.py"><code>synapse.handlers.saml.DefaultSamlMappingProvider</code></a>.</p>
-<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="password-auth-provider-modules"><a class="header" href="#password-auth-provider-modules">Password auth provider modules</a></h1>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h2 style="color:red">
+This page of the Synapse documentation is now deprecated. For up to date
+documentation on setting up or writing a password auth provider module, please see
+<a href="modules.html">this page</a>.
+</h2>
+<h1 id="password-auth-provider-modules"><a class="header" href="#password-auth-provider-modules">Password auth provider modules</a></h1>
 <p>Password auth providers offer a way for server administrators to
 integrate their Synapse installation with an existing authentication
 system.</p>
@@ -7656,6 +7634,10 @@ operating system, the server admin needs to run <code>VACUUM FULL;</code> (or
 <a href="https://www.postgresql.org/docs/current/sql-vacuum.html">PostgreSQL documentation</a>).</p>
 <div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="modules"><a class="header" href="#modules">Modules</a></h1>
 <p>Synapse supports extending its functionality by configuring external modules.</p>
+<p><strong>Note</strong>: When using third-party modules, you effectively allow someone else to run
+custom code on your Synapse homeserver. Server admins are encouraged to verify the
+provenance of the modules they use on their homeserver and make sure the modules aren't
+running malicious code on their instance.</p>
 <h2 id="using-modules"><a class="header" href="#using-modules">Using modules</a></h2>
 <p>To use a module on Synapse, add it to the <code>modules</code> section of the configuration file:</p>
 <pre><code class="language-yaml">modules:
@@ -7667,18 +7649,30 @@ operating system, the server admin needs to run <code>VACUUM FULL;</code> (or
 </code></pre>
 <p>Each module is defined by a path to a Python class as well as a configuration. This
 information for a given module should be available in the module's own documentation.</p>
-<p><strong>Note</strong>: When using third-party modules, you effectively allow someone else to run
-custom code on your Synapse homeserver. Server admins are encouraged to verify the
-provenance of the modules they use on their homeserver and make sure the modules aren't
-running malicious code on their instance.</p>
-<p>Also note that we are currently in the process of migrating module interfaces to this
-system. While some interfaces might be compatible with it, others still require
-configuring modules in another part of Synapse's configuration file.</p>
+<h2 id="using-multiple-modules"><a class="header" href="#using-multiple-modules">Using multiple modules</a></h2>
+<p>The order in which modules are listed in this section is important. When processing an
+action that can be handled by several modules, Synapse will always prioritise the module
+that appears first (i.e. is the highest in the list). This means:</p>
+<ul>
+<li>If several modules register the same callback, the callback registered by the module
+that appears first is used.</li>
+<li>If several modules try to register a handler for the same HTTP path, only the handler
+registered by the module that appears first is used. Handlers registered by the other
+module(s) are ignored and Synapse will log a warning message about them.</li>
+</ul>
+<p>Note that Synapse doesn't allow multiple modules implementing authentication checkers via
+the password auth provider feature for the same login type with different fields. If this
+happens, Synapse will refuse to start.</p>
+<h2 id="current-status"><a class="header" href="#current-status">Current status</a></h2>
+<p>We are currently in the process of migrating module interfaces to this system. While some
+interfaces might be compatible with it, others still require configuring modules in
+another part of Synapse's configuration file.</p>
 <p>Currently, only the following pre-existing interfaces are compatible with this new system:</p>
 <ul>
 <li>spam checker</li>
 <li>third-party rules</li>
 <li>presence router</li>
+<li>password auth providers</li>
 </ul>
 <div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="writing-a-module"><a class="header" href="#writing-a-module">Writing a module</a></h1>
 <p>A module is a Python class that uses Synapse's module API to interact with the
@@ -7690,6 +7684,17 @@ either the output of the module's <code>parse_config</code> static method (see b
 configuration associated with the module in Synapse's configuration file.</p>
 <p>See the documentation for the <code>ModuleApi</code> class
 <a href="https://github.com/matrix-org/synapse/blob/master/synapse/module_api/__init__.py">here</a>.</p>
+<h2 id="when-synapse-runs-with-several-modules-configured"><a class="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 <a href="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>
 <h2 id="handling-the-modules-configuration"><a class="header" href="#handling-the-modules-configuration">Handling the module's configuration</a></h2>
 <p>A module can implement the following static method:</p>
 <pre><code class="language-python">@staticmethod
@@ -7737,13 +7742,19 @@ Synapse instances. Spam checker callbacks can be registered using the module API
 <h2 id="callbacks"><a class="header" href="#callbacks">Callbacks</a></h2>
 <p>The available spam checker callbacks are:</p>
 <h3 id="check_event_for_spam"><a class="header" href="#check_event_for_spam"><code>check_event_for_spam</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def check_event_for_spam(event: &quot;synapse.events.EventBase&quot;) -&gt; Union[bool, str]
 </code></pre>
 <p>Called when receiving an event from a client or via federation. The module can return
 either a <code>bool</code> to indicate whether the event must be rejected because of spam, or a <code>str</code>
 to indicate the event must be rejected because of spam and to give a rejection reason to
 forward to clients.</p>
+<p>If multiple modules implement this callback, they will be considered in order. If a
+callback returns <code>False</code>, Synapse falls through to the next one. The value of the first
+callback that does not return <code>False</code> will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.</p>
 <h3 id="user_may_join_room"><a class="header" href="#user_may_join_room"><code>user_may_join_room</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def user_may_join_room(user: str, room: str, is_invited: bool) -&gt; bool
 </code></pre>
 <p>Called when a user is trying to join a room. The module must return a <code>bool</code> to indicate
@@ -7753,13 +7764,23 @@ whether the user can join the room. The user is represented by their Matrix user
 currently has a pending invite in the room.</p>
 <p>This callback isn't called if the join is performed by a server administrator, or in the
 context of a room creation.</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>
 <h3 id="user_may_invite"><a class="header" href="#user_may_invite"><code>user_may_invite</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def user_may_invite(inviter: str, invitee: str, room_id: str) -&gt; bool
 </code></pre>
 <p>Called when processing an invitation. The module must return a <code>bool</code> indicating whether
 the inviter can invite the invitee to the given room. Both inviter and invitee are
 represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</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>
 <h3 id="user_may_send_3pid_invite"><a class="header" href="#user_may_send_3pid_invite"><code>user_may_send_3pid_invite</code></a></h3>
+<p><em>First introduced in Synapse v1.45.0</em></p>
 <pre><code class="language-python">async def user_may_send_3pid_invite(
     inviter: str,
     medium: str,
@@ -7785,12 +7806,22 @@ for more information regarding third-party identifiers.</p>
 </code></pre>
 <p><strong>Note</strong>: If the third-party identifier is already associated with a matrix user ID,
 <a href="modules/spam_checker_callbacks.html#user_may_invite"><code>user_may_invite</code></a> will be used instead.</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>
 <h3 id="user_may_create_room"><a class="header" href="#user_may_create_room"><code>user_may_create_room</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def user_may_create_room(user: str) -&gt; bool
 </code></pre>
 <p>Called when processing a room creation request. The module must return a <code>bool</code> indicating
 whether the given user (represented by their Matrix user ID) is allowed to create a room.</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>
 <h3 id="user_may_create_room_with_invites"><a class="header" href="#user_may_create_room_with_invites"><code>user_may_create_room_with_invites</code></a></h3>
+<p><em>First introduced in Synapse v1.44.0</em></p>
 <pre><code class="language-python">async def user_may_create_room_with_invites(
     user: str,
     invites: List[str],
@@ -7811,19 +7842,34 @@ corresponding list(s) will be empty.</p>
 <p><strong>Note</strong>: This callback is not called when a room is cloned (e.g. during a room upgrade)
 since no invites are sent when cloning a room. To cover this case, modules also need to
 implement <code>user_may_create_room</code>.</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>
 <h3 id="user_may_create_room_alias"><a class="header" href="#user_may_create_room_alias"><code>user_may_create_room_alias</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def user_may_create_room_alias(user: str, room_alias: &quot;synapse.types.RoomAlias&quot;) -&gt; bool
 </code></pre>
 <p>Called when trying to associate an alias with an existing room. The module must return a
 <code>bool</code> indicating whether the given user (represented by their Matrix user ID) is allowed
 to set the given alias.</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>
 <h3 id="user_may_publish_room"><a class="header" href="#user_may_publish_room"><code>user_may_publish_room</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def user_may_publish_room(user: str, room_id: str) -&gt; bool
 </code></pre>
 <p>Called when trying to publish a room to the homeserver's public rooms directory. The
 module must return a <code>bool</code> indicating whether the given user (represented by their
 Matrix user ID) is allowed to publish the given room.</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>
 <h3 id="check_username_for_spam"><a class="header" href="#check_username_for_spam"><code>check_username_for_spam</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def check_username_for_spam(user_profile: Dict[str, str]) -&gt; bool
 </code></pre>
 <p>Called when computing search results in the user directory. The module must return a
@@ -7836,7 +7882,12 @@ is represented as a dictionary with the following keys:</p>
 </ul>
 <p>The module is given a copy of the original dictionary, so modifying it from within the
 module cannot modify a user's profile when included in user directory search results.</p>
+<p>If multiple modules implement this callback, they will be considered in order. If a
+callback returns <code>False</code>, Synapse falls through to the next one. The value of the first
+callback that does not return <code>False</code> will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.</p>
 <h3 id="check_registration_for_spam"><a class="header" href="#check_registration_for_spam"><code>check_registration_for_spam</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def check_registration_for_spam(
     email_threepid: Optional[dict],
     username: Optional[str],
@@ -7857,7 +7908,13 @@ second item is an IP address. These user agents and IP addresses are the ones th
 used during the registration process.</li>
 <li><code>auth_provider_id</code>: The identifier of the SSO authentication provider, if any.</li>
 </ul>
+<p>If multiple modules implement this callback, they will be considered in order. If a
+callback returns <code>RegistrationBehaviour.ALLOW</code>, Synapse falls through to the next one.
+The value of the first callback that does not return <code>RegistrationBehaviour.ALLOW</code> will
+be used. If this happens, Synapse will not call any of the subsequent implementations of
+this callback.</p>
 <h3 id="check_media_file_for_spam"><a class="header" href="#check_media_file_for_spam"><code>check_media_file_for_spam</code></a></h3>
+<p><em>First introduced in Synapse v1.37.0</em></p>
 <pre><code class="language-python">async def check_media_file_for_spam(
     file_wrapper: &quot;synapse.rest.media.v1.media_storage.ReadableFileWrapper&quot;,
     file_info: &quot;synapse.rest.media.v1._base.FileInfo&quot;,
@@ -7865,6 +7922,10 @@ used during the registration process.</li>
 </code></pre>
 <p>Called when storing a local or remote file. The module must return a boolean indicating
 whether the given file can be stored in the homeserver's media store.</p>
+<p>If multiple modules implement this callback, they will be considered in order. If a
+callback returns <code>False</code>, Synapse falls through to the next one. The value of the first
+callback that does not return <code>False</code> will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.</p>
 <h2 id="example"><a class="header" href="#example">Example</a></h2>
 <p>The example below is a module that implements the spam checker callback
 <code>check_event_for_spam</code> to deny any message sent by users whose Matrix user IDs are
@@ -7915,6 +7976,7 @@ the module API's <code>register_third_party_rules_callbacks</code> method.</p>
 <h2 id="callbacks-1"><a class="header" href="#callbacks-1">Callbacks</a></h2>
 <p>The available third party rules callbacks are:</p>
 <h3 id="check_event_allowed"><a class="header" href="#check_event_allowed"><code>check_event_allowed</code></a></h3>
+<p><em>First introduced in Synapse v1.39.0</em></p>
 <pre><code class="language-python">async def check_event_allowed(
     event: &quot;synapse.events.EventBase&quot;,
     state_events: &quot;synapse.types.StateMap&quot;,
@@ -7942,7 +8004,12 @@ that, it is recommended the module calls <code>event.get_dict()</code> to get th
 dictionary, and modify the returned dictionary accordingly.</p>
 <p>Note that replacing the event only works for events sent by local users, not for events
 received over federation.</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>
 <h3 id="on_create_room"><a class="header" href="#on_create_room"><code>on_create_room</code></a></h3>
+<p><em>First introduced in Synapse v1.39.0</em></p>
 <pre><code class="language-python">async def on_create_room(
     requester: &quot;synapse.types.Requester&quot;,
     request_content: dict,
@@ -7956,7 +8023,13 @@ for a list of possible parameters), and a boolean indicating whether the user pe
 the request is a server admin.</p>
 <p>Modules can modify the <code>request_content</code> (by e.g. adding events to its <code>initial_state</code>),
 or deny the room's creation by raising a <code>module_api.errors.SynapseError</code>.</p>
+<p>If multiple modules implement this callback, they will be considered in order. If a
+callback returns without raising an exception, Synapse falls through to the next one. The
+room creation will be forbidden as soon as one of the callbacks raises an exception. If
+this happens, Synapse will not call any of the subsequent implementations of this
+callback.</p>
 <h3 id="check_threepid_can_be_invited"><a class="header" href="#check_threepid_can_be_invited"><code>check_threepid_can_be_invited</code></a></h3>
+<p><em>First introduced in Synapse v1.39.0</em></p>
 <pre><code class="language-python">async def check_threepid_can_be_invited(
     medium: str,
     address: str,
@@ -7965,7 +8038,12 @@ or deny the room's creation by raising a <code>module_api.errors.SynapseError</c
 </code></pre>
 <p>Called when processing an invite via a third-party identifier (i.e. email or phone number).
 The module must return a boolean indicating whether the invite can go through.</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>
 <h3 id="check_visibility_can_be_modified"><a class="header" href="#check_visibility_can_be_modified"><code>check_visibility_can_be_modified</code></a></h3>
+<p><em>First introduced in Synapse v1.39.0</em></p>
 <pre><code class="language-python">async def check_visibility_can_be_modified(
     room_id: str,
     state_events: &quot;synapse.types.StateMap&quot;,
@@ -7975,6 +8053,10 @@ The module must return a boolean indicating whether the invite can go through.</
 <p>Called when changing the visibility of a room in the local public room directory. The
 visibility is a string that's either &quot;public&quot; or &quot;private&quot;. The module must return a
 boolean indicating whether the change can go through.</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>
 <h2 id="example-1"><a class="header" href="#example-1">Example</a></h2>
 <p>The example below is a module that implements the third-party rules callback
 <code>check_event_allowed</code> to censor incoming messages as dictated by a third-party service.</p>
@@ -8012,6 +8094,7 @@ registered using the module API's <code>register_presence_router_callbacks</code
 <h2 id="callbacks-2"><a class="header" href="#callbacks-2">Callbacks</a></h2>
 <p>The available presence router callbacks are:</p>
 <h3 id="get_users_for_states"><a class="header" href="#get_users_for_states"><code>get_users_for_states</code></a></h3>
+<p><em>First introduced in Synapse v1.42.0</em></p>
 <pre><code class="language-python">async def get_users_for_states(
     state_updates: Iterable[&quot;synapse.api.UserPresenceState&quot;],
 ) -&gt; Dict[str, Set[&quot;synapse.api.UserPresenceState&quot;]]
@@ -8022,7 +8105,11 @@ be used to instruct the server to forward that presence state to specific users.
 must return a dictionary that maps from Matrix user IDs (which can be local or remote) to the
 <code>UserPresenceState</code> changes that they should be forwarded.</p>
 <p>Synapse will then attempt to send the specified presence updates to each user when possible.</p>
+<p>If multiple modules implement this callback, Synapse merges all the dictionaries returned
+by the callbacks. If multiple callbacks return a dictionary containing the same key,
+Synapse concatenates the sets associated with this key from each dictionary. </p>
 <h3 id="get_interested_users"><a class="header" href="#get_interested_users"><code>get_interested_users</code></a></h3>
+<p><em>First introduced in Synapse v1.42.0</em></p>
 <pre><code class="language-python">async def get_interested_users(
     user_id: str
 ) -&gt; Union[Set[str], &quot;synapse.module_api.PRESENCE_ALL_USERS&quot;]
@@ -8036,6 +8123,11 @@ should return the Matrix user IDs of the users whose presence state they are all
 query. The returned users can be local or remote. </p>
 <p>Alternatively the callback can return <code>synapse.module_api.PRESENCE_ALL_USERS</code>
 to indicate that the user should receive updates from all known users.</p>
+<p>If multiple modules implement this callback, they will be considered in order. Synapse
+calls each callback one by one, and use a concatenation of all the <code>set</code>s returned by the
+callbacks. If one callback returns <code>synapse.module_api.PRESENCE_ALL_USERS</code>, Synapse uses
+this value instead. If this happens, Synapse does not call any of the subsequent
+implementations of this callback.</p>
 <h2 id="example-2"><a class="header" href="#example-2">Example</a></h2>
 <p>The example below is a module that implements both presence router callbacks, and ensures
 that <code>@alice:example.org</code> receives all presence updates from <code>@bob:example.com</code> and
@@ -8084,6 +8176,7 @@ Synapse instance. Account validity callbacks can be registered using the module
 <code>register_account_validity_callbacks</code> method.</p>
 <p>The available account validity callbacks are:</p>
 <h3 id="is_user_expired"><a class="header" href="#is_user_expired"><code>is_user_expired</code></a></h3>
+<p><em>First introduced in Synapse v1.39.0</em></p>
 <pre><code class="language-python">async def is_user_expired(user: str) -&gt; Optional[bool]
 </code></pre>
 <p>Called when processing any authenticated request (except for logout requests). The module
@@ -8093,12 +8186,169 @@ represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</p>
 <p>If the module returns <code>True</code>, the current request will be denied with the error code
 <code>ORG_MATRIX_EXPIRED_ACCOUNT</code> and the HTTP status code 403. Note that this doesn't
 invalidate the user's access token.</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.</p>
 <h3 id="on_user_registration"><a class="header" href="#on_user_registration"><code>on_user_registration</code></a></h3>
+<p><em>First introduced in Synapse v1.39.0</em></p>
 <pre><code class="language-python">async def on_user_registration(user: str) -&gt; None
 </code></pre>
 <p>Called after successfully registering a user, in case the module needs to perform extra
 operations to keep track of them. (e.g. add them to a database table). The user is
 represented by their Matrix user ID.</p>
+<p>If multiple modules implement this callback, Synapse runs them all in order.</p>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="password-auth-provider-callbacks"><a class="header" href="#password-auth-provider-callbacks">Password auth provider callbacks</a></h1>
+<p>Password auth providers offer a way for server administrators to integrate
+their Synapse installation with an external authentication system. The callbacks can be
+registered by using the Module API's <code>register_password_auth_provider_callbacks</code> method.</p>
+<h2 id="callbacks-3"><a class="header" href="#callbacks-3">Callbacks</a></h2>
+<h3 id="auth_checkers"><a class="header" href="#auth_checkers"><code>auth_checkers</code></a></h3>
+<p><em>First introduced in Synapse v1.46.0</em></p>
+<pre><code> auth_checkers: Dict[Tuple[str,Tuple], Callable]
+</code></pre>
+<p>A dict mapping from tuples of a login type identifier (such as <code>m.login.password</code>) and a
+tuple of field names (such as <code>(&quot;password&quot;, &quot;secret_thing&quot;)</code>) to authentication checking
+callbacks, which should be of the following form:</p>
+<pre><code class="language-python">async def check_auth(
+    user: str,
+    login_type: str,
+    login_dict: &quot;synapse.module_api.JsonDict&quot;,
+) -&gt; Optional[
+    Tuple[
+        str, 
+        Optional[Callable[[&quot;synapse.module_api.LoginResponse&quot;], Awaitable[None]]]
+    ]
+]
+</code></pre>
+<p>The login type and field names should be provided by the user in the
+request to the <code>/login</code> API. <a href="https://matrix.org/docs/spec/client_server/latest#authentication-types">The Matrix specification</a>
+defines some types, however user defined ones are also allowed.</p>
+<p>The callback is passed the <code>user</code> field provided by the client (which might not be in
+<code>@username:server</code> form), the login type, and a dictionary of login secrets passed by
+the client.</p>
+<p>If the authentication is successful, the module must return the user's Matrix ID (e.g. 
+<code>@alice:example.com</code>) and optionally a callback to be called with the response to the
+<code>/login</code> request. If the module doesn't wish to return a callback, it must return <code>None</code>
+instead.</p>
+<p>If the authentication is unsuccessful, the module must return <code>None</code>.</p>
+<p>If multiple modules register an auth checker for the same login type but with different
+fields, Synapse will refuse to start.</p>
+<p>If multiple modules register an auth checker for the same login type with the same fields,
+then the callbacks will be executed in order, until one returns a Matrix User ID (and
+optionally a callback). In that case, the return value of that callback will be accepted
+and subsequent callbacks will not be fired. If every callback returns <code>None</code>, then the
+authentication fails.</p>
+<h3 id="check_3pid_auth"><a class="header" href="#check_3pid_auth"><code>check_3pid_auth</code></a></h3>
+<p><em>First introduced in Synapse v1.46.0</em></p>
+<pre><code class="language-python">async def check_3pid_auth(
+    medium: str, 
+    address: str,
+    password: str,
+) -&gt; Optional[
+    Tuple[
+        str, 
+        Optional[Callable[[&quot;synapse.module_api.LoginResponse&quot;], Awaitable[None]]]
+    ]
+]
+</code></pre>
+<p>Called when a user attempts to register or log in with a third party identifier,
+such as email. It is passed the medium (eg. <code>email</code>), an address (eg. <code>jdoe@example.com</code>)
+and the user's password.</p>
+<p>If the authentication is successful, the module must return the user's Matrix ID (e.g. 
+<code>@alice:example.com</code>) and optionally a callback to be called with the response to the <code>/login</code> request.
+If the module doesn't wish to return a callback, it must return None instead.</p>
+<p>If the authentication is unsuccessful, the module 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 return <code>None</code>,
+the authentication is denied.</p>
+<h3 id="on_logged_out"><a class="header" href="#on_logged_out"><code>on_logged_out</code></a></h3>
+<p><em>First introduced in Synapse v1.46.0</em></p>
+<pre><code class="language-python">async def on_logged_out(
+    user_id: str,
+    device_id: Optional[str],
+    access_token: str
+) -&gt; None
+</code></pre>
+<p>Called during a logout request for a user. It is passed the qualified user ID, the ID of the
+deactivated device (if any: access tokens are occasionally created without an associated
+device ID), and the (now deactivated) access token.</p>
+<p>If multiple modules implement this callback, Synapse runs them all in order.</p>
+<h2 id="example-3"><a class="header" href="#example-3">Example</a></h2>
+<p>The example module below implements authentication checkers for two different login types: </p>
+<ul>
+<li><code>my.login.type</code> 
+<ul>
+<li>Expects a <code>my_field</code> field to be sent to <code>/login</code></li>
+<li>Is checked by the method: <code>self.check_my_login</code></li>
+</ul>
+</li>
+<li><code>m.login.password</code> (defined in <a href="https://matrix.org/docs/spec/client_server/latest#password-based">the spec</a>)
+<ul>
+<li>Expects a <code>password</code> field to be sent to <code>/login</code></li>
+<li>Is checked by the method: <code>self.check_pass</code> </li>
+</ul>
+</li>
+</ul>
+<pre><code class="language-python">from typing import Awaitable, Callable, Optional, Tuple
+
+import synapse
+from synapse import module_api
+
+
+class MyAuthProvider:
+    def __init__(self, config: dict, api: module_api):
+
+        self.api = api
+
+        self.credentials = {
+            &quot;bob&quot;: &quot;building&quot;,
+            &quot;@scoop:matrix.org&quot;: &quot;digging&quot;,
+        }
+
+        api.register_password_auth_provider_callbacks(
+            auth_checkers={
+                (&quot;my.login_type&quot;, (&quot;my_field&quot;,)): self.check_my_login,
+                (&quot;m.login.password&quot;, (&quot;password&quot;,)): self.check_pass,
+            },
+        )
+
+    async def check_my_login(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: &quot;synapse.module_api.JsonDict&quot;,
+    ) -&gt; Optional[
+        Tuple[
+            str,
+            Optional[Callable[[&quot;synapse.module_api.LoginResponse&quot;], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != &quot;my.login_type&quot;:
+            return None
+
+        if self.credentials.get(username) == login_dict.get(&quot;my_field&quot;):
+            return self.api.get_qualified_user_id(username)
+
+    async def check_pass(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: &quot;synapse.module_api.JsonDict&quot;,
+    ) -&gt; Optional[
+        Tuple[
+            str,
+            Optional[Callable[[&quot;synapse.module_api.LoginResponse&quot;], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != &quot;m.login.password&quot;:
+            return None
+
+        if self.credentials.get(username) == login_dict.get(&quot;password&quot;):
+            return self.api.get_qualified_user_id(username)
+</code></pre>
 <div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="porting-an-existing-module-that-uses-the-old-interface"><a class="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>
@@ -8111,6 +8361,8 @@ for more info).</li>
 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 <a href="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 <a href="modules/index.html#using-modules">this section</a>
 for more info).</p>
@@ -9072,9 +9324,9 @@ See also <a href="admin_api/media_admin_api.html#purge-remote-media-api">Purge R
 <p>URL Parameters</p>
 <ul>
 <li><code>server_name</code>: string - The name of your local server (e.g <code>matrix.org</code>).</li>
-<li><code>before_ts</code>: string representing a positive integer - Unix timestamp in ms.
+<li><code>before_ts</code>: string representing a positive integer - Unix timestamp in milliseconds.
 Files that were last used before this timestamp will be deleted. It is the timestamp of
-last access and not the timestamp creation.</li>
+last access, not the timestamp when the file was created.</li>
 <li><code>size_gt</code>: Optional - string representing a positive integer - Size of the media in bytes.
 Files that are larger will be deleted. Defaults to <code>0</code>.</li>
 <li><code>keep_profiles</code>: Optional - string representing a boolean - Switch to also delete files
@@ -9107,7 +9359,7 @@ If <code>false</code> these files will be deleted. Defaults to <code>true</code>
 </code></pre>
 <p>URL Parameters</p>
 <ul>
-<li><code>unix_timestamp_in_ms</code>: string representing a positive integer - Unix timestamp in ms.
+<li><code>unix_timestamp_in_ms</code>: string representing a positive integer - Unix timestamp in milliseconds.
 All cached media that was last accessed before this timestamp will be removed.</li>
 </ul>
 <p>Response:</p>
@@ -9358,7 +9610,7 @@ token will be returned as a registration token object in the response body.</p>
 <p>The request body must be a JSON object and can contain the following fields:</p>
 <ul>
 <li><code>token</code>: The registration token. A string of no more than 64 characters that
-consists only of characters matched by the regex <code>[A-Za-z0-9-_]</code>.
+consists only of characters matched by the regex <code>[A-Za-z0-9._~-]</code>.
 Default: randomly generated.</li>
 <li><code>uses_allowed</code>: The integer number of times the token can be used to complete
 a registration before it becomes invalid.
@@ -10273,7 +10525,8 @@ server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a
             &quot;auth_provider&quot;: &quot;&lt;provider2&gt;&quot;,
             &quot;external_id&quot;: &quot;&lt;user_id_provider_2&gt;&quot;
         }
-    ]
+    ],
+    &quot;user_type&quot;: null
 }
 </code></pre>
 <p>URL parameters:</p>
@@ -10312,7 +10565,8 @@ specific <code>user_id</code>.</p>
     ],
     &quot;avatar_url&quot;: &quot;&lt;avatar_url&gt;&quot;,
     &quot;admin&quot;: false,
-    &quot;deactivated&quot;: false
+    &quot;deactivated&quot;: false,
+    &quot;user_type&quot;: null
 }
 </code></pre>
 <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a
@@ -10355,6 +10609,9 @@ in homeserver configuration.</li>
 unchanged on existing accounts and set to <code>false</code> for new accounts.
 A user cannot be erased by deactivating with this API. For details on
 deactivating users see <a href="admin_api/user_admin_api.html#deactivate-account">Deactivate Account</a>.</li>
+<li><code>user_type</code> - string or null, optional. If provided, the user type will be
+adjusted. If <code>null</code> given, the user type will be cleared. Other 
+allowed options are: <code>bot</code> and <code>support</code>.</li>
 </ul>
 <p>If the user already exists then optional parameters default to the current value.</p>
 <p>In order to re-activate an account <code>deactivated</code> must be set to <code>false</code>. If
@@ -10542,6 +10799,7 @@ An empty body may be passed for backwards compatibility.</p>
 <li>Remove all 3PIDs from the homeserver</li>
 <li>Delete all devices and E2EE keys</li>
 <li>Delete all access tokens</li>
+<li>Delete all pushers</li>
 <li>Delete the password hash</li>
 <li>Removal from all rooms the user is a member of</li>
 <li>Remove the user from the user directory</li>
@@ -10555,6 +10813,16 @@ is set to <code>true</code>:</p>
 <li>Remove the user's avatar URL</li>
 <li>Mark the user as erased</li>
 </ul>
+<p>The following actions are <strong>NOT</strong> performed. The list may be incomplete.</p>
+<ul>
+<li>Remove mappings of SSO IDs</li>
+<li><a href="admin_api/user_admin_api.html#delete-media-uploaded-by-a-user">Delete media uploaded</a> by user (included avatar images)</li>
+<li>Delete sent and received messages</li>
+<li>Delete E2E cross-signing keys</li>
+<li>Remove the user's creation (registration) timestamp</li>
+<li><a href="admin_api/user_admin_api.html#override-ratelimiting-for-users">Remove rate limit overrides</a></li>
+<li>Remove from monthly active users</li>
+</ul>
 <h2 id="reset-password"><a class="header" href="#reset-password">Reset password</a></h2>
 <p>Changes the password of another user. This will automatically log the user out of all their devices.</p>
 <p>The api is:</p>
@@ -12804,7 +13072,7 @@ connection errors.</p>
 received for each stream so that on reconneciton it can start streaming
 from the correct place. Note: not all RDATA have valid tokens due to
 batching. See <code>RdataCommand</code> for more details.</p>
-<h3 id="example-3"><a class="header" href="#example-3">Example</a></h3>
+<h3 id="example-4"><a class="header" href="#example-4">Example</a></h3>
 <p>An example iteraction is shown below. Each line is prefixed with '&gt;'
 or '&lt;' to indicate which side is sending, these are <em>not</em> included on
 the wire:</p>
@@ -13099,7 +13367,7 @@ graph), and one where we remove redundant links (the transitive reduction of the
 links graph) e.g. if we have chains <code>C3 -&gt; C2 -&gt; C1</code> then the link <code>C3 -&gt; C1</code>
 would not be stored. Synapse uses the former implementations so that it doesn't
 need to recurse to test reachability between chains.</p>
-<h3 id="example-4"><a class="header" href="#example-4">Example</a></h3>
+<h3 id="example-5"><a class="header" href="#example-5">Example</a></h3>
 <p>An example auth graph would look like the following, where chains have been
 formed based on type/state_key and are denoted by colour and are labelled with
 <code>(chain ID, sequence number)</code>. Links are denoted by the arrows (links in grey