From be84aeacf620d9eb01de07a52d67bd4035985fbd Mon Sep 17 00:00:00 2001 From: reivilibre Date: Tue, 2 Aug 2022 10:56:24 +0000 Subject: deploy: c2f48712265de92bd833a15f86935bed1f1efbe5 --- latest/print.html | 572 +++++++++++++++++++++++++----------------------------- 1 file changed, 268 insertions(+), 304 deletions(-) (limited to 'latest/print.html') 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 @@ @@ -909,57 +909,27 @@ to proxied traffic.)

} } -

Caddy v1

-
matrix.example.com {
-  proxy /_matrix http://localhost:8008 {
-    transparent
-  }
-
-  proxy /_synapse/client http://localhost:8008 {
-    transparent
-  }
-}
-
-example.com:8448 {
-  proxy / http://localhost:8008 {
-    transparent
-  }
-}
-

Caddy v2

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
 }

Delegation example:

-
(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"}}`
-    }
+
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
 }
 

 
Apache

@@ -1642,6 +1612,26 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
+

Upgrading to v1.64.0

+

Deprecation of the ability to delegate e-mail verification to identity servers

+

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.

+

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. +Consult the configuration documentation for more information.

+

The option that will be removed is account_threepid_delegates.email.

+

Changes to the event replication streams

+

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.

+

Once all workers are upgraded to v1.64 (or downgraded to v1.63), event +replication will resume as normal.

+

frozendict release

+

frozendict 2.3.3 +has recently been released, which fixes a memory leak that occurs during /sync +requests. We advise server administrators who installed Synapse via pip to upgrade +frozendict with pip install --upgrade frozendict. The Docker image +matrixdotorg/synapse and the Debian packages from packages.matrix.org already +include the updated library.

Upgrading to v1.62.0

New signatures for spam checker callbacks

As a followup to changes in v1.60.0, the following spam-checker callbacks have changed signature:

@@ -3158,12 +3148,12 @@ useful just for development purposes. See

This section contains information on tweaking Synapse via the various options in the configuration file. A configuration file should have been generated when you installed Synapse.

Configuring Synapse

-

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, +

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 here.

Config Conventions

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.

In addition, configuration options referring to size use the following suffixes:

For example, setting max_avatar_size: 10M means that Synapse will not accept files larger than 10,485,760 bytes -for a user avatar.

+for a user avatar.

YAML

The configuration file is a YAML file, which means that certain syntax rules apply if you want your config file to be read properly. A few helpful things to know:

Contents

@@ -3252,7 +3242,7 @@ shown.

documentation on how to configure or create custom modules for Synapse.

modules

-

Use the module sub-option to add modules under this option to extend functionality. +

Use the module sub-option to add modules under this option to extend functionality. The module setting then has a sub-option, config, which can be used to define some configuration for the module.

Defaults to none.

@@ -3282,9 +3272,9 @@ a clean server_name.

The server_name 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.

-

There is no default for this option.

+

There is no default for this option.

Example configuration #1:

-
server_name: matrix.org 
+
server_name: matrix.org
 

 
Example configuration #2:

 
server_name: localhost:8080
@@ -3297,7 +3287,7 @@ lowercase and may contain an explicit port.

 

 

 
web_client_location

-
The absolute URL to the web client which / will redirect to. Defaults to none. 

+
The absolute URL to the web client which / will redirect to. Defaults to none.

 
Example configuration:

 
web_client_location: https://riot.example.com/
 

@@ -3318,7 +3308,7 @@ Otherwise, it should be the URL to reach Synapse's client HTTP listener (see
 
By default, other servers will try to reach our server on port 8448, which can
 be inconvenient in some environments.

 
Provided https://<server_name>/ on port 443 is routed to Synapse, this
-option configures Synapse to serve a file at https://<server_name>/.well-known/matrix/server. 
+option configures Synapse to serve a file at https://<server_name>/.well-known/matrix/server.
 This will tell other servers to send traffic to port 443 instead.

 
This option currently defaults to false.

 
See https://matrix-org.github.io/synapse/latest/delegate.html for more
@@ -3330,11 +3320,12 @@ information.

 
extra_well_known_client_content 

 
This option allows server runners to add arbitrary key-value pairs to the client-facing .well-known response.
 Note that the public_baseurl config option must be provided for Synapse to serve a response to /.well-known/matrix/client at all.

-
If this option is provided, it parses the given yaml to json and 
+
If this option is provided, it parses the given yaml to json and
 serves it on /.well-known/matrix/client endpoint
 alongside the standard properties.

+
Added in Synapse 1.62.0.

 
Example configuration:

-
extra_well_known_client_content : 
+
extra_well_known_client_content :
   option1: value1
   option2: value2
 

@@ -3342,15 +3333,15 @@ alongside the standard properties.

 
soft_file_limit

 
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. 

+Defaults to 0.

 
Example configuration:

 
soft_file_limit: 3
 

 

 
presence

 
Presence tracking allows users to see the state (e.g online/offline)
-of other local and remote users. Set the enabled sub-option to false to

-disable presence tracking on this homeserver. Defaults to true. 
+of other local and remote users. Set the enabled sub-option to false to
+disable presence tracking on this homeserver. Defaults to true.
 This option replaces the previous top-level 'use_presence' option.

 
Example configuration:

 
presence:
@@ -3358,8 +3349,8 @@ This option replaces the previous top-level 'use_presence' option.

 

 

 
require_auth_for_profile_requests

-
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 
+
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 allow_profile_lookup_over_federation is set to false.

 
Example configuration:

 
require_auth_for_profile_requests: true
@@ -3367,10 +3358,10 @@ via the federation API, unless allow_profile_lookup_over_federation
 

 
limit_profile_requests_to_users_who_share_rooms

 
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.

-
Example configuration: 

+
Example configuration:

 
limit_profile_requests_to_users_who_share_rooms: true
 

 

