-
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:
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.
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:
server_name: matrix.org
Example configuration #2:
server_name: localhost:8080
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
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/
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/
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 Delegation of incoming federation traffic for more information.
Example configuration:
serve_server_wellknown: true
extra_well_known_client_content
This option allows server runners to add arbitrary key-value pairs to the client-facing .well-known
response.
Note that the public_baseurl
config option must be provided for Synapse to serve a response to /.well-known/matrix/client
at all.
If this option is provided, it parses the given yaml to json and
serves it on /.well-known/matrix/client
endpoint
alongside the standard properties.
Added in Synapse 1.62.0.
Example configuration:
extra_well_known_client_content :
option1: value1
option2: value2
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
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
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
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
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
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
allow_public_rooms_over_federation
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
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 "10".
Changed in Synapse 1.76: the default version room version was increased from 9 to 10.
Example configuration:
default_room_version: "8"
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]
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]
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
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
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
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.