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