mirror of
https://github.com/matrix-org/synapse.git
synced 2025-02-13 18:55:47 +00:00
deploy: 3853011d01
This commit is contained in:
DMRobertson
parent
47f7381778
commit
6d4ab8fb90
@ -504,6 +504,133 @@ If the room does not define a type, the value will be <code>null</code>.</li>
|
||||
]
|
||||
}
|
||||
</code></pre>
|
||||
<h1 id="room-messages-api"><a class="header" href="#room-messages-api">Room Messages API</a></h1>
|
||||
<p>The Room Messages admin API allows server admins to get all messages
|
||||
sent to a room in a given timeframe. There are various parameters available
|
||||
that allow for filtering and ordering the returned list. This API supports pagination.</p>
|
||||
<p>To use it, you will need to authenticate by providing an <code>access_token</code>
|
||||
for a server admin: see <a href="../usage/administration/admin_api">Admin API</a>.</p>
|
||||
<p>This endpoint mirrors the <a href="https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages">Matrix Spec defined Messages API</a>.</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/messages
|
||||
</code></pre>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following path parameters are required:</p>
|
||||
<ul>
|
||||
<li><code>room_id</code> - The ID of the room you wish you fetch messages from.</li>
|
||||
</ul>
|
||||
<p>The following query parameters are available:</p>
|
||||
<ul>
|
||||
<li><code>from</code> (required) - The token to start returning events from. This token can be obtained from a prev_batch
|
||||
or next_batch token returned by the /sync endpoint, or from an end token returned by a previous request to this endpoint.</li>
|
||||
<li><code>to</code> - The token to spot returning events at.</li>
|
||||
<li><code>limit</code> - The maximum number of events to return. Defaults to <code>10</code>.</li>
|
||||
<li><code>filter</code> - A JSON RoomEventFilter to filter returned events with.</li>
|
||||
<li><code>dir</code> - The direction to return events from. Either <code>f</code> for forwards or <code>b</code> for backwards. Setting
|
||||
this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</li>
|
||||
</ul>
|
||||
<p><strong>Response</strong></p>
|
||||
<p>The following fields are possible in the JSON response body:</p>
|
||||
<ul>
|
||||
<li><code>chunk</code> - A list of room events. The order depends on the dir parameter.
|
||||
Note that an empty chunk does not necessarily imply that no more events are available. Clients should continue to paginate until no end property is returned.</li>
|
||||
<li><code>end</code> - A token corresponding to the end of chunk. This token can be passed back to this endpoint to request further events.
|
||||
If no further events are available, this property is omitted from the response.</li>
|
||||
<li><code>start</code> - A token corresponding to the start of chunk.</li>
|
||||
<li><code>state</code> - A list of state events relevant to showing the chunk.</li>
|
||||
</ul>
|
||||
<p><strong>Example</strong></p>
|
||||
<p>For more details on each chunk, read <a href="https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages">the Matrix specification</a>.</p>
|
||||
<pre><code class="language-json">{
|
||||
"chunk": [
|
||||
{
|
||||
"content": {
|
||||
"body": "This is an example text message",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<b>This is an example text message</b>",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234
|
||||
}
|
||||
},
|
||||
{
|
||||
"content": {
|
||||
"name": "The room name"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "",
|
||||
"type": "m.room.name",
|
||||
"unsigned": {
|
||||
"age": 1234
|
||||
}
|
||||
},
|
||||
{
|
||||
"content": {
|
||||
"body": "Gangnam Style",
|
||||
"info": {
|
||||
"duration": 2140786,
|
||||
"h": 320,
|
||||
"mimetype": "video/mp4",
|
||||
"size": 1563685,
|
||||
"thumbnail_info": {
|
||||
"h": 300,
|
||||
"mimetype": "image/jpeg",
|
||||
"size": 46144,
|
||||
"w": 300
|
||||
},
|
||||
"thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
|
||||
"w": 480
|
||||
},
|
||||
"msgtype": "m.video",
|
||||
"url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234
|
||||
}
|
||||
}
|
||||
],
|
||||
"end": "t47409-4357353_219380_26003_2265",
|
||||
"start": "t47429-4392820_219380_26003_2265"
|
||||
}
|
||||
</code></pre>
|
||||
<h1 id="room-timestamp-to-event-api"><a class="header" href="#room-timestamp-to-event-api">Room Timestamp to Event API</a></h1>
|
||||
<p>The Room Timestamp to Event API endpoint fetches the <code>event_id</code> of the closest event to the given
|
||||
timestamp (<code>ts</code> query parameter) in the given direction (<code>dir</code> query parameter).</p>
|
||||
<p>Useful for cases like jump to date so you can start paginating messages from
|
||||
a given date in the archive.</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code> GET /_synapse/admin/v1/rooms/<room_id>/timestamp_to_event
|
||||
</code></pre>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following path parameters are required:</p>
|
||||
<ul>
|
||||
<li><code>room_id</code> - The ID of the room you wish to check.</li>
|
||||
</ul>
|
||||
<p>The following query parameters are available:</p>
|
||||
<ul>
|
||||
<li><code>ts</code> - a timestamp in milliseconds where we will find the closest event in
|
||||
the given direction.</li>
|
||||
<li><code>dir</code> - can be <code>f</code> or <code>b</code> to indicate forwards and backwards in time from the
|
||||
given timestamp. Defaults to <code>f</code>.</li>
|
||||
</ul>
|
||||
<p><strong>Response</strong></p>
|
||||
<ul>
|
||||
<li><code>event_id</code> - converted from timestamp</li>
|
||||
</ul>
|
||||
<h1 id="block-room-api"><a class="header" href="#block-room-api">Block Room API</a></h1>
|
||||
<p>The Block Room admin API allows server admins to block and unblock rooms,
|
||||
and query to see if a given room is blocked.
|
||||
|
||||
@ -181,6 +181,7 @@ for a server admin: see <a href="../usage/administration/admin_api">Admin API</a
|
||||
"appservice_id": null,
|
||||
"consent_server_notice_sent": null,
|
||||
"consent_version": null,
|
||||
"consent_ts": null,
|
||||
"external_ids": [
|
||||
{
|
||||
"auth_provider": "<provider1>",
|
||||
@ -488,6 +489,7 @@ is set to <code>true</code>:</p>
|
||||
<li>Remove the user's creation (registration) timestamp</li>
|
||||
<li><a href="#override-ratelimiting-for-users">Remove rate limit overrides</a></li>
|
||||
<li>Remove from monthly active users</li>
|
||||
<li>Remove user's consent information (consent version and timestamp)</li>
|
||||
</ul>
|
||||
<h2 id="reset-password"><a class="header" href="#reset-password">Reset password</a></h2>
|
||||
<p>Changes the password of another user. This will automatically log the user out of all their devices.</p>
|
||||
@ -1136,6 +1138,30 @@ for more information.</p>
|
||||
</code></pre>
|
||||
<p>The request and response format is the same as the
|
||||
<a href="https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available">/_matrix/client/r0/register/available</a> API.</p>
|
||||
<h3 id="find-a-user-based-on-their-id-in-an-auth-provider"><a class="header" href="#find-a-user-based-on-their-id-in-an-auth-provider">Find a user based on their ID in an auth provider</a></h3>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/auth_providers/$provider/users/$external_id
|
||||
</code></pre>
|
||||
<p>When a user matched the given ID for the given provider, an HTTP code <code>200</code> with a response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"user_id": "@hello:example.org"
|
||||
}
|
||||
</code></pre>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following parameters should be set in the URL:</p>
|
||||
<ul>
|
||||
<li><code>provider</code> - The ID of the authentication provider, as advertised by the <a href="https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login"><code>GET /_matrix/client/v3/login</code></a> API in the <code>m.login.sso</code> authentication method.</li>
|
||||
<li><code>external_id</code> - The user ID from the authentication provider. Usually corresponds to the <code>sub</code> claim for OIDC providers, or to the <code>uid</code> attestation for SAML2 providers.</li>
|
||||
</ul>
|
||||
<p>The <code>external_id</code> may have characters that are not URL-safe (typically <code>/</code>, <code>:</code> or <code>@</code>), so it is advised to URL-encode those parameters.</p>
|
||||
<p><strong>Errors</strong></p>
|
||||
<p>Returns a <code>404</code> HTTP status code if no user was found, with a response body like this:</p>
|
||||
<pre><code class="language-json">{
|
||||
"errcode":"M_NOT_FOUND",
|
||||
"error":"User not found"
|
||||
}
|
||||
</code></pre>
|
||||
<p><em>Added in Synapse 1.68.0.</em></p>
|
||||
|
||||
</main>
|
||||
|
||||
|
||||
@ -147,9 +147,9 @@
|
||||
</div>
|
||||
|
||||
<h1 id="deprecation-policy-for-platform-dependencies"><a class="header" href="#deprecation-policy-for-platform-dependencies">Deprecation Policy for Platform Dependencies</a></h1>
|
||||
<p>Synapse has a number of platform dependencies, including Python and PostgreSQL.
|
||||
This document outlines the policy towards which versions we support, and when we
|
||||
drop support for versions in the future.</p>
|
||||
<p>Synapse has a number of platform dependencies, including Python, Rust,
|
||||
PostgreSQL and SQLite. This document outlines the policy towards which versions
|
||||
we support, and when we drop support for versions in the future.</p>
|
||||
<h2 id="policy"><a class="header" href="#policy">Policy</a></h2>
|
||||
<p>Synapse follows the upstream support life cycles for Python and PostgreSQL,
|
||||
i.e. when a version reaches End of Life Synapse will withdraw support for that
|
||||
@ -157,6 +157,13 @@ version in future releases.</p>
|
||||
<p>Details on the upstream support life cycles for Python and PostgreSQL are
|
||||
documented at <a href="https://endoflife.date/python">https://endoflife.date/python</a> and
|
||||
<a href="https://endoflife.date/postgresql">https://endoflife.date/postgresql</a>.</p>
|
||||
<p>A Rust compiler is required to build Synapse from source. For any given release
|
||||
the minimum required version may be bumped up to a recent Rust version, and so
|
||||
people building from source should ensure they can fetch recent versions of Rust
|
||||
(e.g. by using <a href="https://rustup.rs/">rustup</a>).</p>
|
||||
<p>The oldest supported version of SQLite is the version
|
||||
<a href="https://packages.debian.org/buster/libsqlite3-0">provided</a> by
|
||||
<a href="https://wiki.debian.org/DebianOldStable">Debian oldstable</a>.</p>
|
||||
<h2 id="context"><a class="header" href="#context">Context</a></h2>
|
||||
<p>It is important for system admins to have a clear understanding of the platform
|
||||
requirements of Synapse and its deprecation policies so that they can
|
||||
@ -167,6 +174,16 @@ long process.</p>
|
||||
<p>By following the upstream support life cycles Synapse can ensure that its
|
||||
dependencies continue to get security patches, while not requiring system admins
|
||||
to constantly update their platform dependencies to the latest versions.</p>
|
||||
<p>For Rust, the situation is a bit different given that a) the Rust foundation
|
||||
does not generally support older Rust versions, and b) the library ecosystem
|
||||
generally bump their minimum support Rust versions frequently. In general, the
|
||||
Synapse team will try to avoid updating the dependency on Rust to the absolute
|
||||
latest version, but introducing a formal policy is hard given the constraints of
|
||||
the ecosystem.</p>
|
||||
<p>On a similar note, SQLite does not generally have a concept of "supported
|
||||
release"; bugfixes are published for the latest minor release only. We chose to
|
||||
track Debian's oldstable as this is relatively conservative, predictably updated
|
||||
and is consistent with the <code>.deb</code> packages released by Matrix.org.</p>
|
||||
|
||||
</main>
|
||||
|
||||
|
||||
@ -166,6 +166,8 @@ on Windows is not officially supported.</p>
|
||||
<p>Synapse can connect to PostgreSQL via the <a href="https://pypi.org/project/psycopg2/">psycopg2</a> Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with <code>sudo apt install libpq-dev</code>.</p>
|
||||
<p>The source code of Synapse is hosted on GitHub. You will also need <a href="https://github.com/git-guides/install-git">a recent version of git</a>.</p>
|
||||
<p>For some tests, you will need <a href="https://docs.docker.com/get-docker/">a recent version of Docker</a>.</p>
|
||||
<p>A recent version of the Rust compiler is needed to build the native modules. The
|
||||
easiest way of installing the latest version is to use <a href="https://rustup.rs/">rustup</a>.</p>
|
||||
<h1 id="3-get-the-source"><a class="header" href="#3-get-the-source">3. Get the source.</a></h1>
|
||||
<p>The preferred and easiest way to contribute changes is to fork the relevant
|
||||
project on GitHub, and then <a href="https://help.github.com/articles/using-pull-requests/">create a pull request</a> to ask us to pull your
|
||||
@ -222,6 +224,10 @@ to check that your contributions render correctly. The docs are written in
|
||||
<p>Some documentation also exists in <a href="https://github.com/matrix-org/synapse/wiki">Synapse's GitHub
|
||||
Wiki</a>, although this is primarily
|
||||
contributed to by community authors.</p>
|
||||
<p>When changes are made to any Rust code then you must call either <code>poetry install</code>
|
||||
or <code>maturin develop</code> (if installed) to rebuild the Rust code. Using <a href="https://github.com/PyO3/maturin"><code>maturin</code></a>
|
||||
is quicker than <code>poetry install</code>, so is recommended when making frequent
|
||||
changes to the Rust code.</p>
|
||||
<h1 id="8-test-test-test"><a class="header" href="#8-test-test-test">8. Test, test, test!</a></h1>
|
||||
<p><a name="test-test-test"></a></p>
|
||||
<p>While you're developing and before submitting a patch, you'll
|
||||
@ -270,7 +276,7 @@ working directory. Typically, this ends up being <code>_trial_temp/test.db</code
|
||||
<p>The database file can then be inspected with:</p>
|
||||
<pre><code class="language-sh">sqlite3 _trial_temp/test.db
|
||||
</code></pre>
|
||||
<p>Note that the database file is cleared at the beginning of each test run. Thus it
|
||||
<p>Note that the database file is cleared at the beginning of each test run. Thus it
|
||||
will always only contain the data generated by the <em>last run test</em>. Though generally
|
||||
when debugging, one is only running a single test anyway.</p>
|
||||
<h3 id="running-tests-under-postgresql"><a class="header" href="#running-tests-under-postgresql">Running tests under PostgreSQL</a></h3>
|
||||
|
||||
@ -242,6 +242,20 @@ context of poetry's venv, without having to run <code>poetry shell</code> before
|
||||
<h2 id="reset-my-venv-to-the-locked-environment"><a class="header" href="#reset-my-venv-to-the-locked-environment">...reset my venv to the locked environment?</a></h2>
|
||||
<pre><code class="language-shell">poetry install --extras all --remove-untracked
|
||||
</code></pre>
|
||||
<h2 id="delete-everything-and-start-over-from-scratch"><a class="header" href="#delete-everything-and-start-over-from-scratch">...delete everything and start over from scratch?</a></h2>
|
||||
<pre><code class="language-shell"># Stop the current virtualenv if active
|
||||
$ deactivate
|
||||
|
||||
# Remove all of the files from the current environment.
|
||||
# Don't worry, even though it says "all", this will only
|
||||
# remove the Poetry virtualenvs for the current project.
|
||||
$ poetry env remove --all
|
||||
|
||||
# Reactivate Poetry shell to create the virtualenv again
|
||||
$ poetry shell
|
||||
# Install everything again
|
||||
$ poetry install --extras all
|
||||
</code></pre>
|
||||
<h2 id="run-a-command-in-the-poetry-virtualenv"><a class="header" href="#run-a-command-in-the-poetry-virtualenv">...run a command in the <code>poetry</code> virtualenv?</a></h2>
|
||||
<p>Use <code>poetry run cmd args</code> when you need the python virtualenv context.
|
||||
To avoid typing <code>poetry run</code> all the time, you can run <code>poetry shell</code>
|
||||
@ -330,6 +344,11 @@ installed <code>poetry</code> with <code>pipx</code>, try <code>pipx runpip poet
|
||||
<p>Poetry caches a bunch of information about packages that isn't readily available
|
||||
from PyPI. (This is what makes poetry seem slow when doing the first
|
||||
<code>poetry install</code>.) Try <code>poetry cache list</code> and <code>poetry cache clear --all <name of cache></code> to see if that fixes things.</p>
|
||||
<h2 id="remove-outdated-egg-info"><a class="header" href="#remove-outdated-egg-info">Remove outdated egg-info</a></h2>
|
||||
<p>Delete the <code>matrix_synapse.egg-info/</code> directory from the root of your Synapse
|
||||
install.</p>
|
||||
<p>This stores some cached information about dependencies and often conflicts with
|
||||
letting Poetry do the right thing.</p>
|
||||
<h2 id="try---verbose-or---dry-run-arguments"><a class="header" href="#try---verbose-or---dry-run-arguments">Try <code>--verbose</code> or <code>--dry-run</code> arguments.</a></h2>
|
||||
<p>Sometimes useful to see what poetry's internal logic is.</p>
|
||||
|
||||
|
||||
@ -360,6 +360,9 @@ and mounting it to <code>/var/synapse</code> should be taken into consideration.
|
||||
<li>Python 3.7 or later, up to Python 3.10.</li>
|
||||
<li>At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org</li>
|
||||
</ul>
|
||||
<p>If building on an uncommon architecture for which pre-built wheels are
|
||||
unavailable, you will need to have a recent Rust compiler installed. The easiest
|
||||
way of installing the latest version is to use <a href="https://rustup.rs/">rustup</a>.</p>
|
||||
<p>To install the Synapse homeserver run:</p>
|
||||
<pre><code class="language-sh">mkdir -p ~/synapse
|
||||
virtualenv -p python3 ~/synapse/env
|
||||
@ -430,8 +433,9 @@ sudo dnf groupinstall "Development Tools"
|
||||
<p>You may need to install the latest Xcode developer tools:</p>
|
||||
<pre><code class="language-sh">xcode-select --install
|
||||
</code></pre>
|
||||
<p>On ARM-based Macs you may need to explicitly install libjpeg which is a pillow dependency. You can use Homebrew (https://brew.sh):</p>
|
||||
<pre><code class="language-sh"> brew install jpeg
|
||||
<p>On ARM-based Macs you may need to install libjpeg and libpq.
|
||||
You can use Homebrew (https://brew.sh):</p>
|
||||
<pre><code class="language-sh"> brew install jpeg libpq
|
||||
</code></pre>
|
||||
<p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
|
||||
via brew and inform <code>pip</code> about it so that <code>psycopg2</code> builds:</p>
|
||||
@ -886,6 +890,10 @@ consider setting <code>bind_addresses: ['127.0.0.1']</code> so that the server o
|
||||
listens to traffic on localhost. (Do not change <code>bind_addresses</code> to <code>127.0.0.1</code>
|
||||
when using a containerized Synapse, as that will prevent it from responding
|
||||
to proxied traffic.)</p>
|
||||
<p>Optionally, you can also set
|
||||
<a href="../usage/configuration/config_documentation.html#listeners"><code>request_id_header</code></a>
|
||||
so that the server extracts and re-uses the same request ID format that the
|
||||
reverse proxy is using.</p>
|
||||
<h2 id="reverse-proxy-configuration-examples"><a class="header" href="#reverse-proxy-configuration-examples">Reverse-proxy configuration examples</a></h2>
|
||||
<p><strong>NOTE</strong>: You only need one of these.</p>
|
||||
<h3 id="nginx"><a class="header" href="#nginx">nginx</a></h3>
|
||||
@ -1547,9 +1555,8 @@ which are no longer maintained.</p>
|
||||
summaries.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>If Synapse was installed using <a href="setup/installation.html#prebuilt-packages">prebuilt
|
||||
packages</a>, you will need to follow the
|
||||
normal process for upgrading those packages.</p>
|
||||
<p>If Synapse was installed using <a href="setup/installation.html#prebuilt-packages">prebuilt packages</a>,
|
||||
you will need to follow the normal process for upgrading those packages.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>If Synapse was installed using pip then upgrade to the latest
|
||||
@ -1617,6 +1624,17 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
|
||||
</code></pre>
|
||||
</li>
|
||||
</ul>
|
||||
<h1 id="upgrading-to-v1680"><a class="header" href="#upgrading-to-v1680">Upgrading to v1.68.0</a></h1>
|
||||
<p>As announced in the upgrade notes for v1.67.0, Synapse now requires a SQLite
|
||||
version of 3.27.0 or higher if SQLite is in use and source checkouts of Synapse
|
||||
now require a recent Rust compiler.</p>
|
||||
<p>Installations using </p>
|
||||
<ul>
|
||||
<li>Docker images <a href="https://hub.docker.com/r/matrixdotorg/synapse">from <code>matrixdotorg</code></a>,</li>
|
||||
<li>Debian packages <a href="https://packages.matrix.org/">from Matrix.org</a>, or</li>
|
||||
<li>PyPI wheels via <code>pip install matrix-synapse</code> (on supported platforms and architectures)</li>
|
||||
</ul>
|
||||
<p>will not be affected.</p>
|
||||
<h1 id="upgrading-to-v1670"><a class="header" href="#upgrading-to-v1670">Upgrading to v1.67.0</a></h1>
|
||||
<h2 id="direct-tcp-replication-is-no-longer-supported-migrate-to-redis"><a class="header" href="#direct-tcp-replication-is-no-longer-supported-migrate-to-redis">Direct TCP replication is no longer supported: migrate to Redis</a></h2>
|
||||
<p>Redis support was added in v1.13.0 with it becoming the recommended method in
|
||||
@ -1642,7 +1660,7 @@ will require a recent Rust compiler. Those using packages or
|
||||
<p>From the next major release (v1.68.0) Synapse will require SQLite 3.27.0 or
|
||||
higher. Synapse v1.67.0 will be the last major release supporting SQLite
|
||||
versions 3.22 to 3.26.</p>
|
||||
<p>Those using docker images or Debian packages from Matrix.org will not be
|
||||
<p>Those using Docker images or Debian packages from Matrix.org will not be
|
||||
affected. If you have installed from source, you should check the version of
|
||||
SQLite used by Python with:</p>
|
||||
<pre><code class="language-shell">python -c "import sqlite3; print(sqlite3.sqlite_version)"
|
||||
@ -3539,7 +3557,16 @@ configuration.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>x_forwarded</code>: Only valid for an 'http' listener. Set to true to use the X-Forwarded-For header as the client IP. Useful when Synapse is
|
||||
behind a reverse-proxy.</p>
|
||||
behind a <a href="usage/configuration/../../reverse_proxy.html">reverse-proxy</a>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>request_id_header</code>: The header extracted from each incoming request that is
|
||||
used as the basis for the request ID. The request ID is used in
|
||||
<a href="usage/configuration/../administration/request_log.html#request-log-format">logs</a> and tracing to
|
||||
correlate and match up requests. When unset, Synapse will automatically
|
||||
generate sequential request IDs. This option is useful when Synapse is behind
|
||||
a <a href="usage/configuration/../../reverse_proxy.html">reverse-proxy</a>.</p>
|
||||
<p><em>Added in Synapse 1.68.0.</em></p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>resources</code>: Only valid for an 'http' listener. A list of resources to host
|
||||
@ -4059,8 +4086,9 @@ on this homeserver.</p>
|
||||
<p>Options related to caching.</p>
|
||||
<hr />
|
||||
<h3 id="event_cache_size"><a class="header" href="#event_cache_size"><code>event_cache_size</code></a></h3>
|
||||
<p>The number of events to cache in memory. Not affected by
|
||||
<code>caches.global_factor</code> and is not part of the <code>caches</code> section. Defaults to 10K.</p>
|
||||
<p>The number of events to cache in memory. Defaults to 10K. Like other caches,
|
||||
this is affected by <code>caches.global_factor</code> (see below).</p>
|
||||
<p>Note that this option is not part of the <code>caches</code> section.</p>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">event_cache_size: 15K
|
||||
</code></pre>
|
||||
@ -4365,7 +4393,7 @@ client is attempting to log into. Defaults to <code>per_second: 0.17</code>,
|
||||
<code>burst_count: 3</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>failted_attempts</code> ratelimits login requests based on the account the
|
||||
<p><code>failed_attempts</code> ratelimits login requests based on the account the
|
||||
client is attempting to log into, based on the amount of failed login
|
||||
attempts for this account. Defaults to <code>per_second: 0.17</code>, <code>burst_count: 3</code>.</p>
|
||||
</li>
|
||||
@ -11583,6 +11611,133 @@ If the room does not define a type, the value will be <code>null</code>.</li>
|
||||
]
|
||||
}
|
||||
</code></pre>
|
||||
<h1 id="room-messages-api"><a class="header" href="#room-messages-api">Room Messages API</a></h1>
|
||||
<p>The Room Messages admin API allows server admins to get all messages
|
||||
sent to a room in a given timeframe. There are various parameters available
|
||||
that allow for filtering and ordering the returned list. This API supports pagination.</p>
|
||||
<p>To use it, you will need to authenticate by providing an <code>access_token</code>
|
||||
for a server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p>
|
||||
<p>This endpoint mirrors the <a href="https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages">Matrix Spec defined Messages API</a>.</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/rooms/<room_id>/messages
|
||||
</code></pre>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following path parameters are required:</p>
|
||||
<ul>
|
||||
<li><code>room_id</code> - The ID of the room you wish you fetch messages from.</li>
|
||||
</ul>
|
||||
<p>The following query parameters are available:</p>
|
||||
<ul>
|
||||
<li><code>from</code> (required) - The token to start returning events from. This token can be obtained from a prev_batch
|
||||
or next_batch token returned by the /sync endpoint, or from an end token returned by a previous request to this endpoint.</li>
|
||||
<li><code>to</code> - The token to spot returning events at.</li>
|
||||
<li><code>limit</code> - The maximum number of events to return. Defaults to <code>10</code>.</li>
|
||||
<li><code>filter</code> - A JSON RoomEventFilter to filter returned events with.</li>
|
||||
<li><code>dir</code> - The direction to return events from. Either <code>f</code> for forwards or <code>b</code> for backwards. Setting
|
||||
this value to <code>b</code> will reverse the above sort order. Defaults to <code>f</code>.</li>
|
||||
</ul>
|
||||
<p><strong>Response</strong></p>
|
||||
<p>The following fields are possible in the JSON response body:</p>
|
||||
<ul>
|
||||
<li><code>chunk</code> - A list of room events. The order depends on the dir parameter.
|
||||
Note that an empty chunk does not necessarily imply that no more events are available. Clients should continue to paginate until no end property is returned.</li>
|
||||
<li><code>end</code> - A token corresponding to the end of chunk. This token can be passed back to this endpoint to request further events.
|
||||
If no further events are available, this property is omitted from the response.</li>
|
||||
<li><code>start</code> - A token corresponding to the start of chunk.</li>
|
||||
<li><code>state</code> - A list of state events relevant to showing the chunk.</li>
|
||||
</ul>
|
||||
<p><strong>Example</strong></p>
|
||||
<p>For more details on each chunk, read <a href="https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages">the Matrix specification</a>.</p>
|
||||
<pre><code class="language-json">{
|
||||
"chunk": [
|
||||
{
|
||||
"content": {
|
||||
"body": "This is an example text message",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<b>This is an example text message</b>",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234
|
||||
}
|
||||
},
|
||||
{
|
||||
"content": {
|
||||
"name": "The room name"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "",
|
||||
"type": "m.room.name",
|
||||
"unsigned": {
|
||||
"age": 1234
|
||||
}
|
||||
},
|
||||
{
|
||||
"content": {
|
||||
"body": "Gangnam Style",
|
||||
"info": {
|
||||
"duration": 2140786,
|
||||
"h": 320,
|
||||
"mimetype": "video/mp4",
|
||||
"size": 1563685,
|
||||
"thumbnail_info": {
|
||||
"h": 300,
|
||||
"mimetype": "image/jpeg",
|
||||
"size": 46144,
|
||||
"w": 300
|
||||
},
|
||||
"thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
|
||||
"w": 480
|
||||
},
|
||||
"msgtype": "m.video",
|
||||
"url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!636q39766251:example.com",
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234
|
||||
}
|
||||
}
|
||||
],
|
||||
"end": "t47409-4357353_219380_26003_2265",
|
||||
"start": "t47429-4392820_219380_26003_2265"
|
||||
}
|
||||
</code></pre>
|
||||
<h1 id="room-timestamp-to-event-api"><a class="header" href="#room-timestamp-to-event-api">Room Timestamp to Event API</a></h1>
|
||||
<p>The Room Timestamp to Event API endpoint fetches the <code>event_id</code> of the closest event to the given
|
||||
timestamp (<code>ts</code> query parameter) in the given direction (<code>dir</code> query parameter).</p>
|
||||
<p>Useful for cases like jump to date so you can start paginating messages from
|
||||
a given date in the archive.</p>
|
||||
<p>The API is:</p>
|
||||
<pre><code> GET /_synapse/admin/v1/rooms/<room_id>/timestamp_to_event
|
||||
</code></pre>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following path parameters are required:</p>
|
||||
<ul>
|
||||
<li><code>room_id</code> - The ID of the room you wish to check.</li>
|
||||
</ul>
|
||||
<p>The following query parameters are available:</p>
|
||||
<ul>
|
||||
<li><code>ts</code> - a timestamp in milliseconds where we will find the closest event in
|
||||
the given direction.</li>
|
||||
<li><code>dir</code> - can be <code>f</code> or <code>b</code> to indicate forwards and backwards in time from the
|
||||
given timestamp. Defaults to <code>f</code>.</li>
|
||||
</ul>
|
||||
<p><strong>Response</strong></p>
|
||||
<ul>
|
||||
<li><code>event_id</code> - converted from timestamp</li>
|
||||
</ul>
|
||||
<h1 id="block-room-api"><a class="header" href="#block-room-api">Block Room API</a></h1>
|
||||
<p>The Block Room admin API allows server admins to block and unblock rooms,
|
||||
and query to see if a given room is blocked.
|
||||
@ -12193,6 +12348,7 @@ for a server admin: see <a href="admin_api/../usage/administration/admin_api">Ad
|
||||
"appservice_id": null,
|
||||
"consent_server_notice_sent": null,
|
||||
"consent_version": null,
|
||||
"consent_ts": null,
|
||||
"external_ids": [
|
||||
{
|
||||
"auth_provider": "<provider1>",
|
||||
@ -12500,6 +12656,7 @@ is set to <code>true</code>:</p>
|
||||
<li>Remove the user's creation (registration) timestamp</li>
|
||||
<li><a href="admin_api/user_admin_api.html#override-ratelimiting-for-users">Remove rate limit overrides</a></li>
|
||||
<li>Remove from monthly active users</li>
|
||||
<li>Remove user's consent information (consent version and timestamp)</li>
|
||||
</ul>
|
||||
<h2 id="reset-password"><a class="header" href="#reset-password">Reset password</a></h2>
|
||||
<p>Changes the password of another user. This will automatically log the user out of all their devices.</p>
|
||||
@ -13148,6 +13305,30 @@ for more information.</p>
|
||||
</code></pre>
|
||||
<p>The request and response format is the same as the
|
||||
<a href="https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available">/_matrix/client/r0/register/available</a> API.</p>
|
||||
<h3 id="find-a-user-based-on-their-id-in-an-auth-provider"><a class="header" href="#find-a-user-based-on-their-id-in-an-auth-provider">Find a user based on their ID in an auth provider</a></h3>
|
||||
<p>The API is:</p>
|
||||
<pre><code>GET /_synapse/admin/v1/auth_providers/$provider/users/$external_id
|
||||
</code></pre>
|
||||
<p>When a user matched the given ID for the given provider, an HTTP code <code>200</code> with a response body like the following is returned:</p>
|
||||
<pre><code class="language-json">{
|
||||
"user_id": "@hello:example.org"
|
||||
}
|
||||
</code></pre>
|
||||
<p><strong>Parameters</strong></p>
|
||||
<p>The following parameters should be set in the URL:</p>
|
||||
<ul>
|
||||
<li><code>provider</code> - The ID of the authentication provider, as advertised by the <a href="https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login"><code>GET /_matrix/client/v3/login</code></a> API in the <code>m.login.sso</code> authentication method.</li>
|
||||
<li><code>external_id</code> - The user ID from the authentication provider. Usually corresponds to the <code>sub</code> claim for OIDC providers, or to the <code>uid</code> attestation for SAML2 providers.</li>
|
||||
</ul>
|
||||
<p>The <code>external_id</code> may have characters that are not URL-safe (typically <code>/</code>, <code>:</code> or <code>@</code>), so it is advised to URL-encode those parameters.</p>
|
||||
<p><strong>Errors</strong></p>
|
||||
<p>Returns a <code>404</code> HTTP status code if no user was found, with a response body like this:</p>
|
||||
<pre><code class="language-json">{
|
||||
"errcode":"M_NOT_FOUND",
|
||||
"error":"User not found"
|
||||
}
|
||||
</code></pre>
|
||||
<p><em>Added in Synapse 1.68.0.</em></p>
|
||||
<div style="break-before: page; page-break-before: always;"></div><h1 id="version-api"><a class="header" href="#version-api">Version API</a></h1>
|
||||
<p>This API returns the running Synapse version and the Python version
|
||||
on which Synapse is being run. This is useful when a Synapse instance
|
||||
@ -14037,14 +14218,14 @@ WHERE room_stats_state.room_id = event_json.room_id" | psql -d synapse -h l
|
||||
-AAAAAAAAAAAAAAAAAAAAA- -BBBBBBBBBBBBBBBBBBBBBB- -C- -DD- -EEEEEE- -FFFFFFFFF- -GG- -HHHHHHHHHHHHHHHHHHHHHHH- -IIIIII- -JJJJJJJ- -KKKKKK-, -LLLLLL- -MMMMMMM- -NNNNNN- O -P- -QQ- -RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR- -SSSSSSSSSSSS- -TTTTTT-
|
||||
</code></pre>
|
||||
<table><thead><tr><th>Part</th><th>Explanation</th></tr></thead><tbody>
|
||||
<tr><td>AAAA</td><td>Timestamp request was logged (not recieved)</td></tr>
|
||||
<tr><td>AAAA</td><td>Timestamp request was logged (not received)</td></tr>
|
||||
<tr><td>BBBB</td><td>Logger name (<code>synapse.access.(http\|https).<tag></code>, where 'tag' is defined in the <code>listeners</code> config section, normally the port)</td></tr>
|
||||
<tr><td>CCCC</td><td>Line number in code</td></tr>
|
||||
<tr><td>DDDD</td><td>Log Level</td></tr>
|
||||
<tr><td>EEEE</td><td>Request Identifier (This identifier is shared by related log lines)</td></tr>
|
||||
<tr><td>FFFF</td><td>Source IP (Or X-Forwarded-For if enabled)</td></tr>
|
||||
<tr><td>GGGG</td><td>Server Port</td></tr>
|
||||
<tr><td>HHHH</td><td>Federated Server or Local User making request (blank if unauthenticated or not supplied)</td></tr>
|
||||
<tr><td>HHHH</td><td>Federated Server or Local User making request (blank if unauthenticated or not supplied).<br/>If this is of the form `@aaa:example.com</td></tr>
|
||||
<tr><td>IIII</td><td>Total Time to process the request</td></tr>
|
||||
<tr><td>JJJJ</td><td>Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)</td></tr>
|
||||
<tr><td>KKKK</td><td>Userland CPU time</td></tr>
|
||||
@ -14208,6 +14389,8 @@ on Windows is not officially supported.</p>
|
||||
<p>Synapse can connect to PostgreSQL via the <a href="https://pypi.org/project/psycopg2/">psycopg2</a> Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with <code>sudo apt install libpq-dev</code>.</p>
|
||||
<p>The source code of Synapse is hosted on GitHub. You will also need <a href="https://github.com/git-guides/install-git">a recent version of git</a>.</p>
|
||||
<p>For some tests, you will need <a href="https://docs.docker.com/get-docker/">a recent version of Docker</a>.</p>
|
||||
<p>A recent version of the Rust compiler is needed to build the native modules. The
|
||||
easiest way of installing the latest version is to use <a href="https://rustup.rs/">rustup</a>.</p>
|
||||
<h1 id="3-get-the-source"><a class="header" href="#3-get-the-source">3. Get the source.</a></h1>
|
||||
<p>The preferred and easiest way to contribute changes is to fork the relevant
|
||||
project on GitHub, and then <a href="https://help.github.com/articles/using-pull-requests/">create a pull request</a> to ask us to pull your
|
||||
@ -14264,6 +14447,10 @@ to check that your contributions render correctly. The docs are written in
|
||||
<p>Some documentation also exists in <a href="https://github.com/matrix-org/synapse/wiki">Synapse's GitHub
|
||||
Wiki</a>, although this is primarily
|
||||
contributed to by community authors.</p>
|
||||
<p>When changes are made to any Rust code then you must call either <code>poetry install</code>
|
||||
or <code>maturin develop</code> (if installed) to rebuild the Rust code. Using <a href="https://github.com/PyO3/maturin"><code>maturin</code></a>
|
||||
is quicker than <code>poetry install</code>, so is recommended when making frequent
|
||||
changes to the Rust code.</p>
|
||||
<h1 id="8-test-test-test"><a class="header" href="#8-test-test-test">8. Test, test, test!</a></h1>
|
||||
<p><a name="test-test-test"></a></p>
|
||||
<p>While you're developing and before submitting a patch, you'll
|
||||
@ -14312,7 +14499,7 @@ working directory. Typically, this ends up being <code>_trial_temp/test.db</code
|
||||
<p>The database file can then be inspected with:</p>
|
||||
<pre><code class="language-sh">sqlite3 _trial_temp/test.db
|
||||
</code></pre>
|
||||
<p>Note that the database file is cleared at the beginning of each test run. Thus it
|
||||
<p>Note that the database file is cleared at the beginning of each test run. Thus it
|
||||
will always only contain the data generated by the <em>last run test</em>. Though generally
|
||||
when debugging, one is only running a single test anyway.</p>
|
||||
<h3 id="running-tests-under-postgresql"><a class="header" href="#running-tests-under-postgresql">Running tests under PostgreSQL</a></h3>
|
||||
@ -15319,6 +15506,20 @@ context of poetry's venv, without having to run <code>poetry shell</code> before
|
||||
<h2 id="reset-my-venv-to-the-locked-environment"><a class="header" href="#reset-my-venv-to-the-locked-environment">...reset my venv to the locked environment?</a></h2>
|
||||
<pre><code class="language-shell">poetry install --extras all --remove-untracked
|
||||
</code></pre>
|
||||
<h2 id="delete-everything-and-start-over-from-scratch"><a class="header" href="#delete-everything-and-start-over-from-scratch">...delete everything and start over from scratch?</a></h2>
|
||||
<pre><code class="language-shell"># Stop the current virtualenv if active
|
||||
$ deactivate
|
||||
|
||||
# Remove all of the files from the current environment.
|
||||
# Don't worry, even though it says "all", this will only
|
||||
# remove the Poetry virtualenvs for the current project.
|
||||
$ poetry env remove --all
|
||||
|
||||
# Reactivate Poetry shell to create the virtualenv again
|
||||
$ poetry shell
|
||||
# Install everything again
|
||||
$ poetry install --extras all
|
||||
</code></pre>
|
||||
<h2 id="run-a-command-in-the-poetry-virtualenv"><a class="header" href="#run-a-command-in-the-poetry-virtualenv">...run a command in the <code>poetry</code> virtualenv?</a></h2>
|
||||
<p>Use <code>poetry run cmd args</code> when you need the python virtualenv context.
|
||||
To avoid typing <code>poetry run</code> all the time, you can run <code>poetry shell</code>
|
||||
@ -15407,6 +15608,11 @@ installed <code>poetry</code> with <code>pipx</code>, try <code>pipx runpip poet
|
||||
<p>Poetry caches a bunch of information about packages that isn't readily available
|
||||
from PyPI. (This is what makes poetry seem slow when doing the first
|
||||
<code>poetry install</code>.) Try <code>poetry cache list</code> and <code>poetry cache clear --all <name of cache></code> to see if that fixes things.</p>
|
||||
<h2 id="remove-outdated-egg-info"><a class="header" href="#remove-outdated-egg-info">Remove outdated egg-info</a></h2>
|
||||
<p>Delete the <code>matrix_synapse.egg-info/</code> directory from the root of your Synapse
|
||||
install.</p>
|
||||
<p>This stores some cached information about dependencies and often conflicts with
|
||||
letting Poetry do the right thing.</p>
|
||||
<h2 id="try---verbose-or---dry-run-arguments"><a class="header" href="#try---verbose-or---dry-run-arguments">Try <code>--verbose</code> or <code>--dry-run</code> arguments.</a></h2>
|
||||
<p>Sometimes useful to see what poetry's internal logic is.</p>
|
||||
<div style="break-before: page; page-break-before: always;"></div><h1 id="cancellation"><a class="header" href="#cancellation">Cancellation</a></h1>
|
||||
@ -16674,9 +16880,9 @@ table. Each subject can have only one.</li>
|
||||
<p>Stats correspond to the present values. Current rows contain the most up-to-date
|
||||
statistics for a room. Each subject can only have one entry.</p>
|
||||
<div style="break-before: page; page-break-before: always;"></div><h1 id="deprecation-policy-for-platform-dependencies"><a class="header" href="#deprecation-policy-for-platform-dependencies">Deprecation Policy for Platform Dependencies</a></h1>
|
||||
<p>Synapse has a number of platform dependencies, including Python and PostgreSQL.
|
||||
This document outlines the policy towards which versions we support, and when we
|
||||
drop support for versions in the future.</p>
|
||||
<p>Synapse has a number of platform dependencies, including Python, Rust,
|
||||
PostgreSQL and SQLite. This document outlines the policy towards which versions
|
||||
we support, and when we drop support for versions in the future.</p>
|
||||
<h2 id="policy"><a class="header" href="#policy">Policy</a></h2>
|
||||
<p>Synapse follows the upstream support life cycles for Python and PostgreSQL,
|
||||
i.e. when a version reaches End of Life Synapse will withdraw support for that
|
||||
@ -16684,6 +16890,13 @@ version in future releases.</p>
|
||||
<p>Details on the upstream support life cycles for Python and PostgreSQL are
|
||||
documented at <a href="https://endoflife.date/python">https://endoflife.date/python</a> and
|
||||
<a href="https://endoflife.date/postgresql">https://endoflife.date/postgresql</a>.</p>
|
||||
<p>A Rust compiler is required to build Synapse from source. For any given release
|
||||
the minimum required version may be bumped up to a recent Rust version, and so
|
||||
people building from source should ensure they can fetch recent versions of Rust
|
||||
(e.g. by using <a href="https://rustup.rs/">rustup</a>).</p>
|
||||
<p>The oldest supported version of SQLite is the version
|
||||
<a href="https://packages.debian.org/buster/libsqlite3-0">provided</a> by
|
||||
<a href="https://wiki.debian.org/DebianOldStable">Debian oldstable</a>.</p>
|
||||
<h2 id="context"><a class="header" href="#context">Context</a></h2>
|
||||
<p>It is important for system admins to have a clear understanding of the platform
|
||||
requirements of Synapse and its deprecation policies so that they can
|
||||
@ -16694,6 +16907,16 @@ long process.</p>
|
||||
<p>By following the upstream support life cycles Synapse can ensure that its
|
||||
dependencies continue to get security patches, while not requiring system admins
|
||||
to constantly update their platform dependencies to the latest versions.</p>
|
||||
<p>For Rust, the situation is a bit different given that a) the Rust foundation
|
||||
does not generally support older Rust versions, and b) the library ecosystem
|
||||
generally bump their minimum support Rust versions frequently. In general, the
|
||||
Synapse team will try to avoid updating the dependency on Rust to the absolute
|
||||
latest version, but introducing a formal policy is hard given the constraints of
|
||||
the ecosystem.</p>
|
||||
<p>On a similar note, SQLite does not generally have a concept of "supported
|
||||
release"; bugfixes are published for the latest minor release only. We chose to
|
||||
track Debian's oldstable as this is relatively conservative, predictably updated
|
||||
and is consistent with the <code>.deb</code> packages released by Matrix.org.</p>
|
||||
<div style="break-before: page; page-break-before: always;"></div><h2 id="summary-of-performance-impact-of-running-on-resource-constrained-devices-such-as-sbcs"><a class="header" href="#summary-of-performance-impact-of-running-on-resource-constrained-devices-such-as-sbcs">Summary of performance impact of running on resource constrained devices such as SBCs</a></h2>
|
||||
<p>I've been running my homeserver on a cubietruck at home now for some time and am often replying to statements like "you need loads of ram to join large rooms" with "it works fine for me". I thought it might be useful to curate a summary of the issues you're likely to run into to help as a scaling-down guide, maybe highlight these for development work or end up as documentation. It seems that once you get up to about 4x1.5GHz arm64 4GiB these issues are no longer a problem.</p>
|
||||
<ul>
|
||||
|
||||
@ -183,6 +183,10 @@ consider setting <code>bind_addresses: ['127.0.0.1']</code> so that the server o
|
||||
listens to traffic on localhost. (Do not change <code>bind_addresses</code> to <code>127.0.0.1</code>
|
||||
when using a containerized Synapse, as that will prevent it from responding
|
||||
to proxied traffic.)</p>
|
||||
<p>Optionally, you can also set
|
||||
<a href="../usage/configuration/config_documentation.html#listeners"><code>request_id_header</code></a>
|
||||
so that the server extracts and re-uses the same request ID format that the
|
||||
reverse proxy is using.</p>
|
||||
<h2 id="reverse-proxy-configuration-examples"><a class="header" href="#reverse-proxy-configuration-examples">Reverse-proxy configuration examples</a></h2>
|
||||
<p><strong>NOTE</strong>: You only need one of these.</p>
|
||||
<h3 id="nginx"><a class="header" href="#nginx">nginx</a></h3>
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -277,6 +277,9 @@ and mounting it to <code>/var/synapse</code> should be taken into consideration.
|
||||
<li>Python 3.7 or later, up to Python 3.10.</li>
|
||||
<li>At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org</li>
|
||||
</ul>
|
||||
<p>If building on an uncommon architecture for which pre-built wheels are
|
||||
unavailable, you will need to have a recent Rust compiler installed. The easiest
|
||||
way of installing the latest version is to use <a href="https://rustup.rs/">rustup</a>.</p>
|
||||
<p>To install the Synapse homeserver run:</p>
|
||||
<pre><code class="language-sh">mkdir -p ~/synapse
|
||||
virtualenv -p python3 ~/synapse/env
|
||||
@ -347,8 +350,9 @@ sudo dnf groupinstall "Development Tools"
|
||||
<p>You may need to install the latest Xcode developer tools:</p>
|
||||
<pre><code class="language-sh">xcode-select --install
|
||||
</code></pre>
|
||||
<p>On ARM-based Macs you may need to explicitly install libjpeg which is a pillow dependency. You can use Homebrew (https://brew.sh):</p>
|
||||
<pre><code class="language-sh"> brew install jpeg
|
||||
<p>On ARM-based Macs you may need to install libjpeg and libpq.
|
||||
You can use Homebrew (https://brew.sh):</p>
|
||||
<pre><code class="language-sh"> brew install jpeg libpq
|
||||
</code></pre>
|
||||
<p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
|
||||
via brew and inform <code>pip</code> about it so that <code>psycopg2</code> builds:</p>
|
||||
|
||||
@ -162,9 +162,8 @@ which are no longer maintained.</p>
|
||||
summaries.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>If Synapse was installed using <a href="setup/installation.html#prebuilt-packages">prebuilt
|
||||
packages</a>, you will need to follow the
|
||||
normal process for upgrading those packages.</p>
|
||||
<p>If Synapse was installed using <a href="setup/installation.html#prebuilt-packages">prebuilt packages</a>,
|
||||
you will need to follow the normal process for upgrading those packages.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>If Synapse was installed using pip then upgrade to the latest
|
||||
@ -232,6 +231,17 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
|
||||
</code></pre>
|
||||
</li>
|
||||
</ul>
|
||||
<h1 id="upgrading-to-v1680"><a class="header" href="#upgrading-to-v1680">Upgrading to v1.68.0</a></h1>
|
||||
<p>As announced in the upgrade notes for v1.67.0, Synapse now requires a SQLite
|
||||
version of 3.27.0 or higher if SQLite is in use and source checkouts of Synapse
|
||||
now require a recent Rust compiler.</p>
|
||||
<p>Installations using </p>
|
||||
<ul>
|
||||
<li>Docker images <a href="https://hub.docker.com/r/matrixdotorg/synapse">from <code>matrixdotorg</code></a>,</li>
|
||||
<li>Debian packages <a href="https://packages.matrix.org/">from Matrix.org</a>, or</li>
|
||||
<li>PyPI wheels via <code>pip install matrix-synapse</code> (on supported platforms and architectures)</li>
|
||||
</ul>
|
||||
<p>will not be affected.</p>
|
||||
<h1 id="upgrading-to-v1670"><a class="header" href="#upgrading-to-v1670">Upgrading to v1.67.0</a></h1>
|
||||
<h2 id="direct-tcp-replication-is-no-longer-supported-migrate-to-redis"><a class="header" href="#direct-tcp-replication-is-no-longer-supported-migrate-to-redis">Direct TCP replication is no longer supported: migrate to Redis</a></h2>
|
||||
<p>Redis support was added in v1.13.0 with it becoming the recommended method in
|
||||
@ -257,7 +267,7 @@ will require a recent Rust compiler. Those using packages or
|
||||
<p>From the next major release (v1.68.0) Synapse will require SQLite 3.27.0 or
|
||||
higher. Synapse v1.67.0 will be the last major release supporting SQLite
|
||||
versions 3.22 to 3.26.</p>
|
||||
<p>Those using docker images or Debian packages from Matrix.org will not be
|
||||
<p>Those using Docker images or Debian packages from Matrix.org will not be
|
||||
affected. If you have installed from source, you should check the version of
|
||||
SQLite used by Python with:</p>
|
||||
<pre><code class="language-shell">python -c "import sqlite3; print(sqlite3.sqlite_version)"
|
||||
|
||||
@ -153,14 +153,14 @@
|
||||
-AAAAAAAAAAAAAAAAAAAAA- -BBBBBBBBBBBBBBBBBBBBBB- -C- -DD- -EEEEEE- -FFFFFFFFF- -GG- -HHHHHHHHHHHHHHHHHHHHHHH- -IIIIII- -JJJJJJJ- -KKKKKK-, -LLLLLL- -MMMMMMM- -NNNNNN- O -P- -QQ- -RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR- -SSSSSSSSSSSS- -TTTTTT-
|
||||
</code></pre>
|
||||
<table><thead><tr><th>Part</th><th>Explanation</th></tr></thead><tbody>
|
||||
<tr><td>AAAA</td><td>Timestamp request was logged (not recieved)</td></tr>
|
||||
<tr><td>AAAA</td><td>Timestamp request was logged (not received)</td></tr>
|
||||
<tr><td>BBBB</td><td>Logger name (<code>synapse.access.(http\|https).<tag></code>, where 'tag' is defined in the <code>listeners</code> config section, normally the port)</td></tr>
|
||||
<tr><td>CCCC</td><td>Line number in code</td></tr>
|
||||
<tr><td>DDDD</td><td>Log Level</td></tr>
|
||||
<tr><td>EEEE</td><td>Request Identifier (This identifier is shared by related log lines)</td></tr>
|
||||
<tr><td>FFFF</td><td>Source IP (Or X-Forwarded-For if enabled)</td></tr>
|
||||
<tr><td>GGGG</td><td>Server Port</td></tr>
|
||||
<tr><td>HHHH</td><td>Federated Server or Local User making request (blank if unauthenticated or not supplied)</td></tr>
|
||||
<tr><td>HHHH</td><td>Federated Server or Local User making request (blank if unauthenticated or not supplied).<br/>If this is of the form `@aaa:example.com</td></tr>
|
||||
<tr><td>IIII</td><td>Total Time to process the request</td></tr>
|
||||
<tr><td>JJJJ</td><td>Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)</td></tr>
|
||||
<tr><td>KKKK</td><td>Userland CPU time</td></tr>
|
||||
|
||||
@ -488,7 +488,16 @@ configuration.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>x_forwarded</code>: Only valid for an 'http' listener. Set to true to use the X-Forwarded-For header as the client IP. Useful when Synapse is
|
||||
behind a reverse-proxy.</p>
|
||||
behind a <a href="../../reverse_proxy.html">reverse-proxy</a>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>request_id_header</code>: The header extracted from each incoming request that is
|
||||
used as the basis for the request ID. The request ID is used in
|
||||
<a href="../administration/request_log.html#request-log-format">logs</a> and tracing to
|
||||
correlate and match up requests. When unset, Synapse will automatically
|
||||
generate sequential request IDs. This option is useful when Synapse is behind
|
||||
a <a href="../../reverse_proxy.html">reverse-proxy</a>.</p>
|
||||
<p><em>Added in Synapse 1.68.0.</em></p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>resources</code>: Only valid for an 'http' listener. A list of resources to host
|
||||
@ -1008,8 +1017,9 @@ on this homeserver.</p>
|
||||
<p>Options related to caching.</p>
|
||||
<hr />
|
||||
<h3 id="event_cache_size"><a class="header" href="#event_cache_size"><code>event_cache_size</code></a></h3>
|
||||
<p>The number of events to cache in memory. Not affected by
|
||||
<code>caches.global_factor</code> and is not part of the <code>caches</code> section. Defaults to 10K.</p>
|
||||
<p>The number of events to cache in memory. Defaults to 10K. Like other caches,
|
||||
this is affected by <code>caches.global_factor</code> (see below).</p>
|
||||
<p>Note that this option is not part of the <code>caches</code> section.</p>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">event_cache_size: 15K
|
||||
</code></pre>
|
||||
@ -1314,7 +1324,7 @@ client is attempting to log into. Defaults to <code>per_second: 0.17</code>,
|
||||
<code>burst_count: 3</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>failted_attempts</code> ratelimits login requests based on the account the
|
||||
<p><code>failed_attempts</code> ratelimits login requests based on the account the
|
||||
client is attempting to log into, based on the amount of failed login
|
||||
attempts for this account. Defaults to <code>per_second: 0.17</code>, <code>burst_count: 3</code>.</p>
|
||||
</li>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user