config_documentation.md

  Defaults to `false`.

* `backchannel_logout_ignore_sub`: by default, the OIDC Back-Channel Logout feature checks that the
  `sub` claim matches the subject claim received during login. This check can be disabled by setting
  this to `true`. Defaults to `false`.

  You might want to disable this if the `subject_claim` returned by the mapping provider is not `sub`.

It is possible to configure Synapse to only allow logins if certain attributes
match particular values in the OIDC userinfo. The requirements can be listed under
`attribute_requirements` as shown here:
```yaml
attribute_requirements:
     - attribute: family_name
       value: "Stephensson"
     - attribute: groups
       value: "admin"
```
All of the listed attributes must match for the login to be permitted. Additional attributes can be added to
userinfo by expanding the `scopes` section of the OIDC config to retrieve
additional information from the OIDC provider.

If the OIDC claim is a list, then the attribute must match any value in the list.
Otherwise, it must exactly match the value of the claim. Using the example
above, the `family_name` claim MUST be "Stephensson", but the `groups`
claim MUST contain "admin".

Example configuration:
```yaml
oidc_providers:
  # Generic example
  #
  - idp_id: my_idp
    idp_name: "My OpenID provider"
    idp_icon: "mxc://example.com/mediaid"
    discover: false
    issuer: "https://accounts.example.com/"
    client_id: "provided-by-your-issuer"
    client_secret: "provided-by-your-issuer"
    client_auth_method: client_secret_post
    scopes: ["openid", "profile"]
    authorization_endpoint: "https://accounts.example.com/oauth2/auth"
    token_endpoint: "https://accounts.example.com/oauth2/token"
    userinfo_endpoint: "https://accounts.example.com/userinfo"
    jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
    skip_verification: true
    user_mapping_provider:
      config:
        subject_claim: "id"
        localpart_template: "{{ user.login }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
    attribute_requirements:
      - attribute: userGroup
        value: "synapseUsers"
```
---
### `cas_config`

Enable Central Authentication Service (CAS) for registration and login.
Has the following sub-options:
* `enabled`: Set this to true to enable authorization against a CAS server.
   Defaults to false.
* `server_url`: The URL of the CAS authorization endpoint.
* `displayname_attribute`: The attribute of the CAS response to use as the display name.
   If no name is given here, no displayname will be set.
* `required_attributes`:  It is possible to configure Synapse to only allow logins if CAS attributes
   match particular values. All of the keys given below must exist
   and the values must match the given value. Alternately if the given value
   is `None` then any value is allowed (the attribute just must exist).
   All of the listed attributes must match for the login to be permitted.

Example configuration:
```yaml
cas_config:
  enabled: true
  server_url: "https://cas-server.com"
  displayname_attribute: name
  required_attributes:
    userGroup: "staff"
    department: None
```
---
### `sso`

Additional settings to use with single-sign on systems such as OpenID Connect,
SAML2 and CAS.

Server admins can configure custom templates for pages related to SSO. See
[here](../../templates.md) for more information.

Options include:
* `client_whitelist`: A list of client URLs which are whitelisted so that the user does not
   have to confirm giving access to their account to the URL. Any client
   whose URL starts with an entry in the following list will not be subject
   to an additional confirmation step after the SSO login is completed.
   WARNING: An entry such as "https://my.client" is insecure, because it
   will also match "https://my.client.evil.site", exposing your users to
   phishing attacks from evil.site. To avoid this, include a slash after the
   hostname: "https://my.client/".
   The login fallback page (used by clients that don't natively support the
   required login flows) is whitelisted in addition to any URLs in this list.
   By default, this list contains only the login fallback page.
* `update_profile_information`: Use this setting to keep a user's profile fields in sync with information from
   the identity provider. Currently only syncing the displayname is supported. Fields
   are checked on every SSO login, and are updated if necessary.
   Note that enabling this option will override user profile information,
   regardless of whether users have opted-out of syncing that
   information when first signing in. Defaults to false.


Example configuration:
```yaml
sso:
    client_whitelist:
      - https://riot.im/develop
      - https://my.custom.client/
    update_profile_information: true
```
---
### `jwt_config`

JSON web token integration. The following settings can be used to make
Synapse JSON web tokens for authentication, instead of its internal
password database.

Each JSON Web Token needs to contain a "sub" (subject) claim, which is
used as the localpart of the mxid.

Additionally, the expiration time ("exp"), not before time ("nbf"),
and issued at ("iat") claims are validated if present.

Note that this is a non-standard login type and client support is
expected to be non-existent.

See [here](../../jwt.md) for more.

Additional sub-options for this setting include:
* `enabled`: Set to true to enable authorization using JSON web
   tokens. Defaults to false.
* `secret`: This is either the private shared secret or the public key used to
   decode the contents of the JSON web token. Required if `enabled` is set to true.
* `algorithm`: The algorithm used to sign (or HMAC) the JSON web token.
   Supported algorithms are listed
   [here (section JWS)](https://docs.authlib.org/en/latest/specs/rfc7518.html).
   Required if `enabled` is set to true.
* `subject_claim`: Name of the claim containing a unique identifier for the user.
   Optional, defaults to `sub`.
* `issuer`: The issuer to validate the "iss" claim against. Optional. If provided the
   "iss" claim will be required and validated for all JSON web tokens.
* `audiences`: A list of audiences to validate the "aud" claim against. Optional.
   If provided the "aud" claim will be required and validated for all JSON web tokens.
   Note that if the "aud" claim is included in a JSON web token then
   validation will fail without configuring audiences.

Example configuration:
```yaml
jwt_config:
    enabled: true
    secret: "provided-by-your-issuer"
    algorithm: "provided-by-your-issuer"
    subject_claim: "name_of_claim"
    issuer: "provided-by-your-issuer"
    audiences:
        - "provided-by-your-issuer"
```
---
### `password_config`

Use this setting to enable password-based logins.

This setting has the following sub-options:
* `enabled`: Defaults to true.
   Set to false to disable password authentication.
   Set to `only_for_reauth` to allow users with existing passwords to use them
   to log in and reauthenticate, whilst preventing new users from setting passwords.
* `localdb_enabled`: Set to false to disable authentication against the local password
   database. This is ignored if `enabled` is false, and is only useful
   if you have other `password_providers`. Defaults to true.
* `pepper`: Set the value here to a secret random string for extra security.
   DO NOT CHANGE THIS AFTER INITIAL SETUP!
* `policy`: Define and enforce a password policy, such as minimum lengths for passwords, etc.
   Each parameter is optional. This is an implementation of MSC2000. Parameters are as follows:
   * `enabled`: Defaults to false. Set to true to enable.
   * `minimum_length`: Minimum accepted length for a password. Defaults to 0.
   * `require_digit`: Whether a password must contain at least one digit.
      Defaults to false.
   * `require_symbol`: Whether a password must contain at least one symbol.
      A symbol is any character that's not a number or a letter. Defaults to false.
   * `require_lowercase`: Whether a password must contain at least one lowercase letter.
      Defaults to false.
   * `require_uppercase`: Whether a password must contain at least one uppercase letter.
      Defaults to false.


Example configuration:
```yaml
password_config:
   enabled: false
   localdb_enabled: false
   pepper: "EVEN_MORE_SECRET"

   policy:
      enabled: true
      minimum_length: 15
      require_digit: true
      require_symbol: true
      require_lowercase: true
      require_uppercase: true
```
---
### `ui_auth`

The amount of time to allow a user-interactive authentication session to be active.

This defaults to 0, meaning the user is queried for their credentials
before every action, but this can be overridden to allow a single
validation to be re-used.  This weakens the protections afforded by
the user-interactive authentication process, by allowing for multiple
(and potentially different) operations to use the same validation session.

This is ignored for potentially "dangerous" operations (including
deactivating an account, modifying an account password, and
adding a 3PID).

Use the `session_timeout` sub-option here to change the time allowed for credential validation.

Example configuration:
```yaml
ui_auth:
    session_timeout: "15s"
```
---
### `email`

Configuration for sending emails from Synapse.

Server admins can configure custom templates for email content. See
[here](../../templates.md) for more information.

This setting has the following sub-options:
* `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
* `smtp_port`: The port on the mail server for outgoing SMTP. Defaults to 465 if `force_tls` is true, else 25.

  _Changed in Synapse 1.64.0:_ the default port is now aware of `force_tls`.
* `smtp_user` and `smtp_pass`: Username/password for authentication to the SMTP server. By default, no
   authentication is attempted.
* `force_tls`: By default, Synapse connects over plain text and then optionally upgrades
   to TLS via STARTTLS. If this option is set to true, TLS is used from the start (Implicit TLS),
   and the option `require_transport_security` is ignored.
   It is recommended to enable this if supported by your mail server.

  _New in Synapse 1.64.0._
* `require_transport_security`: Set to true to require TLS transport security for SMTP.
   By default, Synapse will connect over plain text, and will then switch to
   TLS via STARTTLS *if the SMTP server supports it*. If this option is set,
   Synapse will refuse to connect unless the server supports STARTTLS.
* `enable_tls`: By default, if the server supports TLS, it will be used, and the server
   must present a certificate that is valid for 'smtp_host'. If this option
   is set to false, TLS will not be used.
* `notif_from`: defines the "From" address to use when sending emails.
    It must be set if email sending is enabled. The placeholder '%(app)s' will be replaced by the application name,
    which is normally set in `app_name`, but may be overridden by the
    Matrix client application. Note that the placeholder must be written '%(app)s', including the
    trailing 's'.
* `app_name`: `app_name` defines the default value for '%(app)s' in `notif_from` and email
   subjects. It defaults to 'Matrix'.
* `enable_notifs`: Set to true to enable sending emails for messages that the user
   has missed. Disabled by default.
* `notif_for_new_users`: Set to false to disable automatic subscription to email
   notifications for new users. Enabled by default.
* `client_base_url`: Custom URL for client links within the email notifications. By default
   links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`;
   the old name is still supported for backwards-compatibility but is now deprecated.)
* `validation_token_lifetime`: Configures the time that a validation email will expire after sending.
   Defaults to 1h.
* `invite_client_location`: The web client location to direct users to during an invite. This is passed
   to the identity server as the `org.matrix.web_client_location` key. Defaults
   to unset, giving no guidance to the identity server.
* `subjects`: Subjects to use when sending emails from Synapse. The placeholder '%(app)s' will
   be replaced with the value of the `app_name` setting, or by a value dictated by the Matrix client application.
   In addition, each subject can use the following placeholders: '%(person)s', which will be replaced by the displayname
   of the user(s) that sent the message(s), e.g. "Alice and Bob", and '%(room)s', which will be replaced by the name of the room the
   message(s) have been sent to, e.g. "My super room". In addition, emails related to account administration will
   can use the '%(server_name)s' placeholder, which will be replaced by the value of the
   `server_name` setting in your Synapse configuration.

   Here is a list of subjects for notification emails that can be set:
     * `message_from_person_in_room`: Subject to use to notify about one message from one or more user(s) in a
        room which has a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
     * `message_from_person`: Subject to use to notify about one message from one or more user(s) in a
        room which doesn't have a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s..."
     * `messages_from_person`: Subject to use to notify about multiple messages from one or more users in
        a room which doesn't have a name. Defaults to "[%(app)s] You have messages on %(app)s from %(person)s..."
     * `messages_in_room`: Subject to use to notify about multiple messages in a room which has a
        name. Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room..."
     * `messages_in_room_and_others`: Subject to use to notify about multiple messages in multiple rooms.
        Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
     * `messages_from_person_and_others`: Subject to use to notify about multiple messages from multiple persons in
        multiple rooms. This is similar to the setting above except it's used when
        the room in which the notification was triggered has no name. Defaults to
        "[%(app)s] You have messages on %(app)s from %(person)s and others..."
     * `invite_from_person_to_room`: Subject to use to notify about an invite to a room which has a name.
        Defaults to  "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
     * `invite_from_person`: Subject to use to notify about an invite to a room which doesn't have a
        name. Defaults to "[%(app)s] %(person)s has invited you to chat on %(app)s..."
     * `password_reset`: Subject to use when sending a password reset email. Defaults to "[%(server_name)s] Password reset"
     * `email_validation`: Subject to use when sending a verification email to assert an address's
        ownership. Defaults to "[%(server_name)s] Validate your email"

Example configuration:
```yaml
email:
  smtp_host: mail.server
  smtp_port: 587
  smtp_user: "exampleusername"
  smtp_pass: "examplepassword"
  force_tls: true
  require_transport_security: true
  enable_tls: false
  notif_from: "Your Friendly %(app)s homeserver <noreply@example.com>"
  app_name: my_branded_matrix_server
  enable_notifs: true
  notif_for_new_users: false
  client_base_url: "http://localhost/riot"
  validation_token_lifetime: 15m
  invite_client_location: https://app.element.io

  subjects:
    message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
    message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..."
    messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..."
    messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..."
    messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
    messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..."
    invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
    invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..."
    password_reset: "[%(server_name)s] Password reset"
    email_validation: "[%(server_name)s] Validate your email"
```
---
## Push
Configuration settings related to push notifications

