summary refs log tree commit diff
path: root/latest/usage/configuration/config_documentation.html
diff options
context:
space:
mode:
Diffstat (limited to 'latest/usage/configuration/config_documentation.html')
-rw-r--r--latest/usage/configuration/config_documentation.html79
1 files changed, 71 insertions, 8 deletions
diff --git a/latest/usage/configuration/config_documentation.html b/latest/usage/configuration/config_documentation.html

index 9c26da6455..0b8eddf339 100644 --- a/latest/usage/configuration/config_documentation.html +++ b/latest/usage/configuration/config_documentation.html
@@ -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>.