config_documentation.md

Configuring Synapse

This is intended as a guide to the Synapse configuration. The behavior of a Synapse instance can be modified through the many configuration settings documented here — each config option is explained, including what the default is, how to change the default and what sort of behaviour the setting governs. Also included is an example configuration for each setting. If you don't want to spend a lot of time thinking about options, the config as generated sets sensible defaults for all values. Do note however that the database defaults to SQLite, which is not recommended for production usage. You can read more on this subject here.

Config Conventions

Configuration options that take a time period can be set using a number followed by a letter. Letters have the following meanings:

• s = second
• m = minute
• h = hour
• d = day
• w = week
• y = year

For example, setting redaction_retention_period: 5m would remove redacted messages from the database after 5 minutes, rather than 5 months.

YAML

The configuration file is a YAML file, which means that certain syntax rules apply if you want your config file to be read properly. A few helpful things to know:

• # before any option in the config will comment out that setting and either a default (if available) will be applied or Synapse will ignore the setting. Thus, in example #1 (closed) below, the setting will be read and applied, but in example #2 (closed) the setting will not be read and a default will be applied.

  Example #1 (closed):

  pid_file: DATADIR/homeserver.pid

  Example #2 (closed):

  #pid_file: DATADIR/homeserver.pid

• Indentation matters! The indentation before a setting will determine whether a given setting is read as part of another setting, or considered on its own. Thus, in example #1 (closed), the enabled setting is read as a sub-option of the presence setting, and will be properly applied.

  However, the lack of indentation before the enabled setting in example #2 (closed) means that when reading the config, Synapse will consider both presence and enabled as different settings. In this case, presence has no value, and thus a default applied, and enabled is an option that Synapse doesn't recognize and thus ignores.

  Example #1 (closed):

  presence:
    enabled: false

  Example #2 (closed):

  presence:
  enabled: false

  In this manual, all top-level settings (ones with no indentation) are identified at the beginning of their section (i.e. "Config option: example_setting") and the sub-options, if any, are identified and listed in the body of the section. In addition, each setting has an example of its usage, with the proper indentation shown.

Contents

Modules

Server

Homeserver Blocking

TLS

Federation

Caching

Database

Logging

Ratelimiting

Media Store

Captcha

TURN

Registration

API Configuration

Signing Keys

Single Sign On Integration

Push

Rooms

Opentracing

Workers

Background Updates

Modules

Server admins can expand Synapse's functionality with external modules.

See here for more documentation on how to configure or create custom modules for Synapse.

---

Config option: modules

Use the module sub-option to add modules under this option to extend functionality. The module setting then has a sub-option, config, which can be used to define some configuration for the module.

Defaults to none.

Example configuration:

modules:
  - module: my_super_module.MySuperClass
    config:
      do_thing: true
  - module: my_other_super_module.SomeClass
    config: {}

---

Server

Define your homeserver name and other base options.

---

Config option: server_name

This sets the public-facing domain of the server.

The server_name name will appear at the end of usernames and room addresses created on your server. For example if the server_name was example.com, usernames on your server would be in the format @user:example.com

In most cases you should avoid using a matrix specific subdomain such as matrix.example.com or synapse.example.com as the server_name for the same reasons you wouldn't use user@email.example.com as your email address. See here for information on how to host Synapse on a subdomain while preserving a clean server_name.

The server_name cannot be changed later so it is important to configure this correctly before you start Synapse. It should be all lowercase and may contain an explicit port.

There is no default for this option.

Example configuration #1 (closed):

server_name: matrix.org 

Example configuration #2 (closed):

server_name: localhost:8080

---

Config option: pid_file

When running Synapse as a daemon, the file to store the pid in. Defaults to none.

Example configuration:

pid_file: DATADIR/homeserver.pid

---

Config option: web_client_location

The absolute URL to the web client which / will redirect to. Defaults to none.

Example configuration:

web_client_location: https://riot.example.com/

---

Config option: public_baseurl

The public-facing base URL that clients use to access this Homeserver (not including _matrix/...). This is the same URL a user might enter into the 'Custom Homeserver URL' field on their client. If you use Synapse with a reverse proxy, this should be the URL to reach Synapse via the proxy. Otherwise, it should be the URL to reach Synapse's client HTTP listener (see 'listeners' below).