@@ -3403,7 +3394,7 @@ rooms directory via federation. Defaults to false.

 
The default room version for newly created rooms on this server.

 
Known room versions are listed here

 
For example, for room version 1, default_room_version should be set
-to "1". 

+to "1".

 
Currently defaults to "9".

 
Example configuration:

 
default_room_version: "8"
@@ -3411,14 +3402,14 @@ to "1". 

 

 
gc_thresholds

 
The garbage collection threshold parameters to pass to gc.set_threshold, if defined.
-Defaults to none. 

+Defaults to none.

 
Example configuration:

 
gc_thresholds: [700, 10, 10]
 

 

 
gc_min_interval

 
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 [1s, 10s, 30s] 
+the GC thresholds. This ensures that we don't do GC too frequently. A value of [1s, 10s, 30s]
 indicates that a second must pass between consecutive generation 0 GCs, etc.

 
Defaults to [1s, 10s, 30s].

 
Example configuration:

@@ -3498,7 +3489,7 @@ configuration.

 
Sub-options for each listener include:

 
    
 
  • 
-
    port: the TCP port to bind to. 
    
+
    port: the TCP port to bind to.
    
 
    • 
 
  • 
 
    bind_addresses: 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
 org.matrix.dummy_event event, which will reduce the forward extremities
 in the room.
    
-
    This setting defines the threshold (i.e. number of forward extremities in the room) at which dummy events are sent. 
+
    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.
    
 
    Example configuration:
    
 
    dummy_events_threshold: 5
@@ -3658,30 +3649,30 @@ delete any device that hasn't been accessed for more than the specified amount o
 
    Useful options for Synapse admins.
    
 
    
 
    admin_contact
    
-
    How to reach the server admin, used in ResourceLimitError. Defaults to none. 
    
+
    How to reach the server admin, used in ResourceLimitError. Defaults to none.
    
 
    Example configuration:
    
 
    admin_contact: 'mailto:admin@server.com'
 
    
 
    
 
    hs_disabled and hs_disabled_message
    
 
    Blocks users from connecting to the homeserver and provides a human-readable reason
-why the connection was blocked. Defaults to false. 
    
+why the connection was blocked. Defaults to false.
    
 
    Example configuration:
    
 
    hs_disabled: true
 hs_disabled_message: 'Reason for why the HS is blocked'
 
    
 
    
 
    limit_usage_by_mau
    
-
    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 
+
    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 ResourceLimitError with error type Codes.RESOURCE_LIMIT_EXCEEDED.
 Defaults to false. If this is enabled, a value for max_mau_value must also be set.
    
 
    Example configuration:
    
-
    limit_usage_by_mau: true 
+
    limit_usage_by_mau: true
 
    
 
    
 
    max_mau_value
    
-
    This option sets the hard limit of monthly active users above which the server will start 
+
    This option sets the hard limit of monthly active users above which the server will start
 blocking user actions if limit_usage_by_mau is enabled. Defaults to 0.
    
 
    Example configuration:
    
 
    max_mau_value: 50
@@ -3692,7 +3683,7 @@ blocking user actions if limit_usage_by_mau 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. 
    
+session. Defaults to 0.
    
 
    Example configuration:
    
 
    mau_trial_days: 5
 
    
@@ -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 mau_trial_days instead.
    
 
    Example configuration:
    
-
    mau_appservice_trial_days: 
+
    mau_appservice_trial_days:
   my_appservice_id: 3
   another_appservice_id: 6
 
    
@@ -3721,7 +3712,7 @@ means that alerting is enabled.
    
 
    mau_stats_only
    
 
    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 limit_usage_by_mau
-is true, this is implied to be true. Defaults to false. 
    
+is true, this is implied to be true. Defaults to false.
    
 
    Example configuration:
    
 
    mau_stats_only: true
 
    
@@ -3739,7 +3730,7 @@ reserved threepid (3rd party identifier).
    
 
    
 
    server_context
    
 
    This option is used by phonehome stats to group together related servers.
-Defaults to none. 
    
+Defaults to none.
    
 
    Example configuration:
    
 
    server_context: context
 
    
@@ -3753,11 +3744,11 @@ resource-constrained. Options for this setting include:
    
 
  • enabled: whether this check is enabled. Defaults to false.
    • 
 
  • complexity: the limit above which rooms cannot be joined. The default is 1.0.
    • 
 
  • complexity_error: override the error which is returned when the room is too complex with a
-custom message. 
    • 
+custom message.
    • 
 
  • admins_can_join: allow server admins to join complex rooms. Default is false.
    • 
 

 
Room complexity is an arbitrary measure based on factors such as the number of
-users in the room. 

+users in the room.

 
Example configuration:

 
limit_remote_rooms:
   enabled: true
@@ -3783,7 +3774,7 @@ Defaults to true.

 

 
max_avatar_size

 
The largest permissible file size in bytes for a user avatar. Defaults to no restriction.
-Use M for MB and K for KB. 

+Use M for MB and K for KB.

 
Note that user avatar changes will not work if this is set without using Synapse's media repository.

 
Example configuration:

 
max_avatar_size: 10M
@@ -3815,7 +3806,7 @@ this period redacted events get replaced with their redacted form in the DB.

 
request_token_inhibit_3pid_errors

 
Inhibits the /requestToken endpoints from returning an error that might leak
 information about whether an e-mail address is in use or not on this
-homeserver. 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.

 

 
templates and custom_template_directory

 
These options define templates to use when generating email or HTML page contents.
-The custom_template_directory determines which directory Synapse will try to 
+The custom_template_directory 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.

 
See here for more
 information about using custom templates.

@@ -3861,20 +3852,20 @@ server level.

 the allowed_lifetime_min and allowed_lifetime_max config options.

 
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. 

+filter events received over federation so that events that should have been
+purged are ignored and not stored again.

 
The message retention policies feature is disabled by default.

 
This setting has the following sub-options:

 
    
 
  • 
 
    default_policy: 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 
-min_lifetime and max_lifetime sub-options associated with it. Note that the 
-value of min_lifetime doesn't matter much because Synapse doesn't take it into account yet. 
    
