mirrors/synapse
1
0
Fork 0
mirror of https://github.com/element-hq/synapse.git synced 2024-11-22 09:35:45 +03:00
Code Issues Projects Releases Packages Wiki Activity

deploy: 774e20b570

Browse source
This commit is contained in:
squahtx 2022-12-20 18:10:08 +00:00
parent 3606b75acc
commit 39861031ee
12 changed files with 320 additions and 128 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
latest/development/contributing_guide.html
View file

@ -164,6 +164,7 @@ recommended for development. More information about WSL can be found at
on Windows is not officially supported.</p> on Windows is not officially supported.</p>
<p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <a href="https://www.python.org/downloads/">a recent version of Python 3</a>. Your Python also needs support for <a href="https://docs.python.org/3/library/venv.html">virtual environments</a>. This is usually built-in, but some Linux distributions like Debian and Ubuntu split it out into its own package. Running <code>sudo apt install python3-venv</code> should be enough.</p> <p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <a href="https://www.python.org/downloads/">a recent version of Python 3</a>. Your Python also needs support for <a href="https://docs.python.org/3/library/venv.html">virtual environments</a>. This is usually built-in, but some Linux distributions like Debian and Ubuntu split it out into its own package. Running <code>sudo apt install python3-venv</code> should be enough.</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>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>Synapse has an optional, improved user search with better Unicode support. For that you need the development package of <code>libicu</code>. On Debian or Ubuntu Linux, this can be installed with <code>sudo apt install libicu-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>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>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 <p>A recent version of the Rust compiler is needed to build the native modules. The

31
latest/openid.html
View file