Defaults to https://<server_name>/.

Example configuration:

public_baseurl: https://example.com/

---

Config option: serve_server_wellknown

By default, other servers will try to reach our server on port 8448, which can be inconvenient in some environments.

Provided https://<server_name>/ on port 443 is routed to Synapse, this option configures Synapse to serve a file at https://<server_name>/.well-known/matrix/server. This will tell other servers to send traffic to port 443 instead.

This option currently defaults to false.

See https://matrix-org.github.io/synapse/latest/delegate.html for more information.

Example configuration:

serve_server_wellknown: true

---

Config option: soft_file_limit

Set the soft limit on the number of file descriptors synapse can use. Zero is used to indicate synapse should set the soft limit to the hard limit. Defaults to 0.

Example configuration:

soft_file_limit: 3

---

Config option: presence

Presence tracking allows users to see the state (e.g online/offline) of other local and remote users. Set the enabled sub-option to false to
disable presence tracking on this homeserver. Defaults to true. This option replaces the previous top-level 'use_presence' option.

Example configuration:

presence:
  enabled: false

---

Config option: require_auth_for_profile_requests

Whether to require authentication to retrieve profile data (avatars, display names) of other users through the client API. Defaults to false. Note that profile data is also available via the federation API, unless allow_profile_lookup_over_federation is set to false.

Example configuration:

require_auth_for_profile_requests: true

---

Config option: limit_profile_requests_to_users_who_share_rooms

Use this option to require a user to share a room with another user in order to retrieve their profile information. Only checked on Client-Server requests. Profile requests from other servers should be checked by the requesting server. Defaults to false.

Example configuration:

limit_profile_requests_to_users_who_share_rooms: true

---

Config option: include_profile_data_on_invite

Use this option to prevent a user's profile data from being retrieved and displayed in a room until they have joined it. By default, a user's profile data is included in an invite event, regardless of the values of the above two settings, and whether or not the users share a server. Defaults to true.

Example configuration:

include_profile_data_on_invite: false

---

Config option: allow_public_rooms_without_auth

If set to true, removes the need for authentication to access the server's public rooms directory through the client API, meaning that anyone can query the room directory. Defaults to false.

Example configuration:

allow_public_rooms_without_auth: true

---

Config option: allow_public_rooms_without_auth

If set to true, allows any other homeserver to fetch the server's public rooms directory via federation. Defaults to false.

Example configuration:

allow_public_rooms_over_federation: true

---

Config option: default_room_version

The default room version for newly created rooms on this server.

Known room versions are listed here

For example, for room version 1, default_room_version should be set to "1".

Currently defaults to "9".

Example configuration:

default_room_version: "8"

---

Config option: gc_thresholds

The garbage collection threshold parameters to pass to gc.set_threshold, if defined. Defaults to none.

Example configuration:

gc_thresholds: [700, 10, 10]

---

Config option: gc_min_interval

The minimum time in seconds between each GC for a generation, regardless of the GC thresholds. This ensures that we don't do GC too frequently. A value of [1s, 10s, 30s] indicates that a second must pass between consecutive generation 0 GCs, etc.

Defaults to [1s, 10s, 30s].

Example configuration:

gc_min_interval: [0.5s, 30s, 1m]

---

Config option: filter_timeline_limit

Set the limit on the returned events in the timeline in the get and sync operations. Defaults to 100. A value of -1 means no upper limit.

Example configuration:

filter_timeline_limit: 5000

---

Config option: block_non_admin_invites

Whether room invites to users on this server should be blocked (except those sent by local server admins). Defaults to false.

Example configuration:

block_non_admin_invites: true

---

Config option: enable_search

If set to false, new messages will not be indexed for searching and users will receive errors when searching for messages. Defaults to true.

Example configuration:

enable_search: false

---

Config option: ip_range_blacklist

This option prevents outgoing requests from being sent to the specified blacklisted IP address CIDR ranges. If this option is not specified then it defaults to private IP address ranges (see the example below).

The blacklist applies to the outbound requests for federation, identity servers, push servers, and for checking key validity for third-party invite events.

(0.0.0.0 and :: are always blacklisted, whether or not they are explicitly listed here, since they correspond to unroutable addresses.)

This option replaces federation_ip_range_blacklist in Synapse v1.25.0.

Note: The value is ignored when an HTTP proxy is in use.