---
### `push`

This setting defines options for push notifications.

This option has a number of sub-options. They are as follows:
* `include_content`: Clients requesting push notifications can either have the body of
   the message sent in the notification poke along with other details
   like the sender, or just the event ID and room ID (`event_id_only`).
   If clients choose the to have the body sent, this option controls whether the
   notification request includes the content of the event (other details
   like the sender are still included). If `event_id_only` is enabled, it
   has no effect.
   For modern android devices the notification content will still appear
   because it is loaded by the app. iPhone, however will send a
   notification saying only that a message arrived and who it came from.
   Defaults to true. Set to false to only include the event ID and room ID in push notification payloads.
* `group_unread_count_by_room: false`: When a push notification is received, an unread count is also sent.
   This number can either be calculated as the number of unread messages  for the user, or the number of *rooms* the
   user has unread messages in. Defaults to true, meaning push clients will see the number of
   rooms with unread messages in them. Set to false to instead send the number
   of unread messages.

Example configuration:
```yaml
push:
  include_content: false
  group_unread_count_by_room: false
```
---
## Rooms
Config options relating to rooms.

---
### `encryption_enabled_by_default_for_room_type`

Controls whether locally-created rooms should be end-to-end encrypted by
default.

Possible options are "all", "invite", and "off". They are defined as:

* "all": any locally-created room
* "invite": any room created with the `private_chat` or `trusted_private_chat`
   room creation presets
* "off": this option will take no effect

The default value is "off".

Note that this option will only affect rooms created after it is set. It
will also not affect rooms created by other servers.

Example configuration:
```yaml
encryption_enabled_by_default_for_room_type: invite
```
---
### `user_directory`

This setting defines options related to the user directory.

This option has the following sub-options:
* `enabled`:  Defines whether users can search the user directory. If false then
   empty responses are returned to all queries. Defaults to true.
