diff --git a/latest/print.html b/latest/print.html
index a37d107fc5..914e5e569f 100644
--- a/latest/print.html
+++ b/latest/print.html
@@ -77,7 +77,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 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/config_documentation.html">Configuration Manual</a></li><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 "><a href="usage/configuration/user_authentication/single_sign_on/index.html">Single-Sign On</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/cas.html">CAS</a></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><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/refresh_tokens.html">Refresh 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/background_update_controller_callbacks.html">Background update controller callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_data_callbacks.html">Account data 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="usage/administration/admin_api/background_updates.html">Background Updates</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><li class="chapter-item expanded "><a href="usage/administration/admin_api/federation.html">Federation</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/understanding_synapse_through_grafana_graphs.html">Understanding Synapse Through Grafana Graphs</a></li><li class="chapter-item expanded "><a href="usage/administration/useful_sql_for_admins.html">Useful SQL for Admins</a></li><li class="chapter-item expanded "><a href="usage/administration/database_maintenance_tools.html">Database Maintenance Tools</a></li><li class="chapter-item expanded "><a href="usage/administration/state_groups.html">State Groups</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_faq.html">Admin FAQ</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/releases.html">Release Cycle</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><ol class="section"><li class="chapter-item expanded "><a href="development/demo.html">Demo scripts</a></li></ol></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 "><a href="development/dependencies.html">Dependency management</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/synapse_architecture/cancellation.html">Cancellation</a></li><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><li class="chapter-item expanded "><a href="other/running_synapse_on_single_board_computers.html">Running Synapse on a Single-Board Computer</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 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/config_documentation.html">Configuration Manual</a></li><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 "><a href="usage/configuration/user_authentication/single_sign_on/index.html">Single-Sign On</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/cas.html">CAS</a></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><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/refresh_tokens.html">Refresh 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/background_update_controller_callbacks.html">Background update controller callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_data_callbacks.html">Account data 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="usage/administration/admin_api/background_updates.html">Background Updates</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><li class="chapter-item expanded "><a href="usage/administration/admin_api/federation.html">Federation</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><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/monitoring/reporting_homeserver_usage_statistics.html">Reporting Homeserver Usage Statistics</a></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/understanding_synapse_through_grafana_graphs.html">Understanding Synapse Through Grafana Graphs</a></li><li class="chapter-item expanded "><a href="usage/administration/useful_sql_for_admins.html">Useful SQL for Admins</a></li><li class="chapter-item expanded "><a href="usage/administration/database_maintenance_tools.html">Database Maintenance Tools</a></li><li class="chapter-item expanded "><a href="usage/administration/state_groups.html">State Groups</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_faq.html">Admin FAQ</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/reviews.html">Reviewing Code</a></li><li class="chapter-item expanded "><a href="development/releases.html">Release Cycle</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><ol class="section"><li class="chapter-item expanded "><a href="development/demo.html">Demo scripts</a></li></ol></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 "><a href="development/dependencies.html">Dependency management</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/synapse_architecture/cancellation.html">Cancellation</a></li><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><li class="chapter-item expanded "><a href="other/running_synapse_on_single_board_computers.html">Running Synapse on a Single-Board Computer</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
@@ -386,7 +386,9 @@ python -m synapse.app.homeserver \
--generate-config \
--report-stats=[yes|no]
</code></pre>
-<p>... substituting an appropriate value for <code>--server-name</code>.</p>
+<p>... substituting an appropriate value for <code>--server-name</code> and choosing whether
+or not to report usage statistics (hostname, Synapse version, uptime, total
+users, etc.) to the developers via the <code>--report-stats</code> argument.</p>
<p>This command will generate you a config file that you can then customise, but it will
also generate a set of keys for you. These keys will allow your homeserver to
identify itself to other homeserver, so don't lose or delete them. It would be
@@ -501,11 +503,11 @@ over HTTPS.</p>
<p>Alternatively, you can configure Synapse to expose an HTTPS port. To do
so, you will need to edit <code>homeserver.yaml</code>, as follows:</p>
<ul>
-<li>First, under the <code>listeners</code> section, uncomment the configuration for the
-TLS-enabled listener. (Remove the hash sign (<code>#</code>) at the start of
-each line). The relevant lines are like this:</li>
+<li>First, under the <code>listeners</code> option, add the configuration for the
+TLS-enabled listener like so:</li>
</ul>
-<pre><code class="language-yaml"> - port: 8448
+<pre><code class="language-yaml">listeners:
+ - port: 8448
type: http
tls: true
resources:
@@ -513,9 +515,13 @@ each line). The relevant lines are like this:</li>
</code></pre>
<ul>
<li>
-<p>You will also need to uncomment the <code>tls_certificate_path</code> and
-<code>tls_private_key_path</code> lines under the <code>TLS</code> section. You will need to manage
-provisioning of these certificates yourself.</p>
+<p>You will also need to add the options <code>tls_certificate_path</code> and
+<code>tls_private_key_path</code>. to your configuration file. You will need to manage provisioning of
+these certificates yourself.</p>
+</li>
+<li>
+<p>You can find more information about these options as well as how to configure synapse in the
+<a href="setup/../usage/configuration/config_documentation.html">configuration manual</a>.</p>
<p>If you are using your own certificate, be sure to use a <code>.pem</code> file that
includes the full certificate chain including any intermediate certificates
(for instance, if using certbot, use <code>fullchain.pem</code> as your certificate, not
@@ -751,6 +757,13 @@ of the SQLite database file. This makes it safe to repeat step 1 if
there was a delay between taking the previous snapshot and being ready
to do step 2.</p>
<p>It is safe to at any time kill the port script and restart it.</p>
+<p>However, under no circumstances should the SQLite database be <code>VACUUM</code>ed between
+multiple runs of the script. Doing so can lead to an inconsistent copy of your database
+into Postgres.
+To avoid accidental error, the script will check that SQLite's <code>auto_vacuum</code> mechanism
+is disabled, but the script is not able to protect against a manual <code>VACUUM</code> operation
+performed either by the administrator or by any automated task that the administrator
+may have configured.</p>
<p>Note that the database may take up significantly more (25% - 100% more)
space on disk after porting to Postgres.</p>
<h3 id="using-the-port-script"><a class="header" href="#using-the-port-script">Using the port script</a></h3>
@@ -1147,8 +1160,8 @@ will apply blacklisting of IP addresses.</p>
it is most likely due to the proxy's certificates. To test this, the validation
in Synapse can be deactivated.</p>
<p><strong>NOTE</strong>: This has an impact on security and is for testing purposes only!</p>
-<p>To deactivate the certificate validation, the following setting must be made in
-<a href="setup/../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p>
+<p>To deactivate the certificate validation, the following setting must be added to
+your <a href="setup/../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p>
<pre><code class="language-yaml">use_insecure_ssl_client_just_for_testing_do_not_use: true
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="overview-1"><a class="header" href="#overview-1">Overview</a></h1>
@@ -3379,7 +3392,7 @@ query the room directory. Defaults to false.</p>
<pre><code class="language-yaml">allow_public_rooms_without_auth: true
</code></pre>
<hr />
-<h3 id="allow_public_rooms_without_auth-1"><a class="header" href="#allow_public_rooms_without_auth-1"><code>allow_public_rooms_without_auth</code></a></h3>
+<h3 id="allow_public_rooms_over_federation"><a class="header" href="#allow_public_rooms_over_federation"><code>allow_public_rooms_over_federation</code></a></h3>
<p>If set to true, allows any other homeserver to fetch the server's public
rooms directory via federation. Defaults to false.</p>
<p>Example configuration:</p>
@@ -3634,7 +3647,7 @@ The default value is 10.</p>
<pre><code class="language-yaml">dummy_events_threshold: 5
</code></pre>
<hr />
-<p>Config option <code>delete_stale_devices_after</code></p>
+<h3 id="delete_stale_devices_after"><a class="header" href="#delete_stale_devices_after"><code>delete_stale_devices_after</code></a></h3>
<p>An optional duration. If set, Synapse will run a daily background task to log out and
delete any device that hasn't been accessed for more than the specified amount of time.</p>
<p>Defaults to no duration, which means devices are never pruned.</p>
@@ -4171,6 +4184,101 @@ see <a href="usage/configuration/../../postgres.html">here</a>.</p>
cp_max: 10
</code></pre>
<hr />
+<h3 id="databases"><a class="header" href="#databases"><code>databases</code></a></h3>
+<p>The <code>databases</code> option allows specifying a mapping between certain database tables and
+database host details, spreading the load of a single Synapse instance across multiple
+database backends. This is often referred to as "database sharding". This option is only
+supported for PostgreSQL database backends.</p>
+<p><strong>Important note:</strong> This is a supported option, but is not currently used in production by the
+Matrix.org Foundation. Proceed with caution and always make backups.</p>
+<p><code>databases</code> is a dictionary of arbitrarily-named database entries. Each entry is equivalent
+to the value of the <code>database</code> homeserver config option (see above), with the addition of
+a <code>data_stores</code> key. <code>data_stores</code> is an array of strings that specifies the data store(s)
+(a defined label for a set of tables) that should be stored on the associated database
+backend entry.</p>
+<p>The currently defined values for <code>data_stores</code> are:</p>
+<ul>
+<li>
+<p><code>"state"</code>: Database that relates to state groups will be stored in this database.</p>
+<p>Specifically, that means the following tables:</p>
+<ul>
+<li><code>state_groups</code></li>
+<li><code>state_group_edges</code></li>
+<li><code>state_groups_state</code></li>
+</ul>
+<p>And the following sequences:</p>
+<ul>
+<li><code>state_groups_seq_id</code></li>
+</ul>
+</li>
+<li>
+<p><code>"main"</code>: All other database tables and sequences.</p>
+</li>
+</ul>
+<p>All databases will end up with additional tables used for tracking database schema migrations
+and any pending background updates. Synapse will create these automatically on startup when checking for
+and/or performing database schema migrations.</p>
+<p>To migrate an existing database configuration (e.g. all tables on a single database) to a different
+configuration (e.g. the "main" data store on one database, and "state" on another), do the following:</p>
+<ol>
+<li>
+<p>Take a backup of your existing database. Things can and do go wrong and database corruption is no joke!</p>
+</li>
+<li>
+<p>Ensure all pending database migrations have been applied and background updates have run. The simplest
+way to do this is to use the <code>update_synapse_database</code> script supplied with your Synapse installation.</p>
+<pre><code class="language-sh">update_synapse_database --database-config homeserver.yaml --run-background-updates
+</code></pre>
+</li>
+<li>
+<p>Copy over the necessary tables and sequences from one database to the other. Tables relating to database
+migrations, schemas, schema versions and background updates should <strong>not</strong> be copied.</p>
+<p>As an example, say that you'd like to split out the "state" data store from an existing database which
+currently contains all data stores.</p>
+<p>Simply copy the tables and sequences defined above for the "state" datastore from the existing database
+to the secondary database. As noted above, additional tables will be created in the secondary database
+when Synapse is started.</p>
+</li>
+<li>
+<p>Modify/create the <code>databases</code> option in your <code>homeserver.yaml</code> to match the desired database configuration.</p>
+</li>
+<li>
+<p>Start Synapse. Check that it starts up successfully and that things generally seem to be working.</p>
+</li>
+<li>
+<p>Drop the old tables that were copied in step 3.</p>
+</li>
+</ol>
+<p>Only one of the options <code>database</code> or <code>databases</code> may be specified in your config, but not both.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">databases:
+ basement_box:
+ name: psycopg2
+ txn_limit: 10000
+ data_stores: ["main"]
+ args:
+ user: synapse_user
+ password: secretpassword
+ database: synapse_main
+ host: localhost
+ port: 5432
+ cp_min: 5
+ cp_max: 10
+
+ my_other_database:
+ name: psycopg2
+ txn_limit: 10000
+ data_stores: ["state"]
+ args:
+ user: synapse_user
+ password: secretpassword
+ database: synapse_state
+ host: localhost
+ port: 5432
+ cp_min: 5
+ cp_max: 10
+</code></pre>
+<hr />
<h2 id="logging"><a class="header" href="#logging">Logging</a></h2>
<p>Config options related to logging. </p>
<hr />
@@ -4652,7 +4760,7 @@ Defaults to <code>https://www.recaptcha.net/recaptcha/api/siteverify</code>.</p>
<pre><code class="language-yaml">turn_shared_secret: "YOUR_SHARED_SECRET"
</code></pre>
<hr />
-<p>Config options: <code>turn_username</code> and <code>turn_password</code></p>
+<h3 id="turn_username-and-turn_password"><a class="header" href="#turn_username-and-turn_password"><code>turn_username</code> and <code>turn_password</code></a></h3>
<p>The Username and password if the TURN server needs them and does not use a token.</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">turn_username: "TURNSERVER_USERNAME"
@@ -4994,15 +5102,19 @@ performance problems on large homeservers.</p>
</code></pre>
<hr />
<h3 id="report_stats"><a class="header" href="#report_stats"><code>report_stats</code></a></h3>
-<p>Whether or not to report anonymized homeserver usage statistics. This is originally
+<p>Whether or not to report homeserver usage statistics. This is originally
set when generating the config. Set this option to true or false to change the current
-behavior. </p>
+behavior. See
+<a href="usage/configuration/../administration/monitoring/reporting_homeserver_usage_statistics.html">Reporting Homeserver Usage Statistics</a>
+for information on what data is reported.</p>
+<p>Statistics will be reported 5 minutes after Synapse starts, and then every 3 hours
+after that.</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">report_stats: true
</code></pre>
<hr />
<h3 id="report_stats_endpoint"><a class="header" href="#report_stats_endpoint"><code>report_stats_endpoint</code></a></h3>
-<p>The endpoint to report the anonymized homeserver usage statistics to.
+<p>The endpoint to report homeserver usage statistics to.
Defaults to https://matrix.org/report-usage-stats/push</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">report_stats_endpoint: https://example.com/report-usage-stats/push
@@ -5647,7 +5759,7 @@ to log in and reauthenticate, whilst preventing new users from setting passwords
<li><code>localdb_enabled</code>: Set to false to disable authentication against the local password
database. This is ignored if <code>enabled</code> is false, and is only useful
if you have other <code>password_providers</code>. Defaults to true. </li>
-<li><code>pepper</code>: Set the value here to a secret random string for extra security. # Uncomment and change to a secret random string for extra security.
+<li><code>pepper</code>: Set the value here to a secret random string for extra security.
DO NOT CHANGE THIS AFTER INITIAL SETUP!</li>
<li><code>policy</code>: Define and enforce a password policy, such as minimum lengths for passwords, etc.
Each parameter is optional. This is an implementation of MSC2000. Parameters are as follows:
@@ -6020,7 +6132,7 @@ can create aliases.</p>
action: deny
</code></pre>
<hr />
-<p>Config options: <code>room_list_publication_rules</code></p>
+<h3 id="room_list_publication_rules"><a class="header" href="#room_list_publication_rules"><code>room_list_publication_rules</code></a></h3>
<p>The <code>room_list_publication_rules</code> option controls who can publish and
which rooms can be published in the public room list.</p>
<p>The format of this option is the same as that for
@@ -6212,6 +6324,8 @@ generally required to apply any changes made to this file.</p>
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>
+<p>Documentation for all configuration options can be found in the
+<a href="usage/configuration/./config_documentation.html">Configuration Manual</a>.</p>
<pre><code class="language-yaml"># This file is maintained as an up-to-date snapshot of the default
# homeserver.yaml configuration generated by Synapse. You can find a
# complete accounting of possible configuration options at
@@ -6749,8 +6863,8 @@ maintainer.</p>
</li>
</ul>
<p>To enable the OpenID integration, you should then add a section to the <code>oidc_providers</code>
-setting in your configuration file (or uncomment one of the existing examples).
-See <a href="./sample_config.yaml">sample_config.yaml</a> for some sample settings, as well as
+setting in your configuration file.
+See the <a href="usage/configuration/config_documentation.html#oidc_providers">configuration manual</a> for some sample settings, as well as
the text below for example configurations for specific providers.</p>
<h2 id="sample-configs"><a class="header" href="#sample-configs">Sample configs</a></h2>
<p>Here are a few configs for providers that should work with Synapse.</p>
@@ -7239,8 +7353,8 @@ file</a> for more details.</p>
<p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Central_Authentication_Service">Central Authentication
Service protocol</a>
(CAS) natively.</p>
-<p>Please see the <code>cas_config</code> and <code>sso</code> sections of the <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/homeserver_sample_config.html">Synapse configuration
-file</a> for more details.</p>
+<p>Please see the <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/config_documentation.html#cas_config">cas_config</a> and <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/config_documentation.html#sso">sso</a>
+sections of the configuration manual for more details.</p>
<div 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
@@ -7650,9 +7764,8 @@ provided by <code>matrix.org</code> so no further action is needed.</p>
maintainer.</p>
</li>
</ul>
-<p>To enable the JSON web token integration, you should then add a <code>jwt_config</code> section
-to your configuration file (or uncomment the <code>enabled: true</code> line in the
-existing section). See <a href="./sample_config.yaml">sample_config.yaml</a> for some
+<p>To enable the JSON web token integration, you should then add a <code>jwt_config</code> option
+to your configuration file. See the <a href="usage/configuration/config_documentation.html#jwt_config">configuration manual</a> for some
sample settings.</p>
<h2 id="how-to-test-jwt-as-a-developer"><a class="header" href="#how-to-test-jwt-as-a-developer">How to test JWT as a developer</a></h2>
<p>Although JSON Web Tokens are typically generated from an external server, the
@@ -8268,9 +8381,9 @@ though it will always hide it from clients.</p>
delete the last message in a room. It will, however, hide it from
clients.</p>
<h2 id="server-configuration"><a class="header" href="#server-configuration">Server configuration</a></h2>
-<p>Support for this feature can be enabled and configured in the
-<code>retention</code> section of the Synapse configuration file (see the
-<a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample file</a>).</p>
+<p>Support for this feature can be enabled and configured by adding a the
+<code>retention</code> in the Synapse configuration file (see
+<a href="usage/configuration/config_documentation.html#retention">configuration manual</a>).</p>
<p>To enable support for message retention policies, set the setting
<code>enabled</code> in this section to <code>true</code>.</p>
<h3 id="default-policy"><a class="header" href="#default-policy">Default policy</a></h3>
@@ -8279,8 +8392,8 @@ configuration that is used by Synapse for every room that doesn't have a
message retention policy configured in its state. This allows server
admins to ensure that messages are never kept indefinitely in a server's
database. </p>
-<p>A default policy can be defined as such, in the <code>retention</code> section of
-the configuration file:</p>
+<p>A default policy can be defined as such, by adding the <code>retention</code> option in
+the configuration file and adding these sub-options:</p>
<pre><code class="language-yaml">default_policy:
min_lifetime: 1d
max_lifetime: 1y
@@ -8294,8 +8407,8 @@ duration (using the units <code>s</code> (seconds), <code>m</code> (minutes), <c
expired events from the database. They are only run if support for
message retention policies is enabled in the server's configuration. If
no configuration for purge jobs is configured by the server admin,
-Synapse will use a default configuration, which is described in the
-<a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample configuration file</a>.</p>
+Synapse will use a default configuration, which is described here in the
+<a href="usage/configuration/config_documentation.html#retention">configuration manual</a>.</p>
<p>Some server admins might want a finer control on when events are removed
depending on an event's room's policy. This can be done by setting the
<code>purge_jobs</code> sub-section in the <code>retention</code> section of the configuration
@@ -8336,8 +8449,8 @@ local users between its expiry date and the moment it gets purged from
the server's database.</p>
<h3 id="lifetime-limits"><a class="header" href="#lifetime-limits">Lifetime limits</a></h3>
<p>Server admins can set limits on the values of <code>max_lifetime</code> to use when
-purging old events in a room. These limits can be defined as such in the
-<code>retention</code> section of the configuration file:</p>
+purging old events in a room. These limits can be defined under the
+<code>retention</code> option in the configuration file:</p>
<pre><code class="language-yaml">allowed_lifetime_min: 1d
allowed_lifetime_max: 1y
</code></pre>
@@ -12119,9 +12232,8 @@ belonging to a user.</li>
</ul>
</li>
<li><code>external_ids</code> - array, optional. Allow setting the identifier of the external identity
-provider for SSO (Single sign-on). Details in
-<a href="admin_api/../usage/configuration/homeserver_sample_config.html">Sample Configuration File</a>
-section <code>sso</code> and <code>oidc_providers</code>.
+provider for SSO (Single sign-on). Details in the configuration manual under the
+sections <a href="admin_api/../usage/configuration/config_documentation.html#sso">sso</a> and <a href="admin_api/../usage/configuration/config_documentation.html#oidc_providers">oidc_providers</a>.
<ul>
<li><code>auth_provider</code> - string. ID of the external identity provider. Value of <code>idp_id</code>
in the homeserver configuration. Note that no error is raised if the provided
@@ -13183,8 +13295,10 @@ debugging.</p>
shell access to the server. It should therefore <strong>not</strong> be enabled in
environments where untrusted users have shell access.</p>
<h2 id="configuring-the-manhole"><a class="header" href="#configuring-the-manhole">Configuring the manhole</a></h2>
-<p>To enable it, first uncomment the <code>manhole</code> listener configuration in
-<code>homeserver.yaml</code>. The configuration is slightly different if you're using docker.</p>
+<p>To enable it, first add the <code>manhole</code> listener configuration in your
+<code>homeserver.yaml</code>. You can find information on how to do that
+in the <a href="usage/configuration/config_documentation.html#manhole_settings">configuration manual</a>.
+The configuration is slightly different if you're using docker.</p>
<h4 id="docker-config"><a class="header" href="#docker-config">Docker config</a></h4>
<p>If you are using Docker, set <code>bind_addresses</code> to <code>['0.0.0.0']</code> as shown:</p>
<pre><code class="language-yaml">listeners:
@@ -13481,6 +13595,80 @@ renamed.</p>
<tr><td>python_twisted_reactor_pending_calls</td><td>reactor_pending_calls</td></tr>
<tr><td>python_twisted_reactor_tick_time</td><td>reactor_tick_time</td></tr>
</tbody></table>
+<div style="break-before: page; page-break-before: always;"></div><h1 id="reporting-homeserver-usage-statistics"><a class="header" href="#reporting-homeserver-usage-statistics">Reporting Homeserver Usage Statistics</a></h1>
+<p>When generating your Synapse configuration file, you are asked whether you
+would like to report usage statistics to Matrix.org. These statistics
+provide the foundation a glimpse into the number of Synapse homeservers
+participating in the network, as well as statistics such as the number of
+rooms being created and messages being sent. This feature is sometimes
+affectionately called "phone home" stats. Reporting
+<a href="usage/administration/monitoring/../../configuration/config_documentation.html#report_stats">is optional</a>
+and the reporting endpoint
+<a href="usage/administration/monitoring/../../configuration/config_documentation.html#report_stats_endpoint">can be configured</a>,
+in case you would like to instead report statistics from a set of homeservers
+to your own infrastructure.</p>
+<p>This documentation aims to define the statistics available and the
+homeserver configuration options that exist to tweak it.</p>
+<h2 id="available-statistics"><a class="header" href="#available-statistics">Available Statistics</a></h2>
+<p>The following statistics are sent to the configured reporting endpoint:</p>
+<table><thead><tr><th>Statistic Name</th><th>Type</th><th>Description</th></tr></thead><tbody>
+<tr><td><code>homeserver</code></td><td>string</td><td>The homeserver's server name.</td></tr>
+<tr><td><code>memory_rss</code></td><td>int</td><td>The memory usage of the process (in kilobytes on Unix-based systems, bytes on MacOS).</td></tr>
+<tr><td><code>cpu_average</code></td><td>int</td><td>CPU time in % of a single core (not % of all cores).</td></tr>
+<tr><td><code>server_context</code></td><td>string</td><td>An arbitrary string used to group statistics from a set of homeservers.</td></tr>
+<tr><td><code>timestamp</code></td><td>int</td><td>The current time, represented as the number of seconds since the epoch.</td></tr>
+<tr><td><code>uptime_seconds</code></td><td>int</td><td>The number of seconds since the homeserver was last started.</td></tr>
+<tr><td><code>python_version</code></td><td>string</td><td>The Python version number in use (e.g "3.7.1"). Taken from <code>sys.version_info</code>.</td></tr>
+<tr><td><code>total_users</code></td><td>int</td><td>The number of registered users on the homeserver.</td></tr>
+<tr><td><code>total_nonbridged_users</code></td><td>int</td><td>The number of users, excluding those created by an Application Service.</td></tr>
+<tr><td><code>daily_user_type_native</code></td><td>int</td><td>The number of native users created in the last 24 hours.</td></tr>
+<tr><td><code>daily_user_type_guest</code></td><td>int</td><td>The number of guest users created in the last 24 hours.</td></tr>
+<tr><td><code>daily_user_type_bridged</code></td><td>int</td><td>The number of users created by Application Services in the last 24 hours.</td></tr>
+<tr><td><code>total_room_count</code></td><td>int</td><td>The total number of rooms present on the homeserver.</td></tr>
+<tr><td><code>daily_active_users</code></td><td>int</td><td>The number of unique users<sup class="footnote-reference"><a href="#1">1</a></sup> that have used the homeserver in the last 24 hours.</td></tr>
+<tr><td><code>monthly_active_users</code></td><td>int</td><td>The number of unique users<sup class="footnote-reference"><a href="#1">1</a></sup> that have used the homeserver in the last 30 days.</td></tr>
+<tr><td><code>daily_active_rooms</code></td><td>int</td><td>The number of rooms that have had a (state) event with the type <code>m.room.message</code> sent in them in the last 24 hours.</td></tr>
+<tr><td><code>daily_active_e2ee_rooms</code></td><td>int</td><td>The number of rooms that have had a (state) event with the type <code>m.room.encrypted</code> sent in them in the last 24 hours.</td></tr>
+<tr><td><code>daily_messages</code></td><td>int</td><td>The number of (state) events with the type <code>m.room.message</code> seen in the last 24 hours.</td></tr>
+<tr><td><code>daily_e2ee_messages</code></td><td>int</td><td>The number of (state) events with the type <code>m.room.encrypted</code> seen in the last 24 hours.</td></tr>
+<tr><td><code>daily_sent_messages</code></td><td>int</td><td>The number of (state) events sent by a local user with the type <code>m.room.message</code> seen in the last 24 hours.</td></tr>
+<tr><td><code>daily_sent_e2ee_messages</code></td><td>int</td><td>The number of (state) events sent by a local user with the type <code>m.room.encrypted</code> seen in the last 24 hours.</td></tr>
+<tr><td><code>r30_users_all</code></td><td>int</td><td>The number of 30 day retained users, defined as users who have created their accounts more than 30 days ago, where they were last seen at most 30 days ago and where those two timestamps are over 30 days apart. Includes clients that do not fit into the below r30 client types.</td></tr>
+<tr><td><code>r30_users_android</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "Android" in the user agent string.</td></tr>
+<tr><td><code>r30_users_ios</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "iOS" in the user agent string.</td></tr>
+<tr><td><code>r30_users_electron</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "Electron" in the user agent string.</td></tr>
+<tr><td><code>r30_users_web</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "Mozilla" or "Gecko" in the user agent string.</td></tr>
+<tr><td><code>r30v2_users_all</code></td><td>int</td><td>The number of 30 day retained users, with a revised algorithm. Defined as users that appear more than once in the past 60 days, and have more than 30 days between the most and least recent appearances in the past 60 days. Includes clients that do not fit into the below r30 client types.</td></tr>
+<tr><td><code>r30v2_users_android</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "android" (case-insensitive) in the user agent string.</td></tr>
+<tr><td><code>r30v2_users_ios</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "ios" (case-insensitive) in the user agent string.</td></tr>
+<tr><td><code>r30v2_users_electron</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "electron" (case-insensitive) in the user agent string.</td></tr>
+<tr><td><code>r30v2_users_web</code></td><td>int</td><td>The number of 30 day retained users, as defined above. Filtered only to clients with "mozilla" or "gecko" (case-insensitive) in the user agent string.</td></tr>
+<tr><td><code>cache_factor</code></td><td>int</td><td>The configured <a href="usage/administration/monitoring/../../configuration/config_documentation.html#caching"><code>global factor</code></a> value for caching.</td></tr>
+<tr><td><code>event_cache_size</code></td><td>int</td><td>The configured <a href="usage/administration/monitoring/../../configuration/config_documentation.html#caching"><code>event_cache_size</code></a> value for caching.</td></tr>
+<tr><td><code>database_engine</code></td><td>string</td><td>The database engine that is in use. Either "psycopg2" meaning PostgreSQL is in use, or "sqlite3" for SQLite3.</td></tr>
+<tr><td><code>database_server_version</code></td><td>string</td><td>The version of the database server. Examples being "10.10" for PostgreSQL server version 10.0, and "3.38.5" for SQLite 3.38.5 installed on the system.</td></tr>
+<tr><td><code>log_level</code></td><td>string</td><td>The log level in use. Examples are "INFO", "WARNING", "ERROR", "DEBUG", etc.</td></tr>
+</tbody></table>
+<div class="footnote-definition" id="1"><sup class="footnote-definition-label">1</sup>
+<p>Native matrix users and guests are always counted. If the
+<a href="usage/administration/monitoring/../../configuration/config_documentation.html#track_puppeted_user_ips"><code>track_puppeted_user_ips</code></a>
+option is set to <code>true</code>, "puppeted" users (users that an Application Service have performed
+<a href="https://spec.matrix.org/v1.3/application-service-api/#identity-assertion">an action on behalf of</a>)
+will also be counted. Note that an Application Service can "puppet" any user in their
+<a href="https://spec.matrix.org/v1.3/application-service-api/#registration">user namespace</a>,
+not only users that the Application Service has created. If this happens, the Application Service
+will additionally be counted as a user (irrespective of <code>track_puppeted_user_ips</code>).</p>
+</div>
+<h2 id="using-a-custom-statistics-collection-server"><a class="header" href="#using-a-custom-statistics-collection-server">Using a Custom Statistics Collection Server</a></h2>
+<p>If statistics reporting is enabled, the endpoint that Synapse sends metrics to is configured by the
+<a href="usage/administration/monitoring/../../configuration/config_documentation.html#report_stats_endpoint"><code>report_stats_endpoint</code></a> config
+option. By default, statistics are sent to Matrix.org.</p>
+<p>If you would like to set up your own statistics collection server and send metrics there, you may
+consider using one of the following known implementations:</p>
+<ul>
+<li><a href="https://github.com/matrix-org/panopticon">Matrix.org's Panopticon</a></li>
+<li><a href="https://gitlab.com/famedly/company/devops/services/barad-dur">Famedly's Barad-dûr</a></li>
+</ul>
<div style="break-before: page; page-break-before: always;"></div><h2 id="understanding-synapse-through-grafana-graphs"><a class="header" href="#understanding-synapse-through-grafana-graphs">Understanding Synapse through Grafana graphs</a></h2>
<p>It is possible to monitor much of the internal state of Synapse using <a href="https://prometheus.io">Prometheus</a>
metrics and <a href="https://grafana.com/">Grafana</a>.
@@ -14024,6 +14212,9 @@ Here is how to run your local Synapse checkout against your local Complement che
<li>Passing <code>POSTGRES=1</code> as an environment variable to use the Postgres database instead.</li>
<li>Passing <code>WORKERS=1</code> as an environment variable to use a workerised setup instead. This option implies the use of Postgres.</li>
</ul>
+<p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>, e.g:</p>
+<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages
+</code></pre>
<h3 id="prettier-formatting-with-gotestfmt"><a class="header" href="#prettier-formatting-with-gotestfmt">Prettier formatting with <code>gotestfmt</code></a></h3>
<p>If you want to format the output of the tests the same way as it looks in CI,
install <a href="https://github.com/haveyoudebuggedit/gotestfmt">gotestfmt</a>.</p>
@@ -14050,7 +14241,7 @@ install <a href="https://github.com/haveyoudebuggedit/gotestfmt">gotestfmt</a>.<
<li><code>git push</code> your commit to your fork of Synapse;</li>
<li>on GitHub, <a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request">create the Pull Request</a>;</li>
<li>add a <a href="development/contributing_guide.html#changelog">changelog entry</a> and push it to your Pull Request;</li>
-<li>for most contributors, that's all - however, if you are a member of the organization <code>matrix-org</code>, on GitHub, please request a review from <code>matrix.org / Synapse Core</code>.</li>
+<li>that's it for now, a non-draft pull request will automatically request review from the team;</li>
<li>if you need to update your PR, please avoid rebasing and just add new commits to your branch.</li>
</ol>
<h2 id="changelog"><a class="header" href="#changelog">Changelog</a></h2>
@@ -14199,7 +14390,11 @@ be required.</p>
<li>If there is any error, fix the error.</li>
</ul>
</li>
-<li>If a developer has requested changes, make these changes and let us know if it is ready for a developer to review again.</li>
+<li>If a developer has requested changes, make these changes and let us know if it is ready for a developer to review again.
+<ul>
+<li>A pull request is a conversation, if you disagree with the suggestions, please respond and discuss it.</li>
+</ul>
+</li>
<li>Create a new commit with the changes.
<ul>
<li>Please do NOT overwrite the history. New commits make the reviewer's life easier.</li>
@@ -14207,6 +14402,8 @@ be required.</p>
</ul>
</li>
<li>Back to 1.</li>
+<li>Once the pull request is ready for review again please re-request review from whichever developer did your initial
+review (or leave a comment in the pull request that you believe all required changes have been done).</li>
</ol>
<p>Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly!</p>
<h1 id="11-find-a-new-issue"><a class="header" href="#11-find-a-new-issue">11. Find a new issue.</a></h1>
@@ -14286,99 +14483,97 @@ relative imports (<code>from .types import UserID</code>).</p>
</ul>
</li>
</ul>
-<h2 id="configuration-file-format"><a class="header" href="#configuration-file-format">Configuration file format</a></h2>
-<p>The <a href="./sample_config.yaml">sample configuration file</a> acts as a
+<h2 id="configuration-code-and-documentation-format"><a class="header" href="#configuration-code-and-documentation-format">Configuration code and documentation format</a></h2>
+<p>When adding a configuration option to the code, if several settings are grouped into a single dict, ensure that your code
+correctly handles the top-level option being set to <code>None</code> (as it will be if no sub-options are enabled).</p>
+<p>The <a href="usage/configuration/config_documentation.html">configuration manual</a> acts as a
reference to Synapse's configuration options for server administrators.
Remember that many readers will be unfamiliar with YAML and server
-administration in general, so that it is important that the file be as
-easy to understand as possible, which includes following a consistent
-format.</p>
+administration in general, so it is important that when you add
+a configuration option the documentation be as easy to understand as possible, which
+includes following a consistent format.</p>
<p>Some guidelines follow:</p>
<ul>
<li>
-<p>Sections should be separated with a heading consisting of a single
-line prefixed and suffixed with <code>##</code>. There should be <strong>two</strong> blank
-lines before the section header, and <strong>one</strong> after.</p>
-</li>
-<li>
-<p>Each option should be listed in the file with the following format:</p>
+<p>Each option should be listed in the config manual with the following format:</p>
<ul>
<li>
-<p>A comment describing the setting. Each line of this comment
-should be prefixed with a hash (<code>#</code>) and a space.</p>
-<p>The comment should describe the default behaviour (ie, what
-happens if the setting is omitted), as well as what the effect
-will be if the setting is changed.</p>
-<p>Often, the comment end with something like "uncomment the
-following to <do action>".</p>
+<p>The name of the option, prefixed by <code>###</code>. </p>
</li>
<li>
-<p>A line consisting of only <code>#</code>.</p>
+<p>A comment which describes the default behaviour (i.e. what
+happens if the setting is omitted), as well as what the effect
+will be if the setting is changed.</p>
</li>
<li>
-<p>A commented-out example setting, prefixed with only <code>#</code>.</p>
+<p>An example setting, using backticks to define the code block</p>
<p>For boolean (on/off) options, convention is that this example
-should be the <em>opposite</em> to the default (so the comment will end
-with "Uncomment the following to enable [or disable]
-<feature>." For other options, the example should give some
-non-default value which is likely to be useful to the reader.</p>
+should be the <em>opposite</em> to the default. For other options, the example should give
+some non-default value which is likely to be useful to the reader.</p>
</li>
</ul>
</li>
<li>
-<p>There should be a blank line between each option.</p>
-</li>
-<li>
-<p>Where several settings are grouped into a single dict, <em>avoid</em> the
-convention where the whole block is commented out, resulting in
-comment lines starting <code># #</code>, as this is hard to read and confusing
-to edit. Instead, leave the top-level config option uncommented, and
-follow the conventions above for sub-options. Ensure that your code
-correctly handles the top-level option being set to <code>None</code> (as it
-will be if no sub-options are enabled).</p>
-</li>
-<li>
-<p>Lines should be wrapped at 80 characters.</p>
-</li>
-<li>
-<p>Use two-space indents.</p>
+<p>There should be a horizontal rule between each option, which can be achieved by adding <code>---</code> before and
+after the option.</p>
</li>
<li>
<p><code>true</code> and <code>false</code> are spelt thus (as opposed to <code>True</code>, etc.)</p>
</li>
-<li>
-<p>Use single quotes (<code>'</code>) rather than double-quotes (<code>"</code>) or backticks
-(<code>`</code>) to refer to configuration options.</p>
-</li>
</ul>
<p>Example:</p>
-<pre><code class="language-yaml">## Frobnication ##
-
-# The frobnicator will ensure that all requests are fully frobnicated.
-# To enable it, uncomment the following.
-#
-#frobnicator_enabled: true
-
-# By default, the frobnicator will frobnicate with the default frobber.
-# The following will make it use an alternative frobber.
-#
-#frobincator_frobber: special_frobber
-
-# Settings for the frobber
-#
-frobber:
- # frobbing speed. Defaults to 1.
- #
- #speed: 10
-
- # frobbing distance. Defaults to 1000.
- #
- #distance: 100
+<hr />
+<h3 id="modules-3"><a class="header" href="#modules-3"><code>modules</code></a></h3>
+<p>Use the <code>module</code> sub-option to add a module under <code>modules</code> to extend functionality.
+The <code>module</code> setting then has a sub-option, <code>config</code>, which can be used to define some configuration
+for the <code>module</code>.</p>
+<p>Defaults to none.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">modules:
+ - module: my_super_module.MySuperClass
+ config:
+ do_thing: true
+ - module: my_other_super_module.SomeClass
+ config: {}
</code></pre>
+<hr />
<p>Note that the sample configuration is generated from the synapse code
and is maintained by a script, <code>scripts-dev/generate_sample_config.sh</code>.
Making sure that the output from this script matches the desired format
is left as an exercise for the reader!</p>
+<div style="break-before: page; page-break-before: always;"></div><h1 id="some-notes-on-how-we-do-reviews"><a class="header" href="#some-notes-on-how-we-do-reviews">Some notes on how we do reviews</a></h1>
+<p>The Synapse team works off a shared review queue -- any new pull requests for
+Synapse (or related projects) has a review requested from the entire team. Team
+members should process this queue using the following rules:</p>
+<ul>
+<li>Any high urgency pull requests (e.g. fixes for broken continuous integration
+or fixes for release blockers);</li>
+<li>Follow-up reviews for pull requests which have previously received reviews;</li>
+<li>Any remaining pull requests.</li>
+</ul>
+<p>For the latter two categories above, older pull requests should be prioritised.</p>
+<p>It is explicit that there is no priority given to pull requests from the team
+(vs from the community). If a pull request requires a quick turn around, please
+explicitly communicate this via <a href="https://matrix.to/#/#synapse-dev:matrix.org">#synapse-dev:matrix.org</a>
+or as a comment on the pull request.</p>
+<p>Once an initial review has been completed and the author has made additional changes,
+follow-up reviews should go back to the same reviewer. This helps build a shared
+context and conversation between author and reviewer.</p>
+<p>As a team we aim to keep the number of inflight pull requests to a minimum to ensure
+that ongoing work is finished before starting new work.</p>
+<h2 id="performing-a-review"><a class="header" href="#performing-a-review">Performing a review</a></h2>
+<p>To communicate to the rest of the team the status of each pull request, team
+members should do the following:</p>
+<ul>
+<li>Assign themselves to the pull request (they should be left assigned to the
+pull request until it is merged, closed, or are no longer the reviewer);</li>
+<li>Review the pull request by leaving comments, questions, and suggestions;</li>
+<li>Mark the pull request appropriately (as needing changes or accepted).</li>
+</ul>
+<p>If you are unsure about a particular part of the pull request (or are not confident
+in your understanding of part of the code) then ask questions or request review
+from the team again. When requesting review from the team be sure to leave a comment
+with the rationale on why you're putting it back in the queue.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="synapse-release-cycle"><a class="header" href="#synapse-release-cycle">Synapse Release Cycle</a></h1>
<p>Releases of Synapse follow a two week release cycle with new releases usually
occurring on Tuesdays:</p>
|