Example configuration:

ip_range_blacklist:
  - '127.0.0.0/8'
  - '10.0.0.0/8'
  - '172.16.0.0/12'
  - '192.168.0.0/16'
  - '100.64.0.0/10'
  - '192.0.0.0/24'
  - '169.254.0.0/16'
  - '192.88.99.0/24'
  - '198.18.0.0/15'
  - '192.0.2.0/24'
  - '198.51.100.0/24'
  - '203.0.113.0/24'
  - '224.0.0.0/4'
  - '::1/128'
  - 'fe80::/10'
  - 'fc00::/7'
  - '2001:db8::/32'
  - 'ff00::/8'
  - 'fec0::/10'

---

Config option: ip_range_whitelist

List of IP address CIDR ranges that should be allowed for federation, identity servers, push servers, and for checking key validity for third-party invite events. This is useful for specifying exceptions to wide-ranging blacklisted target IP ranges - e.g. for communication with a push server only visible in your network.

This whitelist overrides ip_range_blacklist and defaults to an empty list.

Example configuration:

ip_range_whitelist:
   - '192.168.1.1'

---

Config option: listeners

List of ports that Synapse should listen on, their purpose and their configuration.

Sub-options for each listener include:

• port: the TCP port to bind to.

• bind_addresses: a list of local addresses to listen on. The default is 'all local interfaces'.

• type: the type of listener. Normally http, but other valid options are:

  • manhole: (see the docs here),

  • metrics: (see the docs here),

  • replication: (see the docs here).

• tls: set to true to enable TLS for this listener. Will use the TLS key/cert specified in tls_private_key_path / tls_certificate_path.

• x_forwarded: Only valid for an 'http' listener. Set to true to use the X-Forwarded-For header as the client IP. Useful when Synapse is behind a reverse-proxy.

• resources: Only valid for an 'http' listener. A list of resources to host on this port. Sub-options for each resource are:

  • names: a list of names of HTTP resources. See below for a list of valid resource names.

  • compress: set to true to enable HTTP compression for this resource.

• additional_resources: Only valid for an 'http' listener. A map of additional endpoints which should be loaded via dynamic modules.

Valid resource names are:

• client: the client-server API (/_matrix/client), and the synapse admin API (/_synapse/admin). Also implies 'media' and 'static'.

• consent: user consent forms (/_matrix/consent). See here for more.

• federation: the server-server API (/_matrix/federation). Also implies media, keys, openid

• keys: the key discovery API (/_matrix/keys).

• media: the media API (/_matrix/media).

• metrics: the metrics interface. See here.

• openid: OpenID authentication. See here.

• replication: the HTTP replication API (/_synapse/replication). See here.

• static: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.)

Example configuration #1 (closed):

listeners:
  # TLS-enabled listener: for when matrix traffic is sent directly to synapse.
  #
  # (Note that you will also need to give Synapse a TLS key and certificate: see the TLS section
  # below.)
  #
  - port: 8448
    type: http
    tls: true
    resources:
      - names: [client, federation]

Example configuration #2 (closed):

listeners:
  # Unsecure HTTP listener: for when matrix traffic passes through a reverse proxy
  # that unwraps TLS.
  #
  # If you plan to use a reverse proxy, please see
  # https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
  #
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1']

    resources:
      - names: [client, federation]
        compress: false

    # example additional_resources:
    additional_resources:
      "/_matrix/my/custom/endpoint":
        module: my_module.CustomRequestHandler
        config: {}

  # Turn on the twisted ssh manhole service on localhost on the given
  # port.
  - port: 9000
    bind_addresses: ['::1', '127.0.0.1']
    type: manhole

---

Config option: manhole_settings

Connection settings for the manhole. You can find more information on the manhole here. Manhole sub-options include:

• username : the username for the manhole. This defaults to 'matrix'.
• password: The password for the manhole. This defaults to 'rabbithole'.
• ssh_priv_key_path and ssh_pub_key_path: The private and public SSH key pair used to encrypt the manhole traffic. If these are left unset, then hardcoded and non-secret keys are used, which could allow traffic to be intercepted if sent over a public network.

Example configuration:

manhole_settings:
  username: manhole
  password: mypassword
  ssh_priv_key_path: CONFDIR/id_rsa
  ssh_pub_key_path: CONFDIR/id_rsa.pub