+'m.room.retention' state event. This option is further specified by the
+min_lifetime and max_lifetime sub-options associated with it. Note that the
+value of min_lifetime doesn't matter much because Synapse doesn't take it into account yet.
    
 
    • 
 
  • 
-
    allowed_lifetime_min and allowed_lifetime_max: Retention policy limits. If 
-set, and the state of a room contains a m.room.retention event in its state 
+
    allowed_lifetime_min and allowed_lifetime_max: Retention policy limits. If
+set, and the state of a room contains a m.room.retention event in its state
 which contains a min_lifetime or a max_lifetime that's out of these bounds,
 Synapse will cap the room's policy to these limits when running purge jobs.
    
 
    • 
@@ -3919,7 +3910,7 @@ configuration).
    
     - longest_max_lifetime: 3d
       interval: 12h
     - shortest_max_lifetime: 3d
-      interval: 1d  
+      interval: 1d
 

 

 
TLS

@@ -3928,16 +3919,16 @@ configuration).

 
tls_certificate_path

 
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. 

+certificate, signed by a recognised Certificate Authority. Defaults to none.

 
Be sure to use a .pem file that includes the full certificate chain including
 any intermediate certificates (for instance, if using certbot, use
-fullchain.pem as your certificate, not cert.pem). 

+fullchain.pem as your certificate, not cert.pem).

 
Example configuration:

 
tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt"
 

 

 
tls_private_key_path

-
PEM-encoded private key for TLS. Defaults to none. 

+
PEM-encoded private key for TLS. Defaults to none.

 
Example configuration:

 
tls_private_key_path: "CONFDIR/SERVERNAME.tls.key"
 

@@ -4072,12 +4063,12 @@ variable would be SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0.

 
  • 
 
    expire_caches: 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. 
    
+caches may result in excessive memory usage.
    
 
    • 
 
  • 
 
    cache_entry_ttl: If expire_caches is enabled, this flag controls how long an entry can
 be in a cache without having been accessed before being evicted.
-Defaults to 30m. 
    
+Defaults to 30m.
    
 
    • 
 
  • 
 
    sync_response_cache_duration: 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.
    
+
    Changed in Synapse 1.62.0: The default was changed from 0 to 2m.
    
 
    • 
 
  • 
 
    cache_autotuning and its sub-options max_cache_memory_usage, target_cache_memory_usage, and
-min_cache_ttl work in conjunction with each other to maintain a balance between cache memory 
-usage and cache entry availability. You must be using jemalloc 
+min_cache_ttl work in conjunction with each other to maintain a balance between cache memory
+usage and cache entry availability. You must be using jemalloc
 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 min_cache_ttl is hit. There is no d
 for this option.
    • 
 
  • min_cache_ttl sets a limit under which newer cache entries are not evicted and is only applied when
 caches are actively being evicted/max_cache_memory_usage 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. 
    • 
+from being emptied while Synapse is evicting due to memory. There is no default value for this option.
 
 
 
@@ -4123,7 +4115,7 @@ from being emptied while Synapse is evicting due to memory. There is no default
 SIGHUP signal to Synapse using e.g.
    
 
    kill -HUP [PID_OF_SYNAPSE_PROCESS]
 
    
-
    If you are running multiple workers, you must individually update the worker 
+
    If you are running multiple workers, you must individually update the worker
 config file and send this signal to each worker process.
    
 
    If you're using the example systemd service
 file in Synapse's contrib directory, you can send a SIGHUP signal by using
@@ -4139,7 +4131,7 @@ its data.
    
 
      
 
    • 
 
      name: this option specifies the database engine to use: either sqlite3 (for SQLite)
-or psycopg2 (for PostgreSQL). If no name is specified Synapse will default to SQLite. 
      
+or psycopg2 (for PostgreSQL). If no name is specified Synapse will default to SQLite.
      
 
      • 
 
    • 
 
      txn_limit gives the maximum number of transactions to run per connection
@@ -4280,7 +4272,7 @@ when Synapse is started.
      
 
    
 
    
 
    Logging
    
-
    Config options related to logging. 
    
+
    Config options related to logging.
    
 
    
 
    log_config
    
 
    This option specifies a yaml python logging config file as described here.
    
@@ -4289,7 +4281,7 @@ when Synapse is started.
    
 
    
 
    
 
    Ratelimiting
    
-
    Options related to ratelimiting in Synapse. 
    
+
    Options related to ratelimiting in Synapse.
    
 
    Each ratelimiting configuration is made of two parameters:
    
 
      
 
    • per_second: number of requests a client can send per second.
      • 
@@ -4308,7 +4300,7 @@ is using. It defaults to: per_second: 0.2, burst_count: 10
 
      rc_registration
      
 
      This option ratelimits registration requests based on the client's IP address.
-It defaults to per_second: 0.17, burst_count: 3. 
      
+It defaults to per_second: 0.17, burst_count: 3.
      
 
      Example configuration:
      
 
      rc_registration:
   per_second: 0.15
@@ -4316,7 +4308,7 @@ It defaults to per_second: 0.17, burst_count: 3. 
      
 
      
 
      
 
      rc_registration_token_validity
      
-
      This option checks the validity of registration tokens that ratelimits requests based on 
+
      This option checks the validity of registration tokens that ratelimits requests based on
 the client's IP address.
 Defaults to per_second: 0.1, burst_count: 5.
      
 
      Example configuration:
      
@@ -4357,9 +4349,9 @@ attempts for this account. Defaults to per_second: 0.17, burs
 
    
 
    
 
    rc_admin_redaction
    
-
    This option sets ratelimiting redactions by room admins. If this is not explicitly 
+
    This option sets ratelimiting redactions by room admins. If this is not explicitly
 set then it uses the same ratelimiting as per rc_message. This is useful
-to allow room admins to deal with abuse quickly. 
    
+to allow room admins to deal with abuse quickly.
    
 
    Example configuration:
    
 
    rc_admin_redaction:
   per_second: 1
@@ -4370,13 +4362,13 @@ to allow room admins to deal with abuse quickly. 
    
 
    This option allows for ratelimiting number of rooms a user can join. This setting has the following sub-options:
    
 
      
 
    • 
-
      local: ratelimits when users are joining rooms the server is already in. 
+
      local: ratelimits when users are joining rooms the server is already in.
 Defaults to per_second: 0.1, burst_count: 10.
      
 
      • 
 
    • 
 
      remote: ratelimits when users are trying to join rooms not on the server (which
 can be more computationally expensive than restricting locally). Defaults to
-per_second: 0.01, burst_count: 10 
      
+per_second: 0.01, burst_count: 10
      
 
      • 
 
    
 
    Example configuration:
    
@@ -4389,6 +4381,19 @@ can be more computationally expensive than restricting locally). Defaults to
     burst_count: 12
 
    
 
    
+
    rc_joins_per_room
    
+
    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.
    
+
    By default, one join is permitted to a room every second, with an accumulating
+buffer of up to ten instantaneous joins.
    
+
    Example configuration (default values):
    
+
    rc_joins_per_room:
+  per_second: 1
+  burst_count: 10
+
    
+
    Added in Synapse 1.64.0.
    
+
    
 
    rc_3pid_validation
    
 
    This option ratelimits how often a user or IP can attempt to validate a 3PID.
 Defaults to per_second: 0.003, burst_count: 5.
    
@@ -4399,9 +4404,9 @@ Defaults to per_second: 0.003, burst_count: 5.
    
 
    
 
    
 
    rc_invites
    
-
    This option sets ratelimiting how often invites can be sent in a room or to a 
+
    This option sets ratelimiting how often invites can be sent in a room or to a
 specific user. per_room defaults to per_second: 0.3, burst_count: 10 and
-per_user defaults to per_second: 0.003, burst_count: 5. 
    
+per_user defaults to per_second: 0.003, burst_count: 5.
    
 
    Client requests that invite user(s) when creating a
 room
 will count against the rc_invites.per_room limit, whereas
@@ -4414,6 +4419,7 @@ limit only, as Synapse presumes ratelimiting by room will be done by the sending
 sender, meaning that a rc_invite.per_user.burst_count of 5 mandates that a single user
 cannot receive more than a burst of 5 invites at a time.
    
 
    In contrast, the rc_invites.per_issuer limit applies to the issuer of the invite, meaning that a rc_invite.per_issuer.burst_count of 5 mandates that single user cannot send more than a burst of 5 invites at a time.
    
+
    Changed in version 1.63: added the per_issuer limit.
    
 
    Example configuration:
    
 
    rc_invites:
   per_room:
@@ -4426,7 +4432,6 @@ cannot receive more than a burst of 5 invites at a time.
    
     per_second: 0.5
     burst_count: 5
 
    
-
    Changed in version 1.63: added the per_issuer limit.
    
 
    
 
    rc_third_party_invite
    
 
    This option ratelimits 3PID invites (i.e. invites sent to a third-party ID
@@ -4439,7 +4444,7 @@ sending the invite. Defaults to per_second: 0.2, burst_count:

    rc_federation

    -

    Defines limits on federation requests.

    +

    Defines limits on federation requests.

    The rc_federation configuration has the following sub-options:

    Example configuration:

    media_storage_providers:
@@ -4510,7 +4515,7 @@ locations. Defaults to none. Associated sub-options are:
    
 
    The largest allowed upload size in bytes.
    
 
    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 here for more on using a reverse proxy with Synapse. 
    
+See here for more on using a reverse proxy with Synapse.
    
 
    Example configuration:
    
 
    max_upload_size: 60M
 
    
@@ -4526,7 +4531,7 @@ See here 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. 
    
+from a precalculated list. Defaults to false.
    
 
    Example configuration:
    
 
    dynamic_thumbnails: true
 
    
@@ -4632,7 +4637,7 @@ you use the following example list as a starting point.
    
 to access even if they are specified in url_preview_ip_range_blacklist.
 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. 
    
+website only visible in your network. Defaults to none.
    
 
    Example configuration:
    
 
    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.
    
 
    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
 here for more
 information. Some examples are:
    
 
      
@@ -4709,8 +4714,8 @@ using quality value syntax (;q=). '*' translates to any language.
      
 
      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 disable_default_providers to true to disable using
-these default oEmbed URLs. Use additional_providers to specify additional files with oEmbed configuration (each 
-should be in the form of providers.json). By default this list is empty. 
      
+these default oEmbed URLs. Use additional_providers to specify additional files with oEmbed configuration (each
+should be in the form of providers.json). By default this list is empty.
      
 
      Example configuration:
      
 
      oembed:
   disable_default_providers: true
@@ -4722,14 +4727,14 @@ should be in the form of providers.json). By default this list is empty. 
      
 
      See here for full details on setting up captcha.
      
 
      
 
      recaptcha_public_key
      
-
      This homeserver's ReCAPTCHA public key. Must be specified if enable_registration_captcha is 
+
      This homeserver's ReCAPTCHA public key. Must be specified if enable_registration_captcha is
 enabled.
      
 
      Example configuration:
      
 
      recaptcha_public_key: "YOUR_PUBLIC_KEY"
 
      
 
      
 
      recaptcha_private_key
      
-
      This homeserver's ReCAPTCHA private key. Must be specified if enable_registration_captcha is 
+
      This homeserver's ReCAPTCHA private key. Must be specified if enable_registration_captcha is
 enabled.
      
 
      Example configuration:
      
 
      recaptcha_private_key: "YOUR_PRIVATE_KEY"
@@ -4737,7 +4742,7 @@ enabled.
      
 
      
 
      enable_registration_captcha
      
 
      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.
      
 
      Example configuration:
      
 
      enable_registration_captcha: true