@ -676,6 +676,37 @@ needed to add OAuth2 capabilities to your Django projects. It supports
display_name_template: &quot;{{ user.first_name }} {{ user.last_name }}&quot; display_name_template: &quot;{{ user.first_name }} {{ user.last_name }}&quot;
email_template: &quot;{{ user.email }}&quot; email_template: &quot;{{ user.email }}&quot;
</code></pre> </code></pre>
<h3 id="mastodon"><a class="header" href="#mastodon">Mastodon</a></h3>
<p><a href="https://docs.joinmastodon.org/">Mastodon</a> instances provide an <a href="https://docs.joinmastodon.org/spec/oauth/">OAuth API</a>, allowing those instances to be used as a single sign-on provider for Synapse.</p>
<p>The first step is to register Synapse as an application with your Mastodon instance, using the <a href="https://docs.joinmastodon.org/methods/apps/#create">Create an application API</a> (see also <a href="https://docs.joinmastodon.org/client/token/">here</a>). There are several ways to do this, but in the example below we are using CURL.</p>
<p>This example assumes that:</p>
<ul>
<li>the Mastodon instance website URL is <code>https://your.mastodon.instance.url</code>, and</li>
<li>Synapse will be registered as an app named <code>my_synapse_app</code>.</li>
</ul>
<p>Send the following request, substituting the value of <code>synapse_public_baseurl</code> from your Synapse installation.</p>
<pre><code class="language-sh">curl -d &quot;client_name=my_synapse_app&amp;redirect_uris=https://[synapse_public_baseurl]/_synapse/client/oidc/callback&quot; -X POST https://your.mastodon.instance.url/api/v1/apps
</code></pre>
<p>You should receive a response similar to the following. Make sure to save it.</p>
<pre><code class="language-json">{&quot;client_id&quot;:&quot;someclientid_123&quot;,&quot;client_secret&quot;:&quot;someclientsecret_123&quot;,&quot;id&quot;:&quot;12345&quot;,&quot;name&quot;:&quot;my_synapse_app&quot;,&quot;redirect_uri&quot;:&quot;https://[synapse_public_baseurl]/_synapse/client/oidc/callback&quot;,&quot;website&quot;:null,&quot;vapid_key&quot;:&quot;somerandomvapidkey_123&quot;}
</code></pre>
<p>As the Synapse login mechanism needs an attribute to uniquely identify users, and Mastodon's endpoint does not return a <code>sub</code> property, an alternative <code>subject_claim</code> has to be set. Your Synapse configuration should include the following:</p>
<pre><code class="language-yaml">oidc_providers:
- idp_id: my_mastodon
idp_name: &quot;Mastodon Instance Example&quot;
discover: false
issuer: &quot;https://your.mastodon.instance.url/@admin&quot;
client_id: &quot;someclientid_123&quot;
client_secret: &quot;someclientsecret_123&quot;
authorization_endpoint: &quot;https://your.mastodon.instance.url/oauth/authorize&quot;
token_endpoint: &quot;https://your.mastodon.instance.url/oauth/token&quot;
userinfo_endpoint: &quot;https://your.mastodon.instance.url/api/v1/accounts/verify_credentials&quot;
scopes: [&quot;read&quot;]
user_mapping_provider:
config:
subject_claim: &quot;id&quot;
</code></pre>
<p>Note that the fields <code>client_id</code> and <code>client_secret</code> are taken from the CURL response above.</p>
</main> </main>

3
latest/postgres.html
View file

@ -147,7 +147,8 @@
</div> </div>
<h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1> <h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1>
<p>Synapse supports PostgreSQL versions 10 or later.</p> <p>The minimum supported version of PostgreSQL is determined by the <a href="deprecation_policy.html">Dependency
Deprecation Policy</a>.</p>
<h2 id="install-postgres-client-libraries"><a class="header" href="#install-postgres-client-libraries">Install postgres client libraries</a></h2> <h2 id="install-postgres-client-libraries"><a class="header" href="#install-postgres-client-libraries">Install postgres client libraries</a></h2>
<p>Synapse will require the python postgres client library in order to <p>Synapse will require the python postgres client library in order to
connect to a postgres database.</p> connect to a postgres database.</p>

222
latest/print.html
View file

@ -290,7 +290,9 @@ the main configuration file at <code>/etc/matrix-synapse/homeserver.yaml</code>.
By doing that, you won't be asked if you want to replace your configuration By doing that, you won't be asked if you want to replace your configuration
file when you upgrade the Debian package to a later version.</p> file when you upgrade the Debian package to a later version.</p>
<h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5> <h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5>
<p>Andrej Shadura maintains a <code>matrix-synapse</code> package in the Debian repositories. <p>Andrej Shadura maintains a
<a href="https://packages.debian.org/sid/matrix-synapse"><code>matrix-synapse</code></a> package in
the Debian repositories.
For <code>bookworm</code> and <code>sid</code>, it can be installed simply with:</p> For <code>bookworm</code> and <code>sid</code>, it can be installed simply with:</p>
<pre><code class="language-sh">sudo apt install matrix-synapse <pre><code class="language-sh">sudo apt install matrix-synapse
</code></pre> </code></pre>
@ -300,16 +302,18 @@ for information on how to use backports.</p>
<p><code>matrix-synapse</code> is no longer maintained for <code>buster</code> and older.</p> <p><code>matrix-synapse</code> is no longer maintained for <code>buster</code> and older.</p>
<h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5> <h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5>
<p>We do not recommend using the packages in the default Ubuntu repository <p>We do not recommend using the packages in the default Ubuntu repository
at this time, as they are old and suffer from known security vulnerabilities. at this time, as they are <a href="https://bugs.launchpad.net/ubuntu/+source/matrix-synapse/+bug/1848709">old and suffer from known security vulnerabilities</a>.
The latest version of Synapse can be installed from <a href="setup/installation.html#matrixorg-packages">our repository</a>.</p> The latest version of Synapse can be installed from <a href="setup/installation.html#matrixorg-packages">our repository</a>.</p>
<h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4> <h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4>
<p>Synapse is in the Fedora repositories as <code>matrix-synapse</code>:</p> <p>Synapse is in the Fedora repositories as
<a href="https://src.fedoraproject.org/rpms/matrix-synapse"><code>matrix-synapse</code></a>:</p>
<pre><code class="language-sh">sudo dnf install matrix-synapse <pre><code class="language-sh">sudo dnf install matrix-synapse
</code></pre> </code></pre>
<p>Oleg Girko provides Fedora RPMs at <p>Additionally, Oleg Girko provides Fedora RPMs at
<a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p> <a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p>
<h4 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h4> <h4 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h4>
<p>Synapse is in the OpenSUSE repositories as <code>matrix-synapse</code>:</p> <p>Synapse is in the OpenSUSE repositories as
<a href="https://software.opensuse.org/package/matrix-synapse"><code>matrix-synapse</code></a>:</p>
<pre><code class="language-sh">sudo zypper install matrix-synapse <pre><code class="language-sh">sudo zypper install matrix-synapse
</code></pre> </code></pre>
<h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4> <h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4>
@ -330,7 +334,8 @@ installing under virtualenv):</p>
sudo pip install py-bcrypt sudo pip install py-bcrypt
</code></pre> </code></pre>
<h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4> <h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4>
<p>Synapse can be found in the void repositories as 'synapse':</p> <p>Synapse can be found in the void repositories as
<a href="https://github.com/void-linux/void-packages/tree/master/srcpkgs/synapse">'synapse'</a>:</p>
<pre><code class="language-sh">xbps-install -Su <pre><code class="language-sh">xbps-install -Su
xbps-install -S synapse xbps-install -S synapse
</code></pre> </code></pre>
@ -414,18 +419,19 @@ header files for Python C extensions.</p>
<p>Installing prerequisites on Ubuntu or Debian:</p> <p>Installing prerequisites on Ubuntu or Debian:</p>
<pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \ <pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \
python3-pip python3-setuptools sqlite3 \ python3-pip python3-setuptools sqlite3 \
libssl-dev virtualenv libjpeg-dev libxslt1-dev libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
</code></pre> </code></pre>
<h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5> <h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5>
<p>Installing prerequisites on ArchLinux:</p> <p>Installing prerequisites on ArchLinux:</p>
<pre><code class="language-sh">sudo pacman -S base-devel python python-pip \ <pre><code class="language-sh">sudo pacman -S base-devel python python-pip \
python-setuptools python-virtualenv sqlite3 python-setuptools python-virtualenv sqlite3 icu
</code></pre> </code></pre>
<h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5> <h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5>
<p>Installing prerequisites on CentOS or Fedora Linux:</p> <p>Installing prerequisites on CentOS or Fedora Linux:</p>
<pre><code class="language-sh">sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \ <pre><code class="language-sh">sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
libwebp-devel libxml2-devel libxslt-devel libpq-devel \ libwebp-devel libxml2-devel libxslt-devel libpq-devel \
python3-virtualenv libffi-devel openssl-devel python3-devel python3-virtualenv libffi-devel openssl-devel python3-devel \
libicu-devel
sudo dnf groupinstall &quot;Development Tools&quot; sudo dnf groupinstall &quot;Development Tools&quot;
</code></pre> </code></pre>
<h5 id="macos"><a class="header" href="#macos">macOS</a></h5> <h5 id="macos"><a class="header" href="#macos">macOS</a></h5>
@ -433,8 +439,10 @@ sudo dnf groupinstall &quot;Development Tools&quot;
<p>You may need to install the latest Xcode developer tools:</p> <p>You may need to install the latest Xcode developer tools:</p>
<pre><code class="language-sh">xcode-select --install <pre><code class="language-sh">xcode-select --install
</code></pre> </code></pre>
<p>On ARM-based Macs you may need to install libjpeg and libpq. <p>Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) for them.</p>
You can use Homebrew (https://brew.sh):</p> <p>You may need to install icu, and make the icu binaries and libraries accessible.
Please follow <a href="https://pypi.org/project/PyICU/">the official instructions of PyICU</a> to do so.</p>
<p>On ARM-based Macs you may also need to install libjpeg and libpq:</p>
<pre><code class="language-sh"> brew install jpeg libpq <pre><code class="language-sh"> brew install jpeg libpq
</code></pre> </code></pre>
<p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL <p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
@ -447,7 +455,8 @@ export CPPFLAGS=&quot;-I/usr/local/opt/openssl/include&quot;
<p>Installing prerequisites on openSUSE:</p> <p>Installing prerequisites on openSUSE:</p>
<pre><code class="language-sh">sudo zypper in -t pattern devel_basis <pre><code class="language-sh">sudo zypper in -t pattern devel_basis
sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \ sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
python-devel libffi-devel libopenssl-devel libjpeg62-devel python-devel libffi-devel libopenssl-devel libjpeg62-devel \
libicu-devel
</code></pre> </code></pre>
<h5 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h5> <h5 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h5>
<p>A port of Synapse is available under <code>net/synapse</code>. The filesystem <p>A port of Synapse is available under <code>net/synapse</code>. The filesystem
@ -646,7 +655,8 @@ failing, e.g.:</p>
<p>If you have any other problems, feel free to ask in <p>If you have any other problems, feel free to ask in
<a href="https://matrix.to/#/#synapse:matrix.org">#synapse:matrix.org</a>.</p> <a href="https://matrix.to/#/#synapse:matrix.org">#synapse:matrix.org</a>.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1> <div style="break-before: page; page-break-before: always;"></div><h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1>
<p>Synapse supports PostgreSQL versions 10 or later.</p> <p>The minimum supported version of PostgreSQL is determined by the <a href="deprecation_policy.html">Dependency
Deprecation Policy</a>.</p>
<h2 id="install-postgres-client-libraries"><a class="header" href="#install-postgres-client-libraries">Install postgres client libraries</a></h2> <h2 id="install-postgres-client-libraries"><a class="header" href="#install-postgres-client-libraries">Install postgres client libraries</a></h2>
<p>Synapse will require the python postgres client library in order to <p>Synapse will require the python postgres client library in order to
connect to a postgres database.</p> connect to a postgres database.</p>
@ -1181,7 +1191,7 @@ However, even with appropriate configuration, NAT is known to cause issues and t
<pre><code>turn_uris: [ &quot;turn:turn.matrix.org?transport=udp&quot;, &quot;turn:turn.matrix.org?transport=tcp&quot; ] <pre><code>turn_uris: [ &quot;turn:turn.matrix.org?transport=udp&quot;, &quot;turn:turn.matrix.org?transport=tcp&quot; ]
turn_shared_secret: &quot;n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons&quot; turn_shared_secret: &quot;n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons&quot;
turn_user_lifetime: 86400000 turn_user_lifetime: 86400000
turn_allow_guests: True turn_allow_guests: true
</code></pre> </code></pre>
<p>After updating the homeserver configuration, you must restart synapse:</p> <p>After updating the homeserver configuration, you must restart synapse:</p>
<ul> <ul>
@ -1761,6 +1771,16 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
<h1 id="upgrading-to-v1740"><a class="header" href="#upgrading-to-v1740">Upgrading to v1.74.0</a></h1>
<h2 id="unicode-support-in-user-search"><a class="header" href="#unicode-support-in-user-search">Unicode support in user search</a></h2>
<p>This version introduces optional support for an <a href="https://github.com/matrix-org/synapse/pull/14464">improved user search dealing with Unicode characters</a>.</p>
<p>If you want to take advantage of this feature you need to install PyICU,
the ICU native dependency and its development headers
so that PyICU can build since no prebuilt wheels are available.</p>
<p>You can follow <a href="https://pypi.org/project/PyICU/">the PyICU documentation</a> to do so,
and then do <code>pip install matrix-synapse[icu]</code> for a PyPI install.</p>
<p>Docker images and Debian packages need nothing specific as they already
include or specify ICU as an explicit dependency.</p>
<h1 id="upgrading-to-v1730"><a class="header" href="#upgrading-to-v1730">Upgrading to v1.73.0</a></h1> <h1 id="upgrading-to-v1730"><a class="header" href="#upgrading-to-v1730">Upgrading to v1.73.0</a></h1>
<h2 id="legacy-prometheus-metric-names-have-now-been-removed"><a class="header" href="#legacy-prometheus-metric-names-have-now-been-removed">Legacy Prometheus metric names have now been removed</a></h2> <h2 id="legacy-prometheus-metric-names-have-now-been-removed"><a class="header" href="#legacy-prometheus-metric-names-have-now-been-removed">Legacy Prometheus metric names have now been removed</a></h2>
<p>Synapse v1.69.0 included the deprecation of legacy Prometheus metric names <p>Synapse v1.69.0 included the deprecation of legacy Prometheus metric names
@ -4159,7 +4179,7 @@ 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. Please be advised <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 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 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 is less risky than deleting newer history but in general caution is advised when enabling this
@ -5477,33 +5497,56 @@ Defaults to https://matrix.org/report-usage-stats/push</p>
<p>Config settings related to the client/server API</p> <p>Config settings related to the client/server API</p>
<hr /> <hr />
<h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state</code></a></h3> <h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state</code></a></h3>
<p>Controls for the state that is shared with users who receive an invite <p>This setting controls the state that is shared with users upon receiving an
to a room. By default, the following state event types are shared with users who invite to a room, or in reply to a knock on a room. By default, the following
receive invites to the room:</p> state events are shared with users:</p>
<ul> <ul>
<li>m.room.join_rules</li> <li><code>m.room.join_rules</code></li>
<li>m.room.canonical_alias</li> <li><code>m.room.canonical_alias</code></li>
<li>m.room.avatar</li> <li><code>m.room.avatar</code></li>
<li>m.room.encryption</li> <li><code>m.room.encryption</code></li>
<li>m.room.name</li> <li><code>m.room.name</code></li>
<li>m.room.create</li> <li><code>m.room.create</code></li>
<li>m.room.topic</li> <li><code>m.room.topic</code></li>
</ul> </ul>
<p>To change the default behavior, use the following sub-options:</p> <p>To change the default behavior, use the following sub-options:</p>
<ul> <ul>
<li><code>disable_default_event_types</code>: set to true to disable the above defaults. If this <li>
is enabled, only the event types listed in <code>additional_event_types</code> are shared. <p><code>disable_default_event_types</code>: boolean. Set to <code>true</code> to disable the above
Defaults to false.</li> defaults. If this is enabled, only the event types listed in
<li><code>additional_event_types</code>: Additional state event types to share with users when they are invited <code>additional_event_types</code> are shared. Defaults to <code>false</code>.</p>
to a room. By default, this list is empty (so only the default event types are shared).</li> </li>
<li>
<p><code>additional_event_types</code>: A list of additional state events to include in the
events to be shared. By default, this list is empty (so only the default event
types are shared).</p>
<p>Each entry in this list should be either a single string or a list of two
strings. </p>
<ul>
<li>A standalone string <code>t</code> represents all events with type <code>t</code> (i.e.
with no restrictions on state keys).</li>
<li>A pair of strings <code>[t, s]</code> represents a single event with type <code>t</code> and
state key <code>s</code>. The same type can appear in two entries with different state
keys: in this situation, both state keys are included in prejoin state.</li>
</ul>
</li>
</ul> </ul>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">room_prejoin_state: <pre><code class="language-yaml">room_prejoin_state:
disable_default_event_types: true disable_default_event_types: false
additional_event_types: additional_event_types:
- org.example.custom.event.type # Share all events of type `org.example.custom.event.typeA`
- m.room.join_rules - org.example.custom.event.typeA
# Share only events of type `org.example.custom.event.typeB` whose
# state_key is &quot;foo&quot;
- [&quot;org.example.custom.event.typeB&quot;, &quot;foo&quot;]
# Share only events of type `org.example.custom.event.typeC` whose
# state_key is &quot;bar&quot; or &quot;baz&quot;
- [&quot;org.example.custom.event.typeC&quot;, &quot;bar&quot;]
- [&quot;org.example.custom.event.typeC&quot;, &quot;baz&quot;]
</code></pre> </code></pre>
<p><em>Changed in Synapse 1.74:</em> admins can filter the events in prejoin state based
on their state key.</p>
<hr /> <hr />
<h3 id="track_puppeted_user_ips"><a class="header" href="#track_puppeted_user_ips"><code>track_puppeted_user_ips</code></a></h3> <h3 id="track_puppeted_user_ips"><a class="header" href="#track_puppeted_user_ips"><code>track_puppeted_user_ips</code></a></h3>
<p>We record the IP address of clients used to access the API for various <p>We record the IP address of clients used to access the API for various
@ -5974,7 +6017,7 @@ which is set to the claims returned by the UserInfo Endpoint and/or
in the ID Token.</p> in the ID Token.</p>
</li> </li>
<li> <li>
<p><code>backchannel_logout_enabled</code>: set to <code>true</code> to process OIDC Back-Channel Logout notifications. <p><code>backchannel_logout_enabled</code>: set to <code>true</code> to process OIDC Back-Channel Logout notifications.
Those notifications are expected to be received on <code>/_synapse/client/oidc/backchannel_logout</code>. Those notifications are expected to be received on <code>/_synapse/client/oidc/backchannel_logout</code>.
Defaults to <code>false</code>.</p> Defaults to <code>false</code>.</p>
</li> </li>
@ -6328,6 +6371,10 @@ ownership. Defaults to &quot;[%(server_name)s] Validate your email&quot;</li>
<p>This setting defines options for push notifications.</p> <p>This setting defines options for push notifications.</p>
<p>This option has a number of sub-options. They are as follows:</p> <p>This option has a number of sub-options. They are as follows:</p>
<ul> <ul>
<li><code>enabled</code>: Enables or disables push notification calculation. Note, disabling this will also
stop unread counts being calculated for rooms. This mode of operation is intended
for homeservers which may only have bots or appservice users connected, or are otherwise
not interested in push/unread counters. This is enabled by default.</li>
<li><code>include_content</code>: Clients requesting push notifications can either have the body of <li><code>include_content</code>: Clients requesting push notifications can either have the body of
the message sent in the notification poke along with other details the message sent in the notification poke along with other details
like the sender, or just the event ID and room ID (<code>event_id_only</code>). like the sender, or just the event ID and room ID (<code>event_id_only</code>).
@ -6347,6 +6394,7 @@ of unread messages.</li>
</ul> </ul>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">push: <pre><code class="language-yaml">push:
enabled: true
include_content: false include_content: false
group_unread_count_by_room: false group_unread_count_by_room: false
</code></pre> </code></pre>
@ -6622,7 +6670,7 @@ loads. Some workers are privileged and can accept requests from other workers.</
<ol> <ol>
<li>The first part (in this section of the manual) defines which shardable tasks <li>The first part (in this section of the manual) defines which shardable tasks
are delegated to privileged workers. This allows unprivileged workers to make are delegated to privileged workers. This allows unprivileged workers to make
request a privileged worker to act on their behalf.</li> requests to a privileged worker to act on their behalf.</li>
<li><a href="usage/configuration/config_documentation.html#individual-worker-configuration">The second part</a> <li><a href="usage/configuration/config_documentation.html#individual-worker-configuration">The second part</a>
controls the behaviour of individual workers in isolation.</li> controls the behaviour of individual workers in isolation.</li>
</ol> </ol>
@ -6631,13 +6679,14 @@ controls the behaviour of individual workers in isolation.</li>
<h3 id="worker_replication_secret"><a class="header" href="#worker_replication_secret"><code>worker_replication_secret</code></a></h3> <h3 id="worker_replication_secret"><a class="header" href="#worker_replication_secret"><code>worker_replication_secret</code></a></h3>
<p>A shared secret used by the replication APIs on the main process to authenticate <p>A shared secret used by the replication APIs on the main process to authenticate
HTTP requests from workers.</p> HTTP requests from workers.</p>
<p>The default, this value is omitted (equivalently <code>null</code>), which means that <p>The default, this value is omitted (equivalently <code>null</code>), which means that
traffic between the workers and the main process is not authenticated.</p> traffic between the workers and the main process is not authenticated.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot; <pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot;
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="start_pushers"><a class="header" href="#start_pushers"><code>start_pushers</code></a></h3> <h3 id="start_pushers"><a class="header" href="#start_pushers"><code>start_pushers</code></a></h3>
<p>Unnecessary to set if using <a href="usage/configuration/config_documentation.html#pusher_instances"><code>pusher_instances</code></a> with <a href="usage/configuration/../../workers.html#synapseappgeneric_worker"><code>generic_workers</code></a>.</p>
<p>Controls sending of push notifications on the main process. Set to <code>false</code> <p>Controls sending of push notifications on the main process. Set to <code>false</code>
if using a <a href="usage/configuration/../../workers.html#synapseapppusher">pusher worker</a>. Defaults to <code>true</code>.</p> if using a <a href="usage/configuration/../../workers.html#synapseapppusher">pusher worker</a>. Defaults to <code>true</code>.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
@ -6645,21 +6694,24 @@ if using a <a href="usage/configuration/../../workers.html#synapseapppusher">pus
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="pusher_instances"><a class="header" href="#pusher_instances"><code>pusher_instances</code></a></h3> <h3 id="pusher_instances"><a class="header" href="#pusher_instances"><code>pusher_instances</code></a></h3>
<p>It is possible to run multiple <a href="usage/configuration/../../workers.html#synapseapppusher">pusher workers</a>, <p>It is possible to scale the processes that handle sending push notifications to <a href="https://github.com/matrix-org/sygnal">sygnal</a>
in which case the work is balanced across them. Use this setting to list the pushers by and email by running a <a href="usage/configuration/../../workers.html#synapseappgeneric_worker"><code>generic_worker</code></a> and adding it's <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a> to
<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>. Ensure the main process and all pusher workers are a <code>pusher_instances</code> map. Doing so will remove handling of this function from the main
restarted after changing this option.</p> process. Multiple workers can be added to this map, in which case the work is balanced
<p>If no or only one pusher worker is configured, this setting is not necessary. across them. Ensure the main process and all pusher workers are restarted after changing
The main process will send out push notifications by default if you do not disable this option.</p>
it by setting <a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a>.</p> <p>Example configuration for a single worker:</p>
<p>Example configuration:</p> <pre><code class="language-yaml">pusher_instances:
<pre><code class="language-yaml">start_pushers: false - pusher_worker1
pusher_instances: </code></pre>
<p>And for multiple workers:</p>
<pre><code class="language-yaml">pusher_instances:
- pusher_worker1 - pusher_worker1
- pusher_worker2 - pusher_worker2
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="send_federation"><a class="header" href="#send_federation"><code>send_federation</code></a></h3> <h3 id="send_federation"><a class="header" href="#send_federation"><code>send_federation</code></a></h3>
<p>Unnecessary to set if using <a href="usage/configuration/config_documentation.html#federation_sender_instances"><code>federation_sender_instances</code></a> with <a href="usage/configuration/../../workers.html#synapseappgeneric_worker"><code>generic_workers</code></a>.</p>
<p>Controls sending of outbound federation transactions on the main process. <p>Controls sending of outbound federation transactions on the main process.
Set to <code>false</code> if using a <a href="usage/configuration/../../workers.html#synapseappfederation_sender">federation sender worker</a>. Set to <code>false</code> if using a <a href="usage/configuration/../../workers.html#synapseappfederation_sender">federation sender worker</a>.
Defaults to <code>true</code>.</p> Defaults to <code>true</code>.</p>
@ -6668,25 +6720,31 @@ Defaults to <code>true</code>.</p>
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3> <h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3>
<p>It is possible to run multiple <p>It is possible to scale the processes that handle sending outbound federation requests
<a href="usage/configuration/../../workers.html#synapseappfederation_sender">federation sender worker</a>, in which by running a <a href="usage/configuration/../../workers.html#synapseappgeneric_worker"><code>generic_worker</code></a> and adding it's <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a> to
case the work is balanced across them. Use this setting to list the senders.</p> a <code>federation_sender_instances</code> map. Doing so will remove handling of this function from
<p>This configuration setting must be shared between all federation sender workers, and if the main process. Multiple workers can be added to this map, in which case the work is
changed all federation sender workers must be stopped at the same time and then balanced across them.</p>
started, to ensure that all instances are running with the same config (otherwise <p>This configuration setting must be shared between all workers handling federation
sending, and if changed all federation sender workers must be stopped at the same time
and then started, to ensure that all instances are running with the same config (otherwise
events may be dropped).</p> events may be dropped).</p>
<p>Example configuration:</p> <p>Example configuration for a single worker:</p>
<pre><code class="language-yaml">send_federation: false <pre><code class="language-yaml">federation_sender_instances:
federation_sender_instances:
- federation_sender1 - federation_sender1
</code></pre> </code></pre>
<p>And for multiple workers:</p>
<pre><code class="language-yaml">federation_sender_instances:
- federation_sender1
- federation_sender2
</code></pre>
<hr /> <hr />
<h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3> <h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3>
<p>When using workers this should be a map from <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a> to the <p>When using workers this should be a map from <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a> to the
HTTP replication listener of the worker, if configured. HTTP replication listener of the worker, if configured.
Each worker declared under <a href="usage/configuration/../../workers.html#stream-writers"><code>stream_writers</code></a> needs Each worker declared under <a href="usage/configuration/../../workers.html#stream-writers"><code>stream_writers</code></a> needs
a HTTP replication listener, and that listener should be included in the <code>instance_map</code>. a HTTP replication listener, and that listener should be included in the <code>instance_map</code>.
(The main process also needs an HTTP replication listener, but it should not be (The main process also needs an HTTP replication listener, but it should not be
listed in the <code>instance_map</code>.)</p> listed in the <code>instance_map</code>.)</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">instance_map: <pre><code class="language-yaml">instance_map:
@ -6787,8 +6845,8 @@ See <a href="usage/configuration/config_documentation.html#worker_replication_se
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="worker_listeners"><a class="header" href="#worker_listeners"><code>worker_listeners</code></a></h3> <h3 id="worker_listeners"><a class="header" href="#worker_listeners"><code>worker_listeners</code></a></h3>
<p>A worker can handle HTTP requests. To do so, a <code>worker_listeners</code> option <p>A worker can handle HTTP requests. To do so, a <code>worker_listeners</code> option
must be declared, in the same way as the <a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code> option</a> must be declared, in the same way as the <a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code> option</a>
in the shared config.</p> in the shared config.</p>
<p>Workers declared in <a href="usage/configuration/config_documentation.html#stream_writers"><code>stream_writers</code></a> will need to include a <p>Workers declared in <a href="usage/configuration/config_documentation.html#stream_writers"><code>stream_writers</code></a> will need to include a
<code>replication</code> listener here, in order to accept internal HTTP requests from <code>replication</code> listener here, in order to accept internal HTTP requests from
@ -6803,7 +6861,7 @@ other workers.</p>
<hr /> <hr />
<h3 id="worker_daemonize"><a class="header" href="#worker_daemonize"><code>worker_daemonize</code></a></h3> <h3 id="worker_daemonize"><a class="header" href="#worker_daemonize"><code>worker_daemonize</code></a></h3>
<p>Specifies whether the worker should be started as a daemon process. <p>Specifies whether the worker should be started as a daemon process.
If Synapse is being managed by <a href="usage/configuration/../../systemd-with-workers/README.html">systemd</a>, this option If Synapse is being managed by <a href="usage/configuration/../../systemd-with-workers/README.html">systemd</a>, this option
must be omitted or set to <code>false</code>.</p> must be omitted or set to <code>false</code>.</p>
<p>Defaults to <code>false</code>.</p> <p>Defaults to <code>false</code>.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
@ -6811,10 +6869,10 @@ must be omitted or set to <code>false</code>.</p>
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="worker_pid_file"><a class="header" href="#worker_pid_file"><code>worker_pid_file</code></a></h3> <h3 id="worker_pid_file"><a class="header" href="#worker_pid_file"><code>worker_pid_file</code></a></h3>
<p>When running a worker as a daemon, we need a place to store the <p>When running a worker as a daemon, we need a place to store the
<a href="https://en.wikipedia.org/wiki/Process_identifier">PID</a> of the worker. <a href="https://en.wikipedia.org/wiki/Process_identifier">PID</a> of the worker.
This option defines the location of that &quot;pid file&quot;.</p> This option defines the location of that &quot;pid file&quot;.</p>
<p>This option is required if <code>worker_daemonize</code> is <code>true</code> and ignored <p>This option is required if <code>worker_daemonize</code> is <code>true</code> and ignored
otherwise. It has no default.</p> otherwise. It has no default.</p>
<p>See also the <a href="usage/configuration/config_documentation.html#pid_file"><code>pid_file</code> option</a> option for the main Synapse process.</p> <p>See also the <a href="usage/configuration/config_documentation.html#pid_file"><code>pid_file</code> option</a> option for the main Synapse process.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
@ -7894,6 +7952,37 @@ needed to add OAuth2 capabilities to your Django projects. It supports
display_name_template: &quot;{{ user.first_name }} {{ user.last_name }}&quot; display_name_template: &quot;{{ user.first_name }} {{ user.last_name }}&quot;
email_template: &quot;{{ user.email }}&quot; email_template: &quot;{{ user.email }}&quot;
</code></pre> </code></pre>
<h3 id="mastodon"><a class="header" href="#mastodon">Mastodon</a></h3>
<p><a href="https://docs.joinmastodon.org/">Mastodon</a> instances provide an <a href="https://docs.joinmastodon.org/spec/oauth/">OAuth API</a>, allowing those instances to be used as a single sign-on provider for Synapse.</p>
<p>The first step is to register Synapse as an application with your Mastodon instance, using the <a href="https://docs.joinmastodon.org/methods/apps/#create">Create an application API</a> (see also <a href="https://docs.joinmastodon.org/client/token/">here</a>). There are several ways to do this, but in the example below we are using CURL.</p>
<p>This example assumes that:</p>
<ul>
<li>the Mastodon instance website URL is <code>https://your.mastodon.instance.url</code>, and</li>
<li>Synapse will be registered as an app named <code>my_synapse_app</code>.</li>
</ul>
<p>Send the following request, substituting the value of <code>synapse_public_baseurl</code> from your Synapse installation.</p>
<pre><code class="language-sh">curl -d &quot;client_name=my_synapse_app&amp;redirect_uris=https://[synapse_public_baseurl]/_synapse/client/oidc/callback&quot; -X POST https://your.mastodon.instance.url/api/v1/apps
</code></pre>
<p>You should receive a response similar to the following. Make sure to save it.</p>
<pre><code class="language-json">{&quot;client_id&quot;:&quot;someclientid_123&quot;,&quot;client_secret&quot;:&quot;someclientsecret_123&quot;,&quot;id&quot;:&quot;12345&quot;,&quot;name&quot;:&quot;my_synapse_app&quot;,&quot;redirect_uri&quot;:&quot;https://[synapse_public_baseurl]/_synapse/client/oidc/callback&quot;,&quot;website&quot;:null,&quot;vapid_key&quot;:&quot;somerandomvapidkey_123&quot;}
</code></pre>
<p>As the Synapse login mechanism needs an attribute to uniquely identify users, and Mastodon's endpoint does not return a <code>sub</code> property, an alternative <code>subject_claim</code> has to be set. Your Synapse configuration should include the following:</p>
<pre><code class="language-yaml">oidc_providers:
- idp_id: my_mastodon
idp_name: &quot;Mastodon Instance Example&quot;
discover: false
issuer: &quot;https://your.mastodon.instance.url/@admin&quot;
client_id: &quot;someclientid_123&quot;
client_secret: &quot;someclientsecret_123&quot;
authorization_endpoint: &quot;https://your.mastodon.instance.url/oauth/authorize&quot;
token_endpoint: &quot;https://your.mastodon.instance.url/oauth/token&quot;
userinfo_endpoint: &quot;https://your.mastodon.instance.url/api/v1/accounts/verify_credentials&quot;
scopes: [&quot;read&quot;]
user_mapping_provider:
config:
subject_claim: &quot;id&quot;
</code></pre>
<p>Note that the fields <code>client_id</code> and <code>client_secret</code> are taken from the CURL response above.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="saml"><a class="header" href="#saml">SAML</a></h1> <div style="break-before: page; page-break-before: always;"></div><h1 id="saml"><a class="header" href="#saml">SAML</a></h1>
<p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language">Security Assertion <p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language">Security Assertion
Markup Language</a> Markup Language</a>
@ -10592,6 +10681,8 @@ after setting this option in the shared configuration!</p>
<p>This style of configuration supersedes the legacy <code>synapse.app.appservice</code> <p>This style of configuration supersedes the legacy <code>synapse.app.appservice</code>
worker application type.</p> worker application type.</p>
<h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3> <h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3>
<p>It is likely this option will be deprecated in the future and is not recommended for new
installations. Instead, <a href="usage/configuration/config_documentation.html#pusher_instances">use <code>synapse.app.generic_worker</code> with the <code>pusher_instances</code></a>.</p>
<p>Handles sending push notifications to sygnal and email. Doesn't handle any <p>Handles sending push notifications to sygnal and email. Doesn't handle any
REST endpoints itself, but you should set REST endpoints itself, but you should set
<a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a> in the <a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a> in the
@ -10623,6 +10714,8 @@ REST endpoints itself, but you should set <code>notify_appservices: False</code>
shared configuration file to stop the main synapse sending appservice notifications.</p> shared configuration file to stop the main synapse sending appservice notifications.</p>
<p>Note this worker cannot be load-balanced: only one instance should be active.</p> <p>Note this worker cannot be load-balanced: only one instance should be active.</p>
<h3 id="synapseappfederation_sender"><a class="header" href="#synapseappfederation_sender"><code>synapse.app.federation_sender</code></a></h3> <h3 id="synapseappfederation_sender"><a class="header" href="#synapseappfederation_sender"><code>synapse.app.federation_sender</code></a></h3>
<p>It is likely this option will be deprecated in the future and not recommended for
new installations. Instead, <a href="usage/configuration/config_documentation.html#federation_sender_instances">use <code>synapse.app.generic_worker</code> with the <code>federation_sender_instances</code></a>. </p>
<p>Handles sending federation traffic to other servers. Doesn't handle any <p>Handles sending federation traffic to other servers. Doesn't handle any
REST endpoints itself, but you should set REST endpoints itself, but you should set
<a href="usage/configuration/config_documentation.html#send_federation"><code>send_federation: false</code></a> <a href="usage/configuration/config_documentation.html#send_federation"><code>send_federation: false</code></a>
@ -10714,7 +10807,9 @@ equivalent to <code>synapse.app.generic_worker</code>:</p>
<li><code>synapse.app.client_reader</code></li> <li><code>synapse.app.client_reader</code></li>
<li><code>synapse.app.event_creator</code></li> <li><code>synapse.app.event_creator</code></li>
<li><code>synapse.app.federation_reader</code></li> <li><code>synapse.app.federation_reader</code></li>
<li><code>synapse.app.federation_sender</code></li>
<li><code>synapse.app.frontend_proxy</code></li> <li><code>synapse.app.frontend_proxy</code></li>
<li><code>synapse.app.pusher</code></li>
<li><code>synapse.app.synchrotron</code></li> <li><code>synapse.app.synchrotron</code></li>
</ul> </ul>
<h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2> <h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2>
@ -14863,7 +14958,7 @@ Access Token:&lt;click to reveal&gt; </p>
<p>Here we can see that the request has been tagged with <code>GET-37</code>. (The tag depends on the method of the HTTP request, so might start with <code>GET-</code>, <code>PUT-</code>, <code>POST-</code>, <code>OPTIONS-</code> or <code>DELETE-</code>.) So to find all lines corresponding to this request, we can do:</p> <p>Here we can see that the request has been tagged with <code>GET-37</code>. (The tag depends on the method of the HTTP request, so might start with <code>GET-</code>, <code>PUT-</code>, <code>POST-</code>, <code>OPTIONS-</code> or <code>DELETE-</code>.) So to find all lines corresponding to this request, we can do:</p>
<pre><code>grep 'GET-37' homeserver.log <pre><code>grep 'GET-37' homeserver.log
</code></pre> </code></pre>
<p>If you want to paste that output into a github issue or matrix room, please remember to surround it with triple-backticks (```) to make it legible (see https://help.github.com/en/articles/basic-writing-and-formatting-syntax#quoting-code).</p> <p>If you want to paste that output into a github issue or matrix room, please remember to surround it with triple-backticks (```) to make it legible (see <a href="https://help.github.com/en/articles/basic-writing-and-formatting-syntax#quoting-code">quoting code</a>).</p>
<h2 id="what-do-all-those-fields-in-the-processed-line-mean"><a class="header" href="#what-do-all-those-fields-in-the-processed-line-mean">What do all those fields in the 'Processed' line mean?</a></h2> <h2 id="what-do-all-those-fields-in-the-processed-line-mean"><a class="header" href="#what-do-all-those-fields-in-the-processed-line-mean">What do all those fields in the 'Processed' line mean?</a></h2>
<p>See <a href="usage/administration/request_log.html">Request log format</a>.</p> <p>See <a href="usage/administration/request_log.html">Request log format</a>.</p>
<h2 id="what-are-the-biggest-rooms-on-my-server"><a class="header" href="#what-are-the-biggest-rooms-on-my-server">What are the biggest rooms on my server?</a></h2> <h2 id="what-are-the-biggest-rooms-on-my-server"><a class="header" href="#what-are-the-biggest-rooms-on-my-server">What are the biggest rooms on my server?</a></h2>
@ -14956,6 +15051,7 @@ recommended for development. More information about WSL can be found at
on Windows is not officially supported.</p> on Windows is not officially supported.</p>
<p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <a href="https://www.python.org/downloads/">a recent version of Python 3</a>. Your Python also needs support for <a href="https://docs.python.org/3/library/venv.html">virtual environments</a>. This is usually built-in, but some Linux distributions like Debian and Ubuntu split it out into its own package. Running <code>sudo apt install python3-venv</code> should be enough.</p> <p>The code of Synapse is written in Python 3. To do pretty much anything, you'll need <a href="https://www.python.org/downloads/">a recent version of Python 3</a>. Your Python also needs support for <a href="https://docs.python.org/3/library/venv.html">virtual environments</a>. This is usually built-in, but some Linux distributions like Debian and Ubuntu split it out into its own package. Running <code>sudo apt install python3-venv</code> should be enough.</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>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>Synapse has an optional, improved user search with better Unicode support. For that you need the development package of <code>libicu</code>. On Debian or Ubuntu Linux, this can be installed with <code>sudo apt install libicu-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>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>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 <p>A recent version of the Rust compiler is needed to build the native modules. The

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

33
latest/setup/installation.html
View file

@ -207,7 +207,9 @@ the main configuration file at <code>/etc/matrix-synapse/homeserver.yaml</code>.
By doing that, you won't be asked if you want to replace your configuration By doing that, you won't be asked if you want to replace your configuration
file when you upgrade the Debian package to a later version.</p> file when you upgrade the Debian package to a later version.</p>
<h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5> <h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5>
<p>Andrej Shadura maintains a <code>matrix-synapse</code> package in the Debian repositories. <p>Andrej Shadura maintains a
<a href="https://packages.debian.org/sid/matrix-synapse"><code>matrix-synapse</code></a> package in
the Debian repositories.
For <code>bookworm</code> and <code>sid</code>, it can be installed simply with:</p> For <code>bookworm</code> and <code>sid</code>, it can be installed simply with:</p>
<pre><code class="language-sh">sudo apt install matrix-synapse <pre><code class="language-sh">sudo apt install matrix-synapse
</code></pre> </code></pre>
@ -217,16 +219,18 @@ for information on how to use backports.</p>
<p><code>matrix-synapse</code> is no longer maintained for <code>buster</code> and older.</p> <p><code>matrix-synapse</code> is no longer maintained for <code>buster</code> and older.</p>
<h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5> <h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5>
<p>We do not recommend using the packages in the default Ubuntu repository <p>We do not recommend using the packages in the default Ubuntu repository
at this time, as they are old and suffer from known security vulnerabilities. at this time, as they are <a href="https://bugs.launchpad.net/ubuntu/+source/matrix-synapse/+bug/1848709">old and suffer from known security vulnerabilities</a>.
The latest version of Synapse can be installed from <a href="#matrixorg-packages">our repository</a>.</p> The latest version of Synapse can be installed from <a href="#matrixorg-packages">our repository</a>.</p>
<h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4> <h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4>
<p>Synapse is in the Fedora repositories as <code>matrix-synapse</code>:</p> <p>Synapse is in the Fedora repositories as
<a href="https://src.fedoraproject.org/rpms/matrix-synapse"><code>matrix-synapse</code></a>:</p>
<pre><code class="language-sh">sudo dnf install matrix-synapse <pre><code class="language-sh">sudo dnf install matrix-synapse
</code></pre> </code></pre>
<p>Oleg Girko provides Fedora RPMs at <p>Additionally, Oleg Girko provides Fedora RPMs at
<a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p> <a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p>
<h4 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h4> <h4 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h4>
<p>Synapse is in the OpenSUSE repositories as <code>matrix-synapse</code>:</p> <p>Synapse is in the OpenSUSE repositories as
<a href="https://software.opensuse.org/package/matrix-synapse"><code>matrix-synapse</code></a>:</p>
<pre><code class="language-sh">sudo zypper install matrix-synapse <pre><code class="language-sh">sudo zypper install matrix-synapse
</code></pre> </code></pre>
<h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4> <h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4>
@ -247,7 +251,8 @@ installing under virtualenv):</p>
sudo pip install py-bcrypt sudo pip install py-bcrypt
</code></pre> </code></pre>
<h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4> <h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4>
<p>Synapse can be found in the void repositories as 'synapse':</p> <p>Synapse can be found in the void repositories as
<a href="https://github.com/void-linux/void-packages/tree/master/srcpkgs/synapse">'synapse'</a>:</p>
<pre><code class="language-sh">xbps-install -Su <pre><code class="language-sh">xbps-install -Su
xbps-install -S synapse xbps-install -S synapse
</code></pre> </code></pre>
@ -331,18 +336,19 @@ header files for Python C extensions.</p>
<p>Installing prerequisites on Ubuntu or Debian:</p> <p>Installing prerequisites on Ubuntu or Debian:</p>
<pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \ <pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \
python3-pip python3-setuptools sqlite3 \ python3-pip python3-setuptools sqlite3 \
libssl-dev virtualenv libjpeg-dev libxslt1-dev libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
</code></pre> </code></pre>
<h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5> <h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5>
<p>Installing prerequisites on ArchLinux:</p> <p>Installing prerequisites on ArchLinux:</p>
<pre><code class="language-sh">sudo pacman -S base-devel python python-pip \ <pre><code class="language-sh">sudo pacman -S base-devel python python-pip \
python-setuptools python-virtualenv sqlite3 python-setuptools python-virtualenv sqlite3 icu
</code></pre> </code></pre>
<h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5> <h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5>
<p>Installing prerequisites on CentOS or Fedora Linux:</p> <p>Installing prerequisites on CentOS or Fedora Linux:</p>
<pre><code class="language-sh">sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \ <pre><code class="language-sh">sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
libwebp-devel libxml2-devel libxslt-devel libpq-devel \ libwebp-devel libxml2-devel libxslt-devel libpq-devel \
python3-virtualenv libffi-devel openssl-devel python3-devel python3-virtualenv libffi-devel openssl-devel python3-devel \
libicu-devel
sudo dnf groupinstall &quot;Development Tools&quot; sudo dnf groupinstall &quot;Development Tools&quot;
</code></pre> </code></pre>
<h5 id="macos"><a class="header" href="#macos">macOS</a></h5> <h5 id="macos"><a class="header" href="#macos">macOS</a></h5>
@ -350,8 +356,10 @@ sudo dnf groupinstall &quot;Development Tools&quot;
<p>You may need to install the latest Xcode developer tools:</p> <p>You may need to install the latest Xcode developer tools:</p>
<pre><code class="language-sh">xcode-select --install <pre><code class="language-sh">xcode-select --install
</code></pre> </code></pre>
<p>On ARM-based Macs you may need to install libjpeg and libpq. <p>Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) for them.</p>
You can use Homebrew (https://brew.sh):</p> <p>You may need to install icu, and make the icu binaries and libraries accessible.
Please follow <a href="https://pypi.org/project/PyICU/">the official instructions of PyICU</a> to do so.</p>
<p>On ARM-based Macs you may also need to install libjpeg and libpq:</p>
<pre><code class="language-sh"> brew install jpeg libpq <pre><code class="language-sh"> brew install jpeg libpq
</code></pre> </code></pre>
<p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL <p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
@ -364,7 +372,8 @@ export CPPFLAGS=&quot;-I/usr/local/opt/openssl/include&quot;
<p>Installing prerequisites on openSUSE:</p> <p>Installing prerequisites on openSUSE:</p>
<pre><code class="language-sh">sudo zypper in -t pattern devel_basis <pre><code class="language-sh">sudo zypper in -t pattern devel_basis
sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \ sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
python-devel libffi-devel libopenssl-devel libjpeg62-devel python-devel libffi-devel libopenssl-devel libjpeg62-devel \
libicu-devel
</code></pre> </code></pre>
<h5 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h5> <h5 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h5>
<p>A port of Synapse is available under <code>net/synapse</code>. The filesystem <p>A port of Synapse is available under <code>net/synapse</code>. The filesystem

2
latest/turn-howto.html
View file

@ -177,7 +177,7 @@ However, even with appropriate configuration, NAT is known to cause issues and t
<pre><code>turn_uris: [ &quot;turn:turn.matrix.org?transport=udp&quot;, &quot;turn:turn.matrix.org?transport=tcp&quot; ] <pre><code>turn_uris: [ &quot;turn:turn.matrix.org?transport=udp&quot;, &quot;turn:turn.matrix.org?transport=tcp&quot; ]
turn_shared_secret: &quot;n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons&quot; turn_shared_secret: &quot;n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons&quot;
turn_user_lifetime: 86400000 turn_user_lifetime: 86400000
turn_allow_guests: True turn_allow_guests: true
</code></pre> </code></pre>
<p>After updating the homeserver configuration, you must restart synapse:</p> <p>After updating the homeserver configuration, you must restart synapse:</p>
<ul> <ul>

10
latest/upgrade.html
View file

@ -231,6 +231,16 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
<h1 id="upgrading-to-v1740"><a class="header" href="#upgrading-to-v1740">Upgrading to v1.74.0</a></h1>
<h2 id="unicode-support-in-user-search"><a class="header" href="#unicode-support-in-user-search">Unicode support in user search</a></h2>
<p>This version introduces optional support for an <a href="https://github.com/matrix-org/synapse/pull/14464">improved user search dealing with Unicode characters</a>.</p>
<p>If you want to take advantage of this feature you need to install PyICU,
the ICU native dependency and its development headers
so that PyICU can build since no prebuilt wheels are available.</p>
<p>You can follow <a href="https://pypi.org/project/PyICU/">the PyICU documentation</a> to do so,
and then do <code>pip install matrix-synapse[icu]</code> for a PyPI install.</p>
<p>Docker images and Debian packages need nothing specific as they already
include or specify ICU as an explicit dependency.</p>
<h1 id="upgrading-to-v1730"><a class="header" href="#upgrading-to-v1730">Upgrading to v1.73.0</a></h1> <h1 id="upgrading-to-v1730"><a class="header" href="#upgrading-to-v1730">Upgrading to v1.73.0</a></h1>
<h2 id="legacy-prometheus-metric-names-have-now-been-removed"><a class="header" href="#legacy-prometheus-metric-names-have-now-been-removed">Legacy Prometheus metric names have now been removed</a></h2> <h2 id="legacy-prometheus-metric-names-have-now-been-removed"><a class="header" href="#legacy-prometheus-metric-names-have-now-been-removed">Legacy Prometheus metric names have now been removed</a></h2>
<p>Synapse v1.69.0 included the deprecation of legacy Prometheus metric names <p>Synapse v1.69.0 included the deprecation of legacy Prometheus metric names

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

@ -194,7 +194,7 @@ Access Token:&lt;click to reveal&gt; </p>
<p>Here we can see that the request has been tagged with <code>GET-37</code>. (The tag depends on the method of the HTTP request, so might start with <code>GET-</code>, <code>PUT-</code>, <code>POST-</code>, <code>OPTIONS-</code> or <code>DELETE-</code>.) So to find all lines corresponding to this request, we can do:</p> <p>Here we can see that the request has been tagged with <code>GET-37</code>. (The tag depends on the method of the HTTP request, so might start with <code>GET-</code>, <code>PUT-</code>, <code>POST-</code>, <code>OPTIONS-</code> or <code>DELETE-</code>.) So to find all lines corresponding to this request, we can do:</p>
<pre><code>grep 'GET-37' homeserver.log <pre><code>grep 'GET-37' homeserver.log
</code></pre> </code></pre>
<p>If you want to paste that output into a github issue or matrix room, please remember to surround it with triple-backticks (```) to make it legible (see https://help.github.com/en/articles/basic-writing-and-formatting-syntax#quoting-code).</p> <p>If you want to paste that output into a github issue or matrix room, please remember to surround it with triple-backticks (```) to make it legible (see <a href="https://help.github.com/en/articles/basic-writing-and-formatting-syntax#quoting-code">quoting code</a>).</p>
<h2 id="what-do-all-those-fields-in-the-processed-line-mean"><a class="header" href="#what-do-all-those-fields-in-the-processed-line-mean">What do all those fields in the 'Processed' line mean?</a></h2> <h2 id="what-do-all-those-fields-in-the-processed-line-mean"><a class="header" href="#what-do-all-those-fields-in-the-processed-line-mean">What do all those fields in the 'Processed' line mean?</a></h2>
<p>See <a href="request_log.html">Request log format</a>.</p> <p>See <a href="request_log.html">Request log format</a>.</p>
<h2 id="what-are-the-biggest-rooms-on-my-server"><a class="header" href="#what-are-the-biggest-rooms-on-my-server">What are the biggest rooms on my server?</a></h2> <h2 id="what-are-the-biggest-rooms-on-my-server"><a class="header" href="#what-are-the-biggest-rooms-on-my-server">What are the biggest rooms on my server?</a></h2>

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

@ -842,7 +842,7 @@ 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. Please be advised <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 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 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 is less risky than deleting newer history but in general caution is advised when enabling this
@ -2160,33 +2160,56 @@ Defaults to https://matrix.org/report-usage-stats/push</p>
<p>Config settings related to the client/server API</p> <p>Config settings related to the client/server API</p>
<hr /> <hr />
<h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state</code></a></h3> <h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state</code></a></h3>
<p>Controls for the state that is shared with users who receive an invite <p>This setting controls the state that is shared with users upon receiving an
to a room. By default, the following state event types are shared with users who invite to a room, or in reply to a knock on a room. By default, the following
receive invites to the room:</p> state events are shared with users:</p>
<ul> <ul>
<li>m.room.join_rules</li> <li><code>m.room.join_rules</code></li>
<li>m.room.canonical_alias</li> <li><code>m.room.canonical_alias</code></li>
<li>m.room.avatar</li> <li><code>m.room.avatar</code></li>
<li>m.room.encryption</li> <li><code>m.room.encryption</code></li>
<li>m.room.name</li> <li><code>m.room.name</code></li>
<li>m.room.create</li> <li><code>m.room.create</code></li>
<li>m.room.topic</li> <li><code>m.room.topic</code></li>
</ul> </ul>
<p>To change the default behavior, use the following sub-options:</p> <p>To change the default behavior, use the following sub-options:</p>
<ul> <ul>
<li><code>disable_default_event_types</code>: set to true to disable the above defaults. If this <li>
is enabled, only the event types listed in <code>additional_event_types</code> are shared. <p><code>disable_default_event_types</code>: boolean. Set to <code>true</code> to disable the above
Defaults to false.</li> defaults. If this is enabled, only the event types listed in
<li><code>additional_event_types</code>: Additional state event types to share with users when they are invited <code>additional_event_types</code> are shared. Defaults to <code>false</code>.</p>
to a room. By default, this list is empty (so only the default event types are shared).</li> </li>
<li>
<p><code>additional_event_types</code>: A list of additional state events to include in the
events to be shared. By default, this list is empty (so only the default event
types are shared).</p>
<p>Each entry in this list should be either a single string or a list of two
strings. </p>
<ul>
<li>A standalone string <code>t</code> represents all events with type <code>t</code> (i.e.
with no restrictions on state keys).</li>
<li>A pair of strings <code>[t, s]</code> represents a single event with type <code>t</code> and
state key <code>s</code>. The same type can appear in two entries with different state
keys: in this situation, both state keys are included in prejoin state.</li>
</ul>
</li>
</ul> </ul>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">room_prejoin_state: <pre><code class="language-yaml">room_prejoin_state:
disable_default_event_types: true disable_default_event_types: false
additional_event_types: additional_event_types:
- org.example.custom.event.type # Share all events of type `org.example.custom.event.typeA`
- m.room.join_rules - org.example.custom.event.typeA
# Share only events of type `org.example.custom.event.typeB` whose
# state_key is &quot;foo&quot;
- [&quot;org.example.custom.event.typeB&quot;, &quot;foo&quot;]
# Share only events of type `org.example.custom.event.typeC` whose
# state_key is &quot;bar&quot; or &quot;baz&quot;
- [&quot;org.example.custom.event.typeC&quot;, &quot;bar&quot;]
- [&quot;org.example.custom.event.typeC&quot;, &quot;baz&quot;]
</code></pre> </code></pre>
<p><em>Changed in Synapse 1.74:</em> admins can filter the events in prejoin state based
on their state key.</p>
<hr /> <hr />
<h3 id="track_puppeted_user_ips"><a class="header" href="#track_puppeted_user_ips"><code>track_puppeted_user_ips</code></a></h3> <h3 id="track_puppeted_user_ips"><a class="header" href="#track_puppeted_user_ips"><code>track_puppeted_user_ips</code></a></h3>
<p>We record the IP address of clients used to access the API for various <p>We record the IP address of clients used to access the API for various
@ -2657,7 +2680,7 @@ which is set to the claims returned by the UserInfo Endpoint and/or
in the ID Token.</p> in the ID Token.</p>
</li> </li>
<li> <li>
<p><code>backchannel_logout_enabled</code>: set to <code>true</code> to process OIDC Back-Channel Logout notifications. <p><code>backchannel_logout_enabled</code>: set to <code>true</code> to process OIDC Back-Channel Logout notifications.
Those notifications are expected to be received on <code>/_synapse/client/oidc/backchannel_logout</code>. Those notifications are expected to be received on <code>/_synapse/client/oidc/backchannel_logout</code>.
Defaults to <code>false</code>.</p> Defaults to <code>false</code>.</p>
</li> </li>
@ -3011,6 +3034,10 @@ ownership. Defaults to &quot;[%(server_name)s] Validate your email&quot;</li>
<p>This setting defines options for push notifications.</p> <p>This setting defines options for push notifications.</p>
<p>This option has a number of sub-options. They are as follows:</p> <p>This option has a number of sub-options. They are as follows:</p>
<ul> <ul>
<li><code>enabled</code>: Enables or disables push notification calculation. Note, disabling this will also
stop unread counts being calculated for rooms. This mode of operation is intended
for homeservers which may only have bots or appservice users connected, or are otherwise
not interested in push/unread counters. This is enabled by default.</li>
<li><code>include_content</code>: Clients requesting push notifications can either have the body of <li><code>include_content</code>: Clients requesting push notifications can either have the body of
the message sent in the notification poke along with other details the message sent in the notification poke along with other details
like the sender, or just the event ID and room ID (<code>event_id_only</code>). like the sender, or just the event ID and room ID (<code>event_id_only</code>).
@ -3030,6 +3057,7 @@ of unread messages.</li>
</ul> </ul>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">push: <pre><code class="language-yaml">push:
enabled: true
include_content: false include_content: false
group_unread_count_by_room: false group_unread_count_by_room: false
</code></pre> </code></pre>
@ -3305,7 +3333,7 @@ loads. Some workers are privileged and can accept requests from other workers.</
<ol> <ol>
<li>The first part (in this section of the manual) defines which shardable tasks <li>The first part (in this section of the manual) defines which shardable tasks
are delegated to privileged workers. This allows unprivileged workers to make are delegated to privileged workers. This allows unprivileged workers to make
request a privileged worker to act on their behalf.</li> requests to a privileged worker to act on their behalf.</li>
<li><a href="#individual-worker-configuration">The second part</a> <li><a href="#individual-worker-configuration">The second part</a>
controls the behaviour of individual workers in isolation.</li> controls the behaviour of individual workers in isolation.</li>
</ol> </ol>
@ -3314,13 +3342,14 @@ controls the behaviour of individual workers in isolation.</li>
<h3 id="worker_replication_secret"><a class="header" href="#worker_replication_secret"><code>worker_replication_secret</code></a></h3> <h3 id="worker_replication_secret"><a class="header" href="#worker_replication_secret"><code>worker_replication_secret</code></a></h3>
<p>A shared secret used by the replication APIs on the main process to authenticate <p>A shared secret used by the replication APIs on the main process to authenticate
HTTP requests from workers.</p> HTTP requests from workers.</p>
<p>The default, this value is omitted (equivalently <code>null</code>), which means that <p>The default, this value is omitted (equivalently <code>null</code>), which means that
traffic between the workers and the main process is not authenticated.</p> traffic between the workers and the main process is not authenticated.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot; <pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot;
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="start_pushers"><a class="header" href="#start_pushers"><code>start_pushers</code></a></h3> <h3 id="start_pushers"><a class="header" href="#start_pushers"><code>start_pushers</code></a></h3>
<p>Unnecessary to set if using <a href="#pusher_instances"><code>pusher_instances</code></a> with <a href="../../workers.html#synapseappgeneric_worker"><code>generic_workers</code></a>.</p>
<p>Controls sending of push notifications on the main process. Set to <code>false</code> <p>Controls sending of push notifications on the main process. Set to <code>false</code>
if using a <a href="../../workers.html#synapseapppusher">pusher worker</a>. Defaults to <code>true</code>.</p> if using a <a href="../../workers.html#synapseapppusher">pusher worker</a>. Defaults to <code>true</code>.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
@ -3328,21 +3357,24 @@ if using a <a href="../../workers.html#synapseapppusher">pusher worker</a>. Defa
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="pusher_instances"><a class="header" href="#pusher_instances"><code>pusher_instances</code></a></h3> <h3 id="pusher_instances"><a class="header" href="#pusher_instances"><code>pusher_instances</code></a></h3>
<p>It is possible to run multiple <a href="../../workers.html#synapseapppusher">pusher workers</a>, <p>It is possible to scale the processes that handle sending push notifications to <a href="https://github.com/matrix-org/sygnal">sygnal</a>
in which case the work is balanced across them. Use this setting to list the pushers by and email by running a <a href="../../workers.html#synapseappgeneric_worker"><code>generic_worker</code></a> and adding it's <a href="#worker_name"><code>worker_name</code></a> to
<a href="#worker_name"><code>worker_name</code></a>. Ensure the main process and all pusher workers are a <code>pusher_instances</code> map. Doing so will remove handling of this function from the main
restarted after changing this option.</p> process. Multiple workers can be added to this map, in which case the work is balanced
<p>If no or only one pusher worker is configured, this setting is not necessary. across them. Ensure the main process and all pusher workers are restarted after changing
The main process will send out push notifications by default if you do not disable this option.</p>
it by setting <a href="#start_pushers"><code>start_pushers: false</code></a>.</p> <p>Example configuration for a single worker:</p>
<p>Example configuration:</p> <pre><code class="language-yaml">pusher_instances:
<pre><code class="language-yaml">start_pushers: false - pusher_worker1
pusher_instances: </code></pre>
<p>And for multiple workers:</p>
<pre><code class="language-yaml">pusher_instances:
- pusher_worker1 - pusher_worker1
- pusher_worker2 - pusher_worker2
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="send_federation"><a class="header" href="#send_federation"><code>send_federation</code></a></h3> <h3 id="send_federation"><a class="header" href="#send_federation"><code>send_federation</code></a></h3>
<p>Unnecessary to set if using <a href="#federation_sender_instances"><code>federation_sender_instances</code></a> with <a href="../../workers.html#synapseappgeneric_worker"><code>generic_workers</code></a>.</p>
<p>Controls sending of outbound federation transactions on the main process. <p>Controls sending of outbound federation transactions on the main process.
Set to <code>false</code> if using a <a href="../../workers.html#synapseappfederation_sender">federation sender worker</a>. Set to <code>false</code> if using a <a href="../../workers.html#synapseappfederation_sender">federation sender worker</a>.
Defaults to <code>true</code>.</p> Defaults to <code>true</code>.</p>
@ -3351,25 +3383,31 @@ Defaults to <code>true</code>.</p>
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3> <h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3>
<p>It is possible to run multiple <p>It is possible to scale the processes that handle sending outbound federation requests
<a href="../../workers.html#synapseappfederation_sender">federation sender worker</a>, in which by running a <a href="../../workers.html#synapseappgeneric_worker"><code>generic_worker</code></a> and adding it's <a href="#worker_name"><code>worker_name</code></a> to
case the work is balanced across them. Use this setting to list the senders.</p> a <code>federation_sender_instances</code> map. Doing so will remove handling of this function from
<p>This configuration setting must be shared between all federation sender workers, and if the main process. Multiple workers can be added to this map, in which case the work is
changed all federation sender workers must be stopped at the same time and then balanced across them.</p>
started, to ensure that all instances are running with the same config (otherwise <p>This configuration setting must be shared between all workers handling federation
sending, and if changed all federation sender workers must be stopped at the same time
and then started, to ensure that all instances are running with the same config (otherwise
events may be dropped).</p> events may be dropped).</p>
<p>Example configuration:</p> <p>Example configuration for a single worker:</p>
<pre><code class="language-yaml">send_federation: false <pre><code class="language-yaml">federation_sender_instances:
federation_sender_instances:
- federation_sender1 - federation_sender1
</code></pre> </code></pre>
<p>And for multiple workers:</p>
<pre><code class="language-yaml">federation_sender_instances:
- federation_sender1
- federation_sender2
</code></pre>
<hr /> <hr />
<h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3> <h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3>
<p>When using workers this should be a map from <a href="#worker_name"><code>worker_name</code></a> to the <p>When using workers this should be a map from <a href="#worker_name"><code>worker_name</code></a> to the
HTTP replication listener of the worker, if configured. HTTP replication listener of the worker, if configured.
Each worker declared under <a href="../../workers.html#stream-writers"><code>stream_writers</code></a> needs Each worker declared under <a href="../../workers.html#stream-writers"><code>stream_writers</code></a> needs
a HTTP replication listener, and that listener should be included in the <code>instance_map</code>. a HTTP replication listener, and that listener should be included in the <code>instance_map</code>.
(The main process also needs an HTTP replication listener, but it should not be (The main process also needs an HTTP replication listener, but it should not be
listed in the <code>instance_map</code>.)</p> listed in the <code>instance_map</code>.)</p>
<p>Example configuration:</p> <p>Example configuration:</p>
<pre><code class="language-yaml">instance_map: <pre><code class="language-yaml">instance_map:
@ -3470,8 +3508,8 @@ See <a href="#worker_replication_secret"><code>worker_replication_secret</code><
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="worker_listeners"><a class="header" href="#worker_listeners"><code>worker_listeners</code></a></h3> <h3 id="worker_listeners"><a class="header" href="#worker_listeners"><code>worker_listeners</code></a></h3>
<p>A worker can handle HTTP requests. To do so, a <code>worker_listeners</code> option <p>A worker can handle HTTP requests. To do so, a <code>worker_listeners</code> option
must be declared, in the same way as the <a href="#listeners"><code>listeners</code> option</a> must be declared, in the same way as the <a href="#listeners"><code>listeners</code> option</a>
in the shared config.</p> in the shared config.</p>
<p>Workers declared in <a href="#stream_writers"><code>stream_writers</code></a> will need to include a <p>Workers declared in <a href="#stream_writers"><code>stream_writers</code></a> will need to include a
<code>replication</code> listener here, in order to accept internal HTTP requests from <code>replication</code> listener here, in order to accept internal HTTP requests from
@ -3486,7 +3524,7 @@ other workers.</p>
<hr /> <hr />
<h3 id="worker_daemonize"><a class="header" href="#worker_daemonize"><code>worker_daemonize</code></a></h3> <h3 id="worker_daemonize"><a class="header" href="#worker_daemonize"><code>worker_daemonize</code></a></h3>
<p>Specifies whether the worker should be started as a daemon process. <p>Specifies whether the worker should be started as a daemon process.
If Synapse is being managed by <a href="../../systemd-with-workers/README.html">systemd</a>, this option If Synapse is being managed by <a href="../../systemd-with-workers/README.html">systemd</a>, this option
must be omitted or set to <code>false</code>.</p> must be omitted or set to <code>false</code>.</p>
<p>Defaults to <code>false</code>.</p> <p>Defaults to <code>false</code>.</p>
<p>Example configuration:</p> <p>Example configuration:</p>
@ -3494,10 +3532,10 @@ must be omitted or set to <code>false</code>.</p>
</code></pre> </code></pre>
<hr /> <hr />
<h3 id="worker_pid_file"><a class="header" href="#worker_pid_file"><code>worker_pid_file</code></a></h3> <h3 id="worker_pid_file"><a class="header" href="#worker_pid_file"><code>worker_pid_file</code></a></h3>
<p>When running a worker as a daemon, we need a place to store the <p>When running a worker as a daemon, we need a place to store the
<a href="https://en.wikipedia.org/wiki/Process_identifier">PID</a> of the worker. <a href="https://en.wikipedia.org/wiki/Process_identifier">PID</a> of the worker.
This option defines the location of that &quot;pid file&quot;.</p> This option defines the location of that &quot;pid file&quot;.</p>
<p>This option is required if <code>worker_daemonize</code> is <code>true</code> and ignored <p>This option is required if <code>worker_daemonize</code> is <code>true</code> and ignored
otherwise. It has no default.</p> otherwise. It has no default.</p>
<p>See also the <a href="#pid_file"><code>pid_file</code> option</a> option for the main Synapse process.</p> <p>See also the <a href="#pid_file"><code>pid_file</code> option</a> option for the main Synapse process.</p>
<p>Example configuration:</p> <p>Example configuration:</p>

6
latest/workers.html
View file

@ -589,6 +589,8 @@ after setting this option in the shared configuration!</p>
<p>This style of configuration supersedes the legacy <code>synapse.app.appservice</code> <p>This style of configuration supersedes the legacy <code>synapse.app.appservice</code>
worker application type.</p> worker application type.</p>
<h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3> <h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3>
<p>It is likely this option will be deprecated in the future and is not recommended for new
installations. Instead, <a href="usage/configuration/config_documentation.html#pusher_instances">use <code>synapse.app.generic_worker</code> with the <code>pusher_instances</code></a>.</p>
<p>Handles sending push notifications to sygnal and email. Doesn't handle any <p>Handles sending push notifications to sygnal and email. Doesn't handle any
REST endpoints itself, but you should set REST endpoints itself, but you should set
<a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a> in the <a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a> in the
@ -620,6 +622,8 @@ REST endpoints itself, but you should set <code>notify_appservices: False</code>
shared configuration file to stop the main synapse sending appservice notifications.</p> shared configuration file to stop the main synapse sending appservice notifications.</p>
<p>Note this worker cannot be load-balanced: only one instance should be active.</p> <p>Note this worker cannot be load-balanced: only one instance should be active.</p>
<h3 id="synapseappfederation_sender"><a class="header" href="#synapseappfederation_sender"><code>synapse.app.federation_sender</code></a></h3> <h3 id="synapseappfederation_sender"><a class="header" href="#synapseappfederation_sender"><code>synapse.app.federation_sender</code></a></h3>
<p>It is likely this option will be deprecated in the future and not recommended for
new installations. Instead, <a href="usage/configuration/config_documentation.html#federation_sender_instances">use <code>synapse.app.generic_worker</code> with the <code>federation_sender_instances</code></a>. </p>
<p>Handles sending federation traffic to other servers. Doesn't handle any <p>Handles sending federation traffic to other servers. Doesn't handle any
REST endpoints itself, but you should set REST endpoints itself, but you should set
<a href="usage/configuration/config_documentation.html#send_federation"><code>send_federation: false</code></a> <a href="usage/configuration/config_documentation.html#send_federation"><code>send_federation: false</code></a>
@ -711,7 +715,9 @@ equivalent to <code>synapse.app.generic_worker</code>:</p>
<li><code>synapse.app.client_reader</code></li> <li><code>synapse.app.client_reader</code></li>
<li><code>synapse.app.event_creator</code></li> <li><code>synapse.app.event_creator</code></li>
<li><code>synapse.app.federation_reader</code></li> <li><code>synapse.app.federation_reader</code></li>
<li><code>synapse.app.federation_sender</code></li>
<li><code>synapse.app.frontend_proxy</code></li> <li><code>synapse.app.frontend_proxy</code></li>
<li><code>synapse.app.pusher</code></li>
<li><code>synapse.app.synchrotron</code></li> <li><code>synapse.app.synchrotron</code></li>
</ul> </ul>
<h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2> <h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2>