mirrors/synapse
1
0
Fork 0
mirror of https://github.com/element-hq/synapse.git synced 2024-11-26 19:47:05 +03:00
Code Issues Projects Releases Packages Wiki Activity

deploy: 6f80fe1e1b

Browse source
This commit is contained in:
squahtx 2022-08-31 12:55:41 +00:00
parent 4add78d514
commit 3a2bd6c6e2
11 changed files with 256 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
latest/admin_api/register_api.html
View file

@ -184,7 +184,20 @@ set the displayname (optional, <code>username</code> by default).</p>
<p>The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being <p>The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being
the shared secret and the content being the nonce, user, password, either the the shared secret and the content being the nonce, user, password, either the
string &quot;admin&quot; or &quot;notadmin&quot;, and optionally the user_type string &quot;admin&quot; or &quot;notadmin&quot;, and optionally the user_type
each separated by NULs. For an example of generation in Python:</p> each separated by NULs.</p>
<p>Here is an easy way to generate the HMAC digest if you have Bash and OpenSSL:</p>
<pre><code class="language-bash"># Update these values and then paste this code block into a bash terminal
nonce='thisisanonce'
username='pepper_roni'
password='pizza'
admin='admin'
secret='shared_secret'
printf '%s\0%s\0%s\0%s' &quot;$nonce&quot; &quot;$username&quot; &quot;$password&quot; &quot;$admin&quot; |
openssl sha1 -hmac &quot;$secret&quot; |
awk '{print $2}'
</code></pre>
<p>For an example of generation in Python:</p>
<pre><code class="language-python">import hmac, hashlib <pre><code class="language-python">import hmac, hashlib
def generate_mac(nonce, user, password, admin=False, user_type=None): def generate_mac(nonce, user, password, admin=False, user_type=None):

6
latest/admin_api/rooms.html
View file

@ -436,6 +436,8 @@ end of the list.</p>
<li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li> <li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
<li><code>room_type</code> - The type of the room taken from the room's creation event; for example &quot;m.space&quot; if the room is a space. <li><code>room_type</code> - The type of the room taken from the room's creation event; for example &quot;m.space&quot; if the room is a space.
If the room does not define a type, the value will be <code>null</code>.</li> If the room does not define a type, the value will be <code>null</code>.</li>
<li><code>forgotten</code> - Whether all local users have
<a href="https://spec.matrix.org/latest/client-server-api/#leaving-rooms">forgotten</a> the room.</li>
</ul> </ul>
<p>The API is:</p> <p>The API is:</p>
<pre><code>GET /_synapse/admin/v1/rooms/&lt;room_id&gt; <pre><code>GET /_synapse/admin/v1/rooms/&lt;room_id&gt;
@ -459,9 +461,11 @@ If the room does not define a type, the value will be <code>null</code>.</li>
&quot;guest_access&quot;: null, &quot;guest_access&quot;: null,
&quot;history_visibility&quot;: &quot;shared&quot;, &quot;history_visibility&quot;: &quot;shared&quot;,
&quot;state_events&quot;: 93534, &quot;state_events&quot;: 93534,
&quot;room_type&quot;: &quot;m.space&quot; &quot;room_type&quot;: &quot;m.space&quot;,
&quot;forgotten&quot;: false
} }
</code></pre> </code></pre>
<p><em>Changed in Synapse 1.66:</em> Added the <code>forgotten</code> key to the response body.</p>
<h1 id="room-members-api"><a class="header" href="#room-members-api">Room Members API</a></h1> <h1 id="room-members-api"><a class="header" href="#room-members-api">Room Members API</a></h1>
<p>The Room Members admin API allows server admins to get a list of all members of a room.</p> <p>The Room Members admin API allows server admins to get a list of all members of a room.</p>
<p>The response includes the following fields:</p> <p>The response includes the following fields:</p>

10
latest/admin_api/user_admin_api.html
View file

@ -799,6 +799,7 @@ same.</p>
&quot;device_id&quot;: &quot;QBUAZIFURK&quot;, &quot;device_id&quot;: &quot;QBUAZIFURK&quot;,
&quot;display_name&quot;: &quot;android&quot;, &quot;display_name&quot;: &quot;android&quot;,
&quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;, &quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;,
&quot;last_seen_user_agent&quot;: &quot;Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0&quot;,
&quot;last_seen_ts&quot;: 1474491775024, &quot;last_seen_ts&quot;: 1474491775024,
&quot;user_id&quot;: &quot;&lt;user_id&gt;&quot; &quot;user_id&quot;: &quot;&lt;user_id&gt;&quot;
}, },
@ -806,6 +807,7 @@ same.</p>
&quot;device_id&quot;: &quot;AUIECTSRND&quot;, &quot;device_id&quot;: &quot;AUIECTSRND&quot;,
&quot;display_name&quot;: &quot;ios&quot;, &quot;display_name&quot;: &quot;ios&quot;,
&quot;last_seen_ip&quot;: &quot;1.2.3.5&quot;, &quot;last_seen_ip&quot;: &quot;1.2.3.5&quot;,
&quot;last_seen_user_agent&quot;: &quot;Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0&quot;,
&quot;last_seen_ts&quot;: 1474491775025, &quot;last_seen_ts&quot;: 1474491775025,
&quot;user_id&quot;: &quot;&lt;user_id&gt;&quot; &quot;user_id&quot;: &quot;&lt;user_id&gt;&quot;
} }
@ -830,6 +832,8 @@ Device objects contain the following fields:</p>
Absent if no name has been set.</li> Absent if no name has been set.</li>
<li><code>last_seen_ip</code> - The IP address where this device was last seen. <li><code>last_seen_ip</code> - The IP address where this device was last seen.
(May be a few minutes out of date, for efficiency reasons).</li> (May be a few minutes out of date, for efficiency reasons).</li>
<li><code>last_seen_user_agent</code> - The user agent of the device when it was last seen.
(May be a few minutes out of date, for efficiency reasons).</li>
<li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this <li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this
devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li> devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li>
<li><code>user_id</code> - Owner of device.</li> <li><code>user_id</code> - Owner of device.</li>
@ -872,6 +876,7 @@ any access token associated with them.</p>
&quot;device_id&quot;: &quot;&lt;device_id&gt;&quot;, &quot;device_id&quot;: &quot;&lt;device_id&gt;&quot;,
&quot;display_name&quot;: &quot;android&quot;, &quot;display_name&quot;: &quot;android&quot;,
&quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;, &quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;,
&quot;last_seen_user_agent&quot;: &quot;Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0&quot;,
&quot;last_seen_ts&quot;: 1474491775024, &quot;last_seen_ts&quot;: 1474491775024,
&quot;user_id&quot;: &quot;&lt;user_id&gt;&quot; &quot;user_id&quot;: &quot;&lt;user_id&gt;&quot;
} }
@ -889,7 +894,12 @@ any access token associated with them.</p>
<li><code>display_name</code> - Display name set by the user for this device. <li><code>display_name</code> - Display name set by the user for this device.
Absent if no name has been set.</li> Absent if no name has been set.</li>
<li><code>last_seen_ip</code> - The IP address where this device was last seen. <li><code>last_seen_ip</code> - The IP address where this device was last seen.
(May be a few minutes out of date, for efficiency reasons).
<ul>
<li><code>last_seen_user_agent</code> - The user agent of the device when it was last seen.
(May be a few minutes out of date, for efficiency reasons).</li> (May be a few minutes out of date, for efficiency reasons).</li>
</ul>
</li>
<li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this <li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this
devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li> devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li>
<li><code>user_id</code> - Owner of device.</li> <li><code>user_id</code> - Owner of device.</li>

