deploy: 1357ae869f279a3f0855c1b1c2750eca2887928e

1 files changed, 223 insertions, 57 deletions

diff --git a/develop/print.html b/develop/print.html
index 03277111d5..feddf18867 100644
--- a/develop/print.html
+++ b/develop/print.html
@@ -3411,7 +3411,7 @@ including _matrix/...). This is the same URL a user might enter into the
 'Custom Homeserver URL' field on their client. If you use Synapse with a
 reverse proxy, this should be the URL to reach Synapse via the proxy.
 Otherwise, it should be the URL to reach Synapse's client HTTP listener (see
-'listeners' below).</p>
+<a href="usage/configuration/config_documentation.html#listeners">'listeners'</a> below).</p>
 <p>Defaults to <code>https://&lt;server_name&gt;/</code>.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">public_baseurl: https://example.com/
@@ -4405,7 +4405,8 @@ when Synapse is started.</p>
 <p>Config options related to logging.</p>
 <hr />
 <h3 id="log_config"><a class="header" href="#log_config"><code>log_config</code></a></h3>
-<p>This option specifies a yaml python logging config file as described <a href="https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema">here</a>.</p>
+<p>This option specifies a yaml python logging config file as described
+<a href="https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema">here</a>.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">log_config: &quot;CONFDIR/SERVERNAME.log.config&quot;
 </code></pre>
@@ -6425,31 +6426,82 @@ mostly related to trace sampling which is documented <a href="https://www.jaeger
         false
 </code></pre>
 <hr />
-<h2 id="workers"><a class="header" href="#workers">Workers</a></h2>
-<p>Configuration options related to workers.</p>
+<h2 id="coordinating-workers"><a class="header" href="#coordinating-workers">Coordinating workers</a></h2>
+<p>Configuration options related to workers which belong in the main config file
+(usually called <code>homeserver.yaml</code>).
+A Synapse deployment can scale horizontally by running multiple Synapse processes
+called <em>workers</em>. Incoming requests are distributed between workers to handle higher
+loads. Some workers are privileged and can accept requests from other workers.</p>
+<p>As a result, the worker configuration is divided into two parts.</p>
+<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>
+<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>
+<p>For guidance on setting up workers, see the <a href="usage/configuration/../../workers.html">worker documentation</a>.</p>
+<hr />
+<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 
+traffic between the workers and the main process is not authenticated.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot;
+</code></pre>
+<hr />
+<h3 id="start_pushers"><a class="header" href="#start_pushers"><code>start_pushers</code></a></h3>
+<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>
+<pre><code class="language-yaml">start_pushers: false
+</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:
+  - pusher_worker1
+  - pusher_worker2
+</code></pre>
 <hr />
 <h3 id="send_federation"><a class="header" href="#send_federation"><code>send_federation</code></a></h3>
 <p>Controls sending of outbound federation transactions on the main process.
-Set to false if using a federation sender worker. Defaults to true.</p>
+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>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">send_federation: false
 </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 federation sender workers, in which case the
-work is balanced across them. Use this setting to list the senders.</p>
+<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
 events may be dropped).</p>
 <p>Example configuration:</p>
-<pre><code class="language-yaml">federation_sender_instances:
+<pre><code class="language-yaml">send_federation: false
+federation_sender_instances:
   - federation_sender1
 </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 worker name to the
-HTTP replication listener of the worker, if configured.</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.
+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 
+listed in the <code>instance_map</code>.)</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">instance_map:
   worker1:
@@ -6459,8 +6511,10 @@ HTTP replication listener of the worker, if configured.</p>
 <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
-handle event persistence and typing notifications. Any worker
-specified here must also be in the <code>instance_map</code>.</p>
+handle writing to streams such as event persistence and typing notifications.
+Any worker specified here must also be in the <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a>.</p>
+<p>See the list of available streams in the
+<a href="usage/configuration/../../workers.html#stream-writers">worker documentation</a>.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">stream_writers:
   events: worker1
@@ -6468,22 +6522,15 @@ specified here must also be in the <code>instance_map</code>.</p>
 </code></pre>
 <hr />
 <h3 id="run_background_tasks_on"><a class="header" href="#run_background_tasks_on"><code>run_background_tasks_on</code></a></h3>
-<p>The worker that is used to run background tasks (e.g. cleaning up expired
-data). If not provided this defaults to the main process.</p>
+<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
+defaults to the main process.</p>
 <p>Example configuration:</p>
 <pre><code class="language-yaml">run_background_tasks_on: worker1
 </code></pre>
 <hr />
-<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 to authenticate HTTP requests
-from workers.</p>
-<p>By default this is unused and traffic is not authenticated.</p>
-<p>Example configuration:</p>
-<pre><code class="language-yaml">worker_replication_secret: &quot;secret_secret&quot;
-</code></pre>
 <h3 id="redis"><a class="header" href="#redis"><code>redis</code></a></h3>
-<p>Configuration for Redis when using workers. This <em>must</em> be enabled when
-using workers (unless using old style direct TCP configuration).
+<p>Configuration for Redis when using workers. This <em>must</em> be enabled when using workers.
 This setting has the following sub-options:</p>
 <ul>
 <li><code>enabled</code>: whether to use Redis support. Defaults to false.</li>
@@ -6498,6 +6545,90 @@ localhost and 6379</li>
   port: 6379
   password: &lt;secret_password&gt;
 </code></pre>
+<hr />
+<h2 id="individual-worker-configuration"><a class="header" href="#individual-worker-configuration">Individual worker configuration</a></h2>
+<p>These options configure an individual worker, in its worker configuration file.
+They should be not be provided when configuring the main process.</p>
+<p>Note also the configuration above for
+<a href="usage/configuration/config_documentation.html#coordinating-workers">coordinating a cluster of workers</a>.</p>
+<p>For guidance on setting up workers, see the <a href="usage/configuration/../../workers.html">worker documentation</a>.</p>
+<hr />
+<h3 id="worker_app"><a class="header" href="#worker_app"><code>worker_app</code></a></h3>
+<p>The type of worker. The currently available worker applications are listed
+in <a href="usage/configuration/../../workers.html#available-worker-applications">worker documentation</a>.</p>
+<p>The most common worker is the
+<a href="usage/configuration/../../workers.html#synapseappgeneric_worker"><code>synapse.app.generic_worker</code></a>.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_app: synapse.app.generic_worker
+</code></pre>
+<hr />
+<h3 id="worker_name"><a class="header" href="#worker_name"><code>worker_name</code></a></h3>
+<p>A unique name for the worker. The worker needs a name to be addressed in
+further parameters and identification in log files. We strongly recommend
+giving each worker a unique <code>worker_name</code>.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_name: generic_worker1
+</code></pre>
+<hr />
+<h3 id="worker_replication_host"><a class="header" href="#worker_replication_host"><code>worker_replication_host</code></a></h3>
+<p>The HTTP replication endpoint that it should talk to on the main Synapse process.
+The main Synapse process defines this with a <code>replication</code> resource in
+<a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code> option</a>.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_replication_host: 127.0.0.1
+</code></pre>
+<hr />
+<h3 id="worker_replication_http_port"><a class="header" href="#worker_replication_http_port"><code>worker_replication_http_port</code></a></h3>
+<p>The HTTP replication port that it should talk to on the main Synapse process.
+The main Synapse process defines this with a <code>replication</code> resource in
+<a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code> option</a>.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_replication_http_port: 9093
+</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> 
+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
+other workers.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_listeners:
+  - type: http
+    port: 8083
+    resources:
+      - names: [client, federation]
+</code></pre>
+<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 
+must be omitted or set to <code>false</code>.</p>
+<p>Defaults to <code>false</code>.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_daemonize: true
+</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 
+<a href="https://en.wikipedia.org/wiki/Process_identifier">PID</a> of the worker.
+This option defines the location of that &quot;pid file&quot;.</p>
+<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>
+<pre><code class="language-yaml">worker_pid_file: DATADIR/generic_worker1.pid
+</code></pre>
+<hr />
+<h3 id="worker_log_config"><a class="header" href="#worker_log_config"><code>worker_log_config</code></a></h3>
+<p>This option specifies a yaml python logging config file as described
+<a href="https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema">here</a>.
+See also the <a href="usage/configuration/config_documentation.html#log_config"><code>log_config</code> option</a> option for the main Synapse process.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
+</code></pre>
+<hr />
 <h2 id="background-updates"><a class="header" href="#background-updates">Background Updates</a></h2>
 <p>Configuration settings related to background updates.</p>
 <hr />
@@ -6595,7 +6726,7 @@ It should be named <code>&lt;SERVERNAME&gt;.log.config</code> by default.</p>
 # Synapse also supports structured logging for machine readable logs which can
 # be ingested by ELK stacks. See [2] for details.
 #
-# [1]: https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
+# [1]: https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema
 # [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html
 
 version: 1
@@ -9873,10 +10004,12 @@ need its own configuration file and can take all of its configuration from the
 shared configuration file.</p>
 <h3 id="shared-configuration"><a class="header" href="#shared-configuration">Shared configuration</a></h3>
 <p>Normally, only a couple of changes are needed to make an existing configuration
-file suitable for use with workers. First, you need to enable an &quot;HTTP replication
-listener&quot; for the main process; and secondly, you need to enable redis-based
-replication. Optionally, a shared secret can be used to authenticate HTTP
-traffic between workers. For example:</p>
+file suitable for use with workers. First, you need to enable an
+<a href="usage/configuration/config_documentation.html#listeners">&quot;HTTP replication listener&quot;</a>
+for the main process; and secondly, you need to enable
+<a href="usage/configuration/config_documentation.html#redis">redis-based replication</a>.
+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:</p>
 <pre><code class="language-yaml"># extend the existing `listeners` section. This defines the ports that the
 # main process will listen on.
 listeners:
@@ -9893,23 +10026,26 @@ worker_replication_secret: &quot;&quot;
 redis:
     enabled: true
 </code></pre>
-<p>See the <a href="usage/configuration/config_documentation.html">configuration manual</a> for the full documentation of each option.</p>
+<p>See the <a href="usage/configuration/config_documentation.html">configuration manual</a>
+for the full documentation of each option.</p>
 <p>Under <strong>no circumstances</strong> should the replication listener be exposed to the
 public internet; replication traffic is:</p>
 <ul>
 <li>always unencrypted</li>
-<li>unauthenticated, unless <code>worker_replication_secret</code> is configured</li>
+<li>unauthenticated, unless <a href="usage/configuration/config_documentation.html#worker_replication_secret"><code>worker_replication_secret</code></a>
+is configured</li>
 </ul>
 <h3 id="worker-configuration"><a class="header" href="#worker-configuration">Worker configuration</a></h3>
 <p>In the config file for each worker, you must specify:</p>
 <ul>
-<li>The type of worker (<code>worker_app</code>). The currently available worker applications are listed below.</li>
-<li>A unique name for the worker (<code>worker_name</code>).</li>
+<li>The type of worker (<a href="usage/configuration/config_documentation.html#worker_app"><code>worker_app</code></a>).
+The currently available worker applications are listed <a href="workers.html#available-worker-applications">below</a>.</li>
+<li>A unique name for the worker (<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>).</li>
 <li>The HTTP replication endpoint that it should talk to on the main synapse process
-(<code>worker_replication_host</code> and <code>worker_replication_http_port</code>)</li>
-<li>If handling HTTP requests, a <code>worker_listeners</code> option with an <code>http</code>
-listener, in the same way as the <a href="usage/configuration/config_documentation.html#listeners"><code>listeners</code></a>
-option in the shared config.</li>
+(<a href="usage/configuration/config_documentation.html#worker_replication_host"><code>worker_replication_host</code></a> and
+<a href="usage/configuration/config_documentation.html#worker_replication_http_port"><code>worker_replication_http_port</code></a>).</li>
+<li>If handling HTTP requests, a <a href="usage/configuration/config_documentation.html#worker_listeners"><code>worker_listeners</code></a> option
+with an <code>http</code> listener.</li>
 <li>If handling the <code>^/_matrix/client/v3/keys/upload</code> endpoint, the HTTP URI for
 the main process (<code>worker_main_http_uri</code>).</li>
 </ul>
@@ -10067,7 +10203,8 @@ For multiple workers not handling the SSO endpoints properly, see
 <a href="https://github.com/matrix-org/synapse/issues/7530">#7530</a> and
 <a href="https://github.com/matrix-org/synapse/issues/9427">#9427</a>.</p>
 <p>Note that a <a href="usage/configuration/config_documentation.html#listeners">HTTP listener</a>
-with <code>client</code> and <code>federation</code> <code>resources</code> must be configured in the <code>worker_listeners</code>
+with <code>client</code> and <code>federation</code> <code>resources</code> must be configured in the
+<a href="usage/configuration/config_documentation.html#worker_listeners"><code>worker_listeners</code></a>
 option in the worker config.</p>
 <h4 id="load-balancing"><a class="header" href="#load-balancing">Load balancing</a></h4>
 <p>It is possible to run multiple instances of this worker app, with incoming requests
@@ -10100,9 +10237,10 @@ effects of bursts of events from that bridge on events sent by normal users.</p>
 of the main process to a particular worker.</p>
 <p>To enable this, the worker must have a
 <a href="usage/configuration/config_documentation.html#listeners">HTTP <code>replication</code> listener</a> configured,
-have a <code>worker_name</code> and be listed in the <code>instance_map</code> config. The same worker
-can handle multiple streams, but unless otherwise documented, each stream can only
-have a single writer.</p>
+have a <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>
+and be listed in the <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a>
+config. The same worker can handle multiple streams, but unless otherwise documented,
+each stream can only have a single writer.</p>
 <p>For example, to move event persistence off to a dedicated worker, the shared
 configuration would include:</p>
 <pre><code class="language-yaml">instance_map:
@@ -10142,9 +10280,24 @@ worker_log_config: /etc/matrix-synapse/event-persister-log.yaml
 be routed to the workers handling that stream. See below for the currently supported
 streams and the endpoints associated with them:</p>
 <h5 id="the-events-stream"><a class="header" href="#the-events-stream">The <code>events</code> stream</a></h5>
-<p>The <code>events</code> stream experimentally supports having multiple writers, where work
-is sharded between them by room ID. Note that you <em>must</em> restart all worker
-instances when adding or removing event persisters. An example <code>stream_writers</code>
+<p>The <code>events</code> stream experimentally supports having multiple writer workers, where load
+is sharded between them by room ID. Each writer is called an <em>event persister</em>. They are
+responsible for</p>
+<ul>
+<li>receiving new events,</li>
+<li>linking them to those already in the room <a href="development/room-dag-concepts.html">DAG</a>,</li>
+<li>persisting them to the DB, and finally</li>
+<li>updating the events stream.</li>
+</ul>
+<p>Because load is sharded in this way, you <em>must</em> restart all worker instances when 
+adding or removing event persisters.</p>
+<p>An <code>event_persister</code> should not be mistaken for an <code>event_creator</code>.
+An <code>event_creator</code> listens for requests from clients to create new events and does
+so. It will then pass those events over HTTP replication to any configured event
+persisters (or the main process if none are configured).</p>
+<p>Note that <code>event_creator</code>s and <code>event_persister</code>s are implemented using the same
+<a href="workers.html#synapse.app.generic_worker"><code>synapse.app.generic_worker</code></a>.</p>
+<p>An example <a href="usage/configuration/config_documentation.html#stream_writers"><code>stream_writers</code></a>
 configuration with multiple writers:</p>
 <pre><code class="language-yaml">stream_writers:
     events:
@@ -10183,13 +10336,15 @@ the stream writer for the <code>presence</code> stream:</p>
 worker. Background tasks are run periodically or started via replication. Exactly
 which tasks are configured to run depends on your Synapse configuration (e.g. if
 stats is enabled). This worker doesn't handle any REST endpoints itself.</p>
-<p>To enable this, the worker must have a <code>worker_name</code> and can be configured to run
-background tasks. For example, to move background tasks to a dedicated worker,
-the shared configuration would include:</p>
+<p>To enable this, the worker must have a unique
+<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>
+and can be configured to run background tasks. For example, to move background tasks
+to a dedicated worker, the shared configuration would include:</p>
 <pre><code class="language-yaml">run_background_tasks_on: background_worker
 </code></pre>
-<p>You might also wish to investigate the <code>update_user_directory_from_worker</code> and
-<code>media_instance_running_background_jobs</code> settings.</p>
+<p>You might also wish to investigate the
+<a href="workers.html#updating-the-user-directory"><code>update_user_directory_from_worker</code></a> and
+<a href="workers.html#synapseappmedia_repository"><code>media_instance_running_background_jobs</code></a> settings.</p>
 <p>An example for a dedicated background worker instance:</p>
 <pre><code class="language-yaml">worker_app: synapse.app.generic_worker
 worker_name: background_worker
@@ -10227,11 +10382,15 @@ after setting this option in the shared configuration!</p>
 worker application type.</p>
 <h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3>
 <p>Handles sending push notifications to sygnal and email. Doesn't handle any
-REST endpoints itself, but you should set <code>start_pushers: False</code> in the
+REST endpoints itself, but you should set
+<a href="usage/configuration/config_documentation.html#start_pushers"><code>start_pushers: false</code></a> in the
 shared configuration file to stop the main synapse sending push notifications.</p>
-<p>To run multiple instances at once the <code>pusher_instances</code> option should list all
-pusher instances by their worker name, e.g.:</p>
-<pre><code class="language-yaml">pusher_instances:
+<p>To run multiple instances at once the
+<a href="usage/configuration/config_documentation.html#pusher_instances"><code>pusher_instances</code></a>
+option should list all pusher instances by their
+<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>, e.g.:</p>
+<pre><code class="language-yaml">start_pushers: false
+pusher_instances:
     - pusher_worker1
     - pusher_worker2
 </code></pre>
@@ -10254,13 +10413,18 @@ shared configuration file to stop the main synapse sending appservice notificati
 <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>Handles sending federation traffic to other servers. Doesn't handle any
-REST endpoints itself, but you should set <code>send_federation: False</code> in the
-shared configuration file to stop the main synapse sending this traffic.</p>
+REST endpoints itself, but you should set
+<a href="usage/configuration/config_documentation.html#send_federation"><code>send_federation: false</code></a>
+in the shared configuration file to stop the main synapse sending this traffic.</p>
 <p>If running multiple federation senders then you must list each
-instance in the <code>federation_sender_instances</code> option by their <code>worker_name</code>.
+instance in the
+<a href="usage/configuration/config_documentation.html#federation_sender_instances"><code>federation_sender_instances</code></a>
+option by their
+<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>.
 All instances must be stopped and started when adding or removing instances.
 For example:</p>
-<pre><code class="language-yaml">federation_sender_instances:
+<pre><code class="language-yaml">send_federation: false
+federation_sender_instances:
     - federation_sender1
     - federation_sender2
 </code></pre>
@@ -10286,7 +10450,9 @@ worker_log_config: /etc/matrix-synapse/federation-sender-log.yaml
 ^/_synapse/admin/v1/quarantine_media/.*$
 ^/_synapse/admin/v1/users/.*/media$
 </code></pre>
-<p>You should also set <code>enable_media_repo: False</code> in the shared configuration
+<p>You should also set
+<a href="usage/configuration/config_documentation.html#enable_media_repo"><code>enable_media_repo: False</code></a>
+in the shared configuration
 file to stop the main synapse running background jobs related to managing the
 media repository. Note that doing so will prevent the main process from being
 able to handle the above endpoints.</p>