* `search_all_users`: Defines whether to search all users visible to your HS when searching
   the user directory. If false, search results will only contain users
    visible in public rooms and users sharing a room with the requester.
    Defaults to false.

    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
    rebuild the indexes in order to search through all known users.
    
    These indexes are built the first time Synapse starts; admins can
    manually trigger a rebuild via the API following the instructions
    [for running background updates](../administration/admin_api/background_updates.md#run),
    set to true to return search results containing all known users, even if that
    user does not share a room with the requester.
* `prefer_local_users`: Defines whether to prefer local users in search query results.
   If set to true, local users are more likely to appear above remote users when searching the
   user directory. Defaults to false.

Example configuration:
```yaml
user_directory:
    enabled: false
    search_all_users: true
    prefer_local_users: true
```
---
### `user_consent`

For detailed instructions on user consent configuration, see [here](../../consent_tracking.md).

Parts of this section are required if enabling the `consent` resource under
[`listeners`](#listeners), in particular `template_dir` and `version`.

* `template_dir`: gives the location of the templates for the HTML forms.
  This directory should contain one subdirectory per language (eg, `en`, `fr`),
  and each language directory should contain the policy document (named as
  <version>.html) and a success page (success.html).

* `version`: specifies the 'current' version of the policy document. It defines
   the version to be served by the consent resource if there is no 'v'
   parameter.

* `server_notice_content`: if enabled, will send a user a "Server Notice"
   asking them to consent to the privacy policy. The [`server_notices` section](#server_notices)
   must also be configured for this to work. Notices will *not* be sent to
   guest users unless `send_server_notice_to_guests` is set to true.

* `block_events_error`, if set, will block any attempts to send events
   until the user consents to the privacy policy. The value of the setting is
   used as the text of the error.

* `require_at_registration`, if enabled, will add a step to the registration
   process, similar to how captcha works. Users will be required to accept the
   policy before their account is created.

* `policy_name` is the display name of the policy users will see when registering
   for an account. Has no effect unless `require_at_registration` is enabled.
   Defaults to "Privacy Policy".

Example configuration:
```yaml
user_consent:
  template_dir: res/templates/privacy
  version: 1.0
  server_notice_content:
    msgtype: m.text
    body: >-
      To continue using this homeserver you must review and agree to the
      terms and conditions at %(consent_uri)s
  send_server_notice_to_guests: true
  block_events_error: >-
    To continue using this homeserver you must review and agree to the
    terms and conditions at %(consent_uri)s
  require_at_registration: false
  policy_name: Privacy Policy
```
---
### `stats`

Settings for local room and user statistics collection. See [here](../../room_and_user_statistics.md)
for more.

* `enabled`: Set to false to disable room and user statistics. Note that doing
   so may cause certain features (such as the room directory) not to work
   correctly. Defaults to true.

Example configuration:
```yaml
stats:
  enabled: false
```
---
### `server_notices`

Use this setting to enable a room which can be used to send notices
from the server to users. It is a special room which users cannot leave; notices
in the room come from a special "notices" user id.

If you use this setting, you *must* define the `system_mxid_localpart`
sub-setting, which defines the id of the user which will be used to send the
notices.

Sub-options for this setting include:
* `system_mxid_display_name`: set the display name of the "notices" user
* `system_mxid_avatar_url`: set the avatar for the "notices" user
* `room_name`: set the room name of the server notices room

Example configuration:
```yaml
server_notices:
  system_mxid_localpart: notices
  system_mxid_display_name: "Server Notices"
  system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"
  room_name: "Server Notices"
```
---
### `enable_room_list_search`

Set to false to disable searching the public room list. When disabled
blocks searching local and remote room lists for local and remote
users by always returning an empty list for all queries. Defaults to true.

Example configuration:
```yaml
enable_room_list_search: false
```
---
### `alias_creation_rules`

The `alias_creation_rules` option controls who is allowed to create aliases
on this server.

The format of this option is a list of rules that contain globs that
match against user_id, room_id and the new alias (fully qualified with
server name). The action in the first rule that matches is taken,
which can currently either be "allow" or "deny".

Missing user_id/room_id/alias fields default to "*".

If no rules match the request is denied. An empty list means no one
can create aliases.

Options for the rules include:
* `user_id`: Matches against the creator of the alias. Defaults to "*".
* `alias`: Matches against the alias being created. Defaults to "*".
* `room_id`: Matches against the room ID the alias is being pointed at. Defaults to "*"
* `action`: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.

Example configuration:
```yaml
alias_creation_rules:
  - user_id: "bad_user"
    alias: "spammy_alias"
    room_id: "*"
    action: deny
```
---
### `room_list_publication_rules`

The `room_list_publication_rules` option controls who can publish and
which rooms can be published in the public room list.

The format of this option is the same as that for
`alias_creation_rules`.

If the room has one or more aliases associated with it, only one of
the aliases needs to match the alias rule. If there are no aliases
then only rules with `alias: *` match.

If no rules match the request is denied. An empty list means no one
can publish rooms.

Options for the rules include:
* `user_id`: Matches against the creator of the alias. Defaults to "*".
* `alias`: Matches against any current local or canonical aliases associated with the room. Defaults to "*".
* `room_id`: Matches against the room ID being published. Defaults to "*".
* `action`: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.

Example configuration:
```yaml
room_list_publication_rules:
  - user_id: "*"
    alias: "*"
    room_id: "*"
    action: allow
```

---
### `default_power_level_content_override`

The `default_power_level_content_override` option controls the default power
levels for rooms.

Useful if you know that your users need special permissions in rooms
that they create (e.g. to send particular types of state events without
needing an elevated power level).  This takes the same shape as the
`power_level_content_override` parameter in the /createRoom API, but
is applied before that parameter.

Note that each key provided inside a preset (for example `events` in the example
below) will overwrite all existing defaults inside that key. So in the example
below, newly-created private_chat rooms will have no rules for any event types
except `com.example.foo`.

Example configuration:
```yaml
default_power_level_content_override:
   private_chat: { "events": { "com.example.foo" : 0 } }
   trusted_private_chat: null
   public_chat: null
```

---
## Opentracing
Configuration options related to Opentracing support.

---
### `opentracing`

These settings enable and configure opentracing, which implements distributed tracing.
This allows you to observe the causal chains of events across servers
including requests, key lookups etc., across any server running
synapse or any other services which support opentracing
(specifically those implemented with Jaeger).

Sub-options include:
* `enabled`: whether tracing is enabled. Set to true to enable. Disabled by default.
* `homeserver_whitelist`: The list of homeservers we wish to send and receive span contexts and span baggage.
   See [here](../../opentracing.md) for more.
   This is a list of regexes which are matched against the `server_name` of the homeserver.
   By default, it is empty, so no servers are matched.
* `force_tracing_for_users`: # A list of the matrix IDs of users whose requests will always be traced,
   even if the tracing system would otherwise drop the traces due to probabilistic sampling.
    By default, the list is empty.
* `jaeger_config`: Jaeger can be configured to sample traces at different rates.
   All configuration options provided by Jaeger can be set here. Jaeger's configuration is
   mostly related to trace sampling which is documented [here](https://www.jaegertracing.io/docs/latest/sampling/).

Example configuration:
```yaml
opentracing:
    enabled: true
    homeserver_whitelist:
      - ".*"
    force_tracing_for_users:
      - "@user1:server_name"
      - "@user2:server_name"

    jaeger_config:
      sampler:
        type: const
        param: 1
      logging:
        false
```
---
## Coordinating workers
Configuration options related to workers which belong in the main config file
(usually called `homeserver.yaml`).
A Synapse deployment can scale horizontally by running multiple Synapse processes
called _workers_. Incoming requests are distributed between workers to handle higher
loads. Some workers are privileged and can accept requests from other workers.

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
   are delegated to privileged workers. This allows unprivileged workers to make
   request a privileged worker to act on their behalf.
1. [The second part](#individual-worker-configuration)
   controls the behaviour of individual workers in isolation.

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

---
### `worker_replication_secret`

A shared secret used by the replication APIs on the main process to authenticate
HTTP requests from workers.

The default, this value is omitted (equivalently `null`), which means that 
traffic between the workers and the main process is not authenticated.

Example configuration:
```yaml
worker_replication_secret: "secret_secret"
```
---
### `start_pushers`

Controls sending of push notifications on the main process. Set to `false`
if using a [pusher worker](../../workers.md#synapseapppusher). Defaults to `true`.

Example configuration:
```yaml
start_pushers: false
```
---
### `pusher_instances`

It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher),
in which case the work is balanced across them. Use this setting to list the pushers by
[`worker_name`](#worker_name). 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.
The main process will send out push notifications by default if you do not disable
it by setting [`start_pushers: false`](#start_pushers).

Example configuration:
```yaml
start_pushers: false
pusher_instances:
  - pusher_worker1
  - pusher_worker2
```
---
### `send_federation`

Controls sending of outbound federation transactions on the main process.
Set to `false` if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
Defaults to `true`.

Example configuration:
```yaml
send_federation: false
```
---
### `federation_sender_instances`

It is possible to run multiple
[federation sender worker](../../workers.md#synapseappfederation_sender), in which
case the work is balanced across them. Use this setting to list the senders.

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).

Example configuration:
```yaml
send_federation: false
federation_sender_instances:
  - federation_sender1
```
---
### `instance_map`

When using workers this should be a map from [`worker_name`](#worker_name) to the
HTTP replication listener of the worker, if configured.
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`.
(The main process also needs an HTTP replication listener, but it should not be 
listed in the `instance_map`.)

Example configuration:
```yaml
instance_map:
  worker1:
    host: localhost
    port: 8034
```
---
### `stream_writers`

Experimental: When using workers you can define which workers should
handle writing to streams such as event persistence and typing notifications.
Any worker specified here must also be in the [`instance_map`](#instance_map).

See the list of available streams in the
[worker documentation](../../workers.md#stream-writers).

Example configuration:
```yaml
stream_writers:
  events: worker1
  typing: worker1
```
---
### `run_background_tasks_on`

The [worker](../../workers.md#background-tasks) that is used to run
background tasks (e.g. cleaning up expired data). If not provided this
defaults to the main process.

Example configuration:
```yaml
run_background_tasks_on: worker1
```
---
### `redis`

Configuration for Redis when using workers. This *must* be enabled when using workers.
This setting has the following sub-options:
* `enabled`: whether to use Redis support. Defaults to false.
* `host` and `port`: Optional host and port to use to connect to redis. Defaults to
   localhost and 6379
* `password`: Optional password if configured on the Redis instance.

Example configuration:
```yaml
redis:
  enabled: true
  host: localhost
  port: 6379
  password: <secret_password>
```
---
## Individual worker configuration
These options configure an individual worker, in its worker configuration file.
They should be not be provided when configuring the main process.

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`

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`

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`

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) 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_daemonize`

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