3
latest/message_retention_policies.html
View file

@ -155,7 +155,8 @@ and allow server and room admins to configure how long messages should
be kept in a homeserver's database before being purged from it. be kept in a homeserver's database before being purged from it.
<strong>Please note that, as this feature isn't part of the Matrix <strong>Please note that, as this feature isn't part of the Matrix
specification yet, this implementation is to be considered as specification yet, this implementation is to be considered as
experimental.</strong> </p> experimental. There are known bugs which may cause database corruption.
Proceed with caution.</strong> </p>
<p>A message retention policy is mainly defined by its <code>max_lifetime</code> <p>A message retention policy is mainly defined by its <code>max_lifetime</code>
parameter, which defines how long a message can be kept around after parameter, which defines how long a message can be kept around after
it was sent to the room. If a room doesn't have a message retention it was sent to the room. If a room doesn't have a message retention

142
latest/print.html
View file

@ -1612,6 +1612,20 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
<h1 id="upgrading-to-v1660"><a class="header" href="#upgrading-to-v1660">Upgrading to v1.66.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.
This removal was previously planned for Synapse 1.64.0, but was
<a href="https://github.com/matrix-org/synapse/issues/13421">delayed</a> until now to give
homeserver administrators more notice of the change.</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 <a href="https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email"><code>email</code> configuration
section</a>
(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>
<h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1> <h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1>
<h2 id="deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers"><a class="header" href="#deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers">Deprecation of the ability to delegate e-mail verification to identity servers</a></h2> <h2 id="deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers"><a class="header" href="#deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers">Deprecation of the ability to delegate e-mail verification to identity servers</a></h2>
<p>Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.</p> <p>Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.</p>
@ -2422,7 +2436,7 @@ updated.</p>
<p>When setting up worker processes, we now recommend the use of a Redis <p>When setting up worker processes, we now recommend the use of a Redis
server for replication. <strong>The old direct TCP connection method is server for replication. <strong>The old direct TCP connection method is
deprecated and will be removed in a future release.</strong> See deprecated and will be removed in a future release.</strong> See
<a href="workers.html">workers</a> for more details.</p> the <a href="https://matrix-org.github.io/synapse/v1.66/workers.html">worker documentation</a> for more details.</p>
<h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1> <h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1>
<p>This version includes a database update which is run as part of the <p>This version includes a database update which is run as part of the
upgrade, and which may take a couple of minutes in the case of a large upgrade, and which may take a couple of minutes in the case of a large
@ -3483,7 +3497,7 @@ configuration.</p>
<p><code>metrics</code>: (see the docs <a href="usage/configuration/../../metrics-howto.html">here</a>),</p> <p><code>metrics</code>: (see the docs <a href="usage/configuration/../../metrics-howto.html">here</a>),</p>
</li> </li>
<li> <li>
<p><code>replication</code>: (see the docs <a href="usage/configuration/../../workers.html">here</a>).</p> <p><code>replication</code>: (deprecated as of Synapse 1.18, see the docs <a href="usage/configuration/../../workers.html">here</a>).</p>
</li> </li>
</ul> </ul>
</li> </li>
@ -3503,7 +3517,7 @@ on this port. Sub-options for each resource are:</p>
</li> </li>
<li> <li>
<p><code>compress</code>: set to true to enable gzip compression on HTTP bodies for this resource. This is currently only supported with the <p><code>compress</code>: set to true to enable gzip compression on HTTP bodies for this resource. This is currently only supported with the
<code>client</code>, <code>consent</code> and <code>metrics</code> resources.</p> <code>client</code>, <code>consent</code>, <code>metrics</code> and <code>federation</code> resources.</p>
</li> </li>
</ul> </ul>
</li> </li>
@ -3770,6 +3784,9 @@ using Synapse's media repository.</p>
<h3 id="redaction_retention_period"><a class="header" href="#redaction_retention_period"><code>redaction_retention_period</code></a></h3> <h3 id="redaction_retention_period"><a class="header" href="#redaction_retention_period"><code>redaction_retention_period</code></a></h3>
<p>How long to keep redacted events in unredacted form in the database. After <p>How long to keep redacted events in unredacted form in the database. After
this period redacted events get replaced with their redacted form in the DB.</p> this period redacted events get replaced with their redacted form in the DB.</p>
<p>Synapse will check whether the rentention period has concluded for redacted
events every 5 minutes. Thus, even if this option is set to <code>0</code>, Synapse may
still take up to 5 minutes to purge redacted events from the database.</p>
<p>Defaults to <code>7d</code>. Set to <code>null</code> to disable.</p> <p>Defaults to <code>7d</code>. Set to <code>null</code> to disable.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">redaction_retention_period: 28d <pre><code class="language-yaml">redaction_retention_period: 28d
@ -3833,7 +3850,11 @@ the <code>allowed_lifetime_min</code> and <code>allowed_lifetime_max</code> conf
which are older than the room's maximum retention period. Synapse will also 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 filter events received over federation so that events that should have been
purged are ignored and not stored again.</p> purged are ignored and not stored again.</p>
<p>The message retention policies feature is disabled by default.</p> <p>The message retention policies feature is disabled by default. Please be advised
that enabling this feature carries some risk. There are known bugs with the implementation
which can cause database corruption. Setting retention to delete older history
is less risky than deleting newer history but in general caution is advised when enabling this
experimental feature. You can read more about this feature <a href="usage/configuration/../../message_retention_policies.html">here</a>.</p>
<p>This setting has the following sub-options:</p> <p>This setting has the following sub-options:</p>
<ul> <ul>
<li> <li>
@ -4926,7 +4947,9 @@ their account.</p>
<p>(Servers handling the these requests must answer the <code>/requestToken</code> endpoints defined <p>(Servers handling the these requests must answer the <code>/requestToken</code> endpoints defined
by the Matrix Identity Service API by the Matrix Identity Service API
<a href="https://matrix.org/docs/spec/identity_service/latest">specification</a>.)</p> <a href="https://matrix.org/docs/spec/identity_service/latest">specification</a>.)</p>
<p><em>Updated in Synapse 1.64.0</em>: The <code>email</code> option is deprecated.</p> <p><em>Deprecated in Synapse 1.64.0</em>: The <code>email</code> option is deprecated.</p>
<p><em>Removed in Synapse 1.66.0</em>: The <code>email</code> option has been removed.
If present, Synapse will report a configuration error on startup.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">account_threepid_delegates: <pre><code class="language-yaml">account_threepid_delegates:
msisdn: http://localhost:8090 # Delegate SMS sending to this local process msisdn: http://localhost:8090 # Delegate SMS sending to this local process
@ -6013,7 +6036,7 @@ user directory. Defaults to false.</li>
<h3 id="user_consent"><a class="header" href="#user_consent"><code>user_consent</code></a></h3> <h3 id="user_consent"><a class="header" href="#user_consent"><code>user_consent</code></a></h3>
<p>For detailed instructions on user consent configuration, see <a href="usage/configuration/../../consent_tracking.html">here</a>.</p> <p>For detailed instructions on user consent configuration, see <a href="usage/configuration/../../consent_tracking.html">here</a>.</p>
<p>Parts of this section are required if enabling the <code>consent</code> resource under <p>Parts of this section are required if enabling the <code>consent</code> resource under
<code>listeners</code>, in particular <code>template_dir</code> and <code>version</code>. # TODO: link <code>listeners</code></p> <a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code></a>, in particular <code>template_dir</code> and <code>version</code>.</p>
<ul> <ul>
<li> <li>
<p><code>template_dir</code>: gives the location of the templates for the HTML forms. <p><code>template_dir</code>: gives the location of the templates for the HTML forms.
@ -6028,7 +6051,7 @@ parameter.</p>
</li> </li>
<li> <li>
<p><code>server_notice_content</code>: if enabled, will send a user a &quot;Server Notice&quot; <p><code>server_notice_content</code>: if enabled, will send a user a &quot;Server Notice&quot;
asking them to consent to the privacy policy. The <code>server_notices</code> section ##TODO: link asking them to consent to the privacy policy. The <a href="usage/configuration/config_documentation.html#server_notices"><code>server_notices</code> section</a>
must also be configured for this to work. Notices will <em>not</em> be sent to must also be configured for this to work. Notices will <em>not</em> be sent to
guest users unless <code>send_server_notice_to_guests</code> is set to true.</p> guest users unless <code>send_server_notice_to_guests</code> is set to true.</p>
</li> </li>
@ -6532,7 +6555,7 @@ webpages it shows to users.</p>
Server admins can configure an additional directory for Synapse to look for templates Server admins can configure an additional directory for Synapse to look for templates
in, allowing them to specify custom templates:</p> in, allowing them to specify custom templates:</p>
<pre><code class="language-yaml">templates: <pre><code class="language-yaml">templates:
custom_templates_directory: /path/to/custom/templates/ custom_template_directory: /path/to/custom/templates/
</code></pre> </code></pre>
<p>If this setting is not set, or the files named below are not found within the directory, <p>If this setting is not set, or the files named below are not found within the directory,
default templates from within the Synapse package will be used.</p> default templates from within the Synapse package will be used.</p>
@ -8268,7 +8291,8 @@ and allow server and room admins to configure how long messages should
be kept in a homeserver's database before being purged from it. be kept in a homeserver's database before being purged from it.
<strong>Please note that, as this feature isn't part of the Matrix <strong>Please note that, as this feature isn't part of the Matrix
specification yet, this implementation is to be considered as specification yet, this implementation is to be considered as
experimental.</strong> </p> experimental. There are known bugs which may cause database corruption.
Proceed with caution.</strong> </p>
<p>A message retention policy is mainly defined by its <code>max_lifetime</code> <p>A message retention policy is mainly defined by its <code>max_lifetime</code>
parameter, which defines how long a message can be kept around after parameter, which defines how long a message can be kept around after
it was sent to the room. If a room doesn't have a message retention it was sent to the room. If a room doesn't have a message retention
@ -10849,7 +10873,20 @@ set the displayname (optional, <code>username</code> by default).</p>
<p>The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being <p>The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being
the shared secret and the content being the nonce, user, password, either the the shared secret and the content being the nonce, user, password, either the
string &quot;admin&quot; or &quot;notadmin&quot;, and optionally the user_type string &quot;admin&quot; or &quot;notadmin&quot;, and optionally the user_type
each separated by NULs. For an example of generation in Python:</p> each separated by NULs.</p>
<p>Here is an easy way to generate the HMAC digest if you have Bash and OpenSSL:</p>
<pre><code class="language-bash"># Update these values and then paste this code block into a bash terminal
nonce='thisisanonce'
username='pepper_roni'
password='pizza'
admin='admin'
secret='shared_secret'
printf '%s\0%s\0%s\0%s' &quot;$nonce&quot; &quot;$username&quot; &quot;$password&quot; &quot;$admin&quot; |
openssl sha1 -hmac &quot;$secret&quot; |
awk '{print $2}'
</code></pre>
<p>For an example of generation in Python:</p>
<pre><code class="language-python">import hmac, hashlib <pre><code class="language-python">import hmac, hashlib
def generate_mac(nonce, user, password, admin=False, user_type=None): def generate_mac(nonce, user, password, admin=False, user_type=None):
@ -11426,6 +11463,8 @@ end of the list.</p>
<li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li> <li><code>state_events</code> - Total number of state_events of a room. Complexity of the room.</li>
<li><code>room_type</code> - The type of the room taken from the room's creation event; for example &quot;m.space&quot; if the room is a space. <li><code>room_type</code> - The type of the room taken from the room's creation event; for example &quot;m.space&quot; if the room is a space.
If the room does not define a type, the value will be <code>null</code>.</li> If the room does not define a type, the value will be <code>null</code>.</li>
<li><code>forgotten</code> - Whether all local users have
<a href="https://spec.matrix.org/latest/client-server-api/#leaving-rooms">forgotten</a> the room.</li>
</ul> </ul>
<p>The API is:</p> <p>The API is:</p>
<pre><code>GET /_synapse/admin/v1/rooms/&lt;room_id&gt; <pre><code>GET /_synapse/admin/v1/rooms/&lt;room_id&gt;
@ -11449,9 +11488,11 @@ If the room does not define a type, the value will be <code>null</code>.</li>
&quot;guest_access&quot;: null, &quot;guest_access&quot;: null,
&quot;history_visibility&quot;: &quot;shared&quot;, &quot;history_visibility&quot;: &quot;shared&quot;,
&quot;state_events&quot;: 93534, &quot;state_events&quot;: 93534,
&quot;room_type&quot;: &quot;m.space&quot; &quot;room_type&quot;: &quot;m.space&quot;,
&quot;forgotten&quot;: false
} }
</code></pre> </code></pre>
<p><em>Changed in Synapse 1.66:</em> Added the <code>forgotten</code> key to the response body.</p>
<h1 id="room-members-api"><a class="header" href="#room-members-api">Room Members API</a></h1> <h1 id="room-members-api"><a class="header" href="#room-members-api">Room Members API</a></h1>
<p>The Room Members admin API allows server admins to get a list of all members of a room.</p> <p>The Room Members admin API allows server admins to get a list of all members of a room.</p>
<p>The response includes the following fields:</p> <p>The response includes the following fields:</p>
@ -12718,6 +12759,7 @@ same.</p>
&quot;device_id&quot;: &quot;QBUAZIFURK&quot;, &quot;device_id&quot;: &quot;QBUAZIFURK&quot;,
&quot;display_name&quot;: &quot;android&quot;, &quot;display_name&quot;: &quot;android&quot;,
&quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;, &quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;,
&quot;last_seen_user_agent&quot;: &quot;Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0&quot;,
&quot;last_seen_ts&quot;: 1474491775024, &quot;last_seen_ts&quot;: 1474491775024,
&quot;user_id&quot;: &quot;&lt;user_id&gt;&quot; &quot;user_id&quot;: &quot;&lt;user_id&gt;&quot;
}, },
@ -12725,6 +12767,7 @@ same.</p>
&quot;device_id&quot;: &quot;AUIECTSRND&quot;, &quot;device_id&quot;: &quot;AUIECTSRND&quot;,
&quot;display_name&quot;: &quot;ios&quot;, &quot;display_name&quot;: &quot;ios&quot;,
&quot;last_seen_ip&quot;: &quot;1.2.3.5&quot;, &quot;last_seen_ip&quot;: &quot;1.2.3.5&quot;,
&quot;last_seen_user_agent&quot;: &quot;Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0&quot;,
&quot;last_seen_ts&quot;: 1474491775025, &quot;last_seen_ts&quot;: 1474491775025,
&quot;user_id&quot;: &quot;&lt;user_id&gt;&quot; &quot;user_id&quot;: &quot;&lt;user_id&gt;&quot;
} }
@ -12749,6 +12792,8 @@ Device objects contain the following fields:</p>
Absent if no name has been set.</li> Absent if no name has been set.</li>
<li><code>last_seen_ip</code> - The IP address where this device was last seen. <li><code>last_seen_ip</code> - The IP address where this device was last seen.
(May be a few minutes out of date, for efficiency reasons).</li> (May be a few minutes out of date, for efficiency reasons).</li>
<li><code>last_seen_user_agent</code> - The user agent of the device when it was last seen.
(May be a few minutes out of date, for efficiency reasons).</li>
<li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this <li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this
devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li> devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li>
<li><code>user_id</code> - Owner of device.</li> <li><code>user_id</code> - Owner of device.</li>
@ -12791,6 +12836,7 @@ any access token associated with them.</p>
&quot;device_id&quot;: &quot;&lt;device_id&gt;&quot;, &quot;device_id&quot;: &quot;&lt;device_id&gt;&quot;,
&quot;display_name&quot;: &quot;android&quot;, &quot;display_name&quot;: &quot;android&quot;,
&quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;, &quot;last_seen_ip&quot;: &quot;1.2.3.4&quot;,
&quot;last_seen_user_agent&quot;: &quot;Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0&quot;,
&quot;last_seen_ts&quot;: 1474491775024, &quot;last_seen_ts&quot;: 1474491775024,
&quot;user_id&quot;: &quot;&lt;user_id&gt;&quot; &quot;user_id&quot;: &quot;&lt;user_id&gt;&quot;
} }
@ -12808,7 +12854,12 @@ any access token associated with them.</p>
<li><code>display_name</code> - Display name set by the user for this device. <li><code>display_name</code> - Display name set by the user for this device.
Absent if no name has been set.</li> Absent if no name has been set.</li>
<li><code>last_seen_ip</code> - The IP address where this device was last seen. <li><code>last_seen_ip</code> - The IP address where this device was last seen.
(May be a few minutes out of date, for efficiency reasons).
<ul>
<li><code>last_seen_user_agent</code> - The user agent of the device when it was last seen.
(May be a few minutes out of date, for efficiency reasons).</li> (May be a few minutes out of date, for efficiency reasons).</li>
</ul>
</li>
<li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this <li><code>last_seen_ts</code> - The timestamp (in milliseconds since the unix epoch) when this
devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li> devices was last seen. (May be a few minutes out of date, for efficiency reasons).</li>
<li><code>user_id</code> - Owner of device.</li> <li><code>user_id</code> - Owner of device.</li>
@ -13896,8 +13947,8 @@ response and will simultaneously return with the first request, but with very
small processing times.</p> small processing times.</p>
<div style="break-before: page; page-break-before: always;"></div><h2 id="admin-faq"><a class="header" href="#admin-faq">Admin FAQ</a></h2> <div style="break-before: page; page-break-before: always;"></div><h2 id="admin-faq"><a class="header" href="#admin-faq">Admin FAQ</a></h2>
<h2 id="how-do-i-become-a-server-admin"><a class="header" href="#how-do-i-become-a-server-admin">How do I become a server admin?</a></h2> <h2 id="how-do-i-become-a-server-admin"><a class="header" href="#how-do-i-become-a-server-admin">How do I become a server admin?</a></h2>
<p>If your server already has an admin account you should use the user admin API to promote other accounts to become admins. See <a href="usage/administration/../../admin_api/user_admin_api.html#Change-whether-a-user-is-a-server-administrator-or-not">User Admin API</a></p> <p>If your server already has an admin account you should use the <a href="usage/administration/../../admin_api/user_admin_api.html#Change-whether-a-user-is-a-server-administrator-or-not">User Admin API</a> to promote other accounts to become admins.</p>
<p>If you don't have any admin accounts yet you won't be able to use the admin API so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account, use the admin APIs to make further changes.</p> <p>If you don't have any admin accounts yet you won't be able to use the admin API, so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account: use the admin APIs to make further changes.</p>
<pre><code class="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com'; <pre><code class="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
</code></pre> </code></pre>
<h2 id="what-servers-are-my-server-talking-to"><a class="header" href="#what-servers-are-my-server-talking-to">What servers are my server talking to?</a></h2> <h2 id="what-servers-are-my-server-talking-to"><a class="header" href="#what-servers-are-my-server-talking-to">What servers are my server talking to?</a></h2>
@ -13914,8 +13965,9 @@ small processing times.</p>
<h2 id="what-users-are-registered-on-my-server"><a class="header" href="#what-users-are-registered-on-my-server">What users are registered on my server?</a></h2> <h2 id="what-users-are-registered-on-my-server"><a class="header" href="#what-users-are-registered-on-my-server">What users are registered on my server?</a></h2>
<pre><code class="language-sql">SELECT NAME from users; <pre><code class="language-sql">SELECT NAME from users;
</code></pre> </code></pre>
<h2 id="manually-resetting-passwords"><a class="header" href="#manually-resetting-passwords">Manually resetting passwords:</a></h2> <h2 id="manually-resetting-passwords"><a class="header" href="#manually-resetting-passwords">Manually resetting passwords</a></h2>
<p>See https://github.com/matrix-org/synapse/blob/master/README.rst#password-reset</p> <p>Users can reset their password through their client. Alternatively, a server admin
can reset a user's password using the <a href="usage/administration/../../admin_api/user_admin_api.html#reset-password">admin API</a>.</p>
<h2 id="i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again"><a class="header" href="#i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again">I have a problem with my server. Can I just delete my database and start again?</a></h2> <h2 id="i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again"><a class="header" href="#i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again">I have a problem with my server. Can I just delete my database and start again?</a></h2>
<p>Deleting your database is unlikely to make anything better. </p> <p>Deleting your database is unlikely to make anything better. </p>
<p>It's easy to make the mistake of thinking that you can start again from a clean slate by dropping your database, but things don't work like that in a federated network: lots of other servers have information about your server.</p> <p>It's easy to make the mistake of thinking that you can start again from a clean slate by dropping your database, but things don't work like that in a federated network: lots of other servers have information about your server.</p>
@ -13956,6 +14008,66 @@ LIMIT 10;
</code></pre> </code></pre>
<p>You can also use the <a href="usage/administration/../../admin_api/rooms.html#list-room-api">List Room API</a> <p>You can also use the <a href="usage/administration/../../admin_api/rooms.html#list-room-api">List Room API</a>
and <code>order_by</code> <code>state_events</code>.</p> and <code>order_by</code> <code>state_events</code>.</p>
<h2 id="people-cant-accept-room-invitations-from-me"><a class="header" href="#people-cant-accept-room-invitations-from-me">People can't accept room invitations from me</a></h2>
<p>The typical failure mode here is that you send an invitation to someone
to join a room or direct chat, but when they go to accept it, they get an
error (typically along the lines of &quot;Invalid signature&quot;). They might see
something like the following in their logs:</p>
<pre><code>2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server &lt;server&gt; with key ed25519:a_EqML: Unable to verify signature for &lt;server&gt;
</code></pre>
<p>This is normally caused by a misconfiguration in your reverse-proxy. See <a href="usage/administration/docs/reverse_proxy.html">the reverse proxy docs</a> and double-check that your settings are correct.</p>
<h2 id="help-synapse-is-slow-and-eats-all-my-ramcpu"><a class="header" href="#help-synapse-is-slow-and-eats-all-my-ramcpu">Help!! Synapse is slow and eats all my RAM/CPU!</a></h2>
<p>First, ensure you are running the latest version of Synapse, using Python 3
with a <a href="usage/administration/../../postgres.html">PostgreSQL database</a>.</p>
<p>Synapse's architecture is quite RAM hungry currently - we deliberately
cache a lot of recent room data and metadata in RAM in order to speed up
common requests. We'll improve this in the future, but for now the easiest
way to either reduce the RAM usage (at the risk of slowing things down)
is to set the almost-undocumented <code>SYNAPSE_CACHE_FACTOR</code> environment
variable. The default is 0.5, which can be decreased to reduce RAM usage
in memory constrained environments, or increased if performance starts to
degrade.</p>
<p>However, degraded performance due to a low cache factor, common on
machines with slow disks, often leads to explosions in memory use due
backlogged requests. In this case, reducing the cache factor will make
things worse. Instead, try increasing it drastically. 2.0 is a good
starting value.</p>
<p>Using <a href="https://jemalloc.net">libjemalloc</a> can also yield a significant
improvement in overall memory use, and especially in terms of giving back
RAM to the OS. To use it, the library must simply be put in the
LD_PRELOAD environment variable when launching Synapse. On Debian, this
can be done by installing the <code>libjemalloc1</code> package and adding this
line to <code>/etc/default/matrix-synapse</code>:</p>
<pre><code>LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1
</code></pre>
<p>This made a significant difference on Python 2.7 - it's unclear how
much of an improvement it provides on Python 3.x.</p>
<p>If you're encountering high CPU use by the Synapse process itself, you
may be affected by a bug with presence tracking that leads to a
massive excess of outgoing federation requests (see <a href="https://github.com/matrix-org/synapse/issues/3971">discussion</a>). If metrics
indicate that your server is also issuing far more outgoing federation
requests than can be accounted for by your users' activity, this is a
likely cause. The misbehavior can be worked around by disabling presence
in the Synapse config file: <a href="usage/administration/../configuration/config_documentation.html#presence">see here</a>.</p>
<h2 id="running-out-of-file-handles"><a class="header" href="#running-out-of-file-handles">Running out of File Handles</a></h2>
<p>If Synapse runs out of file handles, it typically fails badly - live-locking
at 100% CPU, and/or failing to accept new TCP connections (blocking the
connecting client). Matrix currently can legitimately use a lot of file handles,
thanks to busy rooms like <code>#matrix:matrix.org</code> containing hundreds of participating
servers. The first time a server talks in a room it will try to connect
simultaneously to all participating servers, which could exhaust the available
file descriptors between DNS queries &amp; HTTPS sockets, especially if DNS is slow
to respond. (We need to improve the routing algorithm used to be better than
full mesh, but as of March 2019 this hasn't happened yet).</p>
<p>If you hit this failure mode, we recommend increasing the maximum number of
open file handles to be at least 4096 (assuming a default of 1024 or 256).
This is typically done by editing <code>/etc/security/limits.conf</code></p>
<p>Separately, Synapse may leak file handles if inbound HTTP requests get stuck
during processing - e.g. blocked behind a lock or talking to a remote server etc.
This is best diagnosed by matching up the 'Received request' and 'Processed request'
log lines and looking for any 'Processed request' lines which take more than
a few seconds to execute. Please let us know at <a href="https://matrix.to/#/#synapse-dev:matrix.org"><code>#synapse:matrix.org</code></a> if
you see this failure mode so we can help debug it, however.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1> <div style="break-before: page; page-break-before: always;"></div><h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
<p>This document aims to get you started with contributing to Synapse!</p> <p>This document aims to get you started with contributing to Synapse!</p>
<h1 id="1-who-can-contribute-to-synapse"><a class="header" href="#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></h1> <h1 id="1-who-can-contribute-to-synapse"><a class="header" href="#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></h1>

2
latest/searchindex.js
View file

File diff suppressed because one or more lines are too long

2
latest/searchindex.json
View file

File diff suppressed because one or more lines are too long

2
latest/templates.html
View file

@ -153,7 +153,7 @@ webpages it shows to users.</p>
Server admins can configure an additional directory for Synapse to look for templates Server admins can configure an additional directory for Synapse to look for templates
in, allowing them to specify custom templates:</p> in, allowing them to specify custom templates:</p>
<pre><code class="language-yaml">templates: <pre><code class="language-yaml">templates:
custom_templates_directory: /path/to/custom/templates/ custom_template_directory: /path/to/custom/templates/
</code></pre> </code></pre>
<p>If this setting is not set, or the files named below are not found within the directory, <p>If this setting is not set, or the files named below are not found within the directory,
default templates from within the Synapse package will be used.</p> default templates from within the Synapse package will be used.</p>

16
latest/upgrade.html
View file

@ -232,6 +232,20 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
<h1 id="upgrading-to-v1660"><a class="header" href="#upgrading-to-v1660">Upgrading to v1.66.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.
This removal was previously planned for Synapse 1.64.0, but was
<a href="https://github.com/matrix-org/synapse/issues/13421">delayed</a> until now to give
homeserver administrators more notice of the change.</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 <a href="https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email"><code>email</code> configuration
section</a>
(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>
<h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1> <h1 id="upgrading-to-v1640"><a class="header" href="#upgrading-to-v1640">Upgrading to v1.64.0</a></h1>
<h2 id="deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers"><a class="header" href="#deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers">Deprecation of the ability to delegate e-mail verification to identity servers</a></h2> <h2 id="deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers"><a class="header" href="#deprecation-of-the-ability-to-delegate-e-mail-verification-to-identity-servers">Deprecation of the ability to delegate e-mail verification to identity servers</a></h2>
<p>Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.</p> <p>Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.</p>
@ -1042,7 +1056,7 @@ updated.</p>
<p>When setting up worker processes, we now recommend the use of a Redis <p>When setting up worker processes, we now recommend the use of a Redis
server for replication. <strong>The old direct TCP connection method is server for replication. <strong>The old direct TCP connection method is
deprecated and will be removed in a future release.</strong> See deprecated and will be removed in a future release.</strong> See
<a href="workers.html">workers</a> for more details.</p> the <a href="https://matrix-org.github.io/synapse/v1.66/workers.html">worker documentation</a> for more details.</p>
<h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1> <h1 id="upgrading-to-v1140"><a class="header" href="#upgrading-to-v1140">Upgrading to v1.14.0</a></h1>
<p>This version includes a database update which is run as part of the <p>This version includes a database update which is run as part of the
upgrade, and which may take a couple of minutes in the case of a large upgrade, and which may take a couple of minutes in the case of a large

69
latest/usage/administration/admin_faq.html
View file

@ -148,8 +148,8 @@
<h2 id="admin-faq"><a class="header" href="#admin-faq">Admin FAQ</a></h2> <h2 id="admin-faq"><a class="header" href="#admin-faq">Admin FAQ</a></h2>
<h2 id="how-do-i-become-a-server-admin"><a class="header" href="#how-do-i-become-a-server-admin">How do I become a server admin?</a></h2> <h2 id="how-do-i-become-a-server-admin"><a class="header" href="#how-do-i-become-a-server-admin">How do I become a server admin?</a></h2>
<p>If your server already has an admin account you should use the user admin API to promote other accounts to become admins. See <a href="../../admin_api/user_admin_api.html#Change-whether-a-user-is-a-server-administrator-or-not">User Admin API</a></p> <p>If your server already has an admin account you should use the <a href="../../admin_api/user_admin_api.html#Change-whether-a-user-is-a-server-administrator-or-not">User Admin API</a> to promote other accounts to become admins.</p>
<p>If you don't have any admin accounts yet you won't be able to use the admin API so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account, use the admin APIs to make further changes.</p> <p>If you don't have any admin accounts yet you won't be able to use the admin API, so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account: use the admin APIs to make further changes.</p>
<pre><code class="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com'; <pre><code class="language-sql">UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
</code></pre> </code></pre>
<h2 id="what-servers-are-my-server-talking-to"><a class="header" href="#what-servers-are-my-server-talking-to">What servers are my server talking to?</a></h2> <h2 id="what-servers-are-my-server-talking-to"><a class="header" href="#what-servers-are-my-server-talking-to">What servers are my server talking to?</a></h2>
@ -166,8 +166,9 @@
<h2 id="what-users-are-registered-on-my-server"><a class="header" href="#what-users-are-registered-on-my-server">What users are registered on my server?</a></h2> <h2 id="what-users-are-registered-on-my-server"><a class="header" href="#what-users-are-registered-on-my-server">What users are registered on my server?</a></h2>
<pre><code class="language-sql">SELECT NAME from users; <pre><code class="language-sql">SELECT NAME from users;
</code></pre> </code></pre>
<h2 id="manually-resetting-passwords"><a class="header" href="#manually-resetting-passwords">Manually resetting passwords:</a></h2> <h2 id="manually-resetting-passwords"><a class="header" href="#manually-resetting-passwords">Manually resetting passwords</a></h2>
<p>See https://github.com/matrix-org/synapse/blob/master/README.rst#password-reset</p> <p>Users can reset their password through their client. Alternatively, a server admin
can reset a user's password using the <a href="../../admin_api/user_admin_api.html#reset-password">admin API</a>.</p>
<h2 id="i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again"><a class="header" href="#i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again">I have a problem with my server. Can I just delete my database and start again?</a></h2> <h2 id="i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again"><a class="header" href="#i-have-a-problem-with-my-server-can-i-just-delete-my-database-and-start-again">I have a problem with my server. Can I just delete my database and start again?</a></h2>
<p>Deleting your database is unlikely to make anything better. </p> <p>Deleting your database is unlikely to make anything better. </p>
<p>It's easy to make the mistake of thinking that you can start again from a clean slate by dropping your database, but things don't work like that in a federated network: lots of other servers have information about your server.</p> <p>It's easy to make the mistake of thinking that you can start again from a clean slate by dropping your database, but things don't work like that in a federated network: lots of other servers have information about your server.</p>
@ -208,6 +209,66 @@ LIMIT 10;
</code></pre> </code></pre>
<p>You can also use the <a href="../../admin_api/rooms.html#list-room-api">List Room API</a> <p>You can also use the <a href="../../admin_api/rooms.html#list-room-api">List Room API</a>
and <code>order_by</code> <code>state_events</code>.</p> and <code>order_by</code> <code>state_events</code>.</p>
<h2 id="people-cant-accept-room-invitations-from-me"><a class="header" href="#people-cant-accept-room-invitations-from-me">People can't accept room invitations from me</a></h2>
<p>The typical failure mode here is that you send an invitation to someone
to join a room or direct chat, but when they go to accept it, they get an
error (typically along the lines of &quot;Invalid signature&quot;). They might see
something like the following in their logs:</p>
<pre><code>2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server &lt;server&gt; with key ed25519:a_EqML: Unable to verify signature for &lt;server&gt;
</code></pre>
<p>This is normally caused by a misconfiguration in your reverse-proxy. See <a href="docs/reverse_proxy.html">the reverse proxy docs</a> and double-check that your settings are correct.</p>
<h2 id="help-synapse-is-slow-and-eats-all-my-ramcpu"><a class="header" href="#help-synapse-is-slow-and-eats-all-my-ramcpu">Help!! Synapse is slow and eats all my RAM/CPU!</a></h2>
<p>First, ensure you are running the latest version of Synapse, using Python 3
with a <a href="../../postgres.html">PostgreSQL database</a>.</p>
<p>Synapse's architecture is quite RAM hungry currently - we deliberately
cache a lot of recent room data and metadata in RAM in order to speed up
common requests. We'll improve this in the future, but for now the easiest
way to either reduce the RAM usage (at the risk of slowing things down)
is to set the almost-undocumented <code>SYNAPSE_CACHE_FACTOR</code> environment
variable. The default is 0.5, which can be decreased to reduce RAM usage
in memory constrained environments, or increased if performance starts to
degrade.</p>
<p>However, degraded performance due to a low cache factor, common on
machines with slow disks, often leads to explosions in memory use due
backlogged requests. In this case, reducing the cache factor will make
things worse. Instead, try increasing it drastically. 2.0 is a good
starting value.</p>
<p>Using <a href="https://jemalloc.net">libjemalloc</a> can also yield a significant
improvement in overall memory use, and especially in terms of giving back
RAM to the OS. To use it, the library must simply be put in the
LD_PRELOAD environment variable when launching Synapse. On Debian, this
can be done by installing the <code>libjemalloc1</code> package and adding this
line to <code>/etc/default/matrix-synapse</code>:</p>
<pre><code>LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1
</code></pre>
<p>This made a significant difference on Python 2.7 - it's unclear how
much of an improvement it provides on Python 3.x.</p>
<p>If you're encountering high CPU use by the Synapse process itself, you
may be affected by a bug with presence tracking that leads to a
massive excess of outgoing federation requests (see <a href="https://github.com/matrix-org/synapse/issues/3971">discussion</a>). If metrics
indicate that your server is also issuing far more outgoing federation
requests than can be accounted for by your users' activity, this is a
likely cause. The misbehavior can be worked around by disabling presence
in the Synapse config file: <a href="../configuration/config_documentation.html#presence">see here</a>.</p>
<h2 id="running-out-of-file-handles"><a class="header" href="#running-out-of-file-handles">Running out of File Handles</a></h2>
<p>If Synapse runs out of file handles, it typically fails badly - live-locking
at 100% CPU, and/or failing to accept new TCP connections (blocking the
connecting client). Matrix currently can legitimately use a lot of file handles,
thanks to busy rooms like <code>#matrix:matrix.org</code> containing hundreds of participating
servers. The first time a server talks in a room it will try to connect
simultaneously to all participating servers, which could exhaust the available
file descriptors between DNS queries &amp; HTTPS sockets, especially if DNS is slow
to respond. (We need to improve the routing algorithm used to be better than
full mesh, but as of March 2019 this hasn't happened yet).</p>
<p>If you hit this failure mode, we recommend increasing the maximum number of
open file handles to be at least 4096 (assuming a default of 1024 or 256).
This is typically done by editing <code>/etc/security/limits.conf</code></p>
<p>Separately, Synapse may leak file handles if inbound HTTP requests get stuck
during processing - e.g. blocked behind a lock or talking to a remote server etc.
This is best diagnosed by matching up the 'Received request' and 'Processed request'
log lines and looking for any 'Processed request' lines which take more than
a few seconds to execute. Please let us know at <a href="https://matrix.to/#/#synapse-dev:matrix.org"><code>#synapse:matrix.org</code></a> if
you see this failure mode so we can help debug it, however.</p>
</main> </main>

21
latest/usage/configuration/config_documentation.html
View file

@ -482,7 +482,7 @@ configuration.</p>
<p><code>metrics</code>: (see the docs <a href="../../metrics-howto.html">here</a>),</p> <p><code>metrics</code>: (see the docs <a href="../../metrics-howto.html">here</a>),</p>
</li> </li>
<li> <li>
<p><code>replication</code>: (see the docs <a href="../../workers.html">here</a>).</p> <p><code>replication</code>: (deprecated as of Synapse 1.18, see the docs <a href="../../workers.html">here</a>).</p>
</li> </li>
</ul> </ul>
</li> </li>
@ -502,7 +502,7 @@ on this port. Sub-options for each resource are:</p>
</li> </li>
<li> <li>
<p><code>compress</code>: set to true to enable gzip compression on HTTP bodies for this resource. This is currently only supported with the <p><code>compress</code>: set to true to enable gzip compression on HTTP bodies for this resource. This is currently only supported with the
<code>client</code>, <code>consent</code> and <code>metrics</code> resources.</p> <code>client</code>, <code>consent</code>, <code>metrics</code> and <code>federation</code> resources.</p>
</li> </li>
</ul> </ul>
</li> </li>
@ -769,6 +769,9 @@ using Synapse's media repository.</p>
<h3 id="redaction_retention_period"><a class="header" href="#redaction_retention_period"><code>redaction_retention_period</code></a></h3> <h3 id="redaction_retention_period"><a class="header" href="#redaction_retention_period"><code>redaction_retention_period</code></a></h3>
<p>How long to keep redacted events in unredacted form in the database. After <p>How long to keep redacted events in unredacted form in the database. After
this period redacted events get replaced with their redacted form in the DB.</p> this period redacted events get replaced with their redacted form in the DB.</p>
<p>Synapse will check whether the rentention period has concluded for redacted
events every 5 minutes. Thus, even if this option is set to <code>0</code>, Synapse may
still take up to 5 minutes to purge redacted events from the database.</p>
<p>Defaults to <code>7d</code>. Set to <code>null</code> to disable.</p> <p>Defaults to <code>7d</code>. Set to <code>null</code> to disable.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">redaction_retention_period: 28d <pre><code class="language-yaml">redaction_retention_period: 28d
@ -832,7 +835,11 @@ the <code>allowed_lifetime_min</code> and <code>allowed_lifetime_max</code> conf
which are older than the room's maximum retention period. Synapse will also 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 filter events received over federation so that events that should have been
purged are ignored and not stored again.</p> purged are ignored and not stored again.</p>
<p>The message retention policies feature is disabled by default.</p> <p>The message retention policies feature is disabled by default. Please be advised
that enabling this feature carries some risk. There are known bugs with the implementation
which can cause database corruption. Setting retention to delete older history
is less risky than deleting newer history but in general caution is advised when enabling this
experimental feature. You can read more about this feature <a href="../../message_retention_policies.html">here</a>.</p>
<p>This setting has the following sub-options:</p> <p>This setting has the following sub-options:</p>
<ul> <ul>
<li> <li>
@ -1925,7 +1932,9 @@ their account.</p>
<p>(Servers handling the these requests must answer the <code>/requestToken</code> endpoints defined <p>(Servers handling the these requests must answer the <code>/requestToken</code> endpoints defined
by the Matrix Identity Service API by the Matrix Identity Service API
<a href="https://matrix.org/docs/spec/identity_service/latest">specification</a>.)</p> <a href="https://matrix.org/docs/spec/identity_service/latest">specification</a>.)</p>
<p><em>Updated in Synapse 1.64.0</em>: The <code>email</code> option is deprecated.</p> <p><em>Deprecated in Synapse 1.64.0</em>: The <code>email</code> option is deprecated.</p>
<p><em>Removed in Synapse 1.66.0</em>: The <code>email</code> option has been removed.
If present, Synapse will report a configuration error on startup.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">account_threepid_delegates: <pre><code class="language-yaml">account_threepid_delegates:
msisdn: http://localhost:8090 # Delegate SMS sending to this local process msisdn: http://localhost:8090 # Delegate SMS sending to this local process
@ -3012,7 +3021,7 @@ user directory. Defaults to false.</li>
<h3 id="user_consent"><a class="header" href="#user_consent"><code>user_consent</code></a></h3> <h3 id="user_consent"><a class="header" href="#user_consent"><code>user_consent</code></a></h3>
<p>For detailed instructions on user consent configuration, see <a href="../../consent_tracking.html">here</a>.</p> <p>For detailed instructions on user consent configuration, see <a href="../../consent_tracking.html">here</a>.</p>
<p>Parts of this section are required if enabling the <code>consent</code> resource under <p>Parts of this section are required if enabling the <code>consent</code> resource under
<code>listeners</code>, in particular <code>template_dir</code> and <code>version</code>. # TODO: link <code>listeners</code></p> <a href="#listeners"><code>listeners</code></a>, in particular <code>template_dir</code> and <code>version</code>.</p>
<ul> <ul>
<li> <li>
<p><code>template_dir</code>: gives the location of the templates for the HTML forms. <p><code>template_dir</code>: gives the location of the templates for the HTML forms.
@ -3027,7 +3036,7 @@ parameter.</p>
</li> </li>
<li> <li>
<p><code>server_notice_content</code>: if enabled, will send a user a &quot;Server Notice&quot; <p><code>server_notice_content</code>: if enabled, will send a user a &quot;Server Notice&quot;
asking them to consent to the privacy policy. The <code>server_notices</code> section ##TODO: link asking them to consent to the privacy policy. The <a href="#server_notices"><code>server_notices</code> section</a>
must also be configured for this to work. Notices will <em>not</em> be sent to must also be configured for this to work. Notices will <em>not</em> be sent to
guest users unless <code>send_server_notice_to_guests</code> is set to true.</p> guest users unless <code>send_server_notice_to_guests</code> is set to true.</p>
</li> </li>