diff --git a/latest/print.html b/latest/print.html
index 53931652ab..85964f0f41 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="url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/shutdown_room.html">Shutdown Room</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="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 "><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="url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/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 "><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>
@@ -184,65 +184,6 @@
<p>Welcome to the documentation repository for Synapse, the reference
<a href="https://matrix.org">Matrix</a> homeserver implementation.</p>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="installation-instructions"><a class="header" href="#installation-instructions">Installation Instructions</a></h1>
-<p>There are 3 steps to follow under <strong>Installation Instructions</strong>.</p>
-<ul>
-<li><a href="setup/installation.html#installation-instructions">Installation Instructions</a>
-<ul>
-<li><a href="setup/installation.html#choosing-your-server-name">Choosing your server name</a></li>
-<li><a href="setup/installation.html#installing-synapse">Installing Synapse</a>
-<ul>
-<li><a href="setup/installation.html#installing-from-source">Installing from source</a>
-<ul>
-<li><a href="setup/installation.html#platform-specific-prerequisites">Platform-specific prerequisites</a>
-<ul>
-<li><a href="setup/installation.html#debianubunturaspbian">Debian/Ubuntu/Raspbian</a></li>
-<li><a href="setup/installation.html#archlinux">ArchLinux</a></li>
-<li><a href="setup/installation.html#centosfedora">CentOS/Fedora</a></li>
-<li><a href="setup/installation.html#macos">macOS</a></li>
-<li><a href="setup/installation.html#opensuse">OpenSUSE</a></li>
-<li><a href="setup/installation.html#openbsd">OpenBSD</a></li>
-<li><a href="setup/installation.html#windows">Windows</a></li>
-</ul>
-</li>
-</ul>
-</li>
-<li><a href="setup/installation.html#prebuilt-packages">Prebuilt packages</a>
-<ul>
-<li><a href="setup/installation.html#docker-images-and-ansible-playbooks">Docker images and Ansible playbooks</a></li>
-<li><a href="setup/installation.html#debianubuntu">Debian/Ubuntu</a>
-<ul>
-<li><a href="setup/installation.html#matrixorg-packages">Matrix.org packages</a></li>
-<li><a href="setup/installation.html#downstream-debian-packages">Downstream Debian packages</a></li>
-<li><a href="setup/installation.html#downstream-ubuntu-packages">Downstream Ubuntu packages</a></li>
-</ul>
-</li>
-<li><a href="setup/installation.html#fedora">Fedora</a></li>
-<li><a href="setup/installation.html#opensuse-1">OpenSUSE</a></li>
-<li><a href="setup/installation.html#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></li>
-<li><a href="setup/installation.html#archlinux-1">ArchLinux</a></li>
-<li><a href="setup/installation.html#void-linux">Void Linux</a></li>
-<li><a href="setup/installation.html#freebsd">FreeBSD</a></li>
-<li><a href="setup/installation.html#openbsd-1">OpenBSD</a></li>
-<li><a href="setup/installation.html#nixos">NixOS</a></li>
-</ul>
-</li>
-</ul>
-</li>
-<li><a href="setup/installation.html#setting-up-synapse">Setting up Synapse</a>
-<ul>
-<li><a href="setup/installation.html#using-postgresql">Using PostgreSQL</a></li>
-<li><a href="setup/installation.html#tls-certificates">TLS certificates</a></li>
-<li><a href="setup/installation.html#client-well-known-uri">Client Well-Known URI</a></li>
-<li><a href="setup/installation.html#email">Email</a></li>
-<li><a href="setup/installation.html#registering-a-user">Registering a user</a></li>
-<li><a href="setup/installation.html#setting-up-a-turn-server">Setting up a TURN server</a></li>
-<li><a href="setup/installation.html#url-previews">URL previews</a></li>
-<li><a href="setup/installation.html#troubleshooting-installation">Troubleshooting Installation</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
<h2 id="choosing-your-server-name"><a class="header" href="#choosing-your-server-name">Choosing your server name</a></h2>
<p>It is important to choose the name for your server before you install Synapse,
because it cannot be changed later.</p>
@@ -886,6 +827,9 @@ to proxied traffic.)</p>
server_name matrix.example.com;
location ~* ^(\/_matrix|\/_synapse\/client) {
+ # note: do not add a path (even a single /) after the port in `proxy_pass`,
+ # otherwise nginx will canonicalise the URI and cause signature verification
+ # errors.
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
@@ -897,9 +841,7 @@ to proxied traffic.)</p>
}
}
</code></pre>
-<p><strong>NOTE</strong>: Do not add a path after the port in <code>proxy_pass</code>, otherwise nginx will
-canonicalise/normalise the URI.</p>
-<h3 id="caddy-1"><a class="header" href="#caddy-1">Caddy 1</a></h3>
+<h3 id="caddy-v1"><a class="header" href="#caddy-v1">Caddy v1</a></h3>
<pre><code>matrix.example.com {
proxy /_matrix http://localhost:8008 {
transparent
@@ -916,7 +858,7 @@ example.com:8448 {
}
}
</code></pre>
-<h3 id="caddy-2"><a class="header" href="#caddy-2">Caddy 2</a></h3>
+<h3 id="caddy-v2"><a class="header" href="#caddy-v2">Caddy v2</a></h3>
<pre><code>matrix.example.com {
reverse_proxy /_matrix/* http://localhost:8008
reverse_proxy /_synapse/client/* http://localhost:8008
@@ -1545,6 +1487,25 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre>
</li>
</ul>
+<h1 id="upgrading-to-v1420"><a class="header" href="#upgrading-to-v1420">Upgrading to v1.42.0</a></h1>
+<h2 id="removal-of-old-room-admin-api"><a class="header" href="#removal-of-old-room-admin-api">Removal of old Room Admin API</a></h2>
+<p>The following admin APIs were deprecated in <a href="https://github.com/matrix-org/synapse/blob/v1.25.0/CHANGES.md#removal-warning">Synapse 1.25</a>
+(released on 2021-01-13) and have now been removed:</p>
+<ul>
+<li><code>POST /_synapse/admin/v1/purge_room</code></li>
+<li><code>POST /_synapse/admin/v1/shutdown_room/<room_id></code></li>
+</ul>
+<p>Any scripts still using the above APIs should be converted to use the
+<a href="https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#delete-room-api">Delete Room API</a>.</p>
+<h2 id="user-interactive-authentication-fallback-templates-can-now-display-errors"><a class="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
+<a href="../synapse/res/templates/recaptcha.html">reCAPTCHA</a> or
+<a href="../synapse/res/templates/terms.html">terms</a> fallback pages.</p>
+<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>
+<h2 id="removal-of-out-of-date-email-pushers"><a class="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>
<h1 id="upgrading-to-v1410"><a class="header" href="#upgrading-to-v1410">Upgrading to v1.41.0</a></h1>
<h2 id="add-support-for-routing-outbound-http-requests-via-a-proxy-for-federation"><a class="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
@@ -3086,20 +3047,6 @@ presence:
#
#enabled: false
- # Presence routers are third-party modules that can specify additional logic
- # to where presence updates from users are routed.
- #
- presence_router:
- # The custom module's class. Uncomment to use a custom presence router module.
- #
- #module: "my_custom_router.PresenceRouter"
-
- # Configuration options of the custom module. Refer to your module's
- # documentation for available options.
- #
- #config:
- # example_option: 'something'
-
# Whether to require authentication to retrieve profile data (avatars,
# display names) of other users through the client API. Defaults to
# 'false'. Note that profile data is also available via the federation
@@ -3785,6 +3732,8 @@ log_config: "CONFDIR/SERVERNAME.log.config"
# is using
# - one for registration that ratelimits registration requests based on the
# client's IP address.
+# - one for checking the validity of registration tokens that ratelimits
+# requests based on the client's IP address.
# - one for login that ratelimits login requests based on the client's IP
# address.
# - one for login that ratelimits login requests based on the account the
@@ -3813,6 +3762,10 @@ log_config: "CONFDIR/SERVERNAME.log.config"
# per_second: 0.17
# burst_count: 3
#
+#rc_registration_token_validity:
+# per_second: 0.1
+# burst_count: 5
+#
#rc_login:
# address:
# per_second: 0.17
@@ -4161,6 +4114,15 @@ url_preview_accept_language:
#
#enable_3pid_lookup: true
+# Require users to submit a token during registration.
+# Tokens can be managed using the admin API:
+# https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html
+# Note that `enable_registration` must be set to `true`.
+# Disabling this option will not delete any tokens previously generated.
+# Defaults to false. Uncomment the following to require tokens:
+#
+#registration_requires_token: true
+
# If set, allows registration of standard or admin accounts by anyone who
# has the shared secret, even if registration is otherwise disabled.
#
@@ -6167,7 +6129,7 @@ Edit your Synapse config file and change the <code>oidc_config</code> section:</
localpart_template: "{{ user.preferred_username.split('@')[0] }}"
display_name_template: "{{ user.name }}"
</code></pre>
-<h3 id="a-hrefhttpsgithubcomdexidpdexdexa"><a class="header" href="#a-hrefhttpsgithubcomdexidpdexdexa"><a href="https://github.com/dexidp/dex">Dex</a></a></h3>
+<h3 id="dex"><a class="header" href="#dex">Dex</a></h3>
<p><a href="https://github.com/dexidp/dex">Dex</a> is a simple, open-source, certified OpenID Connect Provider.
Although it is designed to help building a full-blown provider with an
external database, it can be configured with static passwords in a config file.</p>
@@ -6196,7 +6158,7 @@ to install Dex.</p>
localpart_template: "{{ user.name }}"
display_name_template: "{{ user.name|capitalize }}"
</code></pre>
-<h3 id="a-hrefhttpswwwkeycloakorgdocslatestserver_adminsso-protocolskeycloaka"><a class="header" href="#a-hrefhttpswwwkeycloakorgdocslatestserver_adminsso-protocolskeycloaka"><a href="https://www.keycloak.org/docs/latest/server_admin/#sso-protocols">Keycloak</a></a></h3>
+<h3 id="keycloak"><a class="header" href="#keycloak">Keycloak</a></h3>
<p><a href="https://www.keycloak.org/docs/latest/server_admin/#sso-protocols">Keycloak</a> is an opensource IdP maintained by Red Hat.</p>
<p>Follow the <a href="https://www.keycloak.org/getting-started">Getting Started Guide</a> to install Keycloak and set up a realm.</p>
<ol>
@@ -6245,7 +6207,8 @@ to install Dex.</p>
localpart_template: "{{ user.preferred_username }}"
display_name_template: "{{ user.name }}"
</code></pre>
-<h3 id="a-hrefhttpsauth0comauth0a"><a class="header" href="#a-hrefhttpsauth0comauth0a"><a href="https://auth0.com/">Auth0</a></a></h3>
+<h3 id="auth0"><a class="header" href="#auth0">Auth0</a></h3>
+<p><a href="https://auth0.com/">Auth0</a> is a hosted SaaS IdP solution.</p>
<ol>
<li>
<p>Create a regular web application for Synapse</p>
@@ -6288,7 +6251,7 @@ to install Dex.</p>
display_name_template: "{{ user.name }}"
</code></pre>
<h3 id="github"><a class="header" href="#github">GitHub</a></h3>
-<p>GitHub is a bit special as it is not an OpenID Connect compliant provider, but
+<p><a href="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 <a href="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
@@ -6317,11 +6280,12 @@ does not return a <code>sub</code> property, an alternative <code>subject_claim<
localpart_template: "{{ user.login }}"
display_name_template: "{{ user.name }}"
</code></pre>
-<h3 id="a-hrefhttpsdevelopersgooglecomidentityprotocolsoauth2openid-connectgooglea"><a class="header" href="#a-hrefhttpsdevelopersgooglecomidentityprotocolsoauth2openid-connectgooglea"><a href="https://developers.google.com/identity/protocols/oauth2/openid-connect">Google</a></a></h3>
+<h3 id="google"><a class="header" href="#google">Google</a></h3>
+<p><a href="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
https://developers.google.com/identity/protocols/oauth2/openid-connect#appsetup).</li>
-<li>add an "OAuth Client ID" for a Web Application under "Credentials".</li>
+<li>Add an "OAuth Client ID" for a Web Application under "Credentials".</li>
<li>Copy the Client ID and Client Secret, and add the following to your synapse config:
<pre><code class="language-yaml">oidc_providers:
- idp_id: google
@@ -6499,6 +6463,54 @@ documentation on setting up SiWA.</p>
config:
email_template: "{{ user.email }}"
</code></pre>
+<h2 id="django-oauth-toolkit"><a class="header" href="#django-oauth-toolkit">Django OAuth Toolkit</a></h2>
+<p><a href="https://github.com/jazzband/django-oauth-toolkit">django-oauth-toolkit</a> is a
+Django application providing out of the box all the endpoints, data and logic
+needed to add OAuth2 capabilities to your Django projects. It supports
+<a href="https://django-oauth-toolkit.readthedocs.io/en/latest/oidc.html">OpenID Connect too</a>.</p>
+<p>Configuration on Django's side:</p>
+<ol>
+<li>Add an application: https://example.com/admin/oauth2_provider/application/add/ and choose parameters like this:</li>
+</ol>
+<ul>
+<li><code>Redirect uris</code>: https://synapse.example.com/_synapse/client/oidc/callback</li>
+<li><code>Client type</code>: <code>Confidential</code></li>
+<li><code>Authorization grant type</code>: <code>Authorization code</code></li>
+<li><code>Algorithm</code>: <code>HMAC with SHA-2 256</code></li>
+</ul>
+<ol start="2">
+<li>
+<p>You can <a href="https://django-oauth-toolkit.readthedocs.io/en/latest/oidc.html#customizing-the-oidc-responses">customize the claims</a> Django gives to synapse (optional):</p>
+<details>
+ <summary>Code sample</summary>
+<pre><code class="language-python">class CustomOAuth2Validator(OAuth2Validator):
+
+ def get_additional_claims(self, request):
+ return {
+ "sub": request.user.email,
+ "email": request.user.email,
+ "first_name": request.user.first_name,
+ "last_name": request.user.last_name,
+ }
+</code></pre>
+</details>
+</li>
+</ol>
+<p>Your synapse config is then:</p>
+<pre><code class="language-yaml">oidc_providers:
+ - idp_id: django_example
+ idp_name: "Django Example"
+ issuer: "https://example.com/o/"
+ client_id: "your-client-id" # CHANGE ME
+ client_secret: "your-client-secret" # CHANGE ME
+ scopes: ["openid"]
+ user_profile_method: "userinfo_endpoint" # needed because oauth-toolkit does not include user information in the authorization response
+ user_mapping_provider:
+ config:
+ localpart_template: "{{ user.email.split('@')[0] }}"
+ display_name_template: "{{ user.first_name }} {{ user.last_name }}"
+ email_template: "{{ user.email }}"
+</code></pre>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="sso-mapping-providers"><a class="header" href="#sso-mapping-providers">SSO Mapping Providers</a></h1>
<p>A mapping provider is a Python class (loaded via a Python module) that
works out how to map attributes of a SSO response to Matrix-specific
@@ -7691,6 +7703,40 @@ 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>
+<h4 id="presence-router-callbacks"><a class="header" href="#presence-router-callbacks">Presence router callbacks</a></h4>
+<p>Presence router callbacks allow module developers to specify additional users (local or remote)
+to receive certain presence updates from local users. Presence router callbacks can be
+registered using the module API's <code>register_presence_router_callbacks</code> method.</p>
+<p>The available presence router callbacks are:</p>
+<pre><code class="language-python">async def get_users_for_states(
+ self,
+ state_updates: Iterable["synapse.api.UserPresenceState"],
+) -> Dict[str, Set["synapse.api.UserPresenceState"]]:
+</code></pre>
+<p><strong>Requires</strong> <code>get_interested_users</code> to also be registered</p>
+<p>Called when processing updates to the presence state of one or more users. This callback can
+be used to instruct the server to forward that presence state to specific users. The module
+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>
+<pre><code class="language-python">async def get_interested_users(
+ self,
+ user_id: str
+) -> Union[Set[str], "synapse.module_api.PRESENCE_ALL_USERS"]
+</code></pre>
+<p><strong>Requires</strong> <code>get_users_for_states</code> to also be registered</p>
+<p>Called when determining which users someone should be able to see the presence state of. This
+callback should return complementary results to <code>get_users_for_state</code> or the presence information
+may not be properly forwarded.</p>
+<p>The callback is given the Matrix user ID for a local user that is requesting presence data and
+should return the Matrix user IDs of the users whose presence state they are allowed to
+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>For example, if the user <code>@alice:example.org</code> is passed to this method, and the Set
+<code>{"@bob:example.com", "@charlie:somewhere.org"}</code> is returned, this signifies that Alice
+should receive presence updates sent by Bob and Charlie, regardless of whether these users
+share a room.</p>
<h3 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></h3>
<p>In order to port a module that uses Synapse's old module interface, its author needs to:</p>
<ul>
@@ -7858,7 +7904,12 @@ action is blocked when at least one of the configured spam checkers flags it.</p
<p>The <a href="https://github.com/matrix-org/mjolnir">Mjolnir</a> project is a full fledged
example using the Synapse spam checking API, including a bot for dynamic
configuration.</p>
-<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="presence-router-module"><a class="header" href="#presence-router-module">Presence Router Module</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 presence router module, please see
+<a href="modules.html">this page</a>.
+</h2>
+<h1 id="presence-router-module"><a class="header" href="#presence-router-module">Presence Router Module</a></h1>
<p>Synapse supports configuring a module that can specify additional users
(local or remote) to should receive certain presence updates from local
users.</p>
@@ -8250,6 +8301,7 @@ expressions:</p>
# Registration/login requests
^/_matrix/client/(api/v1|r0|unstable)/login$
^/_matrix/client/(r0|unstable)/register$
+^/_matrix/client/unstable/org.matrix.msc3231/register/org.matrix.msc3231.login.registration_token/validity$
# Event sending requests
^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/redact
@@ -9112,19 +9164,6 @@ server admin.</p>
<p>To reclaim the disk space and return it to the operating system, you need to run
<code>VACUUM FULL;</code> on the database.</p>
<p><a href="https://www.postgresql.org/docs/current/sql-vacuum.html">https://www.postgresql.org/docs/current/sql-vacuum.html</a></p>
-<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="deprecated-purge-room-api"><a class="header" href="#deprecated-purge-room-api">Deprecated: Purge room API</a></h1>
-<p><strong>The old Purge room API is deprecated and will be removed in a future release.
-See the new <a href="admin_api/rooms.html#delete-room-api">Delete Room API</a> for more details.</strong></p>
-<p>This API will remove all trace of a room from your database.</p>
-<p>All local users must have left the room before it can be removed.</p>
-<p>The API is:</p>
-<pre><code>POST /_synapse/admin/v1/purge_room
-
-{
- "room_id": "!room:id"
-}
-</code></pre>
-<p>You must authenticate using the access token of an admin user.</p>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="shared-secret-registration"><a class="header" href="#shared-secret-registration">Shared-Secret Registration</a></h1>
<p>This API allows for the creation of users in an administrative and
non-interactive way. This is generally used for bootstrapping a Synapse
@@ -9186,6 +9225,243 @@ def generate_mac(nonce, user, password, admin=False, user_type=None):
return mac.hexdigest()
</code></pre>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="registration-tokens"><a class="header" href="#registration-tokens">Registration Tokens</a></h1>
+<p>This API allows you to manage tokens which can be used to authenticate
+registration requests, as proposed in <a href="https://github.com/govynnus/matrix-doc/blob/token-registration/proposals/3231-token-authenticated-registration.md">MSC3231</a>.
+To use it, you will need to enable the <code>registration_requires_token</code> config
+option, and authenticate by providing an <code>access_token</code> for a server admin:
+see <a href="usage/administration/admin_api/../../usage/administration/admin_api">Admin API</a>.
+Note that this API is still experimental; not all clients may support it yet.</p>
+<h2 id="registration-token-objects"><a class="header" href="#registration-token-objects">Registration token objects</a></h2>
+<p>Most endpoints make use of JSON objects that contain details about tokens.
+These objects have the following fields:</p>
+<ul>
+<li><code>token</code>: The token which can be used to authenticate registration.</li>
+<li><code>uses_allowed</code>: The number of times the token can be used to complete a
+registration before it becomes invalid.</li>
+<li><code>pending</code>: The number of pending uses the token has. When someone uses
+the token to authenticate themselves, the pending counter is incremented
+so that the token is not used more than the permitted number of times.
+When the person completes registration the pending counter is decremented,
+and the completed counter is incremented.</li>
+<li><code>completed</code>: The number of times the token has been used to successfully
+complete a registration.</li>
+<li><code>expiry_time</code>: The latest time the token is valid. Given as the number of
+milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
+To convert this into a human-readable form you can remove the milliseconds
+and use the <code>date</code> command. For example, <code>date -d '@1625394937'</code>.</li>
+</ul>
+<h2 id="list-all-tokens"><a class="header" href="#list-all-tokens">List all tokens</a></h2>
+<p>Lists all tokens and details about them. If the request is successful, the top
+level JSON object will have a <code>registration_tokens</code> key which is an array of
+registration token objects.</p>
+<pre><code>GET /_synapse/admin/v1/registration_tokens
+</code></pre>
+<p>Optional query parameters:</p>
+<ul>
+<li><code>valid</code>: <code>true</code> or <code>false</code>. If <code>true</code>, only valid tokens are returned.
+If <code>false</code>, only tokens that have expired or have had all uses exhausted are
+returned. If omitted, all tokens are returned regardless of validity.</li>
+</ul>
+<p>Example:</p>
+<pre><code>GET /_synapse/admin/v1/registration_tokens
+</code></pre>
+<pre><code>200 OK
+
+{
+ "registration_tokens": [
+ {
+ "token": "abcd",
+ "uses_allowed": 3,
+ "pending": 0,
+ "completed": 1,
+ "expiry_time": null
+ },
+ {
+ "token": "pqrs",
+ "uses_allowed": 2,
+ "pending": 1,
+ "completed": 1,
+ "expiry_time": null
+ },
+ {
+ "token": "wxyz",
+ "uses_allowed": null,
+ "pending": 0,
+ "completed": 9,
+ "expiry_time": 1625394937000 // 2021-07-04 10:35:37 UTC
+ }
+ ]
+}
+</code></pre>
+<p>Example using the <code>valid</code> query parameter:</p>
+<pre><code>GET /_synapse/admin/v1/registration_tokens?valid=false
+</code></pre>
+<pre><code>200 OK
+
+{
+ "registration_tokens": [
+ {
+ "token": "pqrs",
+ "uses_allowed": 2,
+ "pending": 1,
+ "completed": 1,
+ "expiry_time": null
+ },
+ {
+ "token": "wxyz",
+ "uses_allowed": null,
+ "pending": 0,
+ "completed": 9,
+ "expiry_time": 1625394937000 // 2021-07-04 10:35:37 UTC
+ }
+ ]
+}
+</code></pre>
+<h2 id="get-one-token"><a class="header" href="#get-one-token">Get one token</a></h2>
+<p>Get details about a single token. If the request is successful, the response
+body will be a registration token object.</p>
+<pre><code>GET /_synapse/admin/v1/registration_tokens/<token>
+</code></pre>
+<p>Path parameters:</p>
+<ul>
+<li><code>token</code>: The registration token to return details of.</li>
+</ul>
+<p>Example:</p>
+<pre><code>GET /_synapse/admin/v1/registration_tokens/abcd
+</code></pre>
+<pre><code>200 OK
+
+{
+ "token": "abcd",
+ "uses_allowed": 3,
+ "pending": 0,
+ "completed": 1,
+ "expiry_time": null
+}
+</code></pre>
+<h2 id="create-token"><a class="header" href="#create-token">Create token</a></h2>
+<p>Create a new registration token. If the request is successful, the newly created
+token will be returned as a registration token object in the response body.</p>
+<pre><code>POST /_synapse/admin/v1/registration_tokens/new
+</code></pre>
+<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>.
+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.
+Default: <code>null</code> (unlimited uses).</li>
+<li><code>expiry_time</code>: The latest time the token is valid. Given as the number of
+milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
+You could use, for example, <code>date '+%s000' -d 'tomorrow'</code>.
+Default: <code>null</code> (token does not expire).</li>
+<li><code>length</code>: The length of the token randomly generated if <code>token</code> is not
+specified. Must be between 1 and 64 inclusive. Default: <code>16</code>.</li>
+</ul>
+<p>If a field is omitted the default is used.</p>
+<p>Example using defaults:</p>
+<pre><code>POST /_synapse/admin/v1/registration_tokens/new
+
+{}
+</code></pre>
+<pre><code>200 OK
+
+{
+ "token": "0M-9jbkf2t_Tgiw1",
+ "uses_allowed": null,
+ "pending": 0,
+ "completed": 0,
+ "expiry_time": null
+}
+</code></pre>
+<p>Example specifying some fields:</p>
+<pre><code>POST /_synapse/admin/v1/registration_tokens/new
+
+{
+ "token": "defg",
+ "uses_allowed": 1
+}
+</code></pre>
+<pre><code>200 OK
+
+{
+ "token": "defg",
+ "uses_allowed": 1,
+ "pending": 0,
+ "completed": 0,
+ "expiry_time": null
+}
+</code></pre>
+<h2 id="update-token"><a class="header" href="#update-token">Update token</a></h2>
+<p>Update the number of allowed uses or expiry time of a token. If the request is
+successful, the updated token will be returned as a registration token object
+in the response body.</p>
+<pre><code>PUT /_synapse/admin/v1/registration_tokens/<token>
+</code></pre>
+<p>Path parameters:</p>
+<ul>
+<li><code>token</code>: The registration token to update.</li>
+</ul>
+<p>The request body must be a JSON object and can contain the following fields:</p>
+<ul>
+<li><code>uses_allowed</code>: The integer number of times the token can be used to complete
+a registration before it becomes invalid. By setting <code>uses_allowed</code> to <code>0</code>
+the token can be easily made invalid without deleting it.
+If <code>null</code> the token will have an unlimited number of uses.</li>
+<li><code>expiry_time</code>: The latest time the token is valid. Given as the number of
+milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
+If <code>null</code> the token will not expire.</li>
+</ul>
+<p>If a field is omitted its value is not modified.</p>
+<p>Example:</p>
+<pre><code>PUT /_synapse/admin/v1/registration_tokens/defg
+
+{
+ "expiry_time": 4781243146000 // 2121-07-06 11:05:46 UTC
+}
+</code></pre>
+<pre><code>200 OK
+
+{
+ "token": "defg",
+ "uses_allowed": 1,
+ "pending": 0,
+ "completed": 0,
+ "expiry_time": 4781243146000
+}
+</code></pre>
+<h2 id="delete-token"><a class="header" href="#delete-token">Delete token</a></h2>
+<p>Delete a registration token. If the request is successful, the response body
+will be an empty JSON object.</p>
+<pre><code>DELETE /_synapse/admin/v1/registration_tokens/<token>
+</code></pre>
+<p>Path parameters:</p>
+<ul>
+<li><code>token</code>: The registration token to delete.</li>
+</ul>
+<p>Example:</p>
+<pre><code>DELETE /_synapse/admin/v1/registration_tokens/wxyz
+</code></pre>
+<pre><code>200 OK
+
+{}
+</code></pre>
+<h2 id="errors"><a class="header" href="#errors">Errors</a></h2>
+<p>If a request fails a "standard error response" will be returned as defined in
+the <a href="https://matrix.org/docs/spec/client_server/r0.6.1#api-standards">Matrix Client-Server API specification</a>.</p>
+<p>For example, if the token specified in a path parameter does not exist a
+<code>404 Not Found</code> error will be returned.</p>
+<pre><code>GET /_synapse/admin/v1/registration_tokens/1234
+</code></pre>
+<pre><code>404 Not Found
+
+{
+ "errcode": "M_NOT_FOUND",
+ "error": "No such registration token: 1234"
+}
+</code></pre>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="edit-room-membership-api"><a class="header" href="#edit-room-membership-api">Edit Room Membership API</a></h1>
<p>This API allows an administrator to join an user account with a given <code>user_id</code>
to a room with a given <code>room_id_or_alias</code>. You can only modify the membership of
@@ -9851,94 +10127,6 @@ ignored in the same way as with <code>PUT /_matrix/client/r0/rooms/{roomId}/send
</code></pre>
<p>Note that server notices must be enabled in <code>homeserver.yaml</code> before this API
can be used. See <a href="admin_api/../server_notices.html">the server notices documentation</a> for more information.</p>
-<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="deprecated-shutdown-room-api"><a class="header" href="#deprecated-shutdown-room-api">Deprecated: Shutdown room API</a></h1>
-<p><strong>The old Shutdown room API is deprecated and will be removed in a future release.
-See the new <a href="admin_api/rooms.html#delete-room-api">Delete Room API</a> for more details.</strong></p>
-<p>Shuts down a room, preventing new joins and moves local users and room aliases automatically
-to a new room. The new room will be created with the user specified by the
-<code>new_room_user_id</code> parameter as room administrator and will contain a message
-explaining what happened. Users invited to the new room will have power level
--10 by default, and thus be unable to speak. The old room's power levels will be changed to
-disallow any further invites or joins.</p>
-<p>The local server will only have the power to move local user and room aliases to
-the new room. Users on other servers will be unaffected.</p>
-<h2 id="api-1"><a class="header" href="#api-1">API</a></h2>
-<p>You will need to authenticate with an access token for an admin user.</p>
-<h3 id="url"><a class="header" href="#url">URL</a></h3>
-<p><code>POST /_synapse/admin/v1/shutdown_room/{room_id}</code></p>
-<h3 id="url-parameters"><a class="header" href="#url-parameters">URL Parameters</a></h3>
-<ul>
-<li><code>room_id</code> - The ID of the room (e.g <code>!someroom:example.com</code>)</li>
-</ul>
-<h3 id="json-body-parameters"><a class="header" href="#json-body-parameters">JSON Body Parameters</a></h3>
-<ul>
-<li><code>new_room_user_id</code> - Required. A string representing the user ID of the user that will admin
-the new room that all users in the old room will be moved to.</li>
-<li><code>room_name</code> - Optional. A string representing the name of the room that new users will be
-invited to.</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.</li>
-</ul>
-<p>If not specified, the default value of <code>room_name</code> is "Content Violation
-Notification". The default value of <code>message</code> is "Sharing illegal content on
-othis server is not permitted and rooms in violation will be blocked."</p>
-<h3 id="response-parameters"><a class="header" href="#response-parameters">Response Parameters</a></h3>
-<ul>
-<li><code>kicked_users</code> - An integer number representing the number of users that
-were kicked.</li>
-<li><code>failed_to_kick_users</code> - An integer number representing the number of users
-that were not kicked.</li>
-<li><code>local_aliases</code> - An array of strings representing the local aliases that were migrated from
-the old room to the new.</li>
-<li><code>new_room_id</code> - A string representing the room ID of the new room.</li>
-</ul>
-<h2 id="example-4"><a class="header" href="#example-4">Example</a></h2>
-<p>Request:</p>
-<pre><code>POST /_synapse/admin/v1/shutdown_room/!somebadroom%3Aexample.com
-
-{
- "new_room_user_id": "@someuser:example.com",
- "room_name": "Content Violation Notification",
- "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service."
-}
-</code></pre>
-<p>Response:</p>
-<pre><code>{
- "kicked_users": 5,
- "failed_to_kick_users": 0,
- "local_aliases": ["#badroom:example.com", "#evilsaloon:example.com],
- "new_room_id": "!newroomid:example.com",
-},
-</code></pre>
-<h2 id="undoing-room-shutdowns-1"><a class="header" href="#undoing-room-shutdowns-1">Undoing room shutdowns</a></h2>
-<p><em>Note</em>: This guide may be outdated by the time you read it. By nature of room shutdowns 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 shutdown is very destructive. Undoing a shutdown 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.</li>
-</ul>
-<p>With all that being said, if you still want to try and recover the room:</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 shutdown room API, not the Content Violation room.</li>
-</ul>
-</li>
-<li>Restart Synapse.</li>
-</ol>
-<p>You will have to manually handle, if you so choose, the following:</p>
-<ul>
-<li>Aliases that would have been redirected to the Content Violation room.</li>
-<li>Users that would have been booted from the room (and will have been force-joined to the Content Violation room).</li>
-<li>Removal of the Content Violation room if desired.</li>
-</ul>
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="users-media-usage-statistics"><a class="header" href="#users-media-usage-statistics">Users' media usage statistics</a></h1>
<p>Returns information about all local media usage of users. Gives the
possibility to filter them by time and user.</p>
@@ -10029,11 +10217,15 @@ server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a
"threepids": [
{
"medium": "email",
- "address": "<user_mail_1>"
+ "address": "<user_mail_1>",
+ "added_at": 1586458409743,
+ "validated_at": 1586458409743
},
{
"medium": "email",
- "address": "<user_mail_2>"
+ "address": "<user_mail_2>",
+ "added_at": 1586458409743,
+ "validated_at": 1586458409743
}
],
"avatar_url": "<avatar_url>",
@@ -11268,50 +11460,8 @@ 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
small processing times.</p>
-<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><!--
- Include the contents of CONTRIBUTING.md from the project root (where GitHub likes it
- to be)
--->
-<h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
-<p>Welcome to Synapse</p>
-<p>This document aims to get you started with contributing to this repo! </p>
-<ul>
-<li><a href="development/contributing_guide.html#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></li>
-<li><a href="development/contributing_guide.html#2-what-do-i-need">2. What do I need?</a></li>
-<li><a href="development/contributing_guide.html#3-get-the-source">3. Get the source.</a></li>
-<li><a href="development/contributing_guide.html#4-install-the-dependencies">4. Install the dependencies</a>
-<ul>
-<li><a href="development/contributing_guide.html#under-unix-macos-linux-bsd-">Under Unix (macOS, Linux, BSD, ...)</a></li>
-<li><a href="development/contributing_guide.html#under-windows">Under Windows</a></li>
-</ul>
-</li>
-<li><a href="development/contributing_guide.html#5-get-in-touch">5. Get in touch.</a></li>
-<li><a href="development/contributing_guide.html#6-pick-an-issue">6. Pick an issue.</a></li>
-<li><a href="development/contributing_guide.html#7-turn-coffee-and-documentation-into-code-and-documentation">7. Turn coffee and documentation into code and documentation!</a></li>
-<li><a href="development/contributing_guide.html#8-test-test-test">8. Test, test, test!</a>
-<ul>
-<li><a href="development/contributing_guide.html#run-the-linters">Run the linters.</a></li>
-<li><a href="development/contributing_guide.html#run-the-unit-tests-twisted-trial">Run the unit tests.</a></li>
-<li><a href="development/contributing_guide.html#run-the-integration-tests-sytest">Run the integration tests (SyTest).</a></li>
-<li><a href="development/contributing_guide.html#run-the-integration-tests-complement">Run the integration tests (Complement).</a></li>
-</ul>
-</li>
-<li><a href="development/contributing_guide.html#9-submit-your-patch">9. Submit your patch.</a>
-<ul>
-<li><a href="development/contributing_guide.html#changelog">Changelog</a>
-<ul>
-<li><a href="development/contributing_guide.html#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></li>
-<li><a href="development/contributing_guide.html#debian-changelog">Debian changelog</a></li>
-</ul>
-</li>
-<li><a href="development/contributing_guide.html#sign-off">Sign off</a></li>
-</ul>
-</li>
-<li><a href="development/contributing_guide.html#10-turn-feedback-into-better-code">10. Turn feedback into better code.</a></li>
-<li><a href="development/contributing_guide.html#11-find-a-new-issue">11. Find a new issue.</a></li>
-<li><a href="development/contributing_guide.html#notes-for-maintainers-on-merging-prs-etc">Notes for maintainers on merging PRs etc</a></li>
-<li><a href="development/contributing_guide.html#conclusion">Conclusion</a></li>
-</ul>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
+<p>This document aims to get you started with contributing to Synapse!</p>
<h1 id="1-who-can-contribute-to-synapse"><a class="header" href="#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></h1>
<p>Everyone is welcome to contribute code to <a href="https://github.com/matrix-org">matrix.org
projects</a>, provided that they are willing to
@@ -11320,7 +11470,7 @@ follow a simple 'inbound=outbound' model for contributions: the act of
submitting an 'inbound' contribution means that the contributor agrees to
license the code under the same terms as the project's overall 'outbound'
license - in our case, this is almost always Apache Software License v2 (see
-<a href="development/LICENSE">LICENSE</a>).</p>
+<a href="https://github.com/matrix-org/synapse/blob/develop/LICENSE">LICENSE</a>).</p>
<h1 id="2-what-do-i-need"><a class="header" href="#2-what-do-i-need">2. What do I need?</a></h1>
<p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <a href="https://wiki.python.org/moin/BeginnersGuide/Download">a recent version of Python 3</a>.</p>
<p>The source code of Synapse is hosted on GitHub. You will also need <a href="https://github.com/git-guides/install-git">a recent version of git</a>.</p>
@@ -11353,19 +11503,27 @@ pip install tox
<h1 id="6-pick-an-issue"><a class="header" href="#6-pick-an-issue">6. Pick an issue.</a></h1>
<p>Fix your favorite problem or perhaps find a <a href="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>
-<h1 id="7-turn-coffee-and-documentation-into-code-and-documentation"><a class="header" href="#7-turn-coffee-and-documentation-into-code-and-documentation">7. Turn coffee and documentation into code and documentation!</a></h1>
-<p>Synapse's code style is documented <a href="development/docs/code_style.html">here</a>. Please follow
-it, including the conventions for the <a href="development/docs/code_style.html#configuration-file-format">sample configuration
-file</a>.</p>
-<p>There is a growing amount of documentation located in the <a href="development/docs">docs</a>
-directory. This documentation is intended primarily for sysadmins running their
+<h1 id="7-turn-coffee-into-code-and-documentation"><a class="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
+<a href="https://github.com/matrix-org/synapse/tree/develop/docs"><code>docs</code></a>
+directory, with a rendered version <a href="https://matrix-org.github.io/synapse">available online</a>.
+This documentation is intended primarily for sysadmins running their
own Synapse instance, as well as developers interacting externally with
-Synapse. <a href="development/docs/dev">docs/dev</a> exists primarily to house documentation for
-Synapse developers. <a href="development/docs/admin_api">docs/admin_api</a> houses documentation
+Synapse.
+<a href="https://github.com/matrix-org/synapse/tree/develop/docs/development"><code>docs/development</code></a>
+exists primarily to house documentation for
+Synapse developers.
+<a href="https://github.com/matrix-org/synapse/tree/develop/docs/admin_api"><code>docs/admin_api</code></a> houses documentation
regarding Synapse's Admin API, which is used mostly by sysadmins and external
service developers.</p>
-<p>If you add new files added to either of these folders, please use <a href="https://guides.github.com/features/mastering-markdown/">GitHub-Flavoured
-Markdown</a>.</p>
+<p>Synapse's code style is documented <a href="development/../code_style.html">here</a>. Please follow
+it, including the conventions for the <a href="development/../code_style.html#configuration-file-format">sample configuration
+file</a>.</p>
+<p>We welcome improvements and additions to our documentation itself! When
+writing new pages, please
+<a href="https://github.com/matrix-org/synapse/tree/develop/docs#adding-to-the-documentation">build <code>docs</code> to a book</a>
+to check that your contributions render correctly. The docs are written in
+<a href="https://guides.github.com/features/mastering-markdown/">GitHub-Flavoured Markdown</a>.</p>
<p>Some documentation also exists in <a href="https://github.com/matrix-org/synapse/wiki">Synapse's GitHub
Wiki</a>, although this is primarily
contributed to by community authors.</p>
@@ -11607,7 +11765,7 @@ flag to <code>git commit</code>, which uses the name and email set in your
<p>By now, you know the drill!</p>
<h1 id="notes-for-maintainers-on-merging-prs-etc"><a class="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
-manage git <a href="development/docs/development/git.html">here</a>.</p>
+manage git <a href="development/git.html">here</a>.</p>
<h1 id="conclusion"><a class="header" href="#conclusion">Conclusion</a></h1>
<p>That's it! Matrix is a very open and collaborative project as you might expect
given our obsession with open communication. If we're going to successfully
@@ -12535,7 +12693,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-5"><a class="header" href="#example-5">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 '>'
or '<' to indicate which side is sending, these are <em>not</em> included on
the wire:</p>
@@ -12831,7 +12989,7 @@ graph), and one where we remove redundant links (the transitive reduction of the
links graph) e.g. if we have chains <code>C3 -> C2 -> C1</code> then the link <code>C3 -> 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-6"><a class="header" href="#example-6">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
|
