-
Andrew Morgan authored
Add a note to the config documentation that the 'delete_stale_devices_after' job always runs on the main process (#15452)
Andrew Morgan authoredAdd a note to the config documentation that the 'delete_stale_devices_after' job always runs on the main process (#15452)
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.
In addition, configuration options referring to size use the following suffixes:
-
M
= MiB, or 1,048,576 bytes -
K
= KiB, or 1024 bytes
For example, setting max_avatar_size: 10M
means that Synapse will not accept files larger than 10,485,760 bytes
for a user avatar.
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 below, the setting will be read and applied, but in example #2 the setting will not be read and a default will be applied.Example #1:
pid_file: DATADIR/homeserver.pid
Example #2:
#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, the
enabled
setting is read as a sub-option of thepresence
setting, and will be properly applied.However, the lack of indentation before the
enabled
setting in example #2 means that when reading the config, Synapse will consider bothpresence
andenabled
as different settings. In this case,presence
has no value, and thus a default applied, andenabled
is an option that Synapse doesn't recognize and thus ignores.Example #1:
presence: enabled: false
Example #2:
presence: enabled: false
In this manual, all top-level settings (ones with no indentation) are identified at the beginning of their section (i.e. "###
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.
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.
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: