config_documentation.md

Set the following to true to disable the warning that is emitted when the
`trusted_key_servers` include 'matrix.org'. See above.

Example configuration:
```yaml
suppress_key_server_warning: true
```
---
### `key_server_signing_keys_path`

The signing keys to use when acting as a trusted key server. If not specified
defaults to the server signing key.

Can contain multiple keys, one per line.

Example configuration:
```yaml
key_server_signing_keys_path: "key_server_signing_keys.key"
```
---
## Single sign-on integration

The following settings can be used to make Synapse use a single sign-on
provider for authentication, instead of its internal password database.

You will probably also want to set the following options to `false` to
disable the regular login/registration flows:
   * [`enable_registration`](#enable_registration)
   * [`password_config.enabled`](#password_config)

---
### `saml2_config`

Enable SAML2 for registration and login. Uses pysaml2. To learn more about pysaml and
to find a full list options for configuring pysaml, read the docs [here](https://pysaml2.readthedocs.io/en/latest/).

At least one of `sp_config` or `config_path` must be set in this section to
enable SAML login. You can either put your entire pysaml config inline using the `sp_config`
option, or you can specify a path to a psyaml config file with the sub-option `config_path`.
This setting has the following sub-options:

* `idp_name`: A user-facing name for this identity provider, which is used to
   offer the user a choice of login mechanisms.
* `idp_icon`: An optional icon for this identity provider, which is presented
   by clients and Synapse's own IdP picker page. If given, must be an
   MXC URI of the format `mxc://<server-name>/<media-id>`. (An easy way to
   obtain such an MXC URI is to upload an image to an (unencrypted) room
   and then copy the "url" from the source of the event.)
* `idp_brand`: An optional brand for this identity provider, allowing clients
   to style the login flow according to the identity provider in question.
   See the [spec](https://spec.matrix.org/latest/) for possible options here.
* `sp_config`: the configuration for the pysaml2 Service Provider. See pysaml2 docs for format of config.
   Default values will be used for the `entityid` and `service` settings,
   so it is not normally necessary to specify them unless you need to
   override them. Here are a few useful sub-options for configuring pysaml:
   * `metadata`: Point this to the IdP's metadata. You must provide either a local
      file via the `local` attribute or (preferably) a URL via the
      `remote` attribute.
   * `accepted_time_diff: 3`: Allowed clock difference in seconds between the homeserver and IdP.
      Defaults to 0.
   * `service`: By default, the user has to go to our login page first. If you'd like
     to allow IdP-initiated login, set `allow_unsolicited` to true under `sp` in the `service`
     section.
* `config_path`: specify a separate pysaml2 configuration file thusly:
  `config_path: "CONFDIR/sp_conf.py"`
* `saml_session_lifetime`: The lifetime of a SAML session. This defines how long a user has to
   complete the authentication process, if `allow_unsolicited` is unset. The default is 15 minutes.
* `user_mapping_provider`: Using this option, an external module can be provided as a
   custom solution to mapping attributes returned from a saml provider onto a matrix user. The
   `user_mapping_provider` has the following attributes:
  * `module`: The custom module's class.
  * `config`: Custom configuration values for the module. Use the values provided in the
     example if you are using the built-in user_mapping_provider, or provide your own
     config values for a custom class if you are using one. This section will be passed as a Python
     dictionary to the module's `parse_config` method. The built-in provider takes the following two
     options:
      * `mxid_source_attribute`: The SAML attribute (after mapping via the attribute maps) to use
          to derive the Matrix ID from. It is 'uid' by default. Note: This used to be configured by the
          `saml2_config.mxid_source_attribute option`. If that is still defined, its value will be used instead.
      * `mxid_mapping`: The mapping system to use for mapping the saml attribute onto a
         matrix ID. Options include: `hexencode` (which maps unpermitted characters to '=xx')
         and `dotreplace` (which replaces unpermitted characters with '.').
         The default is `hexencode`. Note: This used to be configured by the
         `saml2_config.mxid_mapping option`. If that is still defined, its value will be used instead.
* `grandfathered_mxid_source_attribute`: In previous versions of synapse, the mapping from SAML attribute to
   MXID was always calculated dynamically rather than stored in a table. For backwards- compatibility, we will look for `user_ids`
   matching such a pattern before creating a new account. This setting controls the SAML attribute which will be used for this
   backwards-compatibility lookup. Typically it should be 'uid', but if the attribute maps are changed, it may be necessary to change it.
   The default is 'uid'.
* `attribute_requirements`: It is possible to configure Synapse to only allow logins if SAML attributes
    match particular values. The requirements can be listed under
   `attribute_requirements` as shown in the example. All of the listed attributes must
    match for the login to be permitted.
* `idp_entityid`: If the metadata XML contains multiple IdP entities then the `idp_entityid`
   option must be set to the entity to redirect users to.
   Most deployments only have a single IdP entity and so should omit this option.


Once SAML support is enabled, a metadata file will be exposed at
`https://<server>:<port>/_synapse/client/saml2/metadata.xml`, which you may be able to
use to configure your SAML IdP with. Alternatively, you can manually configure
the IdP to use an ACS location of
`https://<server>:<port>/_synapse/client/saml2/authn_response`.

Example configuration:
```yaml
saml2_config:
  sp_config:
    metadata:
      local: ["saml2/idp.xml"]
      remote:
        - url: https://our_idp/metadata.xml
    accepted_time_diff: 3

    service:
      sp:
        allow_unsolicited: true

    # The examples below are just used to generate our metadata xml, and you
    # may well not need them, depending on your setup. Alternatively you
    # may need a whole lot more detail - see the pysaml2 docs!
    description: ["My awesome SP", "en"]
    name: ["Test SP", "en"]

    ui_info:
      display_name:
        - lang: en
          text: "Display Name is the descriptive name of your service."
      description:
        - lang: en
          text: "Description should be a short paragraph explaining the purpose of the service."
      information_url:
        - lang: en
          text: "https://example.com/terms-of-service"
      privacy_statement_url:
        - lang: en
          text: "https://example.com/privacy-policy"
      keywords:
        - lang: en
          text: ["Matrix", "Element"]
      logo:
        - lang: en
          text: "https://example.com/logo.svg"
          width: "200"
          height: "80"

    organization:
      name: Example com
      display_name:
        - ["Example co", "en"]
      url: "http://example.com"

    contact_person:
      - given_name: Bob
        sur_name: "the Sysadmin"
        email_address": ["admin@example.com"]
        contact_type": technical

  saml_session_lifetime: 5m

  user_mapping_provider:
    # Below options are intended for the built-in provider, they should be
    # changed if using a custom module.
    config:
      mxid_source_attribute: displayName
      mxid_mapping: dotreplace

  grandfathered_mxid_source_attribute: upn

  attribute_requirements:
    - attribute: userGroup
      value: "staff"
    - attribute: department
      value: "sales"

  idp_entityid: 'https://our_idp/entityid'
```
---
### `oidc_providers`

List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration
and login. See [here](../../openid.md)
for information on how to configure these options.

For backwards compatibility, it is also possible to configure a single OIDC
provider via an `oidc_config` setting. This is now deprecated and admins are
advised to migrate to the `oidc_providers` format. (When doing that migration,
use `oidc` for the `idp_id` to ensure that existing users continue to be
recognised.)

Options for each entry include:
* `idp_id`: a unique identifier for this identity provider. Used internally
   by Synapse; should be a single word such as 'github'.
   Note that, if this is changed, users authenticating via that provider
   will no longer be recognised as the same user!
   (Use "oidc" here if you are migrating from an old `oidc_config` configuration.)

* `idp_name`: A user-facing name for this identity provider, which is used to
   offer the user a choice of login mechanisms.

* `idp_icon`: An optional icon for this identity provider, which is presented
   by clients and Synapse's own IdP picker page. If given, must be an
   MXC URI of the format `mxc://<server-name>/<media-id>`. (An easy way to
   obtain such an MXC URI is to upload an image to an (unencrypted) room
   and then copy the "url" from the source of the event.)

* `idp_brand`: An optional brand for this identity provider, allowing clients
   to style the login flow according to the identity provider in question.
   See the [spec](https://spec.matrix.org/latest/) for possible options here.

* `discover`: set to false to disable the use of the OIDC discovery mechanism
  to discover endpoints. Defaults to true.

* `issuer`: Required. The OIDC issuer. Used to validate tokens and (if discovery
   is enabled) to discover the provider's endpoints.

* `client_id`: Required. oauth2 client id to use.

* `client_secret`: oauth2 client secret to use. May be omitted if
  `client_secret_jwt_key` is given, or if `client_auth_method` is 'none'.
  Must be omitted if `client_secret_path` is specified.

* `client_secret_path`: path to the oauth2 client secret to use. With that
   it's not necessary to leak secrets into the config file itself.
   Mutually exclusive with `client_secret`. Can be omitted if
   `client_secret_jwt_key` is specified.

   *Added in Synapse 1.91.0.*

* `client_secret_jwt_key`: Alternative to client_secret: details of a key used
   to create a JSON Web Token to be used as an OAuth2 client secret. If
   given, must be a dictionary with the following properties:

  * `key`: a pem-encoded signing key. Must be a suitable key for the
    algorithm specified. Required unless `key_file` is given.

  * `key_file`: the path to file containing a pem-encoded signing key file.
     Required unless `key` is given.

  * `jwt_header`: a dictionary giving properties to include in the JWT
     header. Must include the key `alg`, giving the algorithm used to
     sign the JWT, such as "ES256", using the JWA identifiers in
     RFC7518.

  * `jwt_payload`: an optional dictionary giving properties to include in
    the JWT payload. Normally this should include an `iss` key.

* `client_auth_method`: auth method to use when exchanging the token. Valid
   values are `client_secret_basic` (default), `client_secret_post` and
   `none`.

* `pkce_method`: Whether to use proof key for code exchange when requesting
   and exchanging the token. Valid values are: `auto`, `always`, or `never`. Defaults
   to `auto`, which uses PKCE if supported during metadata discovery. Set to `always`
   to force enable PKCE or `never` to force disable PKCE.

* `scopes`: list of scopes to request. This should normally include the "openid"
   scope. Defaults to `["openid"]`.

* `authorization_endpoint`: the oauth2 authorization endpoint. Required if
   provider discovery is disabled.

* `token_endpoint`: the oauth2 token endpoint. Required if provider discovery is
   disabled.

* `userinfo_endpoint`: the OIDC userinfo endpoint. Required if discovery is
   disabled and the 'openid' scope is not requested.

* `jwks_uri`: URI where to fetch the JWKS. Required if discovery is disabled and
   the 'openid' scope is used.

* `skip_verification`: set to 'true' to skip metadata verification. Use this if
   you are connecting to a provider that is not OpenID Connect compliant.
   Defaults to false. Avoid this in production.

* `user_profile_method`: Whether to fetch the user profile from the userinfo
   endpoint, or to rely on the data returned in the id_token from the `token_endpoint`.
   Valid values are: `auto` or `userinfo_endpoint`.
   Defaults to `auto`, which uses the userinfo endpoint if `openid` is
   not included in `scopes`. Set to `userinfo_endpoint` to always use the
   userinfo endpoint.

* `allow_existing_users`: set to true to allow a user logging in via OIDC to
   match a pre-existing account instead of failing. This could be used if
   switching from password logins to OIDC. Defaults to false.

* `enable_registration`: set to 'false' to disable automatic registration of new
   users. This allows the OIDC SSO flow to be limited to sign in only, rather than
   automatically registering users that have a valid SSO login but do not have
   a pre-registered account. Defaults to true.

* `user_mapping_provider`: Configuration for how attributes returned from a OIDC
   provider are mapped onto a matrix user. This setting has the following
   sub-properties:

     * `module`: The class name of a custom mapping module. Default is
       `synapse.handlers.oidc.JinjaOidcMappingProvider`.
        See [OpenID Mapping Providers](../../sso_mapping_providers.md#openid-mapping-providers)
        for information on implementing a custom mapping provider.

     * `config`: Configuration for the mapping provider module. This section will
        be passed as a Python dictionary to the user mapping provider
        module's `parse_config` method.

        For the default provider, the following settings are available:

       * `subject_template`: Jinja2 template for a unique identifier for the user.
         Defaults to `{{ user.sub }}`, which OpenID Connect compliant providers should provide.

         This replaces and overrides `subject_claim`.

       * `subject_claim`: name of the claim containing a unique identifier
         for the user. Defaults to 'sub', which OpenID Connect
         compliant providers should provide.

         *Deprecated in Synapse v1.75.0.*

       * `picture_template`: Jinja2 template for an url for the user's profile picture.
         Defaults to `{{ user.picture }}`, which OpenID Connect compliant providers should
         provide and has to refer to a direct image file such as PNG, JPEG, or GIF image file.

         This replaces and overrides `picture_claim`.

         Currently only supported in monolithic (single-process) server configurations
         where the media repository runs within the Synapse process.

       * `picture_claim`: name of the claim containing an url for the user's profile picture.
         Defaults to 'picture', which OpenID Connect compliant providers should provide
         and has to refer to a direct image file such as PNG, JPEG, or GIF image file.

         Currently only supported in monolithic (single-process) server configurations
         where the media repository runs within the Synapse process.

         *Deprecated in Synapse v1.75.0.*

       * `localpart_template`: Jinja2 template for the localpart of the MXID.
          If this is not set, the user will be prompted to choose their
          own username (see the documentation for the `sso_auth_account_details.html`
          template). This template can use the `localpart_from_email` filter.

       * `confirm_localpart`: Whether to prompt the user to validate (or
          change) the generated localpart (see the documentation for the
          'sso_auth_account_details.html' template), instead of
          registering the account right away.

       * `display_name_template`: Jinja2 template for the display name to set
          on first login. If unset, no displayname will be set.

       * `email_template`: Jinja2 template for the email address of the user.
          If unset, no email address will be added to the account.

       * `extra_attributes`: a map of Jinja2 templates for extra attributes
          to send back to the client during login. Note that these are non-standard and clients will ignore them
          without modifications.

     When rendering, the Jinja2 templates are given a 'user' variable,
     which is set to the claims returned by the UserInfo Endpoint and/or
     in the ID Token.

* `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`.
  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
    enable_registration: 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.
* `idp_name`: A user-facing name for this identity provider, which is used to
   offer the user a choice of login mechanisms.
* `idp_icon`: An optional icon for this identity provider, which is presented
   by clients and Synapse's own IdP picker page. If given, must be an
   MXC URI of the format `mxc://<server-name>/<media-id>`. (An easy way to
   obtain such an MXC URI is to upload an image to an (unencrypted) room
   and then copy the "url" from the source of the event.)
* `idp_brand`: An optional brand for this identity provider, allowing clients
   to style the login flow according to the identity provider in question.
   See the [spec](https://spec.matrix.org/latest/) for possible options here.
* `server_url`: The URL of the CAS authorization endpoint.
* `protocol_version`: The CAS protocol version, defaults to none (version 3 is required if you want to use "required_attributes").
* `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.
* `enable_registration`: set to 'false' to disable automatic registration of new
   users. This allows the CAS SSO flow to be limited to sign in only, rather than
   automatically registering users that have a valid SSO login but do not have
   a pre-registered account. Defaults to true.

   *Added in Synapse 1.93.0.*

Example configuration:
```yaml
cas_config:
  enabled: true
  server_url: "https://cas-server.com"
  protocol_version: 3
  displayname_attribute: name
  required_attributes:
    userGroup: "staff"
    department: None
  enable_registration: true
```
---
### `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
```
---
## 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:
* `enabled`: Enables or disables push notification calculation. Note, disabling this will also
   stop unread counts being calculated for rooms. This mode of operation is intended
   for homeservers which may only have bots or appservice users connected, or are otherwise
   not interested in push/unread counters. This is enabled by default.
* `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.
* `jitter_delay`: Delays push notifications by a random amount up to the given
  duration. Useful for mitigating timing attacks. Optional, defaults to no
  delay. _Added in Synapse 1.84.0._

Example configuration:
```yaml
push:
  enabled: true
  include_content: false
  group_unread_count_by_room: false
  jitter_delay: "10s"
```
---
## 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 at the time the search is performed. If set to true, will return all users who share a room with the user from the homeserver.
   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.
* `show_locked_users`: Defines whether to show locked users in search query results. Defaults to false.

Example configuration:
```yaml
user_directory:
    enabled: false
    search_all_users: true
    prefer_local_users: true
    show_locked_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
```
---
### `forget_rooms_on_leave`

Set to true to automatically forget rooms for users when they leave them, either
normally or via a kick or ban. Defaults to false.

Example configuration:
```yaml
forget_rooms_on_leave: false
```
---
### `exclude_rooms_from_sync`
A list of rooms to exclude from sync responses. This is useful for server
administrators wishing to group users into a room without these users being able
to see it from their client.

By default, no room is excluded.

Example configuration:
```yaml
exclude_rooms_from_sync:
    - !foo:example.com
```

---
## 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
   requests to 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`

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`
if using a [pusher worker](../../workers.md#synapseapppusher). Defaults to `true`.

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

It is possible to scale the processes that handle sending push notifications to [sygnal](https://github.com/matrix-org/sygnal)
and email by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding it's [`worker_name`](#worker_name) to
a `pusher_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. Ensure the main process and all pusher workers are restarted after changing
this option.