Mirrors
/
synapse-old
mirror of https://github.com/matrix-org/synapse.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

deploy: 98fb610cc0

This commit is contained in:
richvdh 2022-07-29 10:30:04 +00:00
parent eb1326ac43
commit 171dd6e719
5 changed files with 298 additions and 316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

305
v1.64/print.html
View File

@ -1613,15 +1613,6 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</li>
</ul>
<h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1>
<h2 id="delegation-of-email-validation-no-longer-supported"><a class="header" href="#delegation-of-email-validation-no-longer-supported">Delegation of email validation no longer supported</a></h2>
<p>As of this version, Synapse no longer allows the tasks of verifying email address
ownership, and password reset confirmation, to be delegated to an identity server.</p>
<p>To continue to allow users to add email addresses to their homeserver accounts,
and perform password resets, make sure that Synapse is configured with a
working email server in the <code>email</code> configuration section (including, at a
minimum, a <code>notif_from</code> setting.)</p>
<p>Specifying an <code>email</code> setting under <code>account_threepid_delegates</code> will now cause
an error at startup.</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
@ -3152,12 +3143,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
@ -3175,16 +3166,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>
@ -3203,7 +3194,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>
@ -3211,11 +3202,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. &quot;### <code>example_setting</code>&quot;) 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. &quot;### <code>example_setting</code>&quot;) 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>
@ -3246,7 +3237,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>
@ -3276,9 +3267,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
@ -3291,7 +3282,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>
@ -3312,7 +3303,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://&lt;server_name&gt;/</code> on port 443 is routed to Synapse, this
option configures Synapse to serve a file at <code>https://&lt;server_name&gt;/.well-known/matrix/server</code>.
option configures Synapse to serve a file at <code>https://&lt;server_name&gt;/.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
@ -3324,12 +3315,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>
@ -3337,15 +3328,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:
@ -3353,8 +3344,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
@ -3362,10 +3353,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 />
@ -3398,7 +3389,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 &quot;1&quot;. </p>
to &quot;1&quot;.</p>
<p>Currently defaults to &quot;9&quot;.</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">default_room_version: &quot;8&quot;
@ -3406,14 +3397,14 @@ to &quot;1&quot;. </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>
@ -3493,7 +3484,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
@ -3636,7 +3627,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
@ -3653,30 +3644,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
@ -3687,7 +3678,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>
@ -3698,7 +3689,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>
@ -3716,7 +3707,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>
@ -3734,7 +3725,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>
@ -3748,11 +3739,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
@ -3778,7 +3769,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
@ -3810,7 +3801,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
@ -3837,9 +3828,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>
@ -3856,20 +3847,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>
@ -3914,7 +3905,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>
@ -3923,16 +3914,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: &quot;CONFDIR/SERVERNAME.tls.crt&quot;
</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: &quot;CONFDIR/SERVERNAME.tls.key&quot;
</code></pre>
@ -4067,12 +4058,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
@ -4084,8 +4075,8 @@ Defaults 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.
@ -4099,7 +4090,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>
@ -4119,7 +4110,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
@ -4135,7 +4126,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
@ -4276,7 +4267,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>
@ -4285,7 +4276,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>
@ -4304,7 +4295,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
@ -4312,7 +4303,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>
@ -4353,9 +4344,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
@ -4366,13 +4357,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>
@ -4408,9 +4399,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
@ -4448,7 +4439,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>
@ -4474,7 +4465,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>
@ -4483,7 +4474,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
@ -4503,7 +4494,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:
@ -4519,7 +4510,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>
@ -4535,7 +4526,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>
@ -4641,7 +4632,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'
@ -4655,7 +4646,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>
@ -4718,8 +4709,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
@ -4731,14 +4722,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: &quot;YOUR_PUBLIC_KEY&quot;
</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: &quot;YOUR_PRIVATE_KEY&quot;
@ -4746,7 +4737,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
@ -4800,7 +4791,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
@ -4817,7 +4808,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>
@ -4828,7 +4819,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>
@ -4950,7 +4941,7 @@ 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>: No longer accepts an <code>email</code> option.</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:
msisdn: http://localhost:8090 # Delegate SMS sending to this local process
@ -4989,7 +4980,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:
- &quot;#exampleroom:example.com&quot;
@ -5029,9 +5020,9 @@ effect if <code>autocreate_auto_join_rooms</code> is true.</p>
<ul>
<li>&quot;public_chat&quot;: the room is joinable by anyone, including
federated servers if <code>autocreate_auto_join_rooms_federated</code> is true (the default).</li>
<li>&quot;private_chat&quot;: an invitation is required to join these rooms. </li>
<li>&quot;private_chat&quot;: an invitation is required to join these rooms.</li>
<li>&quot;trusted_private_chat&quot;: 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 &quot;private_chat&quot; or &quot;trusted_private_chat&quot; is used then
<code>auto_join_mxid_localpart</code> must also be configured.</p>
@ -5080,7 +5071,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
@ -5088,10 +5079,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>
@ -5102,7 +5093,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>
@ -5135,7 +5126,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>
@ -5148,7 +5139,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
@ -5256,7 +5247,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
@ -5324,16 +5315,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: &quot;CONFDIR/sp_conf.py&quot;</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
@ -5355,7 +5346,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
@ -5421,16 +5412,16 @@ the IdP to use an ACS location of
sur_name: &quot;the Sysadmin&quot;
email_address&quot;: [&quot;admin@example.com&quot;]
contact_type&quot;: 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:
@ -5584,7 +5575,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>
@ -5614,7 +5605,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:
@ -5627,7 +5618,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 &quot;Stephensson&quot;, but the <code>groups</code>
claim MUST contain &quot;admin&quot;.</p>
<p>Example configuration:</p>
@ -5687,7 +5678,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>
@ -5703,7 +5694,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
@ -5740,7 +5731,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 &quot;iss&quot; claim against. Optional. If provided the
<li><code>issuer</code>: The issuer to validate the &quot;iss&quot; claim against. Optional. If provided the
&quot;iss&quot; claim will be required and validated for all JSON web tokens.</li>
<li><code>audiences</code>: A list of audiences to validate the &quot;aud&quot; claim against. Optional.
If provided the &quot;aud&quot; claim will be required and validated for all JSON web tokens.
@ -5749,7 +5740,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: &quot;provided-by-your-issuer&quot;
algorithm: &quot;provided-by-your-issuer&quot;
subject_claim: &quot;name_of_claim&quot;
@ -5759,7 +5750,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.
@ -5768,10 +5759,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>
@ -5804,7 +5795,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
@ -5894,7 +5885,7 @@ of the user(s) that sent the message(s), e.g. &quot;Alice and Bob&quot;, and '%(
message(s) have been sent to, e.g. &quot;My super room&quot;. 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 &quot;[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room...&quot;</li>
@ -5904,13 +5895,13 @@ room which doesn't have a name. Defaults to &quot;[%(app)s] You have a message o
a room which doesn't have a name. Defaults to &quot;[%(app)s] You have messages on %(app)s from %(person)s...&quot;</li>
<li><code>messages_in_room</code>: Subject to use to notify about multiple messages in a room which has a
name. Defaults to &quot;[%(app)s] You have messages on %(app)s in the %(room)s room...&quot;</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 &quot;[%(app)s] You have messages on %(app)s in the %(room)s room and others...&quot;</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
&quot;[%(app)s] You have messages on %(app)s from %(person)s and others...&quot;</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 &quot;[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s...&quot;</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 &quot;[%(app)s] %(person)s has invited you to chat on %(app)s...&quot;</li>
@ -5954,7 +5945,7 @@ ownership. Defaults to &quot;[%(server_name)s] Validate your email&quot;</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
@ -5969,7 +5960,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>
@ -6001,7 +5992,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
@ -6019,7 +6010,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>
@ -6086,14 +6077,14 @@ Defaults to &quot;Privacy Policy&quot;.</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 />
@ -6121,7 +6112,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>
@ -6141,7 +6132,7 @@ can create aliases.</p>
<li><code>user_id</code>: Matches against the creator of the alias. Defaults to &quot;*&quot;.</li>
<li><code>alias</code>: Matches against the alias being created. Defaults to &quot;*&quot;.</li>
<li><code>room_id</code>: Matches against the room ID the alias is being pointed at. Defaults to &quot;*&quot;</li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow. </li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow.</li>
</ul>
<p>Example configuration:</p>
<pre><code class="language-yaml">alias_creation_rules:
@ -6166,7 +6157,7 @@ can publish rooms.</p>
<li><code>user_id</code>: Matches against the creator of the alias. Defaults to &quot;*&quot;.</li>
<li><code>alias</code>: Matches against any current local or canonical aliases associated with the room. Defaults to &quot;*&quot;.</li>
<li><code>room_id</code>: Matches against the room ID being published. Defaults to &quot;*&quot;.</li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow. </li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow.</li>
</ul>
<p>Example configuration:</p>
<pre><code class="language-yaml">room_list_publication_rules:
@ -6208,14 +6199,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>
@ -6240,18 +6231,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
@ -6259,7 +6250,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:
@ -6296,7 +6287,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>
@ -6309,7 +6300,7 @@ localhost and 6379</li>
password: &lt;secret_password&gt;
</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.
@ -6317,7 +6308,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.
@ -6327,7 +6318,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

2
v1.64/searchindex.js
View File

File diff suppressed because one or more lines are too long

2
v1.64/searchindex.json
View File

File diff suppressed because one or more lines are too long

9
v1.64/upgrade.html
View File

@ -233,15 +233,6 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</li>
</ul>
<h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1>
<h2 id="delegation-of-email-validation-no-longer-supported"><a class="header" href="#delegation-of-email-validation-no-longer-supported">Delegation of email validation no longer supported</a></h2>
<p>As of this version, Synapse no longer allows the tasks of verifying email address
ownership, and password reset confirmation, to be delegated to an identity server.</p>
<p>To continue to allow users to add email addresses to their homeserver accounts,
and perform password resets, make sure that Synapse is configured with a
working email server in the <code>email</code> configuration section (including, at a
minimum, a <code>notif_from</code> setting.)</p>
<p>Specifying an <code>email</code> setting under <code>account_threepid_delegates</code> will now cause
an error at startup.</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

296
v1.64/usage/configuration/config_documentation.html
View File

@ -147,12 +147,12 @@
</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="../../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
@ -170,16 +170,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>
@ -198,7 +198,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>
@ -206,11 +206,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. &quot;### <code>example_setting</code>&quot;) 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. &quot;### <code>example_setting</code>&quot;) 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>
@ -241,7 +241,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>
@ -271,9 +271,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
@ -286,7 +286,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>
@ -307,7 +307,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://&lt;server_name&gt;/</code> on port 443 is routed to Synapse, this
option configures Synapse to serve a file at <code>https://&lt;server_name&gt;/.well-known/matrix/server</code>.
option configures Synapse to serve a file at <code>https://&lt;server_name&gt;/.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
@ -319,12 +319,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>
@ -332,15 +332,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:
@ -348,8 +348,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
@ -357,10 +357,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 />
@ -393,7 +393,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 &quot;1&quot;. </p>
to &quot;1&quot;.</p>
<p>Currently defaults to &quot;9&quot;.</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">default_room_version: &quot;8&quot;
@ -401,14 +401,14 @@ to &quot;1&quot;. </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>
@ -488,7 +488,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
@ -631,7 +631,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
@ -648,30 +648,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
@ -682,7 +682,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>
@ -693,7 +693,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>
@ -711,7 +711,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>
@ -729,7 +729,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>
@ -743,11 +743,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
@ -773,7 +773,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
@ -805,7 +805,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
@ -832,9 +832,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="../../templates.html">here</a> for more
information about using custom templates.</p>
@ -851,20 +851,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>
@ -909,7 +909,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>
@ -918,16 +918,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: &quot;CONFDIR/SERVERNAME.tls.crt&quot;
</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: &quot;CONFDIR/SERVERNAME.tls.key&quot;
</code></pre>
@ -1062,12 +1062,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
@ -1079,8 +1079,8 @@ Defaults 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.
@ -1094,7 +1094,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>
@ -1114,7 +1114,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
@ -1130,7 +1130,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
@ -1271,7 +1271,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>
@ -1280,7 +1280,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>
@ -1299,7 +1299,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
@ -1307,7 +1307,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>
@ -1348,9 +1348,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
@ -1361,13 +1361,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>
@ -1403,9 +1403,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
@ -1443,7 +1443,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>
@ -1469,7 +1469,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>
@ -1478,7 +1478,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
@ -1498,7 +1498,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:
@ -1514,7 +1514,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="../../reverse_proxy.html">here</a> for more on using a reverse proxy with Synapse. </p>
See <a href="../../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>
@ -1530,7 +1530,7 @@ See <a href="../../reverse_proxy.html">here</a> for more on using a reverse prox
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>
@ -1636,7 +1636,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'
@ -1650,7 +1650,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>
@ -1713,8 +1713,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
@ -1726,14 +1726,14 @@ should be in the form of providers.json). By default this list is empty. </p>
<p>See <a href="../../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: &quot;YOUR_PUBLIC_KEY&quot;
</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: &quot;YOUR_PRIVATE_KEY&quot;
@ -1741,7 +1741,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
@ -1795,7 +1795,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
@ -1812,7 +1812,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>
@ -1823,7 +1823,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="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>
@ -1945,7 +1945,7 @@ 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>: No longer accepts an <code>email</code> option.</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:
msisdn: http://localhost:8090 # Delegate SMS sending to this local process
@ -1984,7 +1984,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:
- &quot;#exampleroom:example.com&quot;
@ -2024,9 +2024,9 @@ effect if <code>autocreate_auto_join_rooms</code> is true.</p>
<ul>
<li>&quot;public_chat&quot;: the room is joinable by anyone, including
federated servers if <code>autocreate_auto_join_rooms_federated</code> is true (the default).</li>
<li>&quot;private_chat&quot;: an invitation is required to join these rooms. </li>
<li>&quot;private_chat&quot;: an invitation is required to join these rooms.</li>
<li>&quot;trusted_private_chat&quot;: 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 &quot;private_chat&quot; or &quot;trusted_private_chat&quot; is used then
<code>auto_join_mxid_localpart</code> must also be configured.</p>
@ -2075,7 +2075,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
@ -2083,10 +2083,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>
@ -2097,7 +2097,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>
@ -2130,7 +2130,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>
@ -2143,7 +2143,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
@ -2251,7 +2251,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
@ -2319,16 +2319,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: &quot;CONFDIR/sp_conf.py&quot;</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
@ -2350,7 +2350,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
@ -2416,16 +2416,16 @@ the IdP to use an ACS location of
sur_name: &quot;the Sysadmin&quot;
email_address&quot;: [&quot;admin@example.com&quot;]
contact_type&quot;: 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:
@ -2579,7 +2579,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>
@ -2609,7 +2609,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:
@ -2622,7 +2622,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 &quot;Stephensson&quot;, but the <code>groups</code>
claim MUST contain &quot;admin&quot;.</p>
<p>Example configuration:</p>
@ -2682,7 +2682,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="../../templates.html">here</a> for more information.</p>
<p>Options include:</p>
<ul>
@ -2698,7 +2698,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
@ -2735,7 +2735,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 &quot;iss&quot; claim against. Optional. If provided the
<li><code>issuer</code>: The issuer to validate the &quot;iss&quot; claim against. Optional. If provided the
&quot;iss&quot; claim will be required and validated for all JSON web tokens.</li>
<li><code>audiences</code>: A list of audiences to validate the &quot;aud&quot; claim against. Optional.
If provided the &quot;aud&quot; claim will be required and validated for all JSON web tokens.
@ -2744,7 +2744,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: &quot;provided-by-your-issuer&quot;
algorithm: &quot;provided-by-your-issuer&quot;
subject_claim: &quot;name_of_claim&quot;
@ -2754,7 +2754,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.
@ -2763,10 +2763,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>
@ -2799,7 +2799,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
@ -2889,7 +2889,7 @@ of the user(s) that sent the message(s), e.g. &quot;Alice and Bob&quot;, and '%(
message(s) have been sent to, e.g. &quot;My super room&quot;. 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 &quot;[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room...&quot;</li>
@ -2899,13 +2899,13 @@ room which doesn't have a name. Defaults to &quot;[%(app)s] You have a message o
a room which doesn't have a name. Defaults to &quot;[%(app)s] You have messages on %(app)s from %(person)s...&quot;</li>
<li><code>messages_in_room</code>: Subject to use to notify about multiple messages in a room which has a
name. Defaults to &quot;[%(app)s] You have messages on %(app)s in the %(room)s room...&quot;</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 &quot;[%(app)s] You have messages on %(app)s in the %(room)s room and others...&quot;</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
&quot;[%(app)s] You have messages on %(app)s from %(person)s and others...&quot;</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 &quot;[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s...&quot;</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 &quot;[%(app)s] %(person)s has invited you to chat on %(app)s...&quot;</li>
@ -2949,7 +2949,7 @@ ownership. Defaults to &quot;[%(server_name)s] Validate your email&quot;</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
@ -2964,7 +2964,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>
@ -2996,7 +2996,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
@ -3014,7 +3014,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>
@ -3081,14 +3081,14 @@ Defaults to &quot;Privacy Policy&quot;.</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="../../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 />
@ -3116,7 +3116,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>
@ -3136,7 +3136,7 @@ can create aliases.</p>
<li><code>user_id</code>: Matches against the creator of the alias. Defaults to &quot;*&quot;.</li>
<li><code>alias</code>: Matches against the alias being created. Defaults to &quot;*&quot;.</li>
<li><code>room_id</code>: Matches against the room ID the alias is being pointed at. Defaults to &quot;*&quot;</li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow. </li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow.</li>
</ul>
<p>Example configuration:</p>
<pre><code class="language-yaml">alias_creation_rules:
@ -3161,7 +3161,7 @@ can publish rooms.</p>
<li><code>user_id</code>: Matches against the creator of the alias. Defaults to &quot;*&quot;.</li>
<li><code>alias</code>: Matches against any current local or canonical aliases associated with the room. Defaults to &quot;*&quot;.</li>
<li><code>room_id</code>: Matches against the room ID being published. Defaults to &quot;*&quot;.</li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow. </li>
<li><code>action</code>: Whether to &quot;allow&quot; or &quot;deny&quot; the request if the rule matches. Defaults to allow.</li>
</ul>
<p>Example configuration:</p>
<pre><code class="language-yaml">room_list_publication_rules:
@ -3203,14 +3203,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="../../opentracing.html">here</a> for more.
See <a href="../../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>
@ -3235,18 +3235,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
@ -3254,7 +3254,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:
@ -3291,7 +3291,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>
@ -3304,7 +3304,7 @@ localhost and 6379</li>
password: &lt;secret_password&gt;
</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.
@ -3312,7 +3312,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.
@ -3322,7 +3322,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