From 6dbfe29923eb271471bbd74723137f9b0987e644 Mon Sep 17 00:00:00 2001
From: DMRobertson <DMRobertson@users.noreply.github.com>
Date: Tue, 1 Aug 2023 11:02:34 +0000
Subject: deploy: 190c990a76ac0faaaec31340a721cee4d172016a

---
 .../usage/configuration/config_documentation.html  | 79 +++++++++++++++++++---
 1 file changed, 71 insertions(+), 8 deletions(-)

(limited to 'latest/usage/configuration/config_documentation.html')

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>.
-- 
cgit 1.5.1