diff options
| author | reivilibre <reivilibre@users.noreply.github.com> | 2022-08-02 10:56:24 +0000 |
|---|---|---|
| committer | reivilibre <reivilibre@users.noreply.github.com> | 2022-08-02 10:56:24 +0000 |
| commit | be84aeacf620d9eb01de07a52d67bd4035985fbd (patch) | |
| tree | 3f0a6fafff1d4acb044de19a97c3aebde1347da2 /latest/print.html | |
| parent | deploy: cb209638ea8f5ad1ea069e850d295fdadf198e68 (diff) | |
| download | synapse-be84aeacf620d9eb01de07a52d67bd4035985fbd.tar.xz | |
deploy: c2f48712265de92bd833a15f86935bed1f1efbe5
Diffstat (limited to 'latest/print.html')
| -rw-r--r-- | latest/print.html | 572 |
1 files changed, 268 insertions, 304 deletions
diff --git a/latest/print.html b/latest/print.html index c3542a0c40..5ab6177cef 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><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> + <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="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> @@ -909,57 +909,27 @@ to proxied traffic.)</p> } } </code></pre> -<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 - } - - proxy /_synapse/client http://localhost:8008 { - transparent - } -} - -example.com:8448 { - proxy / http://localhost:8008 { - transparent - } -} -</code></pre> <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 + reverse_proxy /_matrix/* localhost:8008 + reverse_proxy /_synapse/client/* localhost:8008 } example.com:8448 { - reverse_proxy http://localhost:8008 + reverse_proxy localhost:8008 } </code></pre> <p><a href="delegate.html">Delegation</a> example:</p> -<pre><code>(matrix-well-known-header) { - # Headers - header Access-Control-Allow-Origin "*" - header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" - header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization" - header Content-Type "application/json" -} - -example.com { - handle /.well-known/matrix/server { - import matrix-well-known-header - respond `{"m.server":"matrix.example.com:443"}` - } - - handle /.well-known/matrix/client { - import matrix-well-known-header - respond `{"m.homeserver":{"base_url":"https://matrix.example.com"},"m.identity_server":{"base_url":"https://identity.example.com"}}` - } +<pre><code>example.com { + header /.well-known/matrix/* Content-Type application/json + header /.well-known/matrix/* Access-Control-Allow-Origin * + respond /.well-known/matrix/server `{"m.server": "matrix.example.com:443"}` + respond /.well-known/matrix/client `{"m.homeserver":{"base_url":"https://matrix.example.com"},"m.identity_server":{"base_url":"https://identity.example.com"}}` } matrix.example.com { - reverse_proxy /_matrix/* http://localhost:8008 - reverse_proxy /_synapse/client/* http://localhost:8008 + reverse_proxy /_matrix/* localhost:8008 + reverse_proxy /_synapse/client/* localhost:8008 } </code></pre> <h3 id="apache"><a class="header" href="#apache">Apache</a></h3> @@ -1642,6 +1612,26 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb </code></pre> </li> </ul> +<h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1> +<h2 id="deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers"><a class="header" href="#deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers">Deprecation of the ability to delegate e-mail verification to identity servers</a></h2> +<p>Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.</p> +<p>If you require your homeserver to verify e-mail addresses or to support password resets via e-mail, please configure your homeserver with SMTP access so that it can send e-mails on its own behalf. +<a href="https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email">Consult the configuration documentation for more information.</a></p> +<p>The option that will be removed is <code>account_threepid_delegates.email</code>.</p> +<h2 id="changes-to-the-event-replication-streams"><a class="header" href="#changes-to-the-event-replication-streams">Changes to the event replication streams</a></h2> +<p>Synapse now includes a flag indicating if an event is an outlier when +replicating it to other workers. This is a forwards- and backwards-incompatible +change: v1.63 and workers cannot process events replicated by v1.64 workers, and +vice versa.</p> +<p>Once all workers are upgraded to v1.64 (or downgraded to v1.63), event +replication will resume as normal.</p> +<h2 id="frozendict-release"><a class="header" href="#frozendict-release">frozendict release</a></h2> +<p><a href="https://github.com/Marco-Sulla/python-frozendict/releases/tag/v2.3.3">frozendict 2.3.3</a> +has recently been released, which fixes a memory leak that occurs during <code>/sync</code> +requests. We advise server administrators who installed Synapse via pip to upgrade +frozendict with <code>pip install --upgrade frozendict</code>. The Docker image +<code>matrixdotorg/synapse</code> and the Debian packages from <code>packages.matrix.org</code> already +include the updated library.</p> <h1 id="upgrading-to-v1620"><a class="header" href="#upgrading-to-v1620">Upgrading to v1.62.0</a></h1> <h2 id="new-signatures-for-spam-checker-callbacks"><a class="header" href="#new-signatures-for-spam-checker-callbacks">New signatures for spam checker callbacks</a></h2> <p>As a followup to changes in v1.60.0, the following spam-checker callbacks have changed signature:</p> @@ -3158,12 +3148,12 @@ useful just for development purposes. See <p>This section contains information on tweaking Synapse via the various options in the configuration file. A configuration file should have been generated when you <a href="usage/configuration/../../setup/installation.html">installed Synapse</a>.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="configuring-synapse"><a class="header" href="#configuring-synapse">Configuring Synapse</a></h1> -<p>This is intended as a guide to the Synapse configuration. The behavior of a Synapse instance can be modified -through the many configuration settings documented here — each config option is explained, +<p>This is intended as a guide to the Synapse configuration. The behavior of a Synapse instance can be modified +through the many configuration settings documented here — each config option is explained, including what the default is, how to change the default and what sort of behaviour the setting governs. -Also included is an example configuration for each setting. If you don't want to spend a lot of time +Also included is an example configuration for each setting. If you don't want to spend a lot of time thinking about options, the config as generated sets sensible defaults for all values. Do note however that the -database defaults to SQLite, which is not recommended for production usage. You can read more on this subject +database defaults to SQLite, which is not recommended for production usage. You can read more on this subject <a href="usage/configuration/../../setup/installation.html#using-postgresql">here</a>.</p> <h2 id="config-conventions"><a class="header" href="#config-conventions">Config Conventions</a></h2> <p>Configuration options that take a time period can be set using a number @@ -3181,16 +3171,16 @@ messages from the database after 5 minutes, rather than 5 months.</p> <p>In addition, configuration options referring to size use the following suffixes:</p> <ul> <li><code>M</code> = MiB, or 1,048,576 bytes</li> -<li><code>K</code> = KiB, or 1024 bytes </li> +<li><code>K</code> = KiB, or 1024 bytes</li> </ul> <p>For example, setting <code>max_avatar_size: 10M</code> means that Synapse will not accept files larger than 10,485,760 bytes -for a user avatar. </p> +for a user avatar.</p> <h3 id="yaml"><a class="header" href="#yaml">YAML</a></h3> <p>The configuration file is a <a href="https://yaml.org/">YAML</a> file, which means that certain syntax rules apply if you want your config file to be read properly. A few helpful things to know:</p> <ul> <li> -<p><code>#</code> before any option in the config will comment out that setting and either a default (if available) will +<p><code>#</code> before any option in the config will comment out that setting and either a default (if available) will be applied or Synapse will ignore the setting. Thus, in example #1 below, the setting will be read and applied, but in example #2 the setting will not be read and a default will be applied.</p> <p>Example #1:</p> @@ -3209,7 +3199,7 @@ is read as a sub-option of the <code>presence</code> setting, and will be proper that when reading the config, Synapse will consider both <code>presence</code> and <code>enabled</code> as different settings. In this case, <code>presence</code> has no value, and thus a default applied, and <code>enabled</code> is an option that Synapse doesn't recognize and thus ignores.</p> -<p>Example #1: </p> +<p>Example #1:</p> <pre><code class="language-yaml">presence: enabled: false </code></pre> @@ -3217,11 +3207,11 @@ is an option that Synapse doesn't recognize and thus ignores.</p> <pre><code class="language-yaml">presence: enabled: false </code></pre> -<p>In this manual, all top-level settings (ones with no indentation) are identified -at the beginning of their section (i.e. "### <code>example_setting</code>") and -the sub-options, if any, are identified and listed in the body of the section. +<p>In this manual, all top-level settings (ones with no indentation) are identified +at the beginning of their section (i.e. "### <code>example_setting</code>") and +the sub-options, if any, are identified and listed in the body of the section. In addition, each setting has an example of its usage, with the proper indentation -shown. </p> +shown.</p> </li> </ul> <h2 id="contents"><a class="header" href="#contents">Contents</a></h2> @@ -3252,7 +3242,7 @@ shown. </p> documentation on how to configure or create custom modules for Synapse.</p> <hr /> <h3 id="modules-1"><a class="header" href="#modules-1"><code>modules</code></a></h3> -<p>Use the <code>module</code> sub-option to add modules under this option to extend functionality. +<p>Use the <code>module</code> sub-option to add modules under this option 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> @@ -3282,9 +3272,9 @@ a clean <code>server_name</code>.</p> <p>The <code>server_name</code> cannot be changed later so it is important to configure this correctly before you start Synapse. It should be all lowercase and may contain an explicit port.</p> -<p>There is no default for this option. </p> +<p>There is no default for this option.</p> <p>Example configuration #1:</p> -<pre><code class="language-yaml">server_name: matrix.org +<pre><code class="language-yaml">server_name: matrix.org </code></pre> <p>Example configuration #2:</p> <pre><code class="language-yaml">server_name: localhost:8080 @@ -3297,7 +3287,7 @@ lowercase and may contain an explicit port.</p> </code></pre> <hr /> <h3 id="web_client_location"><a class="header" href="#web_client_location"><code>web_client_location</code></a></h3> -<p>The absolute URL to the web client which <code>/</code> will redirect to. Defaults to none. </p> +<p>The absolute URL to the web client which <code>/</code> will redirect to. Defaults to none.</p> <p>Example configuration:</p> <pre><code class="language-yaml">web_client_location: https://riot.example.com/ </code></pre> @@ -3318,7 +3308,7 @@ Otherwise, it should be the URL to reach Synapse's client HTTP listener (see <p>By default, other servers will try to reach our server on port 8448, which can be inconvenient in some environments.</p> <p>Provided <code>https://<server_name>/</code> on port 443 is routed to Synapse, this -option configures Synapse to serve a file at <code>https://<server_name>/.well-known/matrix/server</code>. +option configures Synapse to serve a file at <code>https://<server_name>/.well-known/matrix/server</code>. This will tell other servers to send traffic to port 443 instead.</p> <p>This option currently defaults to false.</p> <p>See https://matrix-org.github.io/synapse/latest/delegate.html for more @@ -3330,11 +3320,12 @@ information.</p> <h3 id="extra_well_known_client_content"><a class="header" href="#extra_well_known_client_content"><code>extra_well_known_client_content </code></a></h3> <p>This option allows server runners to add arbitrary key-value pairs to the <a href="https://spec.matrix.org/latest/client-server-api/#well-known-uri">client-facing <code>.well-known</code> response</a>. Note that the <code>public_baseurl</code> config option must be provided for Synapse to serve a response to <code>/.well-known/matrix/client</code> at all.</p> -<p>If this option is provided, it parses the given yaml to json and +<p>If this option is provided, it parses the given yaml to json and serves it on <code>/.well-known/matrix/client</code> endpoint alongside the standard properties.</p> +<p><em>Added in Synapse 1.62.0.</em></p> <p>Example configuration:</p> -<pre><code class="language-yaml">extra_well_known_client_content : +<pre><code class="language-yaml">extra_well_known_client_content : option1: value1 option2: value2 </code></pre> @@ -3342,15 +3333,15 @@ alongside the standard properties.</p> <h3 id="soft_file_limit"><a class="header" href="#soft_file_limit"><code>soft_file_limit</code></a></h3> <p>Set the soft limit on the number of file descriptors synapse can use. Zero is used to indicate synapse should set the soft limit to the hard limit. -Defaults to 0. </p> +Defaults to 0.</p> <p>Example configuration:</p> <pre><code class="language-yaml">soft_file_limit: 3 </code></pre> <hr /> <h3 id="presence"><a class="header" href="#presence"><code>presence</code></a></h3> <p>Presence tracking allows users to see the state (e.g online/offline) -of other local and remote users. Set the <code>enabled</code> sub-option to false to<br /> -disable presence tracking on this homeserver. Defaults to true. +of other local and remote users. Set the <code>enabled</code> sub-option to false to +disable presence tracking on this homeserver. Defaults to true. This option replaces the previous top-level 'use_presence' option.</p> <p>Example configuration:</p> <pre><code class="language-yaml">presence: @@ -3358,8 +3349,8 @@ This option replaces the previous top-level 'use_presence' option.</p> </code></pre> <hr /> <h3 id="require_auth_for_profile_requests"><a class="header" href="#require_auth_for_profile_requests"><code>require_auth_for_profile_requests</code></a></h3> -<p>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 +<p>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 API, unless <code>allow_profile_lookup_over_federation</code> is set to false.</p> <p>Example configuration:</p> <pre><code class="language-yaml">require_auth_for_profile_requests: true @@ -3367,10 +3358,10 @@ via the federation API, unless <code>allow_profile_lookup_over_federation</code> <hr /> <h3 id="limit_profile_requests_to_users_who_share_rooms"><a class="header" href="#limit_profile_requests_to_users_who_share_rooms"><code>limit_profile_requests_to_users_who_share_rooms</code></a></h3> <p>Use this option to require a user to share a room with another user in order -to retrieve their profile information. Only checked on Client-Server +to retrieve their profile information. Only checked on Client-Server requests. Profile requests from other servers should be checked by the requesting server. Defaults to false.</p> -<p>Example configuration: </p> +<p>Example configuration:</p> <pre><code class="language-yaml">limit_profile_requests_to_users_who_share_rooms: true </code></pre> <hr /> @@ -3403,7 +3394,7 @@ rooms directory via federation. Defaults to false.</p> <p>The default room version for newly created rooms on this server.</p> <p>Known room versions are listed <a href="https://spec.matrix.org/latest/rooms/#complete-list-of-room-versions">here</a></p> <p>For example, for room version 1, <code>default_room_version</code> should be set -to "1". </p> +to "1".</p> <p>Currently defaults to "9".</p> <p>Example configuration:</p> <pre><code class="language-yaml">default_room_version: "8" @@ -3411,14 +3402,14 @@ to "1". </p> <hr /> <h3 id="gc_thresholds"><a class="header" href="#gc_thresholds"><code>gc_thresholds</code></a></h3> <p>The garbage collection threshold parameters to pass to <code>gc.set_threshold</code>, if defined. -Defaults to none. </p> +Defaults to none.</p> <p>Example configuration:</p> <pre><code class="language-yaml">gc_thresholds: [700, 10, 10] </code></pre> <hr /> <h3 id="gc_min_interval"><a class="header" href="#gc_min_interval"><code>gc_min_interval</code></a></h3> <p>The minimum time in seconds between each GC for a generation, regardless of -the GC thresholds. This ensures that we don't do GC too frequently. A value of <code>[1s, 10s, 30s]</code> +the GC thresholds. This ensures that we don't do GC too frequently. A value of <code>[1s, 10s, 30s]</code> indicates that a second must pass between consecutive generation 0 GCs, etc.</p> <p>Defaults to <code>[1s, 10s, 30s]</code>.</p> <p>Example configuration:</p> @@ -3498,7 +3489,7 @@ configuration.</p> <p>Sub-options for each listener include:</p> <ul> <li> -<p><code>port</code>: the TCP port to bind to. </p> +<p><code>port</code>: the TCP port to bind to.</p> </li> <li> <p><code>bind_addresses</code>: a list of local addresses to listen on. The default is @@ -3641,7 +3632,7 @@ that room can become quite expensive. To mitigate this, once the number of forward extremities reaches a given threshold, Synapse will send an <code>org.matrix.dummy_event</code> event, which will reduce the forward extremities in the room.</p> -<p>This setting defines the threshold (i.e. number of forward extremities in the room) at which dummy events are sent. +<p>This setting defines the threshold (i.e. number of forward extremities in the room) at which dummy events are sent. The default value is 10.</p> <p>Example configuration:</p> <pre><code class="language-yaml">dummy_events_threshold: 5 @@ -3658,30 +3649,30 @@ delete any device that hasn't been accessed for more than the specified amount o <p>Useful options for Synapse admins.</p> <hr /> <h3 id="admin_contact"><a class="header" href="#admin_contact"><code>admin_contact</code></a></h3> -<p>How to reach the server admin, used in <code>ResourceLimitError</code>. Defaults to none. </p> +<p>How to reach the server admin, used in <code>ResourceLimitError</code>. Defaults to none.</p> <p>Example configuration:</p> <pre><code class="language-yaml">admin_contact: 'mailto:admin@server.com' </code></pre> <hr /> <h3 id="hs_disabled-and-hs_disabled_message"><a class="header" href="#hs_disabled-and-hs_disabled_message"><code>hs_disabled</code> and <code>hs_disabled_message</code></a></h3> <p>Blocks users from connecting to the homeserver and provides a human-readable reason -why the connection was blocked. Defaults to false. </p> +why the connection was blocked. Defaults to false.</p> <p>Example configuration:</p> <pre><code class="language-yaml">hs_disabled: true hs_disabled_message: 'Reason for why the HS is blocked' </code></pre> <hr /> <h3 id="limit_usage_by_mau"><a class="header" href="#limit_usage_by_mau"><code>limit_usage_by_mau</code></a></h3> -<p>This option disables/enables monthly active user blocking. Used in cases where the admin or -server owner wants to limit to the number of monthly active users. When enabled and a limit is +<p>This option disables/enables monthly active user blocking. Used in cases where the admin or +server owner wants to limit to the number of monthly active users. When enabled and a limit is reached the server returns a <code>ResourceLimitError</code> with error type <code>Codes.RESOURCE_LIMIT_EXCEEDED</code>. Defaults to false. If this is enabled, a value for <code>max_mau_value</code> must also be set.</p> <p>Example configuration:</p> -<pre><code class="language-yaml">limit_usage_by_mau: true +<pre><code class="language-yaml">limit_usage_by_mau: true </code></pre> <hr /> <h3 id="max_mau_value"><a class="header" href="#max_mau_value"><code>max_mau_value</code></a></h3> -<p>This option sets the hard limit of monthly active users above which the server will start +<p>This option sets the hard limit of monthly active users above which the server will start blocking user actions if <code>limit_usage_by_mau</code> is enabled. Defaults to 0.</p> <p>Example configuration:</p> <pre><code class="language-yaml">max_mau_value: 50 @@ -3692,7 +3683,7 @@ blocking user actions if <code>limit_usage_by_mau</code> is enabled. Defaults to means that users must be active for the specified number of days before they can be considered active and guards against the case where lots of users sign up in a short space of time never to return after their initial -session. Defaults to 0. </p> +session. Defaults to 0.</p> <p>Example configuration:</p> <pre><code class="language-yaml">mau_trial_days: 5 </code></pre> @@ -3703,7 +3694,7 @@ trial number if the user was registered by an appservice. A value of 0 means no trial days are applied. Appservices not listed in this dictionary use the value of <code>mau_trial_days</code> instead.</p> <p>Example configuration:</p> -<pre><code class="language-yaml">mau_appservice_trial_days: +<pre><code class="language-yaml">mau_appservice_trial_days: my_appservice_id: 3 another_appservice_id: 6 </code></pre> @@ -3721,7 +3712,7 @@ means that alerting is enabled.</p> <h3 id="mau_stats_only"><a class="header" href="#mau_stats_only"><code>mau_stats_only</code></a></h3> <p>If enabled, the metrics for the number of monthly active users will be populated, however no one will be limited based on these numbers. If <code>limit_usage_by_mau</code> -is true, this is implied to be true. Defaults to false. </p> +is true, this is implied to be true. Defaults to false.</p> <p>Example configuration:</p> <pre><code class="language-yaml">mau_stats_only: true </code></pre> @@ -3739,7 +3730,7 @@ reserved threepid (3rd party identifier).</p> <hr /> <h3 id="server_context"><a class="header" href="#server_context"><code>server_context</code></a></h3> <p>This option is used by phonehome stats to group together related servers. -Defaults to none. </p> +Defaults to none.</p> <p>Example configuration:</p> <pre><code class="language-yaml">server_context: context </code></pre> @@ -3753,11 +3744,11 @@ resource-constrained. Options for this setting include:</p> <li><code>enabled</code>: whether this check is enabled. Defaults to false.</li> <li><code>complexity</code>: the limit above which rooms cannot be joined. The default is 1.0.</li> <li><code>complexity_error</code>: override the error which is returned when the room is too complex with a -custom message. </li> +custom message.</li> <li><code>admins_can_join</code>: allow server admins to join complex rooms. Default is false.</li> </ul> <p>Room complexity is an arbitrary measure based on factors such as the number of -users in the room. </p> +users in the room.</p> <p>Example configuration:</p> <pre><code class="language-yaml">limit_remote_rooms: enabled: true @@ -3783,7 +3774,7 @@ Defaults to true.</p> <hr /> <h3 id="max_avatar_size"><a class="header" href="#max_avatar_size"><code>max_avatar_size</code></a></h3> <p>The largest permissible file size in bytes for a user avatar. Defaults to no restriction. -Use M for MB and K for KB. </p> +Use M for MB and K for KB.</p> <p>Note that user avatar changes will not work if this is set without using Synapse's media repository.</p> <p>Example configuration:</p> <pre><code class="language-yaml">max_avatar_size: 10M @@ -3815,7 +3806,7 @@ this period redacted events get replaced with their redacted form in the DB.</p> <h3 id="request_token_inhibit_3pid_errors"><a class="header" href="#request_token_inhibit_3pid_errors"><code>request_token_inhibit_3pid_errors</code></a></h3> <p>Inhibits the <code>/requestToken</code> endpoints from returning an error that might leak information about whether an e-mail address is in use or not on this -homeserver. Defaults to false. +homeserver. Defaults to false. Note that for some endpoints the error situation is the e-mail already being used, and for others the error is entering the e-mail being unused. If this option is enabled, instead of returning an error, these endpoints will @@ -3842,9 +3833,9 @@ all domains.</p> <hr /> <h3 id="templates-and-custom_template_directory"><a class="header" href="#templates-and-custom_template_directory"><code>templates</code> and <code>custom_template_directory</code></a></h3> <p>These options define templates to use when generating email or HTML page contents. -The <code>custom_template_directory</code> determines which directory Synapse will try to +The <code>custom_template_directory</code> determines which directory Synapse will try to find template files in to use to generate email or HTML page contents. -If not set, or a file is not found within the template directory, a default +If not set, or a file is not found within the template directory, a default template from within the Synapse package will be used.</p> <p>See <a href="usage/configuration/../../templates.html">here</a> for more information about using custom templates.</p> @@ -3861,20 +3852,20 @@ server level.</p> the <code>allowed_lifetime_min</code> and <code>allowed_lifetime_max</code> config options.</p> <p>If this feature is enabled, Synapse will regularly look for and purge events which are older than the room's maximum retention period. Synapse will also -filter events received over federation so that events that should have been -purged are ignored and not stored again. </p> +filter events received over federation so that events that should have been +purged are ignored and not stored again.</p> <p>The message retention policies feature is disabled by default.</p> <p>This setting has the following sub-options:</p> <ul> <li> <p><code>default_policy</code>: Default retention policy. If set, Synapse will apply it to rooms that lack the -'m.room.retention' state event. This option is further specified by the -<code>min_lifetime</code> and <code>max_lifetime</code> sub-options associated with it. Note that the -value of <code>min_lifetime</code> doesn't matter much because Synapse doesn't take it into account yet. </p> +'m.room.retention' state event. This option is further specified by the +<code>min_lifetime</code> and <code>max_lifetime</code> sub-options associated with it. Note that the +value of <code>min_lifetime</code> doesn't matter much because Synapse doesn't take it into account yet.</p> </li> <li> -<p><code>allowed_lifetime_min</code> and <code>allowed_lifetime_max</code>: Retention policy limits. If -set, and the state of a room contains a <code>m.room.retention</code> event in its state +<p><code>allowed_lifetime_min</code> and <code>allowed_lifetime_max</code>: Retention policy limits. If +set, and the state of a room contains a <code>m.room.retention</code> event in its state which contains a <code>min_lifetime</code> or a <code>max_lifetime</code> that's out of these bounds, Synapse will cap the room's policy to these limits when running purge jobs.</p> </li> @@ -3919,7 +3910,7 @@ configuration).</p> - longest_max_lifetime: 3d interval: 12h - shortest_max_lifetime: 3d - interval: 1d + interval: 1d </code></pre> <hr /> <h2 id="tls"><a class="header" href="#tls">TLS</a></h2> @@ -3928,16 +3919,16 @@ configuration).</p> <h3 id="tls_certificate_path"><a class="header" href="#tls_certificate_path"><code>tls_certificate_path</code></a></h3> <p>This option specifies a PEM-encoded X509 certificate for TLS. This certificate, as of Synapse 1.0, will need to be a valid and verifiable -certificate, signed by a recognised Certificate Authority. Defaults to none. </p> +certificate, signed by a recognised Certificate Authority. Defaults to none.</p> <p>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 <code>cert.pem</code>). </p> +<code>fullchain.pem</code> as your certificate, not <code>cert.pem</code>).</p> <p>Example configuration:</p> <pre><code class="language-yaml">tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt" </code></pre> <hr /> <h3 id="tls_private_key_path"><a class="header" href="#tls_private_key_path"><code>tls_private_key_path</code></a></h3> -<p>PEM-encoded private key for TLS. Defaults to none. </p> +<p>PEM-encoded private key for TLS. Defaults to none.</p> <p>Example configuration:</p> <pre><code class="language-yaml">tls_private_key_path: "CONFDIR/SERVERNAME.tls.key" </code></pre> @@ -4072,12 +4063,12 @@ variable would be <code>SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0</code>.</p> <li> <p><code>expire_caches</code>: Controls whether cache entries are evicted after a specified time period. Defaults to true. Set to false to disable this feature. Note that never expiring -caches may result in excessive memory usage. </p> +caches may result in excessive memory usage.</p> </li> <li> <p><code>cache_entry_ttl</code>: If <code>expire_caches</code> is enabled, this flag controls how long an entry can be in a cache without having been accessed before being evicted. -Defaults to 30m. </p> +Defaults to 30m.</p> </li> <li> <p><code>sync_response_cache_duration</code>: Controls how long the results of a /sync request are @@ -4085,11 +4076,12 @@ cached for after a successful response is returned. A higher duration can help c with intermittent connections, at the cost of higher memory usage. A value of zero means that sync responses are not cached. Defaults to 2m.</p> +<p><em>Changed in Synapse 1.62.0</em>: The default was changed from 0 to 2m.</p> </li> <li> <p><code>cache_autotuning</code> and its sub-options <code>max_cache_memory_usage</code>, <code>target_cache_memory_usage</code>, and -<code>min_cache_ttl</code> work in conjunction with each other to maintain a balance between cache memory -usage and cache entry availability. You must be using <a href="https://github.com/matrix-org/synapse#help-synapse-is-slow-and-eats-all-my-ramcpu">jemalloc</a> +<code>min_cache_ttl</code> work in conjunction with each other to maintain a balance between cache memory +usage and cache entry availability. You must be using <a href="https://github.com/matrix-org/synapse#help-synapse-is-slow-and-eats-all-my-ramcpu">jemalloc</a> to utilize this option, and all three of the options must be specified for this feature to work. This option defaults to off, enable it by providing values for the sub-options listed below. Please note that the feature will not work and may cause unstable behavior (such as excessive emptying of caches or exceptions) if all of the values are not provided. @@ -4103,7 +4095,7 @@ the setting below, or until the <code>min_cache_ttl</code> is hit. There is no d for this option.</li> <li><code>min_cache_ttl</code> sets a limit under which newer cache entries are not evicted and is only applied when caches are actively being evicted/<code>max_cache_memory_usage</code> has been exceeded. This is to protect hot caches -from being emptied while Synapse is evicting due to memory. There is no default value for this option. </li> +from being emptied while Synapse is evicting due to memory. There is no default value for this option.</li> </ul> </li> </ul> @@ -4123,7 +4115,7 @@ from being emptied while Synapse is evicting due to memory. There is no default <a href="https://en.wikipedia.org/wiki/SIGHUP"><code>SIGHUP</code></a> signal to Synapse using e.g.</p> <pre><code class="language-commandline">kill -HUP [PID_OF_SYNAPSE_PROCESS] </code></pre> -<p>If you are running multiple workers, you must individually update the worker +<p>If you are running multiple workers, you must individually update the worker config file and send this signal to each worker process.</p> <p>If you're using the <a href="https://github.com/matrix-org/synapse/blob/develop/contrib/systemd/matrix-synapse.service">example systemd service</a> file in Synapse's <code>contrib</code> directory, you can send a <code>SIGHUP</code> signal by using @@ -4139,7 +4131,7 @@ its data.</p> <ul> <li> <p><code>name</code>: this option specifies the database engine to use: either <code>sqlite3</code> (for SQLite) -or <code>psycopg2</code> (for PostgreSQL). If no name is specified Synapse will default to SQLite. </p> +or <code>psycopg2</code> (for PostgreSQL). If no name is specified Synapse will default to SQLite.</p> </li> <li> <p><code>txn_limit</code> gives the maximum number of transactions to run per connection @@ -4280,7 +4272,7 @@ when Synapse is started.</p> </code></pre> <hr /> <h2 id="logging"><a class="header" href="#logging">Logging</a></h2> -<p>Config options related to logging. </p> +<p>Config options related to logging.</p> <hr /> <h3 id="log_config"><a class="header" href="#log_config"><code>log_config</code></a></h3> <p>This option specifies a yaml python logging config file as described <a href="https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema">here</a>.</p> @@ -4289,7 +4281,7 @@ when Synapse is started.</p> </code></pre> <hr /> <h2 id="ratelimiting"><a class="header" href="#ratelimiting">Ratelimiting</a></h2> -<p>Options related to ratelimiting in Synapse. </p> +<p>Options related to ratelimiting in Synapse.</p> <p>Each ratelimiting configuration is made of two parameters:</p> <ul> <li><code>per_second</code>: number of requests a client can send per second.</li> @@ -4308,7 +4300,7 @@ is using. It defaults to: <code>per_second: 0.2</code>, <code>burst_count: 10</c <hr /> <h3 id="rc_registration"><a class="header" href="#rc_registration"><code>rc_registration</code></a></h3> <p>This option ratelimits registration requests based on the client's IP address. -It defaults to <code>per_second: 0.17</code>, <code>burst_count: 3</code>. </p> +It defaults to <code>per_second: 0.17</code>, <code>burst_count: 3</code>.</p> <p>Example configuration:</p> <pre><code class="language-yaml">rc_registration: per_second: 0.15 @@ -4316,7 +4308,7 @@ It defaults to <code>per_second: 0.17</code>, <code>burst_count: 3</code>. </p> </code></pre> <hr /> <h3 id="rc_registration_token_validity"><a class="header" href="#rc_registration_token_validity"><code>rc_registration_token_validity</code></a></h3> -<p>This option checks the validity of registration tokens that ratelimits requests based on +<p>This option checks the validity of registration tokens that ratelimits requests based on the client's IP address. Defaults to <code>per_second: 0.1</code>, <code>burst_count: 5</code>.</p> <p>Example configuration:</p> @@ -4357,9 +4349,9 @@ attempts for this account. Defaults to <code>per_second: 0.17</code>, <code>burs </code></pre> <hr /> <h3 id="rc_admin_redaction"><a class="header" href="#rc_admin_redaction"><code>rc_admin_redaction</code></a></h3> -<p>This option sets ratelimiting redactions by room admins. If this is not explicitly +<p>This option sets ratelimiting redactions by room admins. If this is not explicitly set then it uses the same ratelimiting as per <code>rc_message</code>. This is useful -to allow room admins to deal with abuse quickly. </p> +to allow room admins to deal with abuse quickly.</p> <p>Example configuration:</p> <pre><code class="language-yaml">rc_admin_redaction: per_second: 1 @@ -4370,13 +4362,13 @@ to allow room admins to deal with abuse quickly. </p> <p>This option allows for ratelimiting number of rooms a user can join. This setting has the following sub-options:</p> <ul> <li> -<p><code>local</code>: ratelimits when users are joining rooms the server is already in. +<p><code>local</code>: ratelimits when users are joining rooms the server is already in. Defaults to <code>per_second: 0.1</code>, <code>burst_count: 10</code>.</p> </li> <li> <p><code>remote</code>: ratelimits when users are trying to join rooms not on the server (which can be more computationally expensive than restricting locally). Defaults to -<code>per_second: 0.01</code>, <code>burst_count: 10</code> </p> +<code>per_second: 0.01</code>, <code>burst_count: 10</code></p> </li> </ul> <p>Example configuration:</p> @@ -4389,6 +4381,19 @@ can be more computationally expensive than restricting locally). Defaults to burst_count: 12 </code></pre> <hr /> +<h3 id="rc_joins_per_room"><a class="header" href="#rc_joins_per_room"><code>rc_joins_per_room</code></a></h3> +<p>This option allows admins to ratelimit joins to a room based on the number of recent +joins (local or remote) to that room. It is intended to mitigate mass-join spam +waves which target multiple homeservers.</p> +<p>By default, one join is permitted to a room every second, with an accumulating +buffer of up to ten instantaneous joins.</p> +<p>Example configuration (default values):</p> +<pre><code class="language-yaml">rc_joins_per_room: + per_second: 1 + burst_count: 10 +</code></pre> +<p><em>Added in Synapse 1.64.0.</em></p> +<hr /> <h3 id="rc_3pid_validation"><a class="header" href="#rc_3pid_validation"><code>rc_3pid_validation</code></a></h3> <p>This option ratelimits how often a user or IP can attempt to validate a 3PID. Defaults to <code>per_second: 0.003</code>, <code>burst_count: 5</code>.</p> @@ -4399,9 +4404,9 @@ Defaults to <code>per_second: 0.003</code>, <code>burst_count: 5</code>.</p> </code></pre> <hr /> <h3 id="rc_invites"><a class="header" href="#rc_invites"><code>rc_invites</code></a></h3> -<p>This option sets ratelimiting how often invites can be sent in a room or to a +<p>This option sets ratelimiting how often invites can be sent in a room or to a specific user. <code>per_room</code> defaults to <code>per_second: 0.3</code>, <code>burst_count: 10</code> and -<code>per_user</code> defaults to <code>per_second: 0.003</code>, <code>burst_count: 5</code>. </p> +<code>per_user</code> defaults to <code>per_second: 0.003</code>, <code>burst_count: 5</code>.</p> <p>Client requests that invite user(s) when <a href="https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom">creating a room</a> will count against the <code>rc_invites.per_room</code> limit, whereas @@ -4414,6 +4419,7 @@ limit only, as Synapse presumes ratelimiting by room will be done by the sending sender, meaning that a <code>rc_invite.per_user.burst_count</code> of 5 mandates that a single user cannot <em>receive</em> more than a burst of 5 invites at a time.</p> <p>In contrast, the <code>rc_invites.per_issuer</code> limit applies to the <em>issuer</em> of the invite, meaning that a <code>rc_invite.per_issuer.burst_count</code> of 5 mandates that single user cannot <em>send</em> more than a burst of 5 invites at a time.</p> +<p><em>Changed in version 1.63:</em> added the <code>per_issuer</code> limit.</p> <p>Example configuration:</p> <pre><code class="language-yaml">rc_invites: per_room: @@ -4426,7 +4432,6 @@ cannot <em>receive</em> more than a burst of 5 invites at a time.</p> per_second: 0.5 burst_count: 5 </code></pre> -<p><em>Changed in version 1.63:</em> added the <code>per_issuer</code> limit.</p> <hr /> <h3 id="rc_third_party_invite"><a class="header" href="#rc_third_party_invite"><code>rc_third_party_invite</code></a></h3> <p>This option ratelimits 3PID invites (i.e. invites sent to a third-party ID @@ -4439,7 +4444,7 @@ sending the invite. Defaults to <code>per_second: 0.2</code>, <code>burst_count: </code></pre> <hr /> <h3 id="rc_federation"><a class="header" href="#rc_federation"><code>rc_federation</code></a></h3> -<p>Defines limits on federation requests. </p> +<p>Defines limits on federation requests.</p> <p>The <code>rc_federation</code> configuration has the following sub-options:</p> <ul> <li><code>window_size</code>: window size in milliseconds. Defaults to 1000.</li> @@ -4465,7 +4470,7 @@ from a single server. Defaults to 3.</li> <p>Sets outgoing federation transaction frequency for sending read-receipts, per-room.</p> <p>If we end up trying to send out more read-receipts, they will get buffered up -into fewer transactions. Defaults to 50. </p> +into fewer transactions. Defaults to 50.</p> <p>Example configuration:</p> <pre><code class="language-yaml">federation_rr_transactions_per_room_per_second: 40 </code></pre> @@ -4474,7 +4479,7 @@ into fewer transactions. Defaults to 50. </p> <p>Config options related to Synapse's media store.</p> <hr /> <h3 id="enable_media_repo"><a class="header" href="#enable_media_repo"><code>enable_media_repo</code></a></h3> -<p>Enable the media store service in the Synapse master. Defaults to true. +<p>Enable the media store service in the Synapse master. Defaults to true. Set to false if you are using a separate media store worker.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_media_repo: false @@ -4494,7 +4499,7 @@ locations. Defaults to none. Associated sub-options are:</p> <li><code>store_local</code>: whether to store newly uploaded local files</li> <li><code>store_remote</code>: whether to store newly downloaded local files</li> <li><code>store_synchronous</code>: whether to wait for successful storage for local uploads</li> -<li><code>config</code>: sets a path to the resource through the <code>directory</code> option </li> +<li><code>config</code>: sets a path to the resource through the <code>directory</code> option</li> </ul> <p>Example configuration:</p> <pre><code class="language-yaml">media_storage_providers: @@ -4510,7 +4515,7 @@ locations. Defaults to none. Associated sub-options are:</p> <p>The largest allowed upload size in bytes.</p> <p>If you are using a reverse proxy you may also need to set this value in your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body size by default. -See <a href="usage/configuration/../../reverse_proxy.html">here</a> for more on using a reverse proxy with Synapse. </p> +See <a href="usage/configuration/../../reverse_proxy.html">here</a> for more on using a reverse proxy with Synapse.</p> <p>Example configuration:</p> <pre><code class="language-yaml">max_upload_size: 60M </code></pre> @@ -4526,7 +4531,7 @@ See <a href="usage/configuration/../../reverse_proxy.html">here</a> for more on the resolution requested by the client. If true then whenever a new resolution is requested by the client the server will generate a new thumbnail. If false the server will pick a thumbnail -from a precalculated list. Defaults to false. </p> +from a precalculated list. Defaults to false.</p> <p>Example configuration:</p> <pre><code class="language-yaml">dynamic_thumbnails: true </code></pre> @@ -4632,7 +4637,7 @@ you use the following example list as a starting point.</p> to access even if they are specified in <code>url_preview_ip_range_blacklist</code>. This is useful for specifying exceptions to wide-ranging blacklisted target IP ranges - e.g. for enabling URL previews for a specific private -website only visible in your network. Defaults to none. </p> +website only visible in your network. Defaults to none.</p> <p>Example configuration:</p> <pre><code class="language-yaml">url_preview_ip_range_whitelist: - '192.168.1.1' @@ -4646,7 +4651,7 @@ entry that points to a private IP address and circumvent the blacklist. This is more useful if you know there is an entire shape of URL that you know that will never want synapse to try to spider.</p> <p>Each list entry is a dictionary of url component attributes as returned -by urlparse.urlsplit as applied to the absolute form of the URL. See +by urlparse.urlsplit as applied to the absolute form of the URL. See <a href="https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit">here</a> for more information. Some examples are:</p> <ul> @@ -4709,8 +4714,8 @@ using quality value syntax (;q=). '*' translates to any language.</p> <p>oEmbed allows for easier embedding content from a website. It can be used for generating URLs previews of services which support it. A default list of oEmbed providers is included with Synapse. Set <code>disable_default_providers</code> to true to disable using -these default oEmbed URLs. Use <code>additional_providers</code> to specify additional files with oEmbed configuration (each -should be in the form of providers.json). By default this list is empty. </p> +these default oEmbed URLs. Use <code>additional_providers</code> to specify additional files with oEmbed configuration (each +should be in the form of providers.json). By default this list is empty.</p> <p>Example configuration:</p> <pre><code class="language-yaml">oembed: disable_default_providers: true @@ -4722,14 +4727,14 @@ should be in the form of providers.json). By default this list is empty. </p> <p>See <a href="usage/configuration/../../CAPTCHA_SETUP.html">here</a> for full details on setting up captcha.</p> <hr /> <h3 id="recaptcha_public_key"><a class="header" href="#recaptcha_public_key"><code>recaptcha_public_key</code></a></h3> -<p>This homeserver's ReCAPTCHA public key. Must be specified if <code>enable_registration_captcha</code> is +<p>This homeserver's ReCAPTCHA public key. Must be specified if <code>enable_registration_captcha</code> is enabled.</p> <p>Example configuration:</p> <pre><code class="language-yaml">recaptcha_public_key: "YOUR_PUBLIC_KEY" </code></pre> <hr /> <h3 id="recaptcha_private_key"><a class="header" href="#recaptcha_private_key"><code>recaptcha_private_key</code></a></h3> -<p>This homeserver's ReCAPTCHA private key. Must be specified if <code>enable_registration_captcha</code> is +<p>This homeserver's ReCAPTCHA private key. Must be specified if <code>enable_registration_captcha</code> is enabled.</p> <p>Example configuration:</p> <pre><code class="language-yaml">recaptcha_private_key: "YOUR_PRIVATE_KEY" @@ -4737,7 +4742,7 @@ enabled.</p> <hr /> <h3 id="enable_registration_captcha"><a class="header" href="#enable_registration_captcha"><code>enable_registration_captcha</code></a></h3> <p>Set to true to enable ReCaptcha checks when registering, preventing signup -unless a captcha is answered. Requires a valid ReCaptcha public/private key. +unless a captcha is answered. Requires a valid ReCaptcha public/private key. Defaults to false.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_registration_captcha: true @@ -4791,7 +4796,7 @@ it allows users to connect to arbitrary endpoints without having first signed up <hr /> <h3 id="enable_registration"><a class="header" href="#enable_registration"><code>enable_registration</code></a></h3> <p>Enable registration for new users. Defaults to false. It is highly recommended that if you enable registration, -you use either captcha, email, or token-based verification to verify that new users are not bots. In order to enable registration +you use either captcha, email, or token-based verification to verify that new users are not bots. In order to enable registration without any verification, you must also set <code>enable_registration_without_verification</code> to true.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_registration: true @@ -4808,7 +4813,7 @@ unless <code>enable_registration</code> is also enabled.</p> <h3 id="session_lifetime"><a class="header" href="#session_lifetime"><code>session_lifetime</code></a></h3> <p>Time that a user's session remains valid for, after they log in.</p> <p>Note that this is not currently compatible with guest logins.</p> -<p>Note also that this is calculated at login time: changes are not applied retrospectively to users who have already +<p>Note also that this is calculated at login time: changes are not applied retrospectively to users who have already logged in.</p> <p>By default, this is infinite.</p> <p>Example configuration:</p> @@ -4819,7 +4824,7 @@ logged in.</p> <p>Time that an access token remains valid for, if the session is using refresh tokens.</p> <p>For more information about refresh tokens, please see the <a href="usage/configuration/user_authentication/refresh_tokens.html">manual</a>.</p> <p>Note that this only applies to clients which advertise support for refresh tokens.</p> -<p>Note also that this is calculated at login time and refresh time: changes are not applied to +<p>Note also that this is calculated at login time and refresh time: changes are not applied to existing sessions until they are refreshed.</p> <p>By default, this is 5 minutes.</p> <p>Example configuration:</p> @@ -4930,24 +4935,20 @@ This setting is ignored unless <code>public_baseurl</code> is also explicitly se </code></pre> <hr /> <h3 id="account_threepid_delegates"><a class="header" href="#account_threepid_delegates"><code>account_threepid_delegates</code></a></h3> -<p>Handle threepid (email/phone etc) registration and password resets through a set of -<em>trusted</em> identity servers. Note that this allows the configured identity server to -reset passwords for accounts!</p> -<p>Be aware that if <code>email</code> is not set, and SMTP options have not been -configured in the email config block, registration and user password resets via -email will be globally disabled.</p> -<p>Additionally, if <code>msisdn</code> is not set, registration and password resets via msisdn -will be disabled regardless, and users will not be able to associate an msisdn -identifier to their account. This is due to Synapse currently not supporting -any method of sending SMS messages on its own.</p> -<p>To enable using an identity server for operations regarding a particular third-party -identifier type, set the value to the URL of that identity server as shown in the -examples below.</p> -<p>Servers handling the these requests must answer the <code>/requestToken</code> endpoints defined -by the Matrix Identity Service API <a href="https://matrix.org/docs/spec/identity_service/latest">specification</a>.</p> +<p>Delegate verification of phone numbers to an identity server.</p> +<p>When a user wishes to add a phone number to their account, we need to verify that they +actually own that phone number, which requires sending them a text message (SMS). +Currently Synapse does not support sending those texts itself and instead delegates the +task to an identity server. The base URI for the identity server to be used is +specified by the <code>account_threepid_delegates.msisdn</code> option.</p> +<p>If this is left unspecified, Synapse will not allow users to add phone numbers to +their account.</p> +<p>(Servers handling the these requests must answer the <code>/requestToken</code> endpoints defined +by the Matrix Identity Service API +<a href="https://matrix.org/docs/spec/identity_service/latest">specification</a>.)</p> +<p><em>Updated in Synapse 1.64.0</em>: The <code>email</code> option is deprecated.</p> <p>Example configuration:</p> <pre><code class="language-yaml">account_threepid_delegates: - email: https://example.com # Delegate email sending to example.com msisdn: http://localhost:8090 # Delegate SMS sending to this local process </code></pre> <hr /> @@ -4984,7 +4985,7 @@ to the rooms listed under this option.</p> as a publicly joinable room when the first user registers for the homeserver. If the room already exists, make certain it is a publicly joinable room, i.e. the join rule of the room must be set to 'public'. You can find more options -relating to auto-joining rooms below. </p> +relating to auto-joining rooms below.</p> <p>Example configuration:</p> <pre><code class="language-yaml">auto_join_rooms: - "#exampleroom:example.com" @@ -5024,9 +5025,9 @@ effect if <code>autocreate_auto_join_rooms</code> is true.</p> <ul> <li>"public_chat": the room is joinable by anyone, including federated servers if <code>autocreate_auto_join_rooms_federated</code> is true (the default).</li> -<li>"private_chat": an invitation is required to join these rooms. </li> +<li>"private_chat": an invitation is required to join these rooms.</li> <li>"trusted_private_chat": an invitation is required to join this room and the invitee is -assigned a power level of 100 upon joining the room. </li> +assigned a power level of 100 upon joining the room.</li> </ul> <p>If a value of "private_chat" or "trusted_private_chat" is used then <code>auto_join_mxid_localpart</code> must also be configured.</p> @@ -5075,7 +5076,7 @@ raise an error if the registration completes and the username conflicts.</p> <p>Config options related to metrics.</p> <hr /> <h3 id="enable_metrics"><a class="header" href="#enable_metrics"><code>enable_metrics</code></a></h3> -<p>Set to true to enable collection and rendering of performance metrics. +<p>Set to true to enable collection and rendering of performance metrics. Defaults to false.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_metrics: true @@ -5083,10 +5084,10 @@ Defaults to false.</p> <hr /> <h3 id="sentry"><a class="header" href="#sentry"><code>sentry</code></a></h3> <p>Use this option to enable sentry integration. Provide the DSN assigned to you by sentry -with the <code>dsn</code> setting. </p> +with the <code>dsn</code> setting.</p> <p>NOTE: While attempts are made to ensure that the logs don't contain any sensitive information, this cannot be guaranteed. By enabling -this option the sentry server may therefore receive sensitive +this option the sentry server may therefore receive sensitive information, and it in turn may then disseminate sensitive information through insecure notification channels if so configured.</p> <p>Example configuration:</p> @@ -5097,7 +5098,7 @@ through insecure notification channels if so configured.</p> <h3 id="metrics_flags"><a class="header" href="#metrics_flags"><code>metrics_flags</code></a></h3> <p>Flags to enable Prometheus metrics which are not suitable to be enabled by default, either for performance reasons or limited use. -Currently the only option is <code>known_servers</code>, which publishes +Currently the only option is <code>known_servers</code>, which publishes <code>synapse_federation_known_servers</code>, a gauge of the number of servers this homeserver knows about, including itself. May cause performance problems on large homeservers.</p> @@ -5130,7 +5131,7 @@ Defaults to https://matrix.org/report-usage-stats/push</p> <hr /> <h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state:</code></a></h3> <p>Controls for the state that is shared with users who receive an invite -to a room. By default, the following state event types are shared with users who +to a room. By default, the following state event types are shared with users who receive invites to the room:</p> <ul> <li>m.room.join_rules</li> @@ -5143,7 +5144,7 @@ receive invites to the room:</p> </ul> <p>To change the default behavior, use the following sub-options:</p> <ul> -<li><code>disable_default_event_types</code>: set to true to disable the above defaults. If this +<li><code>disable_default_event_types</code>: set to true to disable the above defaults. If this is enabled, only the event types listed in <code>additional_event_types</code> are shared. Defaults to false.</li> <li><code>additional_event_types</code>: Additional state event types to share with users when they are invited @@ -5251,7 +5252,7 @@ warning on start-up. To suppress this warning, set If specified, we will check that the response is signed by at least one of the given keys.</li> <li><code>accept_keys_insecurely</code>: a boolean. Normally, if <code>verify_keys</code> is unset, -and <code>federation_verify_certificates</code> is not <code>true</code>, synapse will refuse +and <code>federation_verify_certificates</code> is not <code>true</code>, synapse will refuse to start, because this would allow anyone who can spoof DNS responses to masquerade as the trusted key server. If you know what you are doing and are sure that your network environment provides a secure connection @@ -5319,16 +5320,16 @@ to allow IdP-initiated login, set <code>allow_unsolicited</code> to true under < section.</li> </ul> </li> -<li><code>config_path</code>: specify a separate pysaml2 configuration file thusly: +<li><code>config_path</code>: specify a separate pysaml2 configuration file thusly: <code>config_path: "CONFDIR/sp_conf.py"</code></li> <li><code>saml_session_lifetime</code>: The lifetime of a SAML session. This defines how long a user has to complete the authentication process, if <code>allow_unsolicited</code> is unset. The default is 15 minutes.</li> -<li><code>user_mapping_provider</code>: Using this option, an external module can be provided as a -custom solution to mapping attributes returned from a saml provider onto a matrix user. The +<li><code>user_mapping_provider</code>: Using this option, an external module can be provided as a +custom solution to mapping attributes returned from a saml provider onto a matrix user. The <code>user_mapping_provider</code> has the following attributes: <ul> -<li><code>module</code>: The custom module's class. </li> -<li><code>config</code>: Custom configuration values for the module. Use the values provided in the +<li><code>module</code>: The custom module's class.</li> +<li><code>config</code>: Custom configuration values for the module. Use the values provided in the example if you are using the built-in user_mapping_provider, or provide your own config values for a custom class if you are using one. This section will be passed as a Python dictionary to the module's <code>parse_config</code> method. The built-in provider takes the following two @@ -5350,7 +5351,7 @@ The default is <code>hexencode</code>. Note: This used to be configured by the MXID was always calculated dynamically rather than stored in a table. For backwards- compatibility, we will look for <code>user_ids</code> matching such a pattern before creating a new account. This setting controls the SAML attribute which will be used for this backwards-compatibility lookup. Typically it should be 'uid', but if the attribute maps are changed, it may be necessary to change it. -The default is 'uid'. </li> +The default is 'uid'.</li> <li><code>attribute_requirements</code>: It is possible to configure Synapse to only allow logins if SAML attributes match particular values. The requirements can be listed under <code>attribute_requirements</code> as shown in the example. All of the listed attributes must @@ -5416,16 +5417,16 @@ the IdP to use an ACS location of sur_name: "the Sysadmin" email_address": ["admin@example.com"] contact_type": technical - + saml_session_lifetime: 5m - + user_mapping_provider: - # Below options are intended for the built-in provider, they should be - # changed if using a custom module. + # Below options are intended for the built-in provider, they should be + # changed if using a custom module. config: mxid_source_attribute: displayName mxid_mapping: dotreplace - + grandfathered_mxid_source_attribute: upn attribute_requirements: @@ -5579,7 +5580,7 @@ compliant providers should provide.</p> <li> <p><code>localpart_template</code>: Jinja2 template for the localpart of the MXID. If this is not set, the user will be prompted to choose their -own username (see the documentation for the <code>sso_auth_account_details.html</code> +own username (see the documentation for the <code>sso_auth_account_details.html</code> template). This template can use the <code>localpart_from_email</code> filter.</p> </li> <li> @@ -5609,7 +5610,7 @@ which is set to the claims returned by the UserInfo Endpoint and/or in the ID Token.</p> </li> </ul> -<p>It is possible to configure Synapse to only allow logins if certain attributes +<p>It is possible to configure Synapse to only allow logins if certain attributes match particular values in the OIDC userinfo. The requirements can be listed under <code>attribute_requirements</code> as shown here:</p> <pre><code class="language-yaml">attribute_requirements: @@ -5622,7 +5623,7 @@ match particular values in the OIDC userinfo. The requirements can be listed und userinfo by expanding the <code>scopes</code> section of the OIDC config to retrieve additional information from the OIDC provider.</p> <p>If the OIDC claim is a list, then the attribute must match any value in the list. -Otherwise, it must exactly match the value of the claim. Using the example +Otherwise, it must exactly match the value of the claim. Using the example above, the <code>family_name</code> claim MUST be "Stephensson", but the <code>groups</code> claim MUST contain "admin".</p> <p>Example configuration:</p> @@ -5682,7 +5683,7 @@ All of the listed attributes must match for the login to be permitted.</li> <h3 id="sso"><a class="header" href="#sso"><code>sso</code></a></h3> <p>Additional settings to use with single-sign on systems such as OpenID Connect, SAML2 and CAS.</p> -<p>Server admins can configure custom templates for pages related to SSO. See +<p>Server admins can configure custom templates for pages related to SSO. See <a href="usage/configuration/../../templates.html">here</a> for more information.</p> <p>Options include:</p> <ul> @@ -5698,7 +5699,7 @@ The login fallback page (used by clients that don't natively support the required login flows) is whitelisted in addition to any URLs in this list. By default, this list contains only the login fallback page.</li> <li><code>update_profile_information</code>: Use this setting to keep a user's profile fields in sync with information from -the identity provider. Currently only syncing the displayname is supported. Fields +the identity provider. Currently only syncing the displayname is supported. Fields are checked on every SSO login, and are updated if necessary. Note that enabling this option will override user profile information, regardless of whether users have opted-out of syncing that @@ -5735,7 +5736,7 @@ Supported algorithms are listed Required if <code>enabled</code> is set to true.</li> <li><code>subject_claim</code>: Name of the claim containing a unique identifier for the user. Optional, defaults to <code>sub</code>.</li> -<li><code>issuer</code>: The issuer to validate the "iss" claim against. Optional. If provided the +<li><code>issuer</code>: The issuer to validate the "iss" claim against. Optional. If provided the "iss" claim will be required and validated for all JSON web tokens.</li> <li><code>audiences</code>: A list of audiences to validate the "aud" claim against. Optional. If provided the "aud" claim will be required and validated for all JSON web tokens. @@ -5744,7 +5745,7 @@ validation will fail without configuring audiences.</li> </ul> <p>Example configuration:</p> <pre><code class="language-yaml">jwt_config: - enabled: true + enabled: true secret: "provided-by-your-issuer" algorithm: "provided-by-your-issuer" subject_claim: "name_of_claim" @@ -5754,7 +5755,7 @@ validation will fail without configuring audiences.</li> </code></pre> <hr /> <h3 id="password_config"><a class="header" href="#password_config"><code>password_config</code></a></h3> -<p>Use this setting to enable password-based logins. </p> +<p>Use this setting to enable password-based logins.</p> <p>This setting has the following sub-options:</p> <ul> <li><code>enabled</code>: Defaults to true. @@ -5763,10 +5764,10 @@ Set to <code>only_for_reauth</code> to allow users with existing passwords to us to log in and reauthenticate, whilst preventing new users from setting passwords.</li> <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> +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. 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. +<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: <ul> <li><code>enabled</code>: Defaults to false. Set to true to enable.</li> @@ -5799,7 +5800,7 @@ Defaults to false.</li> <hr /> <h3 id="ui_auth"><a class="header" href="#ui_auth"><code>ui_auth</code></a></h3> <p>The amount of time to allow a user-interactive authentication session to be active.</p> -<p>This defaults to 0, meaning the user is queried for their credentials +<p>This defaults to 0, meaning the user is queried for their credentials before every action, but this can be overridden to allow a single validation to be re-used. This weakens the protections afforded by the user-interactive authentication process, by allowing for multiple @@ -5823,13 +5824,21 @@ adding a 3PID).</p> <p><code>smtp_host</code>: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.</p> </li> <li> -<p><code>smtp_port</code>: The port on the mail server for outgoing SMTP. Defaults to 25.</p> +<p><code>smtp_port</code>: The port on the mail server for outgoing SMTP. Defaults to 465 if <code>force_tls</code> is true, else 25.</p> +<p><em>Changed in Synapse 1.64.0:</em> the default port is now aware of <code>force_tls</code>.</p> </li> <li> <p><code>smtp_user</code> and <code>smtp_pass</code>: Username/password for authentication to the SMTP server. By default, no authentication is attempted.</p> </li> <li> +<p><code>force_tls</code>: By default, Synapse connects over plain text and then optionally upgrades +to TLS via STARTTLS. If this option is set to true, TLS is used from the start (Implicit TLS), +and the option <code>require_transport_security</code> is ignored. +It is recommended to enable this if supported by your mail server.</p> +<p><em>New in Synapse 1.64.0.</em></p> +</li> +<li> <p><code>require_transport_security</code>: Set to true to require TLS transport security for SMTP. By default, Synapse will connect over plain text, and will then switch to TLS via STARTTLS <em>if the SMTP server supports it</em>. If this option is set, @@ -5881,7 +5890,7 @@ of the user(s) that sent the message(s), e.g. "Alice and Bob", and '%( message(s) have been sent to, e.g. "My super room". In addition, emails related to account administration will can use the '%(server_name)s' placeholder, which will be replaced by the value of the <code>server_name</code> setting in your Synapse configuration.</p> -<p>Here is a list of subjects for notification emails that can be set: </p> +<p>Here is a list of subjects for notification emails that can be set:</p> <ul> <li><code>message_from_person_in_room</code>: Subject to use to notify about one message from one or more user(s) in a room which has a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."</li> @@ -5891,13 +5900,13 @@ room which doesn't have a name. Defaults to "[%(app)s] You have a message o a room which doesn't have a name. Defaults to "[%(app)s] You have messages on %(app)s from %(person)s..."</li> <li><code>messages_in_room</code>: Subject to use to notify about multiple messages in a room which has a name. Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room..."</li> -<li><code>messages_in_room_and_others</code>: Subject to use to notify about multiple messages in multiple rooms. +<li><code>messages_in_room_and_others</code>: Subject to use to notify about multiple messages in multiple rooms. Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."</li> <li><code>messages_from_person_and_others</code>: Subject to use to notify about multiple messages from multiple persons in multiple rooms. This is similar to the setting above except it's used when -the room in which the notification was triggered has no name. Defaults to +the room in which the notification was triggered has no name. Defaults to "[%(app)s] You have messages on %(app)s from %(person)s and others..."</li> -<li><code>invite_from_person_to_room</code>: Subject to use to notify about an invite to a room which has a name. +<li><code>invite_from_person_to_room</code>: Subject to use to notify about an invite to a room which has a name. Defaults to "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."</li> <li><code>invite_from_person</code>: Subject to use to notify about an invite to a room which doesn't have a name. Defaults to "[%(app)s] %(person)s has invited you to chat on %(app)s..."</li> @@ -5913,6 +5922,7 @@ ownership. Defaults to "[%(server_name)s] Validate your email"</li> smtp_port: 587 smtp_user: "exampleusername" smtp_pass: "examplepassword" + force_tls: true require_transport_security: true enable_tls: false notif_from: "Your Friendly %(app)s homeserver <noreply@example.com>" @@ -5940,7 +5950,7 @@ ownership. Defaults to "[%(server_name)s] Validate your email"</li> <p>Configuration settings related to push notifications</p> <hr /> <h3 id="push-1"><a class="header" href="#push-1"><code>push</code></a></h3> -<p>This setting defines options for push notifications. </p> +<p>This setting defines options for push notifications.</p> <p>This option has a number of sub-options. They are as follows:</p> <ul> <li><code>include_content</code>: Clients requesting push notifications can either have the body of @@ -5955,7 +5965,7 @@ because it is loaded by the app. iPhone, however will send a notification saying only that a message arrived and who it came from. Defaults to true. Set to false to only include the event ID and room ID in push notification payloads.</li> <li><code>group_unread_count_by_room: false</code>: When a push notification is received, an unread count is also sent. -This number can either be calculated as the number of unread messages for the user, or the number of <em>rooms</em> the +This number can either be calculated as the number of unread messages for the user, or the number of <em>rooms</em> the user has unread messages in. Defaults to true, meaning push clients will see the number of rooms with unread messages in them. Set to false to instead send the number of unread messages.</li> @@ -5987,7 +5997,7 @@ will also not affect rooms created by other servers.</p> </code></pre> <hr /> <h3 id="user_directory"><a class="header" href="#user_directory"><code>user_directory</code></a></h3> -<p>This setting defines options related to the user directory. </p> +<p>This setting defines options related to the user directory.</p> <p>This option has the following sub-options:</p> <ul> <li><code>enabled</code>: Defines whether users can search the user directory. If false then @@ -6005,7 +6015,7 @@ https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/backg Set to true to return search results containing all known users, even if that user does not share a room with the requester.</li> <li><code>prefer_local_users</code>: Defines whether to prefer local users in search query results. -If set to true, local users are more likely to appear above remote users when searching the +If set to true, local users are more likely to appear above remote users when searching the user directory. Defaults to false.</li> </ul> <p>Example configuration:</p> @@ -6072,14 +6082,14 @@ Defaults to "Privacy Policy".</p> <hr /> <h3 id="stats"><a class="header" href="#stats"><code>stats</code></a></h3> <p>Settings for local room and user statistics collection. See <a href="usage/configuration/../../room_and_user_statistics.html">here</a> -for more. </p> +for more.</p> <ul> <li><code>enabled</code>: Set to false to disable room and user statistics. Note that doing so may cause certain features (such as the room directory) not to work -correctly. Defaults to true. </li> +correctly. Defaults to true.</li> </ul> <p>Example configuration:</p> -<pre><code class="language-yaml">stats: +<pre><code class="language-yaml">stats: enabled: false </code></pre> <hr /> @@ -6107,7 +6117,7 @@ notices.</p> <h3 id="enable_room_list_search"><a class="header" href="#enable_room_list_search"><code>enable_room_list_search</code></a></h3> <p>Set to false to disable searching the public room list. When disabled blocks searching local and remote room lists for local and remote -users by always returning an empty list for all queries. Defaults to true. </p> +users by always returning an empty list for all queries. Defaults to true.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_room_list_search: false </code></pre> @@ -6127,7 +6137,7 @@ can create aliases.</p> <li><code>user_id</code>: Matches against the creator of the alias. Defaults to "*".</li> <li><code>alias</code>: Matches against the alias being created. Defaults to "*".</li> <li><code>room_id</code>: Matches against the room ID the alias is being pointed at. Defaults to "*"</li> -<li><code>action</code>: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow. </li> +<li><code>action</code>: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.</li> </ul> <p>Example configuration:</p> <pre><code class="language-yaml">alias_creation_rules: @@ -6152,7 +6162,7 @@ can publish rooms.</p> <li><code>user_id</code>: Matches against the creator of the alias. Defaults to "*".</li> <li><code>alias</code>: Matches against any current local or canonical aliases associated with the room. Defaults to "*".</li> <li><code>room_id</code>: Matches against the room ID being published. Defaults to "*".</li> -<li><code>action</code>: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow. </li> +<li><code>action</code>: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.</li> </ul> <p>Example configuration:</p> <pre><code class="language-yaml">room_list_publication_rules: @@ -6194,14 +6204,14 @@ synapse or any other services which support opentracing <ul> <li><code>enabled</code>: whether tracing is enabled. Set to true to enable. Disabled by default.</li> <li><code>homeserver_whitelist</code>: The list of homeservers we wish to send and receive span contexts and span baggage. -See <a href="usage/configuration/../../opentracing.html">here</a> for more. +See <a href="usage/configuration/../../opentracing.html">here</a> for more. This is a list of regexes which are matched against the <code>server_name</code> of the homeserver. By default, it is empty, so no servers are matched.</li> <li><code>force_tracing_for_users</code>: # A list of the matrix IDs of users whose requests will always be traced, even if the tracing system would otherwise drop the traces due to probabilistic sampling. By default, the list is empty.</li> <li><code>jaeger_config</code>: Jaeger can be configured to sample traces at different rates. -All configuration options provided by Jaeger can be set here. Jaeger's configuration is +All configuration options provided by Jaeger can be set here. Jaeger's configuration is mostly related to trace sampling which is documented <a href="https://www.jaegertracing.io/docs/latest/sampling/">here</a>.</li> </ul> <p>Example configuration:</p> @@ -6226,18 +6236,18 @@ mostly related to trace sampling which is documented <a href="https://www.jaeger <hr /> <h3 id="send_federation"><a class="header" href="#send_federation"><code>send_federation</code></a></h3> <p>Controls sending of outbound federation transactions on the main process. -Set to false if using a federation sender worker. Defaults to true. </p> +Set to false if using a federation sender worker. Defaults to true.</p> <p>Example configuration:</p> <pre><code class="language-yaml">send_federation: false </code></pre> <hr /> <h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3> <p>It is possible to run multiple federation sender workers, in which case the -work is balanced across them. Use this setting to list the senders. </p> +work is balanced across them. Use this setting to list the senders.</p> <p>This configuration setting must be shared between all federation sender workers, and if changed all federation sender workers must be stopped at the same time and then started, to ensure that all instances are running with the same config (otherwise -events may be dropped). </p> +events may be dropped).</p> <p>Example configuration:</p> <pre><code class="language-yaml">federation_sender_instances: - federation_sender1 @@ -6245,7 +6255,7 @@ events may be dropped). </p> <hr /> <h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3> <p>When using workers this should be a map from worker name to the -HTTP replication listener of the worker, if configured. </p> +HTTP replication listener of the worker, if configured.</p> <p>Example configuration:</p> <pre><code class="language-yaml">instance_map: worker1: @@ -6282,7 +6292,7 @@ from workers.</p> using workers (unless using old style direct TCP configuration). This setting has the following sub-options:</p> <ul> -<li><code>enabled</code>: whether to use Redis support. Defaults to false. </li> +<li><code>enabled</code>: whether to use Redis support. Defaults to false.</li> <li><code>host</code> and <code>port</code>: Optional host and port to use to connect to redis. Defaults to localhost and 6379</li> <li><code>password</code>: Optional password if configured on the Redis instance.</li> @@ -6295,7 +6305,7 @@ localhost and 6379</li> password: <secret_password> </code></pre> <h2 id="background-updates"><a class="header" href="#background-updates">Background Updates</a></h2> -<p>Configuration settings related to background updates. </p> +<p>Configuration settings related to background updates.</p> <hr /> <h3 id="background_updates"><a class="header" href="#background_updates"><code>background_updates</code></a></h3> <p>Background updates are database updates that are run in the background in batches. @@ -6303,7 +6313,7 @@ The duration, minimum batch size, default batch size, whether to sleep between b sleep can all be configured. This is helpful to speed up or slow down the updates. This setting has the following sub-options:</p> <ul> -<li><code>background_update_duration_ms</code>: How long in milliseconds to run a batch of background updates for. Defaults to 100. +<li><code>background_update_duration_ms</code>: How long in milliseconds to run a batch of background updates for. Defaults to 100. Set a different time to change the default.</li> <li><code>sleep_enabled</code>: Whether to sleep between updates. Defaults to true. Set to false to change the default.</li> <li><code>sleep_duration_ms</code>: If sleeping between updates, how long in milliseconds to sleep for. Defaults to 1000. @@ -6313,7 +6323,7 @@ Set a size to change the default.</li> <li><code>default_batch_size</code>: The batch size to use for the first iteration of a new background update. The default is 100. Set a size to change the default.</li> </ul> -<p>Example configuration: </p> +<p>Example configuration:</p> <pre><code class="language-yaml">background_updates: background_update_duration_ms: 500 sleep_enabled: false @@ -8207,90 +8217,6 @@ consent uri for that user.</p> <p>ensure that <code>public_baseurl</code> is set in <code>homeserver.yaml</code>, and gives the base URI that clients use to connect to the server. (It is used to construct <code>consent_uri</code> in the error.)</p> -<div style="break-before: page; page-break-before: always;"></div><h1 id="url-previews-1"><a class="header" href="#url-previews-1">URL Previews</a></h1> -<p>The <code>GET /_matrix/media/r0/preview_url</code> endpoint provides a generic preview API -for URLs which outputs <a href="https://ogp.me/">Open Graph</a> responses (with some Matrix -specific additions).</p> -<p>This does have trade-offs compared to other designs:</p> -<ul> -<li>Pros: -<ul> -<li>Simple and flexible; can be used by any clients at any point</li> -</ul> -</li> -<li>Cons: -<ul> -<li>If each homeserver provides one of these independently, all the HSes in a -room may needlessly DoS the target URI</li> -<li>The URL metadata must be stored somewhere, rather than just using Matrix -itself to store the media.</li> -<li>Matrix cannot be used to distribute the metadata between homeservers.</li> -</ul> -</li> -</ul> -<p>When Synapse is asked to preview a URL it does the following:</p> -<ol> -<li>Checks against a URL blacklist (defined as <code>url_preview_url_blacklist</code> in the -config).</li> -<li>Checks the in-memory cache by URLs and returns the result if it exists. (This -is also used to de-duplicate processing of multiple in-flight requests at once.)</li> -<li>Kicks off a background process to generate a preview: -<ol> -<li>Checks the database cache by URL and timestamp and returns the result if it -has not expired and was successful (a 2xx return code).</li> -<li>Checks if the URL matches an <a href="https://oembed.com/">oEmbed</a> pattern. If it -does, update the URL to download.</li> -<li>Downloads the URL and stores it into a file via the media storage provider -and saves the local media metadata.</li> -<li>If the media is an image: -<ol> -<li>Generates thumbnails.</li> -<li>Generates an Open Graph response based on image properties.</li> -</ol> -</li> -<li>If the media is HTML: -<ol> -<li>Decodes the HTML via the stored file.</li> -<li>Generates an Open Graph response from the HTML.</li> -<li>If a JSON oEmbed URL was found in the HTML via autodiscovery: -<ol> -<li>Downloads the URL and stores it into a file via the media storage provider -and saves the local media metadata.</li> -<li>Convert the oEmbed response to an Open Graph response.</li> -<li>Override any Open Graph data from the HTML with data from oEmbed.</li> -</ol> -</li> -<li>If an image exists in the Open Graph response: -<ol> -<li>Downloads the URL and stores it into a file via the media storage -provider and saves the local media metadata.</li> -<li>Generates thumbnails.</li> -<li>Updates the Open Graph response based on image properties.</li> -</ol> -</li> -</ol> -</li> -<li>If the media is JSON and an oEmbed URL was found: -<ol> -<li>Convert the oEmbed response to an Open Graph response.</li> -<li>If a thumbnail or image is in the oEmbed response: -<ol> -<li>Downloads the URL and stores it into a file via the media storage -provider and saves the local media metadata.</li> -<li>Generates thumbnails.</li> -<li>Updates the Open Graph response based on image properties.</li> -</ol> -</li> -</ol> -</li> -<li>Stores the result in the database cache.</li> -</ol> -</li> -<li>Returns the result.</li> -</ol> -<p>The in-memory cache expires after 1 hour.</p> -<p>Expired entries in the database cache (and their associated media files) are -deleted every 10 seconds. The default expiration time is 1 hour from download.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="user-directory-api-implementation"><a class="header" href="#user-directory-api-implementation">User Directory API Implementation</a></h1> <p>The user directory is currently maintained based on the 'visible' users on this particular server - i.e. ones which your account shares a room with, or @@ -10364,10 +10290,23 @@ command. This is a script that is distributed as part of synapse. It is possibly already on your <code>$PATH</code> depending on how Synapse was installed.</p> <p>Finding your user's <code>access_token</code> is client-dependent, but will usually be shown in the client's settings.</p> <h2 id="making-an-admin-api-request"><a class="header" href="#making-an-admin-api-request">Making an Admin API request</a></h2> +<p>For security reasons, we <a href="usage/administration/admin_api/reverse_proxy.html#synapse-administration-endpoints">recommend</a> +that the Admin API (<code>/_synapse/admin/...</code>) should be hidden from public view using a +reverse proxy. This means you should typically query the Admin API from a terminal on +the machine which runs Synapse.</p> <p>Once you have your <code>access_token</code>, you will need to authenticate each request to an Admin API endpoint by providing the token as either a query parameter or a request header. To add it as a request header in cURL:</p> <pre><code class="language-sh">curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request> </code></pre> +<p>For example, suppose we want to +<a href="usage/administration/admin_api/user_admin_api.html#query-user-account">query the account</a> of the user +<code>@foo:bar.com</code>. We need an admin access token (e.g. +<code>syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk</code>), and we need to know which port +Synapse's <a href="usage/administration/admin_api/config_documentation.html#listeners"><code>client</code> listener</a> is listening +on (e.g. <code>8008</code>). Then we can use the following command to request the account +information from the Admin API.</p> +<pre><code class="language-sh">curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com +</code></pre> <p>For more details on access tokens in Matrix, please refer to the complete <a href="https://matrix.org/docs/spec/client_server/r0.6.1#using-access-tokens">matrix spec documentation</a>.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="account-validity-api"><a class="header" href="#account-validity-api">Account validity API</a></h1> @@ -11280,6 +11219,7 @@ Specifically, rooms are selected if the search term is contained in</p> <li><code>guest_access</code> - Whether guests can join the room. One of: ["can_join", "forbidden"].</li> <li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li> <li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li> +<li><code>room_type</code> - The type of the room taken from the room's creation event; for example "m.space" if the room is a space. If the room does not define a type, the value will be <code>null</code>.</li> </ul> </li> </ul> @@ -11320,7 +11260,8 @@ get the "previous page" of results.</li> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 93534 + "state_events": 93534, + "room_type": "m.space" }, ... (8 hidden items) ... { @@ -11337,7 +11278,8 @@ get the "previous page" of results.</li> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 8345 + "state_events": 8345, + "room_type": null } ], "offset": 0, @@ -11364,7 +11306,8 @@ get the "previous page" of results.</li> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 8 + "state_events": 8, + "room_type": null } ], "offset": 0, @@ -11391,7 +11334,8 @@ get the "previous page" of results.</li> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 93534 + "state_events": 93534, + "room_type": null }, ... (98 hidden items) ... { @@ -11408,7 +11352,8 @@ get the "previous page" of results.</li> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 8345 + "state_events": 8345, + "room_type": "m.space" } ], "offset": 0, @@ -11439,7 +11384,9 @@ parameter to the value of <code>next_token</code>.</p> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 93534 + "state_events": 93534, + "room_type": "m.space" + }, ... (48 hidden items) ... { @@ -11456,7 +11403,9 @@ parameter to the value of <code>next_token</code>.</p> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 8345 + "state_events": 8345, + "room_type": null + } ], "offset": 100, @@ -11487,6 +11436,8 @@ end of the list.</p> <li><code>guest_access</code> - Whether guests can join the room. One of: ["can_join", "forbidden"].</li> <li><code>history_visibility</code> - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].</li> <li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li> +<li><code>room_type</code> - The type of the room taken from the room's creation event; for example "m.space" if the room is a space. +If the room does not define a type, the value will be <code>null</code>.</li> </ul> <p>The API is:</p> <pre><code>GET /_synapse/admin/v1/rooms/<room_id> @@ -11509,7 +11460,8 @@ end of the list.</p> "join_rules": "invite", "guest_access": null, "history_visibility": "shared", - "state_events": 93534 + "state_events": 93534, + "room_type": "m.space" } </code></pre> <h1 id="room-members-api"><a class="header" href="#room-members-api">Room Members API</a></h1> @@ -12603,7 +12555,7 @@ member are returned.</p> These are media that the user has uploaded themselves (<a href="admin_api/../media_repository.html#local-media">local media</a>), as well as <a href="admin_api/../media_repository.html#url-previews">URL preview images</a> requested by the user if the -<a href="admin_api/../development/url_previews.html">feature is enabled</a>.</p> +<a href="admin_api/../usage/configuration/config_documentation.html#url_preview_enabled">feature is enabled</a>.</p> <p>By default, the response is ordered by descending creation date and ascending media ID. The newest media is on top. You can change the order with parameters <code>order_by</code> and <code>dir</code>.</p> @@ -15209,6 +15161,21 @@ be required.</p> <p>because <a href="https://github.com/pypa/build"><code>build</code></a> is a standardish tool which doesn't require poetry. (It's what we use in CI too). However, you could try <code>poetry build</code> too.</p> +<h1 id="troubleshooting-4"><a class="header" href="#troubleshooting-4">Troubleshooting</a></h1> +<h2 id="check-the-version-of-poetry-with-poetry---version"><a class="header" href="#check-the-version-of-poetry-with-poetry---version">Check the version of poetry with <code>poetry --version</code>.</a></h2> +<p>At the time of writing, the 1.2 series is beta only. We have seen some examples +where the lockfiles generated by 1.2 prereleasese aren't interpreted correctly +by poetry 1.1.x. For now, use poetry 1.1.14, which includes a critical +<a href="https://github.com/python-poetry/poetry/pull/5973">change</a> needed to remain +<a href="https://github.com/pypi/warehouse/pull/11775">compatible with PyPI</a>.</p> +<p>It can also be useful to check the version of <code>poetry-core</code> in use. If you've +installed <code>poetry</code> with <code>pipx</code>, try <code>pipx runpip poetry list | grep poetry-core</code>.</p> +<h2 id="clear-caches-poetry-cache-clear---all-pypi"><a class="header" href="#clear-caches-poetry-cache-clear---all-pypi">Clear caches: <code>poetry cache clear --all pypi</code>.</a></h2> +<p>Poetry caches a bunch of information about packages that isn't readily available +from PyPI. (This is what makes poetry seem slow when doing the first +<code>poetry install</code>.) Try <code>poetry cache list</code> and <code>poetry cache clear --all <name of cache></code> to see if that fixes things.</p> +<h2 id="try---verbose-or---dry-run-arguments"><a class="header" href="#try---verbose-or---dry-run-arguments">Try <code>--verbose</code> or <code>--dry-run</code> arguments.</a></h2> +<p>Sometimes useful to see what poetry's internal logic is.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="cancellation"><a class="header" href="#cancellation">Cancellation</a></h1> <p>Sometimes, requests take a long time to service and clients disconnect before Synapse produces a response. To avoid wasting resources, Synapse @@ -16376,8 +16343,7 @@ level).</li> users.</li> <li>caches avatars, attachments and their thumbnails for media uploaded by remote users.</li> -<li>caches resources and thumbnails used for -<a href="development/url_previews.html">URL previews</a>.</li> +<li>caches resources and thumbnails used for URL previews.</li> </ul> <p>All media in Matrix can be identified by a unique <a href="https://spec.matrix.org/latest/client-server-api/#matrix-content-mxc-uris">MXC URI</a>, @@ -16415,9 +16381,7 @@ remote_thumbnail/matrix.org/aa/bb/cccccccccccccccccccc/128-96-image-jpeg-scale <pre><code>remote_thumbnail/matrix.org/aa/bb/cccccccccccccccccccc/128-96-image-jpeg </code></pre> <p>Note that <code>remote_thumbnail/</code> does not have an <code>s</code>.</p> -<h2 id="url-previews-2"><a class="header" href="#url-previews-2">URL Previews</a></h2> -<p>See <a href="development/url_previews.html">URL Previews</a> for documentation on the URL preview -process.</p> +<h2 id="url-previews-1"><a class="header" href="#url-previews-1">URL Previews</a></h2> <p>When generating previews for URLs, Synapse may download and cache various resources, including images. These resources are assigned temporary media IDs of the form <code>yyyy-mm-dd_aaaaaaaaaaaaaaaa</code>, where <code>yyyy-mm-dd</code> is the current |