Matrix-Mirrors/synapse-product
1
0
Fork 0
mirror of https://git.anonymousland.org/anonymousland/synapse-product.git synced 2024-12-19 22:34:17 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update worker docs to update preferred settings for pusher and federation_sender (#14493)

Browse Source 
* 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.
This commit is contained in:
realtyem 2022-12-02 05:38:01 -06:00 committed by GitHub
parent 656dce4baf
commit 6acb6d772a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 53 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
changelog.d/14493.doc Normal file
View File

@ -0,0 +1 @@
Update worker settings for `pusher` and `federation_sender` functionality.

75
docs/usage/configuration/config_documentation.md
View File

@ -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
``` ```

8
docs/workers.md
View File

@ -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`