@@ -4791,7 +4796,7 @@ it allows users to connect to arbitrary endpoints without having first signed up
 
      
 
      enable_registration
      
 
      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 enable_registration_without_verification to true.
      
 
      Example configuration:
      
 
      enable_registration: true
@@ -4808,7 +4813,7 @@ unless enable_registration is also enabled.
      
 
      session_lifetime
      
 
      Time that a user's session remains valid for, after they log in.
      
 
      Note that this is not currently compatible with guest logins.
      
-
      Note also that this is calculated at login time: changes are not applied retrospectively to users who have already 
+
      Note also that this is calculated at login time: changes are not applied retrospectively to users who have already
 logged in.
      
 
      By default, this is infinite.
      
 
      Example configuration:
      
@@ -4819,7 +4824,7 @@ logged in.
      
 
      Time that an access token remains valid for, if the session is using refresh tokens.
      
 
      For more information about refresh tokens, please see the manual.
      
 
      Note that this only applies to clients which advertise support for refresh tokens.
      
-
      Note also that this is calculated at login time and refresh time: changes are not applied to 
+
      Note also that this is calculated at login time and refresh time: changes are not applied to
 existing sessions until they are refreshed.
      
 
      By default, this is 5 minutes.
      
 
      Example configuration:
      
@@ -4930,24 +4935,20 @@ This setting is ignored unless public_baseurl is also explicitly se
 
      
 
      
 
      account_threepid_delegates
      
-
      Handle threepid (email/phone etc) registration and password resets through a set of
-trusted identity servers. Note that this allows the configured identity server to
-reset passwords for accounts!
      
-
      Be aware that if email 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.
      
-
      Additionally, if msisdn 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.
      
-
      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.
      
-
      Servers handling the these requests must answer the /requestToken endpoints defined
-by the Matrix Identity Service API specification.
      
+
      Delegate verification of phone numbers to an identity server.
      
+
      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 account_threepid_delegates.msisdn option.
      
+
      If this is left unspecified, Synapse will not allow users to add phone numbers to
+their account.
      
+
      (Servers handling the these requests must answer the /requestToken endpoints defined
+by the Matrix Identity Service API
+specification.)
      
+
      Updated in Synapse 1.64.0: The email option is deprecated.
      
 
      Example configuration:
      
 
      account_threepid_delegates:
-    email: https://example.com     # Delegate email sending to example.com
     msisdn: http://localhost:8090  # Delegate SMS sending to this local process
 
      
 
      
@@ -4984,7 +4985,7 @@ to the rooms listed under this option.
      
 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. 
      
+relating to auto-joining rooms below.
      
 
      Example configuration:
      
 
      auto_join_rooms:
   - "#exampleroom:example.com"
@@ -5024,9 +5025,9 @@ effect if autocreate_auto_join_rooms is true.
      
 
        
 
      • "public_chat": the room is joinable by anyone, including
 federated servers if autocreate_auto_join_rooms_federated is true (the default).
        • 
-
      • "private_chat": an invitation is required to join these rooms. 
        • 
+
      • "private_chat": an invitation is required to join these rooms.
        • 
 
      • "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. 
        • 
+assigned a power level of 100 upon joining the room.
 
      
 
      If a value of "private_chat" or "trusted_private_chat" is used then
 auto_join_mxid_localpart must also be configured.
      
@@ -5075,7 +5076,7 @@ raise an error if the registration completes and the username conflicts.
      
 
      Config options related to metrics.
      
 
      
 
      enable_metrics
      
-
      Set to true to enable collection and rendering of performance metrics. 
+
      Set to true to enable collection and rendering of performance metrics.
 Defaults to false.
      
 
      Example configuration:
      
 
      enable_metrics: true
@@ -5083,10 +5084,10 @@ Defaults to false.
      
 
      
 
      sentry
      
 
      Use this option to enable sentry integration. Provide the DSN assigned to you by sentry
-with the dsn setting. 
      
+with the dsn setting.
      
 
      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.
      
 
      Example configuration:
      
@@ -5097,7 +5098,7 @@ through insecure notification channels if so configured.
      
 
      metrics_flags
      
 
      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 known_servers, which publishes 
+Currently the only option is known_servers, which publishes
 synapse_federation_known_servers, a gauge of the number of
 servers this homeserver knows about, including itself. May cause
 performance problems on large homeservers.
      
@@ -5130,7 +5131,7 @@ Defaults to https://matrix.org/report-usage-stats/push
      
 
      
 
      room_prejoin_state:
      
 
      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:
      
 
        
 
      • m.room.join_rules
        • 
@@ -5143,7 +5144,7 @@ receive invites to the room:
        
 
      
 
      To change the default behavior, use the following sub-options:
      
 
        
-
      • disable_default_event_types: set to true to disable the above defaults. If this 
+
      • disable_default_event_types: set to true to disable the above defaults. If this
 is enabled, only the event types listed in additional_event_types are shared.
 Defaults to false.
        • 
 
      • additional_event_types: 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.
        • 
 
      • accept_keys_insecurely: a boolean. Normally, if verify_keys is unset,
-and federation_verify_certificates is not true, synapse will refuse 
+and federation_verify_certificates is not true, 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 allow_unsolicited to true under <
 section.
        • 
 
      
 
-
    • config_path: specify a separate pysaml2 configuration file thusly: 
+
    • config_path: specify a separate pysaml2 configuration file thusly:
 config_path: "CONFDIR/sp_conf.py"
      • 
 
    • saml_session_lifetime: The lifetime of a SAML session. This defines how long a user has to
 complete the authentication process, if allow_unsolicited is unset. The default is 15 minutes.
      • 
-
    • user_mapping_provider: 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 
+
    • user_mapping_provider: 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
 user_mapping_provider has the following attributes:
 
        
-
      • module: The custom module's class. 
        • 
-
      • config: Custom configuration values for the module. Use the values provided in the 
+
      • module: The custom module's class.
        • 
+
      • config: 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 parse_config method. The built-in provider takes the following two
@@ -5350,7 +5351,7 @@ The default is hexencode. 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 user_ids
 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'. 
        • 
+The default is 'uid'.
 
      • attribute_requirements: It is possible to configure Synapse to only allow logins if SAML attributes
 match particular values. The requirements can be listed under
 attribute_requirements 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.
        
 
      • 
 
        localpart_template: 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 sso_auth_account_details.html 
+own username (see the documentation for the sso_auth_account_details.html
 template). This template can use the localpart_from_email filter.
        
 
        • 
 
      • 
@@ -5609,7 +5610,7 @@ which is set to the claims returned by the UserInfo Endpoint and/or
 in the ID Token.
        
 
        • 
 
      
-
      It is possible to configure Synapse to only allow logins if certain attributes 
+
      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
 attribute_requirements as shown here:
      
 
      attribute_requirements:
@@ -5622,7 +5623,7 @@ match particular values in the OIDC userinfo. The requirements can be listed und
 userinfo by expanding the scopes section of the OIDC config to retrieve
 additional information from the OIDC provider.
      
 
      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 family_name claim MUST be "Stephensson", but the groups
 claim MUST contain "admin".
      
 
      Example configuration:
      
@@ -5682,7 +5683,7 @@ All of the listed attributes must match for the login to be permitted.
      • 
 
      sso
      
 
      Additional settings to use with single-sign on systems such as OpenID Connect,
 SAML2 and CAS.
      
-
      Server admins can configure custom templates for pages related to SSO. See 
+
      Server admins can configure custom templates for pages related to SSO. See
 here for more information.
      
 
      Options include:
      
 
        
@@ -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.
 
      • update_profile_information: 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 enabled is set to true.
        • 
 
      • subject_claim: Name of the claim containing a unique identifier for the user.
 Optional, defaults to sub.
        • 
-
      • issuer: The issuer to validate the "iss" claim against. Optional. If provided the 
+
      • issuer: The issuer to validate the "iss" claim against. Optional. If provided the
 "iss" claim will be required and validated for all JSON web tokens.
        • 
 
      • audiences: 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.
        • 
 
      
 
      Example configuration:
      
 
      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.
 
      
 
      
 
      password_config
      
-
      Use this setting to enable password-based logins. 
      
+
      Use this setting to enable password-based logins.
      
 
      This setting has the following sub-options:
      
 
        
 
      • enabled: Defaults to true.
@@ -5763,10 +5764,10 @@ Set to only_for_reauth to allow users with existing passwords to us
 to log in and reauthenticate, whilst preventing new users from setting passwords.
        • 
 
      • localdb_enabled: Set to false to disable authentication against the local password
 database. This is ignored if enabled is false, and is only useful
-if you have other password_providers. Defaults to true. 
        • 
+if you have other password_providers. Defaults to true.
 
      • pepper: Set the value here to a secret random string for extra security.
 DO NOT CHANGE THIS AFTER INITIAL SETUP!
        • 
-
      • policy: Define and enforce a password policy, such as minimum lengths for passwords, etc. 
+
      • policy: 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:
 
          
 
        • enabled: Defaults to false. Set to true to enable.
          • 
@@ -5799,7 +5800,7 @@ Defaults to false.
 
          
 
          ui_auth
          
 
          The amount of time to allow a user-interactive authentication session to be active.
          
-
          This defaults to 0, meaning the user is queried for their credentials 
+
          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).
          
 
          smtp_host: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
          
 
 
        • 
-
          smtp_port: The port on the mail server for outgoing SMTP. Defaults to 25.
          
+
          smtp_port: The port on the mail server for outgoing SMTP. Defaults to 465 if force_tls is true, else 25.
          
+
          Changed in Synapse 1.64.0: the default port is now aware of force_tls.
          
 
          • 
 
        • 
 
          smtp_user and smtp_pass: Username/password for authentication to the SMTP server. By default, no
 authentication is attempted.
          
 
          • 
 
        • 
+
          force_tls: 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 require_transport_security is ignored.
+It is recommended to enable this if supported by your mail server.
          
+
          New in Synapse 1.64.0.
          
+
          • 
+
        • 
 
          require_transport_security: 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 if the SMTP server supports it. 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
 server_name setting in your Synapse configuration.
          
-
          Here is a list of subjects for notification emails that can be set: 
          
+
          Here is a list of subjects for notification emails that can be set:
          
 
            
 
          • message_from_person_in_room: 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..."
            • 
@@ -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..."
 
          • messages_in_room: 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..."
            • 
-
          • messages_in_room_and_others: Subject to use to notify about multiple messages in multiple rooms. 
+
          • messages_in_room_and_others: 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..."
            • 
 
          • messages_from_person_and_others: 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..."
            • 
-
          • invite_from_person_to_room: Subject to use to notify about an invite to a room which has a name. 
+
          • invite_from_person_to_room: 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..."
            • 
 
          • invite_from_person: 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..."
            • 
@@ -5913,6 +5922,7 @@ ownership. Defaults to "[%(server_name)s] Validate your email"
   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"
 
            Configuration settings related to push notifications
            
 
            
 
            push
            
-
            This setting defines options for push notifications. 
            
+
            This setting defines options for push notifications.
            
 
            This option has a number of sub-options. They are as follows:
            
 
              
 
            • include_content: 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.
              • 
 
            • group_unread_count_by_room: false: 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 rooms the 
+This number can either be calculated as the number of unread messages  for the user, or the number of rooms 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.
              • 
@@ -5987,7 +5997,7 @@ will also not affect rooms created by other servers.
              
 
      
 
      
 
      user_directory
      
-
      This setting defines options related to the user directory. 
      
+
      This setting defines options related to the user directory.
      
 
      This option has the following sub-options:
      
 
        
 
      • enabled:  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.
        • 
 
      • prefer_local_users: 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.
        • 
 
      
 
      Example configuration:
      
@@ -6072,14 +6082,14 @@ Defaults to "Privacy Policy".
      
 
      
 
      stats
      
 
      Settings for local room and user statistics collection. See here
