Update worker docs to update preferred settings for pusher and federation_sender (#14493)
* Fix one typo on line 3700(and apparently do something to other lines, no idea) * Update config_documentation.md with more information about how federation_senders and pushers settings can be handled. Specifically, that the instance map style of config does not require the special other variables that enable and disable functionality and that a single worker CAN be added to the map not only just two or more. * Extra line here for consistency and appearance. * Add link to sygnal repo. * Add deprecation notice to workers.md and point to the newer alternative method of defining this functionality. * Changelog * Correct version number of Synapse the deprecation is happening in. * Update quiet deprecation with simple notice and suggestion.pull/14600/head
parent
656dce4baf
commit
6acb6d772a
|
@ -0,0 +1 @@
|
||||||
|
Update worker settings for `pusher` and `federation_sender` functionality.
|
|
@ -858,7 +858,7 @@ 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
|
filter events received over federation so that events that should have been
|
||||||
purged are ignored and not stored again.
|
purged are ignored and not stored again.
|
||||||
|
|
||||||
The message retention policies feature is disabled by default. Please be advised
|
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
|
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
|
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
|
is less risky than deleting newer history but in general caution is advised when enabling this
|
||||||
|
@ -3003,7 +3003,7 @@ Options for each entry include:
|
||||||
which is set to the claims returned by the UserInfo Endpoint and/or
|
which is set to the claims returned by the UserInfo Endpoint and/or
|
||||||
in the ID Token.
|
in the ID Token.
|
||||||
|
|
||||||
* `backchannel_logout_enabled`: set to `true` to process OIDC Back-Channel Logout notifications.
|
* `backchannel_logout_enabled`: set to `true` to process OIDC Back-Channel Logout notifications.
|
||||||
Those notifications are expected to be received on `/_synapse/client/oidc/backchannel_logout`.
|
Those notifications are expected to be received on `/_synapse/client/oidc/backchannel_logout`.
|
||||||
Defaults to `false`.
|
Defaults to `false`.
|
||||||
|
|
||||||
|
@ -3425,7 +3425,7 @@ This option has the following sub-options:
|
||||||
NB. If you set this to true, and the last time the user_directory search
|
NB. If you set this to true, and the last time the user_directory search
|
||||||
indexes were (re)built was before Synapse 1.44, you'll have to
|
indexes were (re)built was before Synapse 1.44, you'll have to
|
||||||
rebuild the indexes in order to search through all known users.
|
rebuild the indexes in order to search through all known users.
|
||||||
|
|
||||||
These indexes are built the first time Synapse starts; admins can
|
These indexes are built the first time Synapse starts; admins can
|
||||||
manually trigger a rebuild via the API following the instructions
|
manually trigger a rebuild via the API following the instructions
|
||||||
[for running background updates](../administration/admin_api/background_updates.md#run),
|
[for running background updates](../administration/admin_api/background_updates.md#run),
|
||||||
|
@ -3684,7 +3684,7 @@ As a result, the worker configuration is divided into two parts.
|
||||||
|
|
||||||
1. The first part (in this section of the manual) defines which shardable tasks
|
1. The first part (in this section of the manual) defines which shardable tasks
|
||||||
are delegated to privileged workers. This allows unprivileged workers to make
|
are delegated to privileged workers. This allows unprivileged workers to make
|
||||||
request a privileged worker to act on their behalf.
|
requests to a privileged worker to act on their behalf.
|
||||||
1. [The second part](#individual-worker-configuration)
|
1. [The second part](#individual-worker-configuration)
|
||||||
controls the behaviour of individual workers in isolation.
|
controls the behaviour of individual workers in isolation.
|
||||||
|
|
||||||
|
@ -3696,7 +3696,7 @@ For guidance on setting up workers, see the [worker documentation](../../workers
|
||||||
A shared secret used by the replication APIs on the main process to authenticate
|
A shared secret used by the replication APIs on the main process to authenticate
|
||||||
HTTP requests from workers.
|
HTTP requests from workers.
|
||||||
|
|
||||||
The default, this value is omitted (equivalently `null`), which means that
|
The default, this value is omitted (equivalently `null`), which means that
|
||||||
traffic between the workers and the main process is not authenticated.
|
traffic between the workers and the main process is not authenticated.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
|
@ -3706,6 +3706,8 @@ worker_replication_secret: "secret_secret"
|
||||||
---
|
---
|
||||||
### `start_pushers`
|
### `start_pushers`
|
||||||
|
|
||||||
|
Unnecessary to set if using [`pusher_instances`](#pusher_instances) with [`generic_workers`](../../workers.md#synapseappgeneric_worker).
|
||||||
|
|
||||||
Controls sending of push notifications on the main process. Set to `false`
|
Controls sending of push notifications on the main process. Set to `false`
|
||||||
if using a [pusher worker](../../workers.md#synapseapppusher). Defaults to `true`.
|
if using a [pusher worker](../../workers.md#synapseapppusher). Defaults to `true`.
|
||||||
|
|
||||||
|
@ -3716,25 +3718,30 @@ start_pushers: false
|
||||||
---
|
---
|
||||||
### `pusher_instances`
|
### `pusher_instances`
|
||||||
|
|
||||||
It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher),
|
It is possible to scale the processes that handle sending push notifications to [sygnal](https://github.com/matrix-org/sygnal)
|
||||||
in which case the work is balanced across them. Use this setting to list the pushers by
|
and email by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding it's [`worker_name`](#worker_name) to
|
||||||
[`worker_name`](#worker_name). Ensure the main process and all pusher workers are
|
a `pusher_instances` map. Doing so will remove handling of this function from the main
|
||||||
restarted after changing this option.
|
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.
|
||||||
|
|
||||||
If no or only one pusher worker is configured, this setting is not necessary.
|
Example configuration for a single worker:
|
||||||
The main process will send out push notifications by default if you do not disable
|
```yaml
|
||||||
it by setting [`start_pushers: false`](#start_pushers).
|
pusher_instances:
|
||||||
|
- pusher_worker1
|
||||||
Example configuration:
|
```
|
||||||
|
And for multiple workers:
|
||||||
```yaml
|
```yaml
|
||||||
start_pushers: false
|
|
||||||
pusher_instances:
|
pusher_instances:
|
||||||
- pusher_worker1
|
- pusher_worker1
|
||||||
- pusher_worker2
|
- pusher_worker2
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
### `send_federation`
|
### `send_federation`
|
||||||
|
|
||||||
|
Unnecessary to set if using [`federation_sender_instances`](#federation_sender_instances) with [`generic_workers`](../../workers.md#synapseappgeneric_worker).
|
||||||
|
|
||||||
Controls sending of outbound federation transactions on the main process.
|
Controls sending of outbound federation transactions on the main process.
|
||||||
Set to `false` if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
|
Set to `false` if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
|
||||||
Defaults to `true`.
|
Defaults to `true`.
|
||||||
|
@ -3746,29 +3753,36 @@ send_federation: false
|
||||||
---
|
---
|
||||||
### `federation_sender_instances`
|
### `federation_sender_instances`
|
||||||
|
|
||||||
It is possible to run multiple
|
It is possible to scale the processes that handle sending outbound federation requests
|
||||||
[federation sender worker](../../workers.md#synapseappfederation_sender), in which
|
by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding it's [`worker_name`](#worker_name) to
|
||||||
case the work is balanced across them. Use this setting to list the senders.
|
a `federation_sender_instances` 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.
|
||||||
|
|
||||||
This configuration setting must be shared between all federation sender workers, and if
|
This configuration setting must be shared between all workers handling federation
|
||||||
changed all federation sender workers must be stopped at the same time and then
|
sending, and if changed all federation sender workers must be stopped at the same time
|
||||||
started, to ensure that all instances are running with the same config (otherwise
|
and then started, to ensure that all instances are running with the same config (otherwise
|
||||||
events may be dropped).
|
events may be dropped).
|
||||||
|
|
||||||
Example configuration:
|
Example configuration for a single worker:
|
||||||
```yaml
|
```yaml
|
||||||
send_federation: false
|
|
||||||
federation_sender_instances:
|
federation_sender_instances:
|
||||||
- federation_sender1
|
- federation_sender1
|
||||||
```
|
```
|
||||||
|
And for multiple workers:
|
||||||
|
```yaml
|
||||||
|
federation_sender_instances:
|
||||||
|
- federation_sender1
|
||||||
|
- federation_sender2
|
||||||
|
```
|
||||||
---
|
---
|
||||||
### `instance_map`
|
### `instance_map`
|
||||||
|
|
||||||
When using workers this should be a map from [`worker_name`](#worker_name) to the
|
When using workers this should be a map from [`worker_name`](#worker_name) to the
|
||||||
HTTP replication listener of the worker, if configured.
|
HTTP replication listener of the worker, if configured.
|
||||||
Each worker declared under [`stream_writers`](../../workers.md#stream-writers) needs
|
Each worker declared under [`stream_writers`](../../workers.md#stream-writers) needs
|
||||||
a HTTP replication listener, and that listener should be included in the `instance_map`.
|
a HTTP replication listener, and that listener should be included in the `instance_map`.
|
||||||
(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 `instance_map`.)
|
listed in the `instance_map`.)
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
|
@ -3902,8 +3916,8 @@ worker_replication_http_tls: true
|
||||||
---
|
---
|
||||||
### `worker_listeners`
|
### `worker_listeners`
|
||||||
|
|
||||||
A worker can handle HTTP requests. To do so, a `worker_listeners` option
|
A worker can handle HTTP requests. To do so, a `worker_listeners` option
|
||||||
must be declared, in the same way as the [`listeners` option](#listeners)
|
must be declared, in the same way as the [`listeners` option](#listeners)
|
||||||
in the shared config.
|
in the shared config.
|
||||||
|
|
||||||
Workers declared in [`stream_writers`](#stream_writers) will need to include a
|
Workers declared in [`stream_writers`](#stream_writers) will need to include a
|
||||||
|
@ -3922,7 +3936,7 @@ worker_listeners:
|
||||||
### `worker_daemonize`
|
### `worker_daemonize`
|
||||||
|
|
||||||
Specifies whether the worker should be started as a daemon process.
|
Specifies whether the worker should be started as a daemon process.
|
||||||
If Synapse is being managed by [systemd](../../systemd-with-workers/README.md), this option
|
If Synapse is being managed by [systemd](../../systemd-with-workers/README.md), this option
|
||||||
must be omitted or set to `false`.
|
must be omitted or set to `false`.
|
||||||
|
|
||||||
Defaults to `false`.
|
Defaults to `false`.
|
||||||
|
@ -3934,11 +3948,11 @@ worker_daemonize: true
|
||||||
---
|
---
|
||||||
### `worker_pid_file`
|
### `worker_pid_file`
|
||||||
|
|
||||||
When running a worker as a daemon, we need a place to store the
|
When running a worker as a daemon, we need a place to store the
|
||||||
[PID](https://en.wikipedia.org/wiki/Process_identifier) of the worker.
|
[PID](https://en.wikipedia.org/wiki/Process_identifier) of the worker.
|
||||||
This option defines the location of that "pid file".
|
This option defines the location of that "pid file".
|
||||||
|
|
||||||
This option is required if `worker_daemonize` is `true` and ignored
|
This option is required if `worker_daemonize` is `true` and ignored
|
||||||
otherwise. It has no default.
|
otherwise. It has no default.
|
||||||
|
|
||||||
See also the [`pid_file` option](#pid_file) option for the main Synapse process.
|
See also the [`pid_file` option](#pid_file) option for the main Synapse process.
|
||||||
|
@ -3988,4 +4002,3 @@ background_updates:
|
||||||
min_batch_size: 10
|
min_batch_size: 10
|
||||||
default_batch_size: 50
|
default_batch_size: 50
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
@ -505,6 +505,9 @@ worker application type.
|
||||||
|
|
||||||
### `synapse.app.pusher`
|
### `synapse.app.pusher`
|
||||||
|
|
||||||
|
It is likely this option will be deprecated in the future and is not recommended for new
|
||||||
|
installations. Instead, [use `synapse.app.generic_worker` with the `pusher_instances`](usage/configuration/config_documentation.md#pusher_instances).
|
||||||
|
|
||||||
Handles sending push notifications to sygnal and email. Doesn't handle any
|
Handles sending push notifications to sygnal and email. Doesn't handle any
|
||||||
REST endpoints itself, but you should set
|
REST endpoints itself, but you should set
|
||||||
[`start_pushers: false`](usage/configuration/config_documentation.md#start_pushers) in the
|
[`start_pushers: false`](usage/configuration/config_documentation.md#start_pushers) in the
|
||||||
|
@ -543,6 +546,9 @@ Note this worker cannot be load-balanced: only one instance should be active.
|
||||||
|
|
||||||
### `synapse.app.federation_sender`
|
### `synapse.app.federation_sender`
|
||||||
|
|
||||||
|
It is likely this option will be deprecated in the future and not recommended for
|
||||||
|
new installations. Instead, [use `synapse.app.generic_worker` with the `federation_sender_instances`](usage/configuration/config_documentation.md#federation_sender_instances).
|
||||||
|
|
||||||
Handles sending federation traffic to other servers. Doesn't handle any
|
Handles sending federation traffic to other servers. Doesn't handle any
|
||||||
REST endpoints itself, but you should set
|
REST endpoints itself, but you should set
|
||||||
[`send_federation: false`](usage/configuration/config_documentation.md#send_federation)
|
[`send_federation: false`](usage/configuration/config_documentation.md#send_federation)
|
||||||
|
@ -639,7 +645,9 @@ equivalent to `synapse.app.generic_worker`:
|
||||||
* `synapse.app.client_reader`
|
* `synapse.app.client_reader`
|
||||||
* `synapse.app.event_creator`
|
* `synapse.app.event_creator`
|
||||||
* `synapse.app.federation_reader`
|
* `synapse.app.federation_reader`
|
||||||
|
* `synapse.app.federation_sender`
|
||||||
* `synapse.app.frontend_proxy`
|
* `synapse.app.frontend_proxy`
|
||||||
|
* `synapse.app.pusher`
|
||||||
* `synapse.app.synchrotron`
|
* `synapse.app.synchrotron`
|
||||||
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue