deploy: 774e20b570
This commit is contained in:
squahtx
parent
3606b75acc
commit
39861031ee
|
|
@ -164,6 +164,7 @@ recommended for development. More information about WSL can be found at
|
|||
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>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>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
|
||||
|
|
|
|||
|
|
@ -676,6 +676,37 @@ needed to add OAuth2 capabilities to your Django projects. It supports
|
|||
display_name_template: "{{ user.first_name }} {{ user.last_name }}"
|
||||
email_template: "{{ user.email }}"
|
||||
</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 "client_name=my_synapse_app&redirect_uris=https://[synapse_public_baseurl]/_synapse/client/oidc/callback" -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">{"client_id":"someclientid_123","client_secret":"someclientsecret_123","id":"12345","name":"my_synapse_app","redirect_uri":"https://[synapse_public_baseurl]/_synapse/client/oidc/callback","website":null,"vapid_key":"somerandomvapidkey_123"}
|
||||
</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: "Mastodon Instance Example"
|
||||
discover: false
|
||||
issuer: "https://your.mastodon.instance.url/@admin"
|
||||
client_id: "someclientid_123"
|
||||
client_secret: "someclientsecret_123"
|
||||
authorization_endpoint: "https://your.mastodon.instance.url/oauth/authorize"
|
||||
token_endpoint: "https://your.mastodon.instance.url/oauth/token"
|
||||
userinfo_endpoint: "https://your.mastodon.instance.url/api/v1/accounts/verify_credentials"
|
||||
scopes: ["read"]
|
||||
user_mapping_provider:
|
||||
config:
|
||||
subject_claim: "id"
|
||||
</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>
|
||||
|
||||
|
|
|
|||
|
|
@ -147,7 +147,8 @@
|
|||
</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>
|
||||
<p>Synapse will require the python postgres client library in order to
|
||||
connect to a postgres database.</p>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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>
|
||||
<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>
|
||||
<pre><code class="language-sh">sudo apt install matrix-synapse
|
||||
</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>
|
||||
<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
|
||||
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>
|
||||
<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
|
||||
</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>
|
||||
<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
|
||||
</code></pre>
|
||||
<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
|
||||
</code></pre>
|
||||
<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
|
||||
xbps-install -S synapse
|
||||
</code></pre>
|
||||
|
|
@ -414,18 +419,19 @@ header files for Python C extensions.</p>
|
|||
<p>Installing prerequisites on Ubuntu or Debian:</p>
|
||||
<pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \
|
||||
python3-pip python3-setuptools sqlite3 \
|
||||
libssl-dev virtualenv libjpeg-dev libxslt1-dev
|
||||
libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
|
||||
</code></pre>
|
||||
<h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5>
|
||||
<p>Installing prerequisites on ArchLinux:</p>
|
||||
<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>
|
||||
<h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5>
|
||||
<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 \
|
||||
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 "Development Tools"
|
||||
</code></pre>
|
||||
<h5 id="macos"><a class="header" href="#macos">macOS</a></h5>
|
||||
|
|
@ -433,8 +439,10 @@ 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 install libjpeg and libpq.
|
||||
You can use Homebrew (https://brew.sh):</p>
|
||||
<p>Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) for them.</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
|
||||
</code></pre>
|
||||
<p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
|
||||
|
|
@ -447,7 +455,8 @@ export CPPFLAGS="-I/usr/local/opt/openssl/include"
|
|||
<p>Installing prerequisites on openSUSE:</p>
|
||||
<pre><code class="language-sh">sudo zypper in -t pattern devel_basis
|
||||
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>
|
||||
<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
|
||||
|
|
@ -646,7 +655,8 @@ failing, e.g.:</p>
|
|||
<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>
|
||||
<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>
|
||||
<p>Synapse will require the python postgres client library in order to
|
||||
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: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
|
||||
turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
|
||||
turn_user_lifetime: 86400000
|
||||
turn_allow_guests: True
|
||||
turn_allow_guests: true
|
||||
</code></pre>
|
||||
<p>After updating the homeserver configuration, you must restart synapse:</p>
|
||||
<ul>
|
||||
|
|
@ -1761,6 +1771,16 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
|
|||
</code></pre>
|
||||
</li>
|
||||
</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>
|
||||
<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
|
||||
|
|
@ -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
|
||||
filter events received over federation so that events that should have been
|
||||
purged are ignored and not stored again.</p>
|
||||
<p>The message retention policies feature is disabled by default. 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
|
||||
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
|
||||
|
|
@ -5477,33 +5497,56 @@ Defaults to https://matrix.org/report-usage-stats/push</p>
|
|||
<p>Config settings related to the client/server API</p>
|
||||
<hr />
|
||||
<h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state</code></a></h3>
|
||||
<p>Controls for the state that is shared with users who receive an invite
|
||||
to a room. By default, the following state event types are shared with users who
|
||||
receive invites to the room:</p>
|
||||
<p>This setting controls the state that is shared with users upon receiving an
|
||||
invite to a room, or in reply to a knock on a room. By default, the following
|
||||
state events are shared with users:</p>
|
||||
<ul>
|
||||
<li>m.room.join_rules</li>
|
||||
<li>m.room.canonical_alias</li>
|
||||
<li>m.room.avatar</li>
|
||||
<li>m.room.encryption</li>
|
||||
<li>m.room.name</li>
|
||||
<li>m.room.create</li>
|
||||
<li>m.room.topic</li>
|
||||
<li><code>m.room.join_rules</code></li>
|
||||
<li><code>m.room.canonical_alias</code></li>
|
||||
<li><code>m.room.avatar</code></li>
|
||||
<li><code>m.room.encryption</code></li>
|
||||
<li><code>m.room.name</code></li>
|
||||
<li><code>m.room.create</code></li>
|
||||
<li><code>m.room.topic</code></li>
|
||||
</ul>
|
||||
<p>To change the default behavior, use the following sub-options:</p>
|
||||
<ul>
|
||||
<li><code>disable_default_event_types</code>: set to true to disable the above defaults. If this
|
||||
is enabled, only the event types listed in <code>additional_event_types</code> are shared.
|
||||
Defaults to false.</li>
|
||||
<li><code>additional_event_types</code>: Additional state event types to share with users when they are invited
|
||||
to a room. By default, this list is empty (so only the default event types are shared).</li>
|
||||
<li>
|
||||
<p><code>disable_default_event_types</code>: boolean. Set to <code>true</code> to disable the above
|
||||
defaults. If this is enabled, only the event types listed in
|
||||
<code>additional_event_types</code> are shared. Defaults to <code>false</code>.</p>
|
||||
</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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">room_prejoin_state:
|
||||
disable_default_event_types: true
|
||||
disable_default_event_types: false
|
||||
additional_event_types:
|
||||
- org.example.custom.event.type
|
||||
- m.room.join_rules
|
||||
# Share all events of type `org.example.custom.event.typeA`
|
||||
- org.example.custom.event.typeA
|
||||
# Share only events of type `org.example.custom.event.typeB` whose
|
||||
# state_key is "foo"
|
||||
- ["org.example.custom.event.typeB", "foo"]
|
||||
# Share only events of type `org.example.custom.event.typeC` whose
|
||||
# state_key is "bar" or "baz"
|
||||
- ["org.example.custom.event.typeC", "bar"]
|
||||
- ["org.example.custom.event.typeC", "baz"]
|
||||
</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 />
|
||||
<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
|
||||
|
|
@ -5974,7 +6017,7 @@ which is set to the claims returned by the UserInfo Endpoint and/or
|
|||
in the ID Token.</p>
|
||||
</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>.
|
||||
Defaults to <code>false</code>.</p>
|
||||
</li>
|
||||
|
|
@ -6328,6 +6371,10 @@ ownership. Defaults to "[%(server_name)s] Validate your email"</li>
|
|||
<p>This setting defines options for push notifications.</p>
|
||||
<p>This option has a number of sub-options. They are as follows:</p>
|
||||
<ul>
|
||||
<li><code>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
|
||||
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>).
|
||||
|
|
@ -6347,6 +6394,7 @@ of unread messages.</li>
|
|||
</ul>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">push:
|
||||
enabled: true
|
||||
include_content: false
|
||||
group_unread_count_by_room: false
|
||||
</code></pre>
|
||||
|
|
@ -6622,7 +6670,7 @@ loads. Some workers are privileged and can accept requests from other workers.</
|
|||
<ol>
|
||||
<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
|
||||
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>
|
||||
controls the behaviour of individual workers in isolation.</li>
|
||||
</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>
|
||||
<p>A shared secret used by the replication APIs on the main process to authenticate
|
||||
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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">worker_replication_secret: "secret_secret"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<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>
|
||||
if using a <a href="usage/configuration/../../workers.html#synapseapppusher">pusher worker</a>. Defaults to <code>true</code>.</p>
|
||||
<p>Example configuration:</p>
|
||||
|
|
@ -6645,21 +6694,24 @@ if using a <a href="usage/configuration/../../workers.html#synapseapppusher">pus
|
|||
</code></pre>
|
||||
<hr />
|
||||
<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>,
|
||||
in which case the work is balanced across them. Use this setting to list the pushers by
|
||||
<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>. Ensure the main process and all pusher workers are
|
||||
restarted after changing this option.</p>
|
||||
<p>If no or only one pusher worker is configured, this setting is not necessary.
|
||||
The main process will send out push notifications by default if you do not disable
|
||||
it by setting <a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a>.</p>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">start_pushers: false
|
||||
pusher_instances:
|
||||
<p>It is possible to scale the processes that handle sending push notifications to <a href="https://github.com/matrix-org/sygnal">sygnal</a>
|
||||
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 <code>pusher_instances</code> map. Doing so will remove handling of this function from the main
|
||||
process. Multiple workers can be added to this map, in which case the work is balanced
|
||||
across them. Ensure the main process and all pusher workers are restarted after changing
|
||||
this option.</p>
|
||||
<p>Example configuration for a single worker:</p>
|
||||
<pre><code class="language-yaml">pusher_instances:
|
||||
- pusher_worker1
|
||||
</code></pre>
|
||||
<p>And for multiple workers:</p>
|
||||
<pre><code class="language-yaml">pusher_instances:
|
||||
- pusher_worker1
|
||||
- pusher_worker2
|
||||
</code></pre>
|
||||
<hr />
|
||||
<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.
|
||||
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>
|
||||
|
|
@ -6668,25 +6720,31 @@ Defaults to <code>true</code>.</p>
|
|||
</code></pre>
|
||||
<hr />
|
||||
<h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3>
|
||||
<p>It is possible to run multiple
|
||||
<a href="usage/configuration/../../workers.html#synapseappfederation_sender">federation sender worker</a>, in which
|
||||
case the work is balanced across them. Use this setting to list the senders.</p>
|
||||
<p>This configuration setting must be shared between all federation sender workers, and if
|
||||
changed all federation sender workers must be stopped at the same time and then
|
||||
started, to ensure that all instances are running with the same config (otherwise
|
||||
<p>It is possible to scale the processes that handle sending outbound federation requests
|
||||
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 <code>federation_sender_instances</code> map. Doing so will remove handling of this function from
|
||||
the main process. Multiple workers can be added to this map, in which case the work is
|
||||
balanced across them.</p>
|
||||
<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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">send_federation: false
|
||||
federation_sender_instances:
|
||||
<p>Example configuration for a single worker:</p>
|
||||
<pre><code class="language-yaml">federation_sender_instances:
|
||||
- federation_sender1
|
||||
</code></pre>
|
||||
<p>And for multiple workers:</p>
|
||||
<pre><code class="language-yaml">federation_sender_instances:
|
||||
- federation_sender1
|
||||
- federation_sender2
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3>
|
||||
<p>When using workers this should be a map from <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a> to the
|
||||
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>.
|
||||
(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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">instance_map:
|
||||
|
|
@ -6787,8 +6845,8 @@ See <a href="usage/configuration/config_documentation.html#worker_replication_se
|
|||
</code></pre>
|
||||
<hr />
|
||||
<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
|
||||
must be declared, in the same way as the <a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code> option</a>
|
||||
<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>
|
||||
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
|
||||
<code>replication</code> listener here, in order to accept internal HTTP requests from
|
||||
|
|
@ -6803,7 +6861,7 @@ other workers.</p>
|
|||
<hr />
|
||||
<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.
|
||||
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>
|
||||
<p>Defaults to <code>false</code>.</p>
|
||||
<p>Example configuration:</p>
|
||||
|
|
@ -6811,10 +6869,10 @@ must be omitted or set to <code>false</code>.</p>
|
|||
</code></pre>
|
||||
<hr />
|
||||
<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.
|
||||
This option defines the location of that "pid file".</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>
|
||||
<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>
|
||||
|
|
@ -7894,6 +7952,37 @@ needed to add OAuth2 capabilities to your Django projects. It supports
|
|||
display_name_template: "{{ user.first_name }} {{ user.last_name }}"
|
||||
email_template: "{{ user.email }}"
|
||||
</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 "client_name=my_synapse_app&redirect_uris=https://[synapse_public_baseurl]/_synapse/client/oidc/callback" -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">{"client_id":"someclientid_123","client_secret":"someclientsecret_123","id":"12345","name":"my_synapse_app","redirect_uri":"https://[synapse_public_baseurl]/_synapse/client/oidc/callback","website":null,"vapid_key":"somerandomvapidkey_123"}
|
||||
</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: "Mastodon Instance Example"
|
||||
discover: false
|
||||
issuer: "https://your.mastodon.instance.url/@admin"
|
||||
client_id: "someclientid_123"
|
||||
client_secret: "someclientsecret_123"
|
||||
authorization_endpoint: "https://your.mastodon.instance.url/oauth/authorize"
|
||||
token_endpoint: "https://your.mastodon.instance.url/oauth/token"
|
||||
userinfo_endpoint: "https://your.mastodon.instance.url/api/v1/accounts/verify_credentials"
|
||||
scopes: ["read"]
|
||||
user_mapping_provider:
|
||||
config:
|
||||
subject_claim: "id"
|
||||
</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>
|
||||
<p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language">Security Assertion
|
||||
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>
|
||||
worker application type.</p>
|
||||
<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
|
||||
REST endpoints itself, but you should set
|
||||
<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>
|
||||
<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>
|
||||
<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
|
||||
REST endpoints itself, but you should set
|
||||
<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.event_creator</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.pusher</code></li>
|
||||
<li><code>synapse.app.synchrotron</code></li>
|
||||
</ul>
|
||||
<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:<click to reveal> </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
|
||||
</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>
|
||||
<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>
|
||||
|
|
@ -14956,6 +15051,7 @@ recommended for development. More information about WSL can be found at
|
|||
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>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>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
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
|
|
@ -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
|
||||
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>
|
||||
<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>
|
||||
<pre><code class="language-sh">sudo apt install matrix-synapse
|
||||
</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>
|
||||
<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
|
||||
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>
|
||||
<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
|
||||
</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>
|
||||
<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
|
||||
</code></pre>
|
||||
<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
|
||||
</code></pre>
|
||||
<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
|
||||
xbps-install -S synapse
|
||||
</code></pre>
|
||||
|
|
@ -331,18 +336,19 @@ header files for Python C extensions.</p>
|
|||
<p>Installing prerequisites on Ubuntu or Debian:</p>
|
||||
<pre><code class="language-sh">sudo apt install build-essential python3-dev libffi-dev \
|
||||
python3-pip python3-setuptools sqlite3 \
|
||||
libssl-dev virtualenv libjpeg-dev libxslt1-dev
|
||||
libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
|
||||
</code></pre>
|
||||
<h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5>
|
||||
<p>Installing prerequisites on ArchLinux:</p>
|
||||
<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>
|
||||
<h5 id="centosfedora"><a class="header" href="#centosfedora">CentOS/Fedora</a></h5>
|
||||
<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 \
|
||||
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 "Development Tools"
|
||||
</code></pre>
|
||||
<h5 id="macos"><a class="header" href="#macos">macOS</a></h5>
|
||||
|
|
@ -350,8 +356,10 @@ 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 install libjpeg and libpq.
|
||||
You can use Homebrew (https://brew.sh):</p>
|
||||
<p>Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) for them.</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
|
||||
</code></pre>
|
||||
<p>On macOS Catalina (10.15) you may need to explicitly install OpenSSL
|
||||
|
|
@ -364,7 +372,8 @@ export CPPFLAGS="-I/usr/local/opt/openssl/include"
|
|||
<p>Installing prerequisites on openSUSE:</p>
|
||||
<pre><code class="language-sh">sudo zypper in -t pattern devel_basis
|
||||
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>
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -177,7 +177,7 @@ However, even with appropriate configuration, NAT is known to cause issues and t
|
|||
<pre><code>turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
|
||||
turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
|
||||
turn_user_lifetime: 86400000
|
||||
turn_allow_guests: True
|
||||
turn_allow_guests: true
|
||||
</code></pre>
|
||||
<p>After updating the homeserver configuration, you must restart synapse:</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -231,6 +231,16 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
|
|||
</code></pre>
|
||||
</li>
|
||||
</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>
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -194,7 +194,7 @@ Access Token:<click to reveal> </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
|
||||
</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>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
filter events received over federation so that events that should have been
|
||||
purged are ignored and not stored again.</p>
|
||||
<p>The message retention policies feature is disabled by default. 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
|
||||
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
|
||||
|
|
@ -2160,33 +2160,56 @@ Defaults to https://matrix.org/report-usage-stats/push</p>
|
|||
<p>Config settings related to the client/server API</p>
|
||||
<hr />
|
||||
<h3 id="room_prejoin_state"><a class="header" href="#room_prejoin_state"><code>room_prejoin_state</code></a></h3>
|
||||
<p>Controls for the state that is shared with users who receive an invite
|
||||
to a room. By default, the following state event types are shared with users who
|
||||
receive invites to the room:</p>
|
||||
<p>This setting controls the state that is shared with users upon receiving an
|
||||
invite to a room, or in reply to a knock on a room. By default, the following
|
||||
state events are shared with users:</p>
|
||||
<ul>
|
||||
<li>m.room.join_rules</li>
|
||||
<li>m.room.canonical_alias</li>
|
||||
<li>m.room.avatar</li>
|
||||
<li>m.room.encryption</li>
|
||||
<li>m.room.name</li>
|
||||
<li>m.room.create</li>
|
||||
<li>m.room.topic</li>
|
||||
<li><code>m.room.join_rules</code></li>
|
||||
<li><code>m.room.canonical_alias</code></li>
|
||||
<li><code>m.room.avatar</code></li>
|
||||
<li><code>m.room.encryption</code></li>
|
||||
<li><code>m.room.name</code></li>
|
||||
<li><code>m.room.create</code></li>
|
||||
<li><code>m.room.topic</code></li>
|
||||
</ul>
|
||||
<p>To change the default behavior, use the following sub-options:</p>
|
||||
<ul>
|
||||
<li><code>disable_default_event_types</code>: set to true to disable the above defaults. If this
|
||||
is enabled, only the event types listed in <code>additional_event_types</code> are shared.
|
||||
Defaults to false.</li>
|
||||
<li><code>additional_event_types</code>: Additional state event types to share with users when they are invited
|
||||
to a room. By default, this list is empty (so only the default event types are shared).</li>
|
||||
<li>
|
||||
<p><code>disable_default_event_types</code>: boolean. Set to <code>true</code> to disable the above
|
||||
defaults. If this is enabled, only the event types listed in
|
||||
<code>additional_event_types</code> are shared. Defaults to <code>false</code>.</p>
|
||||
</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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">room_prejoin_state:
|
||||
disable_default_event_types: true
|
||||
disable_default_event_types: false
|
||||
additional_event_types:
|
||||
- org.example.custom.event.type
|
||||
- m.room.join_rules
|
||||
# Share all events of type `org.example.custom.event.typeA`
|
||||
- org.example.custom.event.typeA
|
||||
# Share only events of type `org.example.custom.event.typeB` whose
|
||||
# state_key is "foo"
|
||||
- ["org.example.custom.event.typeB", "foo"]
|
||||
# Share only events of type `org.example.custom.event.typeC` whose
|
||||
# state_key is "bar" or "baz"
|
||||
- ["org.example.custom.event.typeC", "bar"]
|
||||
- ["org.example.custom.event.typeC", "baz"]
|
||||
</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 />
|
||||
<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
|
||||
|
|
@ -2657,7 +2680,7 @@ which is set to the claims returned by the UserInfo Endpoint and/or
|
|||
in the ID Token.</p>
|
||||
</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>.
|
||||
Defaults to <code>false</code>.</p>
|
||||
</li>
|
||||
|
|
@ -3011,6 +3034,10 @@ ownership. Defaults to "[%(server_name)s] Validate your email"</li>
|
|||
<p>This setting defines options for push notifications.</p>
|
||||
<p>This option has a number of sub-options. They are as follows:</p>
|
||||
<ul>
|
||||
<li><code>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
|
||||
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>).
|
||||
|
|
@ -3030,6 +3057,7 @@ of unread messages.</li>
|
|||
</ul>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">push:
|
||||
enabled: true
|
||||
include_content: false
|
||||
group_unread_count_by_room: false
|
||||
</code></pre>
|
||||
|
|
@ -3305,7 +3333,7 @@ loads. Some workers are privileged and can accept requests from other workers.</
|
|||
<ol>
|
||||
<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
|
||||
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>
|
||||
controls the behaviour of individual workers in isolation.</li>
|
||||
</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>
|
||||
<p>A shared secret used by the replication APIs on the main process to authenticate
|
||||
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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">worker_replication_secret: "secret_secret"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<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>
|
||||
if using a <a href="../../workers.html#synapseapppusher">pusher worker</a>. Defaults to <code>true</code>.</p>
|
||||
<p>Example configuration:</p>
|
||||
|
|
@ -3328,21 +3357,24 @@ if using a <a href="../../workers.html#synapseapppusher">pusher worker</a>. Defa
|
|||
</code></pre>
|
||||
<hr />
|
||||
<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>,
|
||||
in which case the work is balanced across them. Use this setting to list the pushers by
|
||||
<a href="#worker_name"><code>worker_name</code></a>. Ensure the main process and all pusher workers are
|
||||
restarted after changing this option.</p>
|
||||
<p>If no or only one pusher worker is configured, this setting is not necessary.
|
||||
The main process will send out push notifications by default if you do not disable
|
||||
it by setting <a href="#start_pushers"><code>start_pushers: false</code></a>.</p>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">start_pushers: false
|
||||
pusher_instances:
|
||||
<p>It is possible to scale the processes that handle sending push notifications to <a href="https://github.com/matrix-org/sygnal">sygnal</a>
|
||||
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 <code>pusher_instances</code> map. Doing so will remove handling of this function from the main
|
||||
process. Multiple workers can be added to this map, in which case the work is balanced
|
||||
across them. Ensure the main process and all pusher workers are restarted after changing
|
||||
this option.</p>
|
||||
<p>Example configuration for a single worker:</p>
|
||||
<pre><code class="language-yaml">pusher_instances:
|
||||
- pusher_worker1
|
||||
</code></pre>
|
||||
<p>And for multiple workers:</p>
|
||||
<pre><code class="language-yaml">pusher_instances:
|
||||
- pusher_worker1
|
||||
- pusher_worker2
|
||||
</code></pre>
|
||||
<hr />
|
||||
<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.
|
||||
Set to <code>false</code> if using a <a href="../../workers.html#synapseappfederation_sender">federation sender worker</a>.
|
||||
Defaults to <code>true</code>.</p>
|
||||
|
|
@ -3351,25 +3383,31 @@ Defaults to <code>true</code>.</p>
|
|||
</code></pre>
|
||||
<hr />
|
||||
<h3 id="federation_sender_instances"><a class="header" href="#federation_sender_instances"><code>federation_sender_instances</code></a></h3>
|
||||
<p>It is possible to run multiple
|
||||
<a href="../../workers.html#synapseappfederation_sender">federation sender worker</a>, in which
|
||||
case the work is balanced across them. Use this setting to list the senders.</p>
|
||||
<p>This configuration setting must be shared between all federation sender workers, and if
|
||||
changed all federation sender workers must be stopped at the same time and then
|
||||
started, to ensure that all instances are running with the same config (otherwise
|
||||
<p>It is possible to scale the processes that handle sending outbound federation requests
|
||||
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 <code>federation_sender_instances</code> map. Doing so will remove handling of this function from
|
||||
the main process. Multiple workers can be added to this map, in which case the work is
|
||||
balanced across them.</p>
|
||||
<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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">send_federation: false
|
||||
federation_sender_instances:
|
||||
<p>Example configuration for a single worker:</p>
|
||||
<pre><code class="language-yaml">federation_sender_instances:
|
||||
- federation_sender1
|
||||
</code></pre>
|
||||
<p>And for multiple workers:</p>
|
||||
<pre><code class="language-yaml">federation_sender_instances:
|
||||
- federation_sender1
|
||||
- federation_sender2
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h3 id="instance_map"><a class="header" href="#instance_map"><code>instance_map</code></a></h3>
|
||||
<p>When using workers this should be a map from <a href="#worker_name"><code>worker_name</code></a> to the
|
||||
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>.
|
||||
(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>
|
||||
<p>Example configuration:</p>
|
||||
<pre><code class="language-yaml">instance_map:
|
||||
|
|
@ -3470,8 +3508,8 @@ See <a href="#worker_replication_secret"><code>worker_replication_secret</code><
|
|||
</code></pre>
|
||||
<hr />
|
||||
<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
|
||||
must be declared, in the same way as the <a href="#listeners"><code>listeners</code> option</a>
|
||||
<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>
|
||||
in the shared config.</p>
|
||||
<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
|
||||
|
|
@ -3486,7 +3524,7 @@ other workers.</p>
|
|||
<hr />
|
||||
<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.
|
||||
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>
|
||||
<p>Defaults to <code>false</code>.</p>
|
||||
<p>Example configuration:</p>
|
||||
|
|
@ -3494,10 +3532,10 @@ must be omitted or set to <code>false</code>.</p>
|
|||
</code></pre>
|
||||
<hr />
|
||||
<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.
|
||||
This option defines the location of that "pid file".</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>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
worker application type.</p>
|
||||
<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
|
||||
REST endpoints itself, but you should set
|
||||
<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>
|
||||
<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>
|
||||
<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
|
||||
REST endpoints itself, but you should set
|
||||
<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.event_creator</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.pusher</code></li>
|
||||
<li><code>synapse.app.synchrotron</code></li>
|
||||
</ul>
|
||||
<h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2>
|
||||
|
|
|
|||
Loading…
Reference in New Issue