---

Config option: dummy_events_threshold

Forward extremities can build up in a room due to networking delays between homeservers. Once this happens in a large room, calculation of the state of that room can become quite expensive. To mitigate this, once the number of forward extremities reaches a given threshold, Synapse will send an org.matrix.dummy_event event, which will reduce the forward extremities in the room.

This setting defines the threshold (i.e. number of forward extremities in the room) at which dummy events are sent. The default value is 10.

Example configuration:

dummy_events_threshold: 5

---

Homeserver blocking

Useful options for Synapse admins.

---

Config option: admin_contact

How to reach the server admin, used in ResourceLimitError. Defaults to none.

Example configuration:

admin_contact: 'mailto:admin@server.com'

---

Config option: hs_disabled and hs_disabled_message

Blocks users from connecting to the homeserver and provides a human-readable reason why the connection was blocked. Defaults to false.

Example configuration:

hs_disabled: true
hs_disabled_message: 'Reason for why the HS is blocked'

---

Config option: limit_usage_by_mau

This option disables/enables monthly active user blocking. Used in cases where the admin or server owner wants to limit to the number of monthly active users. When enabled and a limit is reached the server returns a ResourceLimitError with error type Codes.RESOURCE_LIMIT_EXCEEDED. Defaults to false. If this is enabled, a value for max_mau_value must also be set.

Example configuration:

limit_usage_by_mau: true 

---

Config option: max_mau_value

This option sets the hard limit of monthly active users above which the server will start blocking user actions if limit_usage_by_mau is enabled. Defaults to 0.

Example configuration:

max_mau_value: 50

---

Config option: mau_trial_days

The option mau_trial_days is a means to add a grace period for active users. It means that users must be active for the specified number of days before they can be considered active and guards against the case where lots of users sign up in a short space of time never to return after their initial session. Defaults to 0.

Example configuration:

mau_trial_days: 5

---

Config option: mau_appservice_trial_days

The option mau_appservice_trial_days is similar to mau_trial_days, but applies a different trial number if the user was registered by an appservice. A value of 0 means no trial days are applied. Appservices not listed in this dictionary use the value of mau_trial_days instead.

Example configuration:

mau_appservice_trial_days: 
  my_appservice_id: 3
  another_appservice_id: 6

---

Config option: mau_limit_alerting

The option mau_limit_alerting is a means of limiting client-side alerting should the mau limit be reached. This is useful for small instances where the admin has 5 mau seats (say) for 5 specific people and no interest increasing the mau limit further. Defaults to true, which means that alerting is enabled.

Example configuration:

mau_limit_alerting: false

---

Config option: mau_stats_only

If enabled, the metrics for the number of monthly active users will be populated, however no one will be limited based on these numbers. If limit_usage_by_mau is true, this is implied to be true. Defaults to false.

Example configuration:

mau_stats_only: true

---

Config option: mau_limit_reserved_threepids

Sometimes the server admin will want to ensure certain accounts are never blocked by mau checking. These accounts are specified by this option. Defaults to none. Add accounts by specifying the medium and address of the reserved threepid (3rd party identifier).

Example configuration:

mau_limit_reserved_threepids:
  - medium: 'email'
    address: 'reserved_user@example.com'

---

Config option: server_context

This option is used by phonehome stats to group together related servers. Defaults to none.

Example configuration:

server_context: context

---

Config option: limit_remote_rooms

When this option is enabled, the room "complexity" will be checked before a user joins a new remote room. If it is above the complexity limit, the server will disallow joining, or will instantly leave. This is useful for homeservers that are resource-constrained. Options for this setting include:

• enabled: whether this check is enabled. Defaults to false.
• complexity: the limit above which rooms cannot be joined. The default is 1.0.
• complexity_error: override the error which is returned when the room is too complex with a custom message.
• admins_can_join: allow server admins to join complex rooms. Default is false.

Room complexity is an arbitrary measure based on factors such as the number of users in the room.

Example configuration:

limit_remote_rooms:
  enabled: true
  complexity: 0.5
  complexity_error: "I can't let you do that, Dave."
  admins_can_join: true

---

Config option: require_membership_for_aliases

Whether to require a user to be in the room to add an alias to it. Defaults to true.

Example configuration:

require_membership_for_aliases: false