config_documentation.md

Note also the configuration above for
[coordinating a cluster of workers](#coordinating-workers).

For guidance on setting up workers, see the [worker documentation](../../workers.md).

---
### `worker_app`

The type of worker. The currently available worker applications are listed
in [worker documentation](../../workers.md#available-worker-applications).

The most common worker is the
[`synapse.app.generic_worker`](../../workers.md#synapseappgeneric_worker).

Example configuration:
```yaml
worker_app: synapse.app.generic_worker
```
---
### `worker_name`

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 `worker_name`.

Example configuration:
```yaml
worker_name: generic_worker1
```
---
### `worker_replication_host`
*Deprecated as of version 1.84.0. Place `host` under `main` entry on the [`instance_map`](#instance_map) in your shared yaml configuration instead.*

The HTTP replication endpoint that it should talk to on the main Synapse process.
The main Synapse process defines this with a `replication` resource in
[`listeners` option](#listeners).

Example configuration:
```yaml
worker_replication_host: 127.0.0.1
```
---
### `worker_replication_http_port`
*Deprecated as of version 1.84.0. Place `port` under `main` entry on the [`instance_map`](#instance_map) in your shared yaml configuration instead.*

The HTTP replication port that it should talk to on the main Synapse process.
The main Synapse process defines this with a `replication` resource in
[`listeners` option](#listeners).

Example configuration:
```yaml
worker_replication_http_port: 9093
```
---
### `worker_replication_http_tls`
*Deprecated as of version 1.84.0. Place `tls` under `main` entry on the [`instance_map`](#instance_map) in your shared yaml configuration instead.*

Whether TLS should be used for talking to the HTTP replication port on the main
Synapse process.
The main Synapse process defines this with the `tls` option on its [listener](#listeners) that
has the `replication` resource enabled.

**Please note:** by default, it is not safe to expose replication ports to the
public Internet, even with TLS enabled.
See [`worker_replication_secret`](#worker_replication_secret).

Defaults to `false`.

*Added in Synapse 1.72.0.*

Example configuration:
```yaml
worker_replication_http_tls: true
```
---
### `worker_listeners`

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)
in the shared config.

Workers declared in [`stream_writers`](#stream_writers) and [`instance_map`](#instance_map)
 will need to include a `replication` listener here, in order to accept internal HTTP 
requests from other workers.

Example configuration:
```yaml
worker_listeners:
  - type: http
    port: 8083
    resources:
      - names: [client, federation]
```
---
### `worker_manhole`

A worker may have a listener for [`manhole`](../../manhole.md).
It allows server administrators to access a Python shell on the worker.

Example configuration:
```yaml
worker_manhole: 9000
```

This is a short form for:
```yaml
worker_listeners:
  - port: 9000
    bind_addresses: ['127.0.0.1']
    type: manhole
```

It needs also an additional [`manhole_settings`](#manhole_settings) configuration.

---
### `worker_daemonize`

Specifies whether the worker should be started as a daemon process.
If Synapse is being managed by [systemd](../../systemd-with-workers/), this option
must be omitted or set to `false`.

Defaults to `false`.

Example configuration:
```yaml
worker_daemonize: true
```
---
### `worker_pid_file`

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.
This option defines the location of that "pid file".

This option is required if `worker_daemonize` is `true` and ignored
otherwise. It has no default.

See also the [`pid_file` option](#pid_file) option for the main Synapse process.

Example configuration:
```yaml
worker_pid_file: DATADIR/generic_worker1.pid
```
---
### `worker_log_config`

This option specifies a yaml python logging config file as described
[here](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema).
See also the [`log_config` option](#log_config) option for the main Synapse process.

Example configuration:
```yaml
worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
```
---
## Background Updates
Configuration settings related to background updates.

---
### `background_updates`

Background updates are database updates that are run in the background in batches.
The duration, minimum batch size, default batch size, whether to sleep between batches and if so, how long to
sleep can all be configured. This is helpful to speed up or slow down the updates.
This setting has the following sub-options:
* `background_update_duration_ms`: How long in milliseconds to run a batch of background updates for. Defaults to 100.
   Set a different time to change the default.
* `sleep_enabled`: Whether to sleep between updates. Defaults to true. Set to false to change the default.
* `sleep_duration_ms`: If sleeping between updates, how long in milliseconds to sleep for. Defaults to 1000.
   Set a duration to change the default.
* `min_batch_size`: Minimum size a batch of background updates can be. Must be greater than 0. Defaults to 1.
   Set a size to change the default.
* `default_batch_size`: The batch size to use for the first iteration of a new background update. The default is 100.
   Set a size to change the default.

Example configuration:
```yaml
background_updates:
    background_update_duration_ms: 500
    sleep_enabled: false
    sleep_duration_ms: 300
    min_batch_size: 10
    default_batch_size: 50
```