-for more. 
      
+for more.
      
 
        
 
      • enabled: 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. 
        • 
+correctly. Defaults to true.
 
      
 
      Example configuration:
      
-
      stats:  
+
      stats:
   enabled: false
 
      
 
      
@@ -6107,7 +6117,7 @@ notices.
      
 
 
      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. 
      
+users by always returning an empty list for all queries. Defaults to true.
      
 
      Example configuration:
      
 
      enable_room_list_search: false
 
      
@@ -6127,7 +6137,7 @@ can create aliases.
      
 
    • user_id: Matches against the creator of the alias. Defaults to "*".
      • 
 
    • alias: Matches against the alias being created. Defaults to "*".
      • 
 
    • room_id: Matches against the room ID the alias is being pointed at. Defaults to "*"
      • 
-
    • action: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow. 
      • 
+
    • action: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.
      • 
 
    
 
    Example configuration:
    
 
    alias_creation_rules:
@@ -6152,7 +6162,7 @@ can publish rooms.
    
 
  • user_id: Matches against the creator of the alias. Defaults to "*".
    • 
 
  • alias: Matches against any current local or canonical aliases associated with the room. Defaults to "*".
    • 
 
  • room_id: Matches against the room ID being published. Defaults to "*".
    • 
-
  • action: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow. 
    • 
+
  • action: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.
    • 
 
 
    Example configuration:
    
 
    room_list_publication_rules:
@@ -6194,14 +6204,14 @@ synapse or any other services which support opentracing
 
      
 
    • enabled: whether tracing is enabled. Set to true to enable. Disabled by default.
      • 
 
    • homeserver_whitelist: The list of homeservers we wish to send and receive span contexts and span baggage.
-See here for more. 
+See here for more.
 This is a list of regexes which are matched against the server_name of the homeserver.
 By default, it is empty, so no servers are matched.
      • 
 
    • force_tracing_for_users: # 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.
      • 
 
    • jaeger_config: 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 here.
      • 
 
    
 
    Example configuration:
    
@@ -6226,18 +6236,18 @@ mostly related to trace sampling which is documented send_federation
 
    Controls sending of outbound federation transactions on the main process.
-Set to false if using a federation sender worker. Defaults to true. 
    
+Set to false if using a federation sender worker. Defaults to true.
    
 
    Example configuration:
    
 
    send_federation: false
 
    
 
    
 
    federation_sender_instances
    
 
    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. 
    
+work is balanced across them. Use this setting to list the senders.
    
 
    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). 
    
+events may be dropped).
    
 
    Example configuration:
    
 
    federation_sender_instances:
   - federation_sender1
@@ -6245,7 +6255,7 @@ events may be dropped). 
    
 
    
 
    instance_map
    
 
    When using workers this should be a map from worker name to the
-HTTP replication listener of the worker, if configured. 
    
+HTTP replication listener of the worker, if configured.
    
 
    Example configuration:
    
 
    instance_map:
   worker1:
@@ -6282,7 +6292,7 @@ from workers.
    
 using workers (unless using old style direct TCP configuration).
 This setting has the following sub-options:
    
 
      
-
    • enabled: whether to use Redis support. Defaults to false. 
      • 
+
    • enabled: whether to use Redis support. Defaults to false.
      • 
 
    • host and port: Optional host and port to use to connect to redis. Defaults to
 localhost and 6379
      • 
 
    • password: Optional password if configured on the Redis instance.
      • 
@@ -6295,7 +6305,7 @@ localhost and 6379
   password: <secret_password>
 
    
 
    Background Updates
    
-
    Configuration settings related to background updates. 
    
+
    Configuration settings related to background updates.
    
 
    
 
    background_updates
    
 
    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:
    
 
      
-
    • background_update_duration_ms: How long in milliseconds to run a batch of background updates for. Defaults to 100. 
+
    • background_update_duration_ms: How long in milliseconds to run a batch of background updates for. Defaults to 100.
 Set a different time to change the default.
      • 
 
    • sleep_enabled: Whether to sleep between updates. Defaults to true. Set to false to change the default.
      • 
 
    • sleep_duration_ms: 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.
      • 
 
    • default_batch_size: 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.
      • 
 
    
-
    Example configuration: 
    
+
    Example configuration:
    
 
    background_updates:
     background_update_duration_ms: 500
     sleep_enabled: false
@@ -8207,90 +8217,6 @@ consent uri for that user.
    
 
    ensure that public_baseurl is set in homeserver.yaml, and gives the base
 URI that clients use to connect to the server. (It is used to construct
 consent_uri in the error.)
    
-
    URL Previews
    
-
    The GET /_matrix/media/r0/preview_url endpoint provides a generic preview API
-for URLs which outputs Open Graph responses (with some Matrix
-specific additions).
    
-
    This does have trade-offs compared to other designs:
    
-
      
-
    • Pros:
-
        
-
      • Simple and flexible; can be used by any clients at any point
        • 
-
      
-
      • 
-
    • Cons:
-
        
-
      • If each homeserver provides one of these independently, all the HSes in a
-room may needlessly DoS the target URI
        • 
-
      • The URL metadata must be stored somewhere, rather than just using Matrix
-itself to store the media.
        • 
-
      • Matrix cannot be used to distribute the metadata between homeservers.
        • 
-
      
-
      • 
-
    
-
    When Synapse is asked to preview a URL it does the following:
    
-
      
-
    1. Checks against a URL blacklist (defined as url_preview_url_blacklist in the
-config).
      2. 
-
    2. 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.)
      3. 
-
    3. Kicks off a background process to generate a preview:
-
        
-
      1. Checks the database cache by URL and timestamp and returns the result if it
-has not expired and was successful (a 2xx return code).
        2. 
-
      2. Checks if the URL matches an oEmbed pattern. If it
-does, update the URL to download.
        3. 
-
      3. Downloads the URL and stores it into a file via the media storage provider
-and saves the local media metadata.
        4. 
-
      4. If the media is an image:
-
          
-
        1. Generates thumbnails.
          2. 
-
        2. Generates an Open Graph response based on image properties.
          3. 
-
        
-
        5. 
-
      5. If the media is HTML:
-
          
-
        1. Decodes the HTML via the stored file.
          2. 
-
        2. Generates an Open Graph response from the HTML.
          3. 
-
        3. If a JSON oEmbed URL was found in the HTML via autodiscovery:
-
            
-
          1. Downloads the URL and stores it into a file via the media storage provider
-and saves the local media metadata.
            2. 
-
          2. Convert the oEmbed response to an Open Graph response.
            3. 
-
          3. Override any Open Graph data from the HTML with data from oEmbed.
            4. 
-
          
-
          4. 
-
        4. If an image exists in the Open Graph response:
-
            
-
          1. Downloads the URL and stores it into a file via the media storage
-provider and saves the local media metadata.
            2. 
-
          2. Generates thumbnails.
            3. 
-
          3. Updates the Open Graph response based on image properties.
            4. 
-
          
-
          5. 
-
        
-
        6. 
-
      6. If the media is JSON and an oEmbed URL was found:
-
          
-
        1. Convert the oEmbed response to an Open Graph response.
          2. 
-
        2. If a thumbnail or image is in the oEmbed response:
-
            
-
          1. Downloads the URL and stores it into a file via the media storage
-provider and saves the local media metadata.
            2. 
-
          2. Generates thumbnails.
            3. 
-
          3. Updates the Open Graph response based on image properties.
            4. 
-
          
-
          3. 
-
        
-
        7. 
-
      7. Stores the result in the database cache.
        8. 
-
      
-
      4. 
-
    4. Returns the result.
      5. 
-
    
-
    The in-memory cache expires after 1 hour.
    
-
    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.
    
 
    User Directory API Implementation
    
 
    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 $PATH depending on how Synapse was installed.
    
 
    Finding your user's access_token is client-dependent, but will usually be shown in the client's settings.
    
 
    Making an Admin API request
    
+
    For security reasons, we recommend
+that the Admin API (/_synapse/admin/...) 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.
    
 
    Once you have your access_token, 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:
    
 
    curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>
 
    
+
    For example, suppose we want to
+query the account of the user
+@foo:bar.com. We need an admin access token (e.g.
+syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk), and we need to know which port
+Synapse's client listener is listening
+on (e.g. 8008). Then we can use the following command to request the account
+information from the Admin API.
    
+
    curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com
+
    
 
    For more details on access tokens in Matrix, please refer to the complete
 matrix spec documentation.
    
 
    Account validity API
    
@@ -11280,6 +11219,7 @@ Specifically, rooms are selected if the search term is contained in
    
 
  • guest_access - Whether guests can join the room. One of: ["can_join", "forbidden"].
    • 
 
  • history_visibility - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].
    • 
 
  • state_events - Total number of state_events of a room. Complexity of the room.
    • 
+
  • room_type - 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 null.
    • 
 
 
 
@@ -11320,7 +11260,8 @@ get the "previous page" of results.
       "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.
       "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.
       "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.
       "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.
       "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 next_token.
    
       "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 next_token.
    
       "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.
    
 
  • guest_access - Whether guests can join the room. One of: ["can_join", "forbidden"].
    • 
 
  • history_visibility - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].
    • 
 
  • state_events - Total number of state_events of a room. Complexity of the room.
    • 
+
  • room_type - 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 null.
    • 
 
 
    The API is:
    
 
    GET /_synapse/admin/v1/rooms/<room_id>
@@ -11509,7 +11460,8 @@ end of the list.
    
   "join_rules": "invite",
   "guest_access": null,
   "history_visibility": "shared",
-  "state_events": 93534
+  "state_events": 93534,
+  "room_type": "m.space"
 }
 
    
 
    Room Members API
    
@@ -12603,7 +12555,7 @@ member are returned.
    
 These are media that the user has uploaded themselves
 (local media), as well as
 URL preview images requested by the user if the
-feature is enabled.
    
+feature is enabled.
    
 
    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
 order_by and dir.
    
@@ -15209,6 +15161,21 @@ be required.
    
 
    because build is a standardish tool which
 doesn't require poetry. (It's what we use in CI too). However, you could try
 poetry build too.
    
+
    Troubleshooting
    
+
    Check the version of poetry with poetry --version.
    
+
    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
+change needed to remain
+compatible with PyPI.
    
+
    It can also be useful to check the version of poetry-core in use. If you've
+installed poetry with pipx, try pipx runpip poetry list | grep poetry-core.
    
+
    Clear caches: poetry cache clear --all pypi.
    
+
    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
+poetry install.) Try poetry cache list and poetry cache clear --all <name of cache> to see if that fixes things.
    
+
    Try --verbose or --dry-run arguments.
    
+
    Sometimes useful to see what poetry's internal logic is.
    
 
    Cancellation
    
 
    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).
 users.
 
  • caches avatars, attachments and their thumbnails for media uploaded by remote
 users.
    • 
-
  • caches resources and thumbnails used for
-URL previews.
    • 
+
  • caches resources and thumbnails used for URL previews.
    • 
 
 
    All media in Matrix can be identified by a unique
 MXC URI,
@@ -16415,9 +16381,7 @@ remote_thumbnail/matrix.org/aa/bb/cccccccccccccccccccc/128-96-image-jpeg-scale
 
    remote_thumbnail/matrix.org/aa/bb/cccccccccccccccccccc/128-96-image-jpeg
 
    
 
    Note that remote_thumbnail/ does not have an s.
    
-
    URL Previews
    
-
    See URL Previews for documentation on the URL preview
-process.
    
+
    URL Previews
    
 
    When generating previews for URLs, Synapse may download and cache various
 resources, including images. These resources are assigned temporary media IDs
 of the form yyyy-mm-dd_aaaaaaaaaaaaaaaa, where yyyy-mm-dd is the current
-- 
cgit 1.4.1