mirrors/synapse
mirrors/synapse
1
0
Fork 0
mirror of https://github.com/element-hq/synapse.git synced 2025-03-28 18:38:31 +00:00
Code Activity

deploy: 190c990a76

Browse source
This commit is contained in:
DMRobertson 2023-08-01 11:02:34 +00:00
parent bb9baae962
commit 6dbfe29923
9 changed files with 228 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
latest/admin_api/user_admin_api.html
View file

@ -813,7 +813,8 @@ when admins wish to do actions on behalf of a user.</p>
</code></pre>
<p>An optional <code>valid_until_ms</code> field can be specified in the request body as an
integer timestamp that specifies when the token should expire. By default tokens
do not expire.</p>
do not expire. Note that this API does not allow a user to login as themselves
(to create more tokens).</p>
<p>A response body like the following is returned:</p>
<pre><code class="language-json">{
&quot;access_token&quot;: &quot;&lt;opaque_access_token_string&gt;&quot;

1
latest/development/contributing_guide.html
View file

@ -392,6 +392,7 @@ See the <a href="../workers.html">worker documentation</a> for additional inform
</li>
<li>Passing <code>ASYNCIO_REACTOR=1</code> as an environment variable to use the Twisted asyncio reactor instead of the default one.</li>
<li>Passing <code>PODMAN=1</code> will use the <a href="https://podman.io/">podman</a> container runtime, instead of docker.</li>
<li>Passing <code>UNIX_SOCKETS=1</code> will utilise Unix socket functionality for Synapse, Redis, and Postgres(when applicable).</li>
</ul>
<p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>, e.g:</p>
<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages

129
latest/print.html
View file

@ -320,8 +320,8 @@ The latest version of Synapse can be installed from <a href="setup/installation.
<p>Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
<a href="https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/">https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/</a></p>
<h4 id="archlinux"><a class="header" href="#archlinux">ArchLinux</a></h4>
<p>The quickest way to get up and running with ArchLinux is probably with the community package
<a href="https://archlinux.org/packages/community/x86_64/matrix-synapse/">https://archlinux.org/packages/community/x86_64/matrix-synapse/</a>, which should pull in most of
<p>The quickest way to get up and running with ArchLinux is probably with the package provided by ArchLinux
<a href="https://archlinux.org/packages/extra/x86_64/matrix-synapse/">https://archlinux.org/packages/extra/x86_64/matrix-synapse/</a>, which should pull in most of
the necessary dependencies.</p>
<p>pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):</p>
<pre><code class="language-sh">sudo pip install --upgrade pip
@ -1779,6 +1779,12 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre>
</li>
</ul>
<h1 id="upgrading-to-v1890"><a class="header" href="#upgrading-to-v1890">Upgrading to v1.89.0</a></h1>
<h2 id="removal-of-unspecced-user-property-for-register"><a class="header" href="#removal-of-unspecced-user-property-for-register">Removal of unspecced <code>user</code> property for <code>/register</code></a></h2>
<p>Application services can no longer call <code>/register</code> with a <code>user</code> property to create new users.
The standard <code>username</code> property should be used instead. See the
<a href="https://spec.matrix.org/v1.7/application-service-api/#server-admin-style-permissions">Application Service specification</a>
for more information.</p>
<h1 id="upgrading-to-v1880"><a class="header" href="#upgrading-to-v1880">Upgrading to v1.88.0</a></h1>
<h2 id="minimum-supported-python-version"><a class="header" href="#minimum-supported-python-version">Minimum supported Python version</a></h2>
<p>The minimum supported Python version has been increased from v3.7 to v3.8.
@ -4043,6 +4049,23 @@ on this port. Sub-options for each resource are:</p>
additional endpoints which should be loaded via dynamic modules.</p>
</li>
</ul>
<p>Unix socket support (<em>Added in Synapse 1.89.0</em>):</p>
<ul>
<li><code>path</code>: A path and filename for a Unix socket. Make sure it is located in a
directory with read and write permissions, and that it already exists (the directory
will not be created). Defaults to <code>None</code>.
<ul>
<li><strong>Note</strong>: The use of both <code>path</code> and <code>port</code> options for the same <code>listener</code> is not
compatible.</li>
<li>The <code>x_forwarded</code> option defaults to true when using Unix sockets and can be omitted.</li>
<li>Other options that would not make sense to use with a UNIX socket, such as
<code>bind_addresses</code> and <code>tls</code> will be ignored and can be removed.</li>
</ul>
</li>
<li><code>mode</code>: The file permissions to set on the UNIX socket. Defaults to <code>666</code></li>
<li><strong>Note:</strong> Must be set as <code>type: http</code> (does not support <code>metrics</code> and <code>manhole</code>).
Also make sure that <code>metrics</code> is not included in <code>resources</code> -&gt; <code>names</code></li>
</ul>
<p>Valid resource names are:</p>
<ul>
<li>
@ -4061,7 +4084,7 @@ additional endpoints which should be loaded via dynamic modules.</p>
<p><code>media</code>: the media API (/_matrix/media).</p>
</li>
<li>
<p><code>metrics</code>: the metrics interface. See <a href="usage/configuration/../../metrics-howto.html">here</a>.</p>
<p><code>metrics</code>: the metrics interface. See <a href="usage/configuration/../../metrics-howto.html">here</a>. (Not compatible with Unix sockets)</p>
</li>
<li>
<p><code>openid</code>: OpenID authentication. See <a href="usage/configuration/../../openid.html">here</a>.</p>
@ -4123,6 +4146,20 @@ for <a href="usage/configuration/../../workers.html">workers</a> and containers
bind_addresses: ['::1', '127.0.0.1']
type: manhole
</code></pre>
<p>Example configuration #3:</p>
<pre><code class="language-yaml">listeners:
# Unix socket listener: Ideal for Synapse deployments behind a reverse proxy, offering
# lightweight interprocess communication without TCP/IP overhead, avoid port
# conflicts, and providing enhanced security through system file permissions.
#
# Note that x_forwarded will default to true, when using a UNIX socket. Please see
# https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
#
- path: /var/run/synapse/main_public.sock
type: http
resources:
- names: [client, federation]
</code></pre>
<hr />
<h3 id="manhole_settings"><a class="header" href="#manhole_settings"><code>manhole_settings</code></a></h3>
<p>Connection settings for the manhole. You can find more information
@ -7035,13 +7072,14 @@ events may be dropped).</p>
</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, and to the main process.
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 entry on the <code>instance_map</code>, and it should be listed under
<code>main</code> <strong>if even one other worker exists</strong>. Ensure the port matches with what is declared
inside the <code>listener</code> block for a <code>replication</code> listener.</p>
<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, and to the main process. Each worker
declared under <a href="usage/configuration/../../workers.html#stream-writers"><code>stream_writers</code></a> and
<a href="usage/configuration/config_documentation.html#outbound_federation_restricted_to"><code>outbound_federation_restricted_to</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 entry on the <code>instance_map</code>, and it should be listed under
<code>main</code> <strong>if even one other worker exists</strong>. Ensure the port matches with what is
declared inside the <code>listener</code> block for a <code>replication</code> listener.</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">instance_map:
main:
@ -7051,6 +7089,13 @@ inside the <code>listener</code> block for a <code>replication</code> listener.<
host: localhost
port: 8034
</code></pre>
<p>Example configuration(#2, for UNIX sockets):</p>
<pre><code class="language-yaml">instance_map:
main:
path: /var/run/synapse/main_replication.sock
worker1:
path: /var/run/synapse/worker1_replication.sock
</code></pre>
<hr />
<h3 id="stream_writers"><a class="header" href="#stream_writers"><code>stream_writers</code></a></h3>
<p>Experimental: When using workers you can define which workers should
@ -7064,6 +7109,19 @@ Any worker specified here must also be in the <a href="usage/configuration/confi
typing: worker1
</code></pre>
<hr />
<h3 id="outbound_federation_restricted_to"><a class="header" href="#outbound_federation_restricted_to"><code>outbound_federation_restricted_to</code></a></h3>
<p>When using workers, you can restrict outbound federation traffic to only go through a
specific subset of workers. Any worker specified here must also be in the
<a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a>.
<a href="usage/configuration/config_documentation.html#worker_replication_secret"><code>worker_replication_secret</code></a> must also be configured to
authorize inter-worker communication.</p>
<pre><code class="language-yaml">outbound_federation_restricted_to:
- federation_sender1
- federation_sender2
</code></pre>
<h2>Also see the <a href="usage/configuration/../../workers.html#restrict-outbound-federation-traffic-to-a-specific-set-of-workers">worker
documentation</a>
for more info.</h2>
<h3 id="run_background_tasks_on"><a class="header" href="#run_background_tasks_on"><code>run_background_tasks_on</code></a></h3>
<p>The <a href="usage/configuration/../../workers.html#background-tasks">worker</a> that is used to run
background tasks (e.g. cleaning up expired data). If not provided this
@ -7190,6 +7248,17 @@ requests from other workers.</p>
resources:
- names: [client, federation]
</code></pre>
<p>Example configuration(#2, using UNIX sockets with a <code>replication</code> listener):</p>
<pre><code class="language-yaml">worker_listeners:
- type: http
path: /var/run/synapse/worker_public.sock
resources:
- names: [client, federation]
- type: http
path: /var/run/synapse/worker_replication.sock
resources:
- names: [replication]
</code></pre>
<hr />
<h3 id="worker_manhole"><a class="header" href="#worker_manhole"><code>worker_manhole</code></a></h3>
<p>A worker may have a listener for <a href="usage/configuration/../../manhole.html"><code>manhole</code></a>.
@ -10832,9 +10901,15 @@ for the main process</li>
<li>Secondly, you need to enable
<a href="usage/configuration/config_documentation.html#redis">redis-based replication</a></li>
<li>You will need to add an <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a>
with the <code>main</code> process defined, as well as the relevant connection information from
it's HTTP <code>replication</code> listener (defined in step 1 above). Note that the <code>host</code> defined
is the address the worker needs to look for the <code>main</code> process at, not necessarily the same address that is bound to.</li>
with the <code>main</code> process defined, as well as the relevant connection information from
it's HTTP <code>replication</code> listener (defined in step 1 above).
<ul>
<li>Note that the <code>host</code> defined is the address the worker needs to look for the <code>main</code>
process at, not necessarily the same address that is bound to.</li>
<li>If you are using Unix sockets for the <code>replication</code> resource, make sure to
use a <code>path</code> to the socket file instead of a <code>port</code>.</li>
</ul>
</li>
<li>Optionally, a <a href="usage/configuration/config_documentation.html#worker_replication_secret">shared secret</a>
can be used to authenticate HTTP traffic between workers. For example:</li>
</ul>
@ -10907,10 +10982,10 @@ recommend the use of <code>systemd</code> where available: for information on se
<h2 id="start-synapse-with-poetry"><a class="header" href="#start-synapse-with-poetry">Start Synapse with Poetry</a></h2>
<p>The following applies to Synapse installations that have been installed from source using <code>poetry</code>.</p>
<p>You can start the main Synapse process with Poetry by running the following command:</p>
<pre><code class="language-console">poetry run synapse_homeserver -c [your homeserver.yaml]
<pre><code class="language-console">poetry run synapse_homeserver --config-file [your homeserver.yaml]
</code></pre>
<p>For worker setups, you can run the following command</p>
<pre><code class="language-console">poetry run synapse_worker -c [your worker.yaml]
<pre><code class="language-console">poetry run synapse_worker --config-file [your homeserver.yaml] --config-file [your worker.yaml]
</code></pre>
<h2 id="available-worker-applications"><a class="header" href="#available-worker-applications">Available worker applications</a></h2>
<h3 id="synapseappgeneric_worker"><a class="header" href="#synapseappgeneric_worker"><code>synapse.app.generic_worker</code></a></h3>
@ -11235,6 +11310,26 @@ the stream writer for the <code>receipts</code> stream:</p>
the stream writer for the <code>presence</code> stream:</p>
<pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/presence/
</code></pre>
<h4 id="restrict-outbound-federation-traffic-to-a-specific-set-of-workers"><a class="header" href="#restrict-outbound-federation-traffic-to-a-specific-set-of-workers">Restrict outbound federation traffic to a specific set of workers</a></h4>
<p>The
<a href="usage/configuration/config_documentation.html#outbound_federation_restricted_to"><code>outbound_federation_restricted_to</code></a>
configuration is useful to make sure outbound federation traffic only goes through a
specified subset of workers. This allows you to set more strict access controls (like a
firewall) for all workers and only allow the <code>federation_sender</code>'s to contact the
outside world.</p>
<pre><code class="language-yaml">instance_map:
main:
host: localhost
port: 8030
federation_sender1:
host: localhost
port: 8034
outbound_federation_restricted_to:
- federation_sender1
worker_replication_secret: &quot;secret_secret&quot;
</code></pre>
<h4 id="background-tasks"><a class="header" href="#background-tasks">Background tasks</a></h4>
<p>There is also support for moving background tasks to a separate
worker. Background tasks are run periodically or started via replication. Exactly
@ -14284,7 +14379,8 @@ when admins wish to do actions on behalf of a user.</p>
</code></pre>
<p>An optional <code>valid_until_ms</code> field can be specified in the request body as an
integer timestamp that specifies when the token should expire. By default tokens
do not expire.</p>
do not expire. Note that this API does not allow a user to login as themselves
(to create more tokens).</p>
<p>A response body like the following is returned:</p>
<pre><code class="language-json">{
&quot;access_token&quot;: &quot;&lt;opaque_access_token_string&gt;&quot;
@ -16111,6 +16207,7 @@ See the <a href="development/../workers.html">worker documentation</a> for addit
</li>
<li>Passing <code>ASYNCIO_REACTOR=1</code> as an environment variable to use the Twisted asyncio reactor instead of the default one.</li>
<li>Passing <code>PODMAN=1</code> will use the <a href="https://podman.io/">podman</a> container runtime, instead of docker.</li>
<li>Passing <code>UNIX_SOCKETS=1</code> will utilise Unix socket functionality for Synapse, Redis, and Postgres(when applicable).</li>
</ul>
<p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>, e.g:</p>
<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages

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

4
latest/setup/installation.html
View file

@ -237,8 +237,8 @@ The latest version of Synapse can be installed from <a href="#matrixorg-packages
<p>Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
<a href="https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/">https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/</a></p>
<h4 id="archlinux"><a class="header" href="#archlinux">ArchLinux</a></h4>
<p>The quickest way to get up and running with ArchLinux is probably with the community package
<a href="https://archlinux.org/packages/community/x86_64/matrix-synapse/">https://archlinux.org/packages/community/x86_64/matrix-synapse/</a>, which should pull in most of
<p>The quickest way to get up and running with ArchLinux is probably with the package provided by ArchLinux
<a href="https://archlinux.org/packages/extra/x86_64/matrix-synapse/">https://archlinux.org/packages/extra/x86_64/matrix-synapse/</a>, which should pull in most of
the necessary dependencies.</p>
<p>pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):</p>
<pre><code class="language-sh">sudo pip install --upgrade pip

6
latest/upgrade.html
View file

@ -231,6 +231,12 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
</code></pre>
</li>
</ul>
<h1 id="upgrading-to-v1890"><a class="header" href="#upgrading-to-v1890">Upgrading to v1.89.0</a></h1>
<h2 id="removal-of-unspecced-user-property-for-register"><a class="header" href="#removal-of-unspecced-user-property-for-register">Removal of unspecced <code>user</code> property for <code>/register</code></a></h2>
<p>Application services can no longer call <code>/register</code> with a <code>user</code> property to create new users.
The standard <code>username</code> property should be used instead. See the
<a href="https://spec.matrix.org/v1.7/application-service-api/#server-admin-style-permissions">Application Service specification</a>
for more information.</p>
<h1 id="upgrading-to-v1880"><a class="header" href="#upgrading-to-v1880">Upgrading to v1.88.0</a></h1>
<h2 id="minimum-supported-python-version"><a class="header" href="#minimum-supported-python-version">Minimum supported Python version</a></h2>
<p>The minimum supported Python version has been increased from v3.7 to v3.8.

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

@ -523,6 +523,23 @@ on this port. Sub-options for each resource are:</p>
additional endpoints which should be loaded via dynamic modules.</p>
</li>
</ul>
<p>Unix socket support (<em>Added in Synapse 1.89.0</em>):</p>
<ul>
<li><code>path</code>: A path and filename for a Unix socket. Make sure it is located in a
directory with read and write permissions, and that it already exists (the directory
will not be created). Defaults to <code>None</code>.
<ul>
<li><strong>Note</strong>: The use of both <code>path</code> and <code>port</code> options for the same <code>listener</code> is not
compatible.</li>
<li>The <code>x_forwarded</code> option defaults to true when using Unix sockets and can be omitted.</li>
<li>Other options that would not make sense to use with a UNIX socket, such as
<code>bind_addresses</code> and <code>tls</code> will be ignored and can be removed.</li>
</ul>
</li>
<li><code>mode</code>: The file permissions to set on the UNIX socket. Defaults to <code>666</code></li>
<li><strong>Note:</strong> Must be set as <code>type: http</code> (does not support <code>metrics</code> and <code>manhole</code>).
Also make sure that <code>metrics</code> is not included in <code>resources</code> -&gt; <code>names</code></li>
</ul>
<p>Valid resource names are:</p>
<ul>
<li>
@ -541,7 +558,7 @@ additional endpoints which should be loaded via dynamic modules.</p>
<p><code>media</code>: the media API (/_matrix/media).</p>
</li>
<li>
<p><code>metrics</code>: the metrics interface. See <a href="../../metrics-howto.html">here</a>.</p>
<p><code>metrics</code>: the metrics interface. See <a href="../../metrics-howto.html">here</a>. (Not compatible with Unix sockets)</p>
</li>
<li>
<p><code>openid</code>: OpenID authentication. See <a href="../../openid.html">here</a>.</p>
@ -603,6 +620,20 @@ for <a href="../../workers.html">workers</a> and containers without listener e.g
bind_addresses: ['::1', '127.0.0.1']
type: manhole
</code></pre>
<p>Example configuration #3:</p>
<pre><code class="language-yaml">listeners:
# Unix socket listener: Ideal for Synapse deployments behind a reverse proxy, offering
# lightweight interprocess communication without TCP/IP overhead, avoid port
# conflicts, and providing enhanced security through system file permissions.
#
# Note that x_forwarded will default to true, when using a UNIX socket. Please see
# https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
#
- path: /var/run/synapse/main_public.sock
type: http
resources:
- names: [client, federation]
</code></pre>
<hr />
<h3 id="manhole_settings"><a class="header" href="#manhole_settings"><code>manhole_settings</code></a></h3>
<p>Connection settings for the manhole. You can find more information
@ -3515,13 +3546,14 @@ events may be dropped).</p>
</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, and to the main process.
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 entry on the <code>instance_map</code>, and it should be listed under
<code>main</code> <strong>if even one other worker exists</strong>. Ensure the port matches with what is declared
inside the <code>listener</code> block for a <code>replication</code> listener.</p>
<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, and to the main process. Each worker
declared under <a href="../../workers.html#stream-writers"><code>stream_writers</code></a> and
<a href="#outbound_federation_restricted_to"><code>outbound_federation_restricted_to</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 entry on the <code>instance_map</code>, and it should be listed under
<code>main</code> <strong>if even one other worker exists</strong>. Ensure the port matches with what is
declared inside the <code>listener</code> block for a <code>replication</code> listener.</p>
<p>Example configuration:</p>
<pre><code class="language-yaml">instance_map:
main:
@ -3531,6 +3563,13 @@ inside the <code>listener</code> block for a <code>replication</code> listener.<
host: localhost
port: 8034
</code></pre>
<p>Example configuration(#2, for UNIX sockets):</p>
<pre><code class="language-yaml">instance_map:
main:
path: /var/run/synapse/main_replication.sock
worker1:
path: /var/run/synapse/worker1_replication.sock
</code></pre>
<hr />
<h3 id="stream_writers"><a class="header" href="#stream_writers"><code>stream_writers</code></a></h3>
<p>Experimental: When using workers you can define which workers should
@ -3544,6 +3583,19 @@ Any worker specified here must also be in the <a href="#instance_map"><code>inst
typing: worker1
</code></pre>
<hr />
<h3 id="outbound_federation_restricted_to"><a class="header" href="#outbound_federation_restricted_to"><code>outbound_federation_restricted_to</code></a></h3>
<p>When using workers, you can restrict outbound federation traffic to only go through a
specific subset of workers. Any worker specified here must also be in the
<a href="#instance_map"><code>instance_map</code></a>.
<a href="#worker_replication_secret"><code>worker_replication_secret</code></a> must also be configured to
authorize inter-worker communication.</p>
<pre><code class="language-yaml">outbound_federation_restricted_to:
- federation_sender1
- federation_sender2
</code></pre>
<h2>Also see the <a href="../../workers.html#restrict-outbound-federation-traffic-to-a-specific-set-of-workers">worker
documentation</a>
for more info.</h2>
<h3 id="run_background_tasks_on"><a class="header" href="#run_background_tasks_on"><code>run_background_tasks_on</code></a></h3>
<p>The <a href="../../workers.html#background-tasks">worker</a> that is used to run
background tasks (e.g. cleaning up expired data). If not provided this
@ -3670,6 +3722,17 @@ requests from other workers.</p>
resources:
- names: [client, federation]
</code></pre>
<p>Example configuration(#2, using UNIX sockets with a <code>replication</code> listener):</p>
<pre><code class="language-yaml">worker_listeners:
- type: http
path: /var/run/synapse/worker_public.sock
resources:
- names: [client, federation]
- type: http
path: /var/run/synapse/worker_replication.sock
resources:
- names: [replication]
</code></pre>
<hr />
<h3 id="worker_manhole"><a class="header" href="#worker_manhole"><code>worker_manhole</code></a></h3>
<p>A worker may have a listener for <a href="../../manhole.html"><code>manhole</code></a>.

36
latest/workers.html
View file

@ -218,9 +218,15 @@ for the main process</li>
<li>Secondly, you need to enable
<a href="usage/configuration/config_documentation.html#redis">redis-based replication</a></li>
<li>You will need to add an <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a>
with the <code>main</code> process defined, as well as the relevant connection information from
it's HTTP <code>replication</code> listener (defined in step 1 above). Note that the <code>host</code> defined
is the address the worker needs to look for the <code>main</code> process at, not necessarily the same address that is bound to.</li>
with the <code>main</code> process defined, as well as the relevant connection information from
it's HTTP <code>replication</code> listener (defined in step 1 above).
<ul>
<li>Note that the <code>host</code> defined is the address the worker needs to look for the <code>main</code>
process at, not necessarily the same address that is bound to.</li>
<li>If you are using Unix sockets for the <code>replication</code> resource, make sure to
use a <code>path</code> to the socket file instead of a <code>port</code>.</li>
</ul>
</li>
<li>Optionally, a <a href="usage/configuration/config_documentation.html#worker_replication_secret">shared secret</a>
can be used to authenticate HTTP traffic between workers. For example:</li>
</ul>
@ -293,10 +299,10 @@ recommend the use of <code>systemd</code> where available: for information on se
<h2 id="start-synapse-with-poetry"><a class="header" href="#start-synapse-with-poetry">Start Synapse with Poetry</a></h2>
<p>The following applies to Synapse installations that have been installed from source using <code>poetry</code>.</p>
<p>You can start the main Synapse process with Poetry by running the following command:</p>
<pre><code class="language-console">poetry run synapse_homeserver -c [your homeserver.yaml]
<pre><code class="language-console">poetry run synapse_homeserver --config-file [your homeserver.yaml]
</code></pre>
<p>For worker setups, you can run the following command</p>
<pre><code class="language-console">poetry run synapse_worker -c [your worker.yaml]
<pre><code class="language-console">poetry run synapse_worker --config-file [your homeserver.yaml] --config-file [your worker.yaml]
</code></pre>
<h2 id="available-worker-applications"><a class="header" href="#available-worker-applications">Available worker applications</a></h2>
<h3 id="synapseappgeneric_worker"><a class="header" href="#synapseappgeneric_worker"><code>synapse.app.generic_worker</code></a></h3>
@ -621,6 +627,26 @@ the stream writer for the <code>receipts</code> stream:</p>
the stream writer for the <code>presence</code> stream:</p>
<pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/presence/
</code></pre>
<h4 id="restrict-outbound-federation-traffic-to-a-specific-set-of-workers"><a class="header" href="#restrict-outbound-federation-traffic-to-a-specific-set-of-workers">Restrict outbound federation traffic to a specific set of workers</a></h4>
<p>The
<a href="usage/configuration/config_documentation.html#outbound_federation_restricted_to"><code>outbound_federation_restricted_to</code></a>
configuration is useful to make sure outbound federation traffic only goes through a
specified subset of workers. This allows you to set more strict access controls (like a
firewall) for all workers and only allow the <code>federation_sender</code>'s to contact the
outside world.</p>
<pre><code class="language-yaml">instance_map:
main:
host: localhost
port: 8030
federation_sender1:
host: localhost
port: 8034
outbound_federation_restricted_to:
- federation_sender1
worker_replication_secret: &quot;secret_secret&quot;
</code></pre>
<h4 id="background-tasks"><a class="header" href="#background-tasks">Background tasks</a></h4>
<p>There is also support for moving background tasks to a separate
worker. Background tasks are run periodically or started via replication